neuromcp (Adel Elo13)

neuromcp——人工智能主体的主权记忆

任何型号。你的记忆。留在当地。

neuromcp是第一个 主权记忆 AI层：一个开源的MCP服务器，为Claude、GPT、Gemini和Ollama提供持久的、可搜索的内存——完全存储在您的机器上。没有API密钥。没有云同步。无需订阅即可记住您是谁。

主权记忆 =您完全拥有的数据，存在于您控制的硬件上，并且可以在您使用的每个模型上移植。云存储产品拥有您的数据；主权记忆意味着 *你* 同上

](https://www.npmjs.com/package/neuromcp) ](https://www.npmjs.com/package/neuromcp)  

npx neuromcp

为什么选择neuromcp

LLM是一种商品。你的记忆是护城河。 GPT-5、克劳德4、双子座——它们都趋同。你明年使用的模型会有所不同。你建立的每一次对话、决定和偏好的记忆都是你的。neuromcp将该层保留在您的机器上，并使其可在任何兼容MCP的客户端上移植。

本地优先是一种设计选择，而不是限制。 没有遥测。没有数据离开你的笔记本电脑。没有供应商有你谈话的副本。审计每一行触及你记忆的代码。SQLite+本地嵌入；所有东西都放在一个磁盘上。

一次安装。每一个客户。 Claude Desktop、Cursor、Windsurf、Codex CLI、Continue、LibreChat、Open WebUI——neuromcp支持MCP，因此它可以在任何支持MCP的地方工作。明天换型号；你的记忆随之而来。

真正的回忆，而不是关键字匹配。 混合检索结合了矢量搜索（nomic嵌入文本，768 dim）、BM25全文、图形链接和学习有用性先验。在LongMemEval上有500个干扰物时，R@5保持在93.3%。您的上下文窗口会获得正确的内存，而不仅仅是最近的内存。

LongMemEval-S精度

转载： OMB_ANSWER_LLM=claude OMB_ANSWER_MODEL=opus OMB_JUDGE_LLM=claude OMB_JUDGE_MODEL=opus uv run omb run --dataset longmemeval -s s -m neuromcp -c "single-session-user,single-session-assistant,multi-session,temporal-reasoning,knowledge-update,single-session-preference" --query-limit 17

样本量诚实。 n=102（每类17×6类）。威尔逊的95%置信区间为98/102≈90.5-98.7%。在任何“顶级”声明之前，使用相同配置进行完整的500q运行是下一个里程碑。

基准（v0.18.0）

Oracle拆分（干净-简单模式）

Oracle拆分LongMemEval将正确的内存隔离在一个小内存中 语料库。每个本地MCP存储系统在这里都声称约99%。它测量 “排名者是否致力于清洁输入”——仅此而已。

分心分裂（v0.18.0，诚实）

相同的30个问题+从其他人那里随机提取的1000个分心记忆 问题的大海捞针。正确的记忆现在与真实的噪音竞争。

复制： npx tsx eval/longmemeval-distractor-runner.ts --limit 5 --distractors 1000

样本量。 500干扰物行n=30（Wilson 95%置信区间为 28/30≈78-99%R@5）。1000个干扰物行为n=5——初步， 威尔逊95%置信区间\[57%，100%\]。1000个干扰物n=30的跑步需要大约36分钟 在一个Ollama的例子中；缓存干扰物批处理是v0.19.0 工作。将500个干扰数字视为可防御的，1000个干扰数字作为可防御的 方向积极，但动力不足。

头对头比较是v0.19.0的明确工作。 后见之明（当地 OSS MCP，LongMemEval声称约94.6%）和Mem0/Zep发布了自己的 数字在自己的马具上。直到我们让他们全部对抗 相同的语料库+嵌入器，称任何本地MCP服务器为“最先进的” 是营销，不是衡量。neuromcp发布其数字 样本量注意事项，以便您判断方向；不要读绝对 他们的优势还在。

混合排序器（BM25+向量+注意力+图形+有用性优先） 将R@5=100%保持在1000:1的干扰物与目标物的比例 样品。MRR降至74%，因为正确的内存有时不正确 排名1，但在我们所看到的排名中总是≤5。早期v0.18.0数字 （R@5.23%）来自测试FakeEmbedder——在v0.18.1中修复。

这个基准没有证明什么： 端到端应答 正确性、长期多会话推理或优越性 在商业云系统（Mem0、Zep）上进行了自己的基准测试。 这些比较需要它们的数字在相同的干扰物分割上， 尚未发表。

为什么

AI代理在会话之间会忘记一切。现有的解决方案要么存储平面键-值对（对实际知识没有用处），要么需要云基础设施和API密钥。

neuromcp给你两层记忆：

1. MCP服务器 --混合搜索（矢量+全文+图形）、逐字回忆、内存管理、自动整合，所有这些都在一个SQLite文件中
2. Wiki知识库 --编译的Markdown知识可以在崩溃中幸存下来，在会话中复合，并在每次启动时为您的代理项目提供感知上下文

建筑

~/.neuromcp/
├── memory.db               ← SQLite: hybrid search, MCP tools
├── wiki/                   ← Compiled knowledge (git-tracked)
│   ├── index.md            ← Routekaart — LLM reads this FIRST
│   ├── schema.md           ← Operating rules for the LLM
│   ├── log.md              ← Append-only changelog
│   ├── people/             ← User profiles, preferences
│   ├── projects/           ← Project knowledge (stack, auth, URLs)
│   ├── systems/            ← Infrastructure (tools, MCP servers)
│   ├── patterns/           ← Reusable patterns (error fixes, routing)
│   ├── decisions/          ← Architecture decisions with context
│   └── skills/             ← Repeatable procedures
└── raw/sessions/           ← Raw session logs (auto-generated)

wiki是如何工作的

自愈固结管道（v0.15.0+）

每4小时，洗衣代理就会运行一次 run-consolidation.sh，其中 端到端协调四个步骤：

1. consolidate-sessions.py --对每个项目的原始会话进行批处理，

要求克劳德提供事实摘要，并将其与事实进行核对 原始来源。当审计员标记特定的不受支持的索赔时 整合者现在 自动剥离这些线条并重新审核一次 --所以 一句推测性的话不再能杀死一整批人。

1. rescue-rejected.py --解析仍然失败的任何批，

不支持的声明将被删除，清理后的摘要为 附在其维基页面上。纯文本手术，没有法学硕士电话。

1. entity-linker.py --每一页都有交叉链接：一个简单的提及

添加了另一个注册实体（people/、projects/、systems/） 到页面的 related: 正面。使wiki表现得像 没有单独图形数据库的图形。

1. rebuild-index.py --再生 index.md 按类别

-index.md 文件夹。超过10页的类别会自动拆分，因此 随着wiki的扩展，会话启动路由器保持紧凑。

该管道是幂等的，可以随时重新运行。

法学硕士在课程开始时知道什么

Schema (operating rules) → How to maintain the wiki
Index (knowledge map)    → What knowledge exists
User profile             → Who you are, how you work
Project page             → Current project details (auto-detected from cwd)
Last session             → What happened last time

快速开始

1.启动MCP服务器

npx neuromcp

2.初始化wiki+钩子(必需的 闭环归因）

npx neuromcp-init-wiki

这将创建wiki结构，安装钩子（Claude Code）和规则（其他编辑器），并自动配置所有内容。 没有这一步, npx neuromcp 仍然作为一个带有42个工具的普通MCP服务器运行，但没有安装关闭归因循环的评论挂钩——检索可以工作，但有用性分数永远不会累积。多次运行是安全的——不会覆盖现有配置。

编辑器兼容性

neuromcp可与任何兼容MCP的编辑器配合使用。两层集成：

克劳德代码 通过原生钩子获得完整的体验——即使LLM忘记了，上下文注入和持久性也会自动发生。

其他编辑 获取指示LLM在会话开始/结束时调用neuromcp工具的规则文件。这取决于LLM合规性——它在实践中运行良好，但不像钩子那样保证。

# Auto-detect installed editors
npx neuromcp-init-wiki

# Target a specific editor
npx neuromcp-init-wiki --editor cursor

# Install rules for all supported editors
npx neuromcp-init-wiki --editor all

支持的编辑器： cursor, windsurf, cline, copilot （VS码）， jetbrains, zed

推荐：添加Ollama进行真正的语义搜索

ollama pull nomic-embed-text

neuromcp会自动检测到它。不需要配置。

安装

克劳德代码

// ~/.claude.json → mcpServers
{
  "neuromcp": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "neuromcp"]
  }
}

克劳德桌面

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "neuromcp": {
      "command": "npx",
      "args": ["-y", "neuromcp"]
    }
  }
}

光标/风帆/克莱恩

格式相同——添加到编辑器的MCP设置中。

按项目隔离

// .mcp.json in project root
{
  "mcpServers": {
    "neuromcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "neuromcp"],
      "env": {
        "NEUROMCP_DB_PATH": ".neuromcp/memory.db",
        "NEUROMCP_NAMESPACE": "my-project"
      }
    }
  }
}

MCP表面

核心工具

逐字工具

资源（13）

提示（3）

Wiki知识库

维基是经过编译的、人类可读的知识层。它用结构化、相互关联的Markdown页面取代了会话日志的混乱。

为什么选择维基而不是更多的矢量搜索？

Wiki页面格式

---
title: My Project
type: project
created: 2026-04-06
updated: 2026-04-06
confidence: high
related: [other-project, oauth-setup]
---

# My Project

Description, stack, auth, deployment details...

如何使用

安装钩子后，wiki会自动工作。法学硕士：

1. 倒像 index.md 在会议上开始了解存在的知识
2. 读取与当前任务相关的特定页面
3. 学习新东西时更新页面
4. 如果wiki需要更新，则每8次工具调用就会提醒一次

你也可以手动浏览和编辑维基——它只是Markdown文件。

自动合并（可选）

一旦你积累了原始会话日志，维基就可以自动保持新鲜。计划作业读取未处理的会话，并将其按项目分组（通过检测 $HOME/projects/ 会话内容中的路径），并使用 claude CLI用于合成 ## [date] 进入正确的wiki页面。

npx neuromcp-enable-consolidation

安装内容：

• ~/.neuromcp/scripts/consolidate-sessions.py --工人
• ~/.neuromcp/scripts/run-consolidation.sh --有门槛保护的跑步者
• macOS：每4小时发射一次的洗衣剂(com.neuromcp.consolidate)
• Linux：打印要手动添加的cron代码段

要求：

• python3 ≥3.8分 PATH
• 这 claude 命令行界面 上 PATH

内置防护装置：

• 阈值：如果少于5个未处理的会话，则跳过
• 输出是从一个有围栏的标记块中提取的；道歉/叙述文本被拒绝
• 分类账(~/.neuromcp/consolidation-ledger.json)使重新运行具有幂等性
• 大型项目积压是自动批处理的（默认为每批15个会话 claude 呼叫；用以下方式覆盖 --max-sessions)

卸载： npx neuromcp-enable-consolidation --uninstall

更改间隔： npx neuromcp-enable-consolidation --interval 7200 （每2小时一次）

幻觉守卫（eval循环）。 每个整合器输出在维基被触及之前都会经过第二次Haiku审核。如果生成的摘要中的任何事实声明都无法追溯到原始会话，则块将转到 ~/.neuromcp/review-queue/ 而不是wiki。没有幻觉般的说法泄露出去。

具有时间替代的原子事实。 摘要获得批准后，也会被提炼成简短的独立事实，并存储为 category='fact' 行与 valid_from=today当一个新的事实是Jaccard与同一项目中的一个现有事实相似时，Haiku决定new是否取代OLD——如果是，则旧的一行得到 superseded_by_id 和 valid_to 集。检索默认仅使用当前事实(superseded_by_id IS NULL)因此，过时的结论再也不会出现。

自动检索+混合索引

一旦维基有了内容，就让它 *可搜索的* 所以 UserPromptSubmit 钩子可以自动显示相关页面（不再需要“LLM必须记住调用” search"):

npx neuromcp-index-wiki              # index wiki pages into memories_fts + memories_vec
npx neuromcp-index-wiki --rebuild    # wipe wiki entries first, then reindex
npx neuromcp-index-wiki --dry-run    # preview what would change
npx neuromcp-index-wiki --no-embed   # FTS-only mode (no embedding provider needed)

npx neuromcp-backfill-embeddings     # embed any memory still missing a vector

索引器将每个页面拆分为 ## 节标题，并将每个节存储为重复数据消除的内存(source='wiki', category='wiki').每个部分都写入FTS5索引 *和* 通过配置的提供者（Ollama）嵌入→ 开放人工智能→ ONNX），因此矢量搜索也有效。

在提示时间 neuromcp-auto-retrieve.js 钩叫 neuromcp-query，它并行运行FTS5 BM25和sqlite向量余弦搜索，并通过以下方式融合排名 互惠排名融合 （k=60）。前3个合并结果被注入为 `` 背景。

钩子是通过以下方式自动安装的 neuromcp-init-wiki 并注册于 UserPromptSubmit 在克劳德代码的 settings.json。在大型wiki更新后重新运行索引器（或安排它——它是幂等的）。

调谐：

已知上游问题

claude macOS上非TTY子进程的CLI流挂起 --如果您编写与以下对象的交互脚本 claude -p 从另一个进程（例如计划作业），通过管道传输 script -q /dev/null 以分配伪TTY。否则stdout缓冲区永远不会刷新。我们在必要时在整合商内部解决这个问题。

内存管理

命名空间 按项目、代理或域隔离内存。

信任级别 (high, medium, low, unverified)对搜索结果进行排序并控制抗衰减性。

软删除 墓碑记忆——可恢复30天。

内容哈希 （SHA-256）在写入时进行重复数据消除。

族系跟踪 记录每个内存的源、项目ID和代理ID。

配置

所有这些都是通过环境变量实现的。默认设置适用于大多数设置。

v0.9的新增功能

自动捕获（v0.9.0）

会话挂钩自动提取高信号事件——无需手动 store_memory 需要呼叫：

全流水线自动捕获（v0.9.1）

自动捕获的内存现在通过整个存储管道：数据消除、矛盾检测、嵌入、实体提取和声明——通过HTTP端点(POST /api/store).当HTTP不可用时，回退到原始SQL。

矛盾解决现在有三个层次：

• 取代 （得分>0.5）：旧记忆失效，新记忆接管
• 共存 （得分0.35–0.5）：两者都保留，通过链接 contradicts 知识图中的边
• 旗帜 （0.3-0.35分）：报告审查

解释模式（v0.9.2）

每 search_memory 结果包括 explain 字段：

{
  "explain": {
    "source_trust": { "level": "high", "reason": "Directly provided by user" },
    "temporal_validity": { "currently_valid": true, "superseded_by": null },
    "contradictions": [{ "memory_id": "abc", "content_preview": "...", "resolution": "coexist" }],
    "claims": [{ "subject": "neuromcp", "predicate": "version", "object": "0.9.2" }],
    "confidence": { "retrieval_score": 0.016, "source_trust_score": 1.0, "overall": 0.85 }
  }
}

我们发布了所有这些内容——模式版本、整合数学、评论输出、带有CI的基准数字——这样你就可以准确地审计系统记住了什么以及如何记住。如果另一个本地优先系统发布了相同或更好的内容，请链接welcome。

比较

许可证

AGPL-3.0 对于发动机 src/. 麻省理工学院 为了 bin/, templates/, scripts/, docs/，以及 examples/ （雕刻——见 LICENSE-EXAMPLES).

许可证常见问题

我可以在商业上使用neuromcp吗？ 对。将neuromcp作为你的一部分 在您自己的基础架构上，您自己的应用程序是不受限制的。仅限AGPL 如果你 修改 发动机代码AND 分配 或 主机 它作为一种网络服务。

我可以在我的闭源产品中从npm安装neuromcp吗？ 对。使用 作为依赖项发布的二进制文件不会触发AGPL传染。

如果我将neuromcp作为SaaS托管怎么办？ 那么AGPL第13条适用：你必须 用户可用的源代码（包括您的修改）。 这是我们为引擎选择的明确的反分叉条款——它停止了 资金充足的竞争对手不会拿走代码，把它放在登录后， 并将其作为自己的产品运输。

我可以复制CLI脚本或模板吗？ 对。一切都在 bin/, templates/, scripts/, docs/，以及 examples/ 双重许可 AGPL-3.0或MIT。在你的下游项目中选择麻省理工学院。

需要不同的发动机术语吗？ 商业双重许可证 可用--联系维护人员。