neuromcp

neuromcp — AI Agent 的自主记忆

任何模型。你的记忆。留在本地。

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

自主记忆 = 由你完全拥有、存储在你掌控的硬件上，并可在你使用的所有模型之间移植的数据。云记忆产品拥有你的数据；自主记忆意味着拥有者是你。

npx neuromcp-init   # one command: detects your MCP clients, writes configs, sets up the wiki

或者无需任何设置，直接运行基础服务：npx neuromcp。遇到问题？ npx neuromcp-doctor 一次运行即可诊断守护进程、Ollama、嵌入模型 和数据库。

内置记忆浏览器：命名空间中关联最多的实体及其关系，以可拖动、 缩放和点击的力导向图呈现——通过 localhost 提供服务，绝不来自 云端。参见记忆浏览器与 Obsidian。

为什么选择 neuromcp

大模型是商品。你的记忆才是护城河。 GPT-5、Claude 4、Gemini——它们都在趋同。你明年使用的模型会有所不同。你积累的每次对话、决策和偏好所形成的记忆都属于你。neuromcp 将这一层保留在你的设备上，并使其可在任何兼容 MCP 的客户端之间移植。

本地优先是设计选择，而非限制。 没有遥测。数据不会离开你的笔记本电脑。没有供应商留存你的对话副本。你可以审查每一行会接触你记忆的代码。SQLite + 本地嵌入模型；所有内容都能存放在一块磁盘上。

安装一次。适用于所有客户端。 Claude Desktop、Cursor、Windsurf、Codex CLI、Continue、LibreChat、Open WebUI——neuromcp 使用 MCP，因此只要支持 MCP 就能使用。明天换用其他模型，你的记忆也会随之而来。

真正的回忆，而非关键词匹配。 混合检索结合了向量搜索（nomic-embed-text，768 维）、BM25 全文搜索、图关系链接和经过学习的效用先验。在 LongMemEval 的 500 个干扰项条件下，R@5 仍达到 93.3%。你的上下文窗口会获取正确的记忆，而不只是最近的记忆。

LongMemEval-S 准确率

运行	得分	样本	配置
v7（当前）	96.08% (98/102)	n=102	Opus 生成器 + Opus 评审器，单模型
v6	95.10% (97/102)	n=102	与 v7 相同，使用先前的提示集

复现：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（6 个类别，每类 17 个）。98/102 的 Wilson 95% 置信区间约为 90.5–98.7%。在宣称达到“顶级”之前，下一项里程碑是使用相同配置完成完整的 500 道题运行。

基准测试（v0.18.0）

Oracle 划分（干净数据 — 简单模式）

模式	R@5	R@10	命中率
提取（混合）	100%	100%	100%

Oracle 划分的 LongMemEval 会在小型语料库中隔离出正确记忆。 每个本地 MCP 记忆系统在这里都宣称达到约 99%。它衡量的是 “排序器在干净输入上是否有效”——仅此而已。

干扰项拆分（v0.18.0，真实测试）

相同的 30 个问题 + 1000 条从其他问题的候选记忆中随机抽取的干扰记忆。正确记忆现在要与真实噪声竞争。

嵌入模型	干扰项	N	R@5	R@10	MRR
Ollama nomic-embed-text	0（预言机）	30	100%	100%	100%
Ollama nomic-embed-text	200	5	100%	100%	100%
Ollama nomic-embed-text	500	30	93.3%	93.3%	80.3%
Ollama nomic-embed-text	1000	5	100%	100%	74%

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

样本量。 500 个干扰项这一行的 n=30（28/30 的 Wilson 95% 置信区间：R@5 约为 78-99%）。1000 个干扰项这一行的 n=5——初步结果，Wilson 95% 置信区间为 [57%, 100%]。在单个 Ollama 实例上运行 1000 个干扰项、n=30 的测试约需 36 分钟；缓存干扰项批处理是 v0.19.0 的工作。500 个干扰项的数据具有参考价值，1000 个干扰项的数据方向积极但样本量不足。

正面对比明确列为 v0.19.0 的工作。 Hindsight（本地开源 MCP，声称 LongMemEval 得分约为 94.6%）以及 Mem0/Zep 都在各自的测试框架上公布了数据。在我们让它们在相同语料 + 嵌入模型上运行之前，把任何本地 MCP 服务称为“最先进”都是营销，而非测量。neuromcp 会公布数据并附上样本量说明，供你判断趋势；目前不要据此认定其绝对优越。

混合排序器（BM25 + 向量 + 注意力 + 图 + 实用性先验）在观测样本中，即使干扰项与目标记忆比例达到 1000:1，仍保持 R@5 = 100%。MRR 降至 74%，因为正确记忆有时并非排名第 1，但在观测结果中始终位于前 5。较早的 v0.18.0 数据（R@5 为 23%）来自 FakeEmbedder 测试——已在 v0.18.1 修复。

**此基准测试无法证明：**端到端答案正确性、长期多会话推理能力，或在 Mem0、Zep 自有基准测试上优于商业云系统。要进行这些比较，需要它们在相同干扰项拆分上的数据，而目前尚未公布。

原因

AI Agent 会在会话之间忘记一切。现有方案要么存储扁平的键值对（对真实知识毫无用处），要么需要云基础设施和 API 密钥。

neuromcp 为你提供两层记忆：

1. MCP 服务 — 混合搜索（向量 + 全文 + 图）、逐字回忆、记忆治理、自动整合，全部存储在一个 SQLite 文件中
2. Wiki 知识库 — 编译后的 Markdown 知识，可在崩溃后保留、随会话逐步积累，并在每次启动时为 Agent 提供了解项目上下文

灵感来自 Karpathy 的 LLM Wiki、Mastra 的 Observational Memory 和 Zep 的时序知识图谱——但比它们都简单。无需向量数据库、无需嵌入流程、无需云服务。只需 Markdown 文件 + Git + 钩子。

架构

~/.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 的工作方式

何时	会发生什么
会话开始时	钩子注入 index.md + 用户档案 + 自动检测到的项目页面（约 1300 个 token）
会话期间	大模型在学到需要长期保留的信息时更新 Wiki 页面
每 8 次工具调用	钩子提醒大模型更新 Wiki
会话结束时	钩子写入原始会话日志 + Git 自动提交所有 Wiki 变更
发生崩溃时	每 5 次工具调用就将检查点写入文件。可通过 Git 历史回滚。

自愈式整合流水线（v0.15.0+）

每隔约 4 小时，launchd 代理会运行 run-consolidation.sh，端到端协调以下四个步骤：

1. consolidate-sessions.py — 按项目批量处理原始会话，请 Claude 生成事实摘要，并对照原始来源核查事实。审计器标记出具体的无依据说法后，整合器现在会自动删除这些行并重新审计一次——这样，一句推测性陈述就不会再让整批内容作废。
2. rescue-rejected.py — 解析仍未通过的批次，移除无依据的说法，并将清理后的摘要追加到对应的 wiki 页面。这只是纯文本处理，不会调用大模型。
3. entity-linker.py — 为每个页面添加交叉链接：在 related: frontmatter 中加入对其他已注册实体（people/、projects/、systems/）的直接提及。无需单独的图数据库，就能让 wiki 像图谱一样运作。
4. 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

快速开始

一条命令（推荐）

npx neuromcp-init

检测已安装的 MCP 客户端（Claude Desktop、Claude Code、Cursor、Windsurf），将 neuromcp 条目写入各自的配置（并备份原配置），初始化 wiki 和钩子，并检查 Ollama 是否可用。--dry-run 可预览所有操作，不会写入任何内容。

对于图形界面客户端（Claude Desktop、Codex Desktop），请先进行永久安装：npm install -g neuromcp && neuromcp-init。只有永久安装后，初始化程序才能写入这些客户端所需的绝对 node 和脚本路径——如果使用裸 npx 缓存（可能会被垃圾回收），程序会有意退回到依赖 PATH 的 npx 配置，而图形界面客户端通常无法解析此配置。

手动步骤（init 的幕后操作）

1. 启动 MCP 服务

npx neuromcp

2. 初始化 wiki 和钩子（闭环归因的必需步骤）

npx neuromcp-init-wiki

此操作会创建 wiki 结构、安装钩子（Claude Code）和规则（其他编辑器），并自动完成所有配置。若不执行此步骤，npx neuromcp 仍会作为包含 46 个工具 的普通 MCP 服务运行，但用于闭合归因循环的评估器钩子不会安装——检索功能仍可用，但有用性评分永远不会累积。可安全地多次运行，不会覆盖已有配置。

编辑器兼容性

neuromcp 适用于任何兼容 MCP 的编辑器。集成分为两个等级：

功能	Claude Code	Cursor / Windsurf / Cline / Copilot / JetBrains / Zed
MCP 工具（46 个）	完整支持	完整支持
会话开始时提供上下文	钩子（自动）	规则（由大模型驱动，尽力而为）
会话结束时持久化	钩子（自动）	规则（由大模型驱动，尽力而为）
wiki 提醒	每 8 次工具调用	无
崩溃恢复检查点	有	无

通过原生钩子，Claude Code 可获得完整体验——上下文注入和持久化都会自动进行，即使大模型忘记执行也不受影响。

其他编辑器会获取规则文件，指示大模型在会话开始和结束时调用 neuromcp 工具。这取决于大模型是否遵循指令——实际使用效果良好，但不像钩子那样有保证。

# 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 Code）、jetbrains、zed

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

ollama pull nomic-embed-text

neuromcp 会自动检测，无需配置。

非英语记忆：使用多语言嵌入模型

nomic-embed-text 以英语为中心。在一个真实的荷兰语记忆库（2,402 条记忆、40 个荷兰语改写查询、15 个无关查询）中，它仅有 2.5% 的概率能在前 5 条结果中找到正确记忆，而且无关查询的得分高于真正的匹配项。在同一数据上使用 bge-m3（多语言，1024 维）：

嵌入模型	Recall@5	MRR@10	相关项与无关项可区分（AUROC）
nomic-embed-text	2.5%	0.03	0.08
bge-m3	65%	0.47	0.99

要切换现有安装：

ollama pull bge-m3
npx neuromcp-reembed                 # dry run on a copy
npx neuromcp-reembed --apply         # rebuild the index (keeps a backup)

设置 NEUROMCP_EMBEDDING_MODEL=bge-m3 后运行重新嵌入。此后，所有采用默认 auto 设置的客户端都会使用构建索引时所用的模型，因此无需进行其他配置。使用 bge-m3 时，search_memory 还会应用经过校准的相关性下限（0.45），让无关查询返回空结果，而不是噪声；关键词（FTS）和知识图谱命中项始终会通过。

对于非英语记忆，请将 NEUROMCP_RERANKER=none 保持不变：捆绑的交叉编码器（ms-marco-MiniLM-L-6-v2）仅支持英语，在上述荷兰语基准测试中会让 MRR 从 0.46 降至 0.18。

升级

npm install -g neuromcp@latest
npx neuromcp-init-wiki        # updates installed hooks; safe to re-run
npx neuromcp-doctor check     # confirms hooks, daemon and embeddings

neuromcp-init-wiki 只会复制一次 Claude Code 钩子；在 0.30.0 之前，它之后不会再处理这些钩子，因此钩子的修复无法更新已有安装。现在重新运行它会更新所有未修改过的旧版 neuromcp 钩子（每个钩子旁都会保留备份）、将旧的 .js 钩子迁移为 .cjs（并在旧路径留下转发存根），同时保留你编辑过的钩子——它会列出这些钩子，而 --update-hooks 会一并替换它们。neuromcp-doctor check 会报告过时的钩子。

安装

最可靠的方式是 npm install -g neuromcp && neuromcp-init——它会将下面的条目写入每个检测到的客户端配置中（并事先创建备份）。请从永久安装位置运行 init，不要直接通过 npx 运行：从 npx 缓存运行时，它会有意退回到依赖 PATH 的条目，而图形界面客户端通常无法解析该条目。手动配置方式如下：

Claude Code

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

这里可以使用 npx，因为 Claude Code 从终端运行，并会继承你的 PATH。

Claude Desktop / Codex Desktop / 任意图形界面客户端

图形界面应用由窗口管理器启动，而非登录 shell，因此它们继承的 PATH 很精简，通常既没有 node 也没有 npx（nvm、fnm、Volta 和 Homebrew 的安装位置都不在 /usr/bin）。请使用绝对路径——从 0.29.3 起，neuromcp-init 正是这样写入配置的：

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "neuromcp": {
      "command": "/opt/homebrew/opt/node@22/bin/node",
      "args": ["/opt/homebrew/lib/node_modules/neuromcp/bin/neuromcp.mjs"]
    }
  }
}

使用以下命令查找你自己的两个路径：

which node                      # → "command"
npm root -g                     # → "args": ["<that>/neuromcp/bin/neuromcp.mjs"]

（bin/neuromcp.mjs 保留了 #!/usr/bin/env node shebang，因此仍可直接在终端运行。）

Cursor / Windsurf / Cline

格式相同——将配置添加到编辑器的 MCP 设置中。每种客户端的可直接复制粘贴配置都位于 examples/。

共享守护进程（运行多个客户端时推荐）

默认情况下，每个客户端都会启动自己的 neuromcp 进程。改用一个共享的后台守护进程即可为所有客户端提供服务——只需一个数据库连接、一条嵌入处理流水线，也无需每个客户端冷启动：

npx neuromcp-enable-daemon --port 3200   # macOS launchd agent; verify with: curl -s http://127.0.0.1:3200/health

然后将客户端指向守护进程：

// Claude Code (~/.claude.json) — native HTTP transport
{ "neuromcp": { "type": "http", "url": "http://127.0.0.1:3200/mcp" } }

// Claude Desktop — stdio-only, bridge via neuromcp-connect.
// The bridge waits for the daemon on cold boot (plain mcp-remote exits
// fatally when the client starts before the daemon has bound its port,
// leaving a permanent "Server disconnected").
{ "neuromcp": { "command": "npx", "args": ["-y", "--package=neuromcp", "neuromcp-connect", "http://127.0.0.1:3200/mcp"] } }

守护进程仅绑定到环回地址，会拒绝不在允许列表中的 Host 和 Origin 请求头（防御 DNS 重绑定），并且按设计在此边界内不进行身份验证。卸载：npx neuromcp-enable-daemon --uninstall。

平台支持

组件	macOS	Linux	Windows
MCP 服务（stdio + HTTP）	✅	✅（CI）	⚠️ 未经测试——原生依赖附带 win-x64 预构建版本，欢迎提交报告
共享守护进程自动启动（enable-daemon）	✅ launchd	手动配置 systemd	❌
自动整合（enable-consolidation）	✅ launchd	cron 片段	❌
Claude Code 钩子	✅	✅	⚠️ 未经测试

按项目隔离

// .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"
      }
    }
  }
}

记忆浏览器与 Obsidian

看不到的记忆，就无法信任。neuromcp 提供两种方式来查看你的 Agent 实际掌握的内容——两者都在本地运行，且都为只读。

内置 Web 视图

运行共享守护进程后，打开 http://127.0.0.1:<port>/ui（默认端口为 3200）：

• 图谱 — 以力导向画布展示命名空间中的顶层实体及其关系。拖动节点、滚动缩放、点击节点，即可列出与其关联的记忆（仅显示当前记忆；已被取代的记忆默认隐藏，除非你主动查询）。
• 时间线 — 输入主题，查看关于该主题的事实如何随时间演变，包括哪条记忆取代了哪条记忆。

此 UI 是一个不含外部资源的单页应用（采用严格的 CSP，不使用 CDN），且仅通过回环地址提供服务：将守护进程绑定到非回环主机后，/ui 和 /api/* 路由将全部停用。

Wiki 的 Obsidian 图谱

Wiki（~/.neuromcp/wiki）是纯 Markdown，因此可以直接作为 Obsidian 仓库打开。Obsidian 根据 [[wikilinks]] 绘制图谱，而 neuromcp 将关系保存在 frontmatter 中，因此请运行一次桥接程序（幂等，支持 --dry-run）：

npx neuromcp-obsidian-bridge

neuromcp-init-wiki 还会创建最精简的 wiki/.obsidian/（按页面类型分组着色，不含插件）——仅当该目录不存在时；绝不会修改现有仓库设置。详情：docs/OBSIDIAN.md。

MCP 能力

涵盖 8 个类别的 46 个工具 — 完整的自动生成参考文档（包含每个参数）位于 docs/TOOLS.md（每次变更时都会根据实际注册信息重新生成；CI 会在文档不一致时失败）。

类别	工具数	亮点
核心记忆	11	store_memory（去重 + 矛盾检测 + 意外度评分）、search_memory（混合 RRF + 解释元数据）、recall_answer（通过差距分析生成带引用的摘录式回答）、search_all
知识图谱	6	create_entity、create_relation、query_graph、compute_centrality（PageRank）
事件	10	start_episode/end_episode、聚类、memory_timeline
多 Agent	9	register_agent、find_expert、审核队列、记忆传递
原文存储	3	对原始文本进行精确回忆 FTS，从不概括或清理
Wiki	3	wiki_ingest、wiki_lint、wiki_briefing
归因与实用性	3	log_retrieval、cite_memories — 补全实用性先验闭环
反思	1	generate_reflection

选择合适的检索工具： search_memory 返回经过排序的原始记忆；recall_answer 综合生成带引用的摘录式回答（或如实返回 not_in_memory）；recall_memory 是不带语义处理的普通 ID/筛选条件查询；search_all 会将原文存储纳入检索范围。

资源（13）

URI	说明
memory://stats	全局统计信息
memory://recent	最近的 20 条记忆
memory://namespaces	所有命名空间及其计数
memory://health	服务健康状态 + 指标
memory://stats/{namespace}	各命名空间的统计信息
memory://recent/{namespace}	命名空间中的近期记忆
memory://id/{id}	按 ID 获取单条记忆
memory://tag/{tag}	按标签获取记忆
memory://namespace/{ns}	命名空间中的全部内容
memory://consolidation/log	最近的整合条目
memory://operations	正在进行或最近的操作

提示词（3）

提示词	说明
memory_context_for_task	搜索相关记忆并将其整理为大模型上下文
review_memory_candidate	显示候选记忆及其近似重复项
consolidation_dry_run	预览整合操作，不实际应用

Wiki 知识库

Wiki 是经过整理、便于人阅读的知识层。它用结构化、相互关联的 Markdown 页面，取代杂乱的会话日志。

为什么用 Wiki，而不是继续增加向量搜索？

传统 RAG	neuromcp Wiki
每次查询都重新推导答案	知识只编译一次，并随时间不断完善
分块伪影、检索噪声	带有来源引用、便于阅读的页面
向量数据库、嵌入流水线	纯 Markdown + Git
黑盒检索	可审计、可编辑、可移植
知识逐渐消失	知识不断积累

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 次工具就会收到提醒

你也可以手动浏览和编辑 Wiki——它只是一些 Markdown 文件。

自动整合（可选）

积累原始会话日志后，可以自动保持 Wiki 内容更新。定时任务会读取尚未处理的会话，按项目分组（通过检测会话内容中的 $HOME/projects/<name> 路径），并使用 claude CLI 将 ## [date] 条目综合写入相应的 Wiki 页面。

npx neuromcp-enable-consolidation

安装内容：

• ~/.neuromcp/scripts/consolidate-sessions.py — 工作程序
• ~/.neuromcp/scripts/run-consolidation.sh — 带阈值保护的运行脚本
• macOS：每 4 小时运行一次的 launchd 代理（com.neuromcp.consolidate）
• Linux：输出一段供手动添加的 cron 配置

要求：

• PATH 中有 python3 ≥ 3.8
• PATH 中有 claude CLI

内置保护机制：

• 阈值：未处理的会话少于 5 个时跳过
• 从围栏 Markdown 代码块中提取输出；拒绝道歉或叙述性文本
• 清单（~/.neuromcp/consolidation-ledger.json）确保重复运行具有幂等性
• 自动分批处理积压量较大的项目（每次调用 claude 默认处理 15 个会话；可通过 --max-sessions 覆盖）

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

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

幻觉防护（eval-loop）。 每次整合器输出都会先经过第二个 Haiku 审核，然后才会写入 Wiki。如果生成摘要中的任何事实性声明无法追溯到原始会话，该部分内容就会进入 ~/.neuromcp/review-queue/，而不是 Wiki。不会有幻觉声明混入其中。

支持时间性取代的原子事实。 摘要获批后，还会被提炼为简短、独立的事实，并以 category='fact' 的行存储，valid_from=today。当新事实与同一项目中的现有事实具有较高 Jaccard 相似度时，Haiku 会判断新事实是否取代旧事实；如果是，旧行就会设置 superseded_by_id 和 valid_to。检索默认只使用当前事实（superseded_by_id IS NULL），因此过时的结论不会再次出现。

自动检索 + 混合索引

知识库内容就绪后，将其设为可搜索，这样 UserPromptSubmit 钩子就能自动显示相关页面（无需再让“大模型必须记得调用 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 → OpenAI → ONNX）生成嵌入，因此也支持向量搜索。

在提示时，neuromcp-auto-retrieve.js 钩子会调用 neuromcp-query，并行执行 FTS5 BM25 和 sqlite-vec 余弦搜索，再通过倒数排名融合（k=60）合并排名。合并后的前三条结果会作为 <neuromcp-recall> 上下文注入。

neuromcp-init-wiki 会自动安装该钩子，并将其注册到 Claude Code 的 settings.json 中的 UserPromptSubmit 下。对知识库进行大量更新后，请重新运行索引器（也可以安排定期运行——该操作是幂等的）。

调优：

环境变量	默认值	用途
NEUROMCP_BM25_THRESHOLD	-1.0	值越严格（越负）= 较弱的关键词匹配越少
NEUROMCP_QUERY_BIN	自动检测	覆盖 neuromcp-query 二进制文件的路径
NEUROMCP_NO_EMBED	0	设为 1 可强制仅使用 FTS 建立索引
NEUROMCP_CONTRADICTION_CHECK	1	设为 0 可跳过 Haiku 的替代判断
NEUROMCP_AUDIT_FAIL_OPEN	0	设为 1 可在基础设施故障时绕过整合器审计（默认故障时关闭）

已知的上游问题

memories_vec 在 DELETE 后不会回收空间 — sqlite-vec #54 / #265。编辑知识库章节后重新建立索引时，旧的向量行会被标记为已删除，但其存储空间仍会保留。数据库文件会持续增大，直到运行 npx neuromcp-index-wiki --rebuild，该命令会删除并重新创建向量行。如果你经常编辑知识库，请每隔几周执行一次重建。

在 macOS 上，从非 TTY 子进程调用 claude CLI 会导致流式传输挂起 — 如果你从另一个进程（例如计划任务）通过脚本调用 claude -p，请通过 script -q /dev/null 管道传输，以分配伪 TTY。否则 stdout 缓冲区永远不会刷新。我们已在必要时于整合器内部对此进行规避。

记忆治理

命名空间按项目、Agent 或领域隔离记忆。

信任级别（high、medium、low、unverified）为搜索结果排序，并控制其抵抗衰减的能力。

软删除会为记忆添加墓碑标记——可在 30 天内恢复。

内容哈希（SHA-256）会在写入时进行去重。

溯源跟踪会记录每条记忆的来源、项目 ID 和 Agent ID。

配置

所有配置均通过环境变量完成。默认值适用于大多数设置。

变量	默认值	描述
NEUROMCP_DB_PATH	~/.neuromcp/memory.db	数据库文件路径
NEUROMCP_EMBEDDING_PROVIDER	auto	auto、onnx、ollama、openai
NEUROMCP_DEFAULT_NAMESPACE	default	默认命名空间
NEUROMCP_AUTO_CONSOLIDATE	false	启用定期整合
NEUROMCP_TOMBSTONE_TTL_DAYS	30	永久清理前的天数
NEUROMCP_LOG_LEVEL	info	debug、info、warn、error
NEUROMCP_MODEL_DIR	~/.neuromcp/models	缓存 ONNX 备用模型的位置
NEUROMCP_DISABLE_MODEL_DOWNLOAD	未设置	1 禁止首次运行时按需下载模型
NEUROMCP_STRICT_EMBEDDINGS	未设置	1 = 索引与提供方不匹配时直接崩溃，而不是以降级模式启动
NEUROMCP_EMBEDDING_RETRY_ATTEMPTS	3	降级前遍历提供方级联的次数
NEUROMCP_EMBEDDING_RETRY_BASE_MS	500	首次退避延迟（每次尝试翻倍）

更新内容

完整历史记录见 CHANGELOG.md。近期亮点：

• v0.29 — 处处应用当前有效性：默认情况下，所有读取路径都会隐藏已被取代的记忆（可通过 include_superseded / valid_at 选择启用）；内置网页记忆浏览器，包含力导向图和时间线；Obsidian 桥接和非破坏性知识库初始化；修复冷启动竞态（守护进程在进程启动时绑定端口）；neuromcp-doctor 和 neuromcp-connect 会在其配置的端口上查找守护进程；切换嵌入提供方不再导致现有数据库无法使用（neuromcp-reembed、降级模式）；通过 Trusted Publishing 发布 npm 包（无需令牌）；图谱概览不再被系统自身的矛盾处理机制污染。
• v0.28 — neuromcp-init 一键设置（检测客户端、写入配置并备份）；将 neuromcp-doctor 重建为真正的故障分诊工具；自动生成 docs/TOOLS.md + docs/BENCHMARK.md；提供 examples/ 客户端配置；在存储时下推命名空间过滤；实体前缀合并现在需要证据。
• v0.27 — 安全版本：修复 wiki_ingest 中的 CWE-22 路径遍历问题；守护进程对 MCP 规范中的 Origin 进行验证；neuromcp-connect 提供可安全应对启动竞态的 Claude Desktop 桥接；新增运行时健康检查钩子。
• v0.26 — recall_answer（使用确定性抽取式回答并提供引用 + 差距分析，不在读取路径上调用大模型）；可选的本地交叉编码器重排器（经如实的 A/B 测试后默认关闭）；修正召回质量。
• v0.20–0.25 — 共享 HTTP 守护进程、会话隔离、批评器钩子、实体去重规范化、干扰项基准测试强化。

解释模式

每个 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.26.0" }],
    "confidence": { "retrieval_score": 0.016, "source_trust_score": 1.0, "overall": 0.85 }
  }
}

矛盾解决分为三个层级，其中涉及图谱的两个层级都需要声明级证据——主体相同、谓词互斥（is、uses、runs 等；参见 src/config/predicate-classes.json）、对象不同：取代（证据 + 启发式评分 > 0.5：旧记忆失效）、共存（证据 + 评分位于 (0.3, 0.5]：两者都保留，并通过 contradicts 图谱边关联）、标记（仅启发式信号——数值差异、否定词——在 store_memory 结果中报告以供审查，绝不写入图谱）。仅凭关键词启发式永远不能使记忆失效或断言存在矛盾：错误的判断会成为所有下游大模型的幻觉来源。

故障排除

npx neuromcp-doctor check          # human-readable report
npx neuromcp-doctor check --json   # same checks, machine-readable

一次运行即可检查：Node 版本、原生模块是否确实可加载（better-sqlite3、sqlite-vec）、数据库是否可打开、共享守护进程的 /health、Ollama 是否可连接且是否已拉取 nomic-embed-text、ONNX 回退模型是否存在，以及数据库中的向量索引是否仍与此机器可连接的提供方匹配。退出代码：0 表示正常，1 表示降级（例如没有 Ollama，正在使用 ONNX 回退），2 表示故障。提交任何错误报告前，请先附上其输出。

“嵌入维度不匹配”／向量搜索不可用

向量索引是宽度固定的 vec0 表：ONNX 回退时为 384，Ollama 的 nomic-embed-text 为 768。如果提供方发生变化（你在使用回退方案运行后安装了 Ollama，或者 Ollama 不可用，导致 auto 级联回退到 ONNX），新的提供方就无法写入旧索引。

从 0.29.3 开始，这不再会导致服务无法启动。它会：

1. 优先选择与现有索引匹配的提供方，
2. 对短暂不可用的提供方进行重试，并采用退避策略，
3. 否则以降级模式启动——全文搜索仍可用，向量搜索会被禁用，新记忆将不带嵌入内容存储，并排队等待 backfill_embeddings。不会删除任何内容，也绝不会在你不知情时重建索引。

neuromcp-doctor check 会指出当前状态。要恢复向量搜索，可任选一种方案：

# a) restore the provider that matches the index
ollama serve && ollama pull nomic-embed-text      # 768-dim index
# or force the fallback for a 384-dim index:
export NEUROMCP_EMBEDDING_PROVIDER=onnx

# b) rebuild the index for the provider you want (works on a COPY first)
npx neuromcp-reembed                 # dry run: rebuild a copy, report, discard
npx neuromcp-reembed --keep-copy     # same, but keep the copy to inspect
npx neuromcp-reembed --apply         # swap it in; original kept as *.pre-reembed-<ts>

执行 --apply 前，请停止所有客户端。回滚只需将文件移回原位。

不使用 Xcode / 禁用安装脚本时的安装方式

better-sqlite3 通过其安装脚本获取预编译二进制文件。 使用 npm install --ignore-scripts（或经过强化的 .npmrc，或 pnpm 的 构建许可列表）时，软件包虽然可以安装，但没有原生绑定， 因此无法正常工作。npm 11 默认设置为 ignore-scripts=false，所以直接 安装即可：

npm install -g neuromcp                      # normal path, scripts run
npm install -g neuromcp --ignore-scripts=false   # if your .npmrc disables them

如果你已经在禁用脚本的情况下完成安装，请按上述方式重新安装（在全局 前缀中直接运行 npm rebuild 并不能可靠地生成绑定）。

约 33 MB 的 ONNX 备用模型不再依赖 postinstall：它会在首次使用时 延迟下载到 ~/.neuromcp/models （即使软件包位于 root 所有的全局前缀中，用户仍可写入此目录）。你可以 运行 npx neuromcp-download-model 提前下载，也可以通过 NEUROMCP_DISABLE_MODEL_DOWNLOAD=1 完全禁止下载。

对比

功能	neuromcp	Hindsight	Mem0	Letta/MemGPT	agentmemory
LongMemEval R@5（oracle）	99.8%	—	—	—	—
LongMemEval R@5（1000 个干扰项，n=5，Ollama）	100%（初步结果，CI [57%, 100%]）	未公布	未公布	未公布	未公布
搜索	混合（向量 + FTS + RRF + 图）	向量 + 重排序	向量	向量	向量
自动捕获	确定性（无大模型成本）	大模型提取	否	Agent 自行编辑	是
解释模式	是（信任度、矛盾、声明）	否	否	否	否
知识图谱	实体、关系、PageRank	实体 + 信念	否	否	否
矛盾检测	三级（取代/共存/标记）+ 图边	信念更新	否	否	否
时效性	记忆和关系上的 valid_from/valid_to	是	否	否	否
Wiki 知识库	编译后的 Markdown + Git	否	否	分层区块	否
本地优先	SQLite，无云服务	SQLite	云服务 / Postgres	服务端	本地
嵌入	内置 ONNX（零配置）+ Ollama	外部	外部 API	外部	外部
治理	命名空间、信任级别、软删除	命名空间	API 密钥	按 Agent 划分	跨 Agent
基础设施	无	无	云账户	服务端	无
定价	免费（AGPL-3.0）	免费（MIT）	免费增值（获 2390 万美元融资）	免费（获 1000 万美元融资）	免费（Apache-2.0）

许可证

src/ 中的引擎采用 AGPL-3.0 许可证。bin/、templates/、 scripts/、docs/ 和 examples/ 采用 MIT 许可证（例外条款——参见 LICENSE-EXAMPLES）。

许可证常见问题

我可以将 neuromcp 用于商业用途吗？ 可以。在你自己的基础设施上将 neuromcp 作为自己应用的一部分运行，不受限制。AGPL 仅在你修改引擎代码 并且分发该代码或将其托管为网络服务时才会产生义务。

我可以在闭源产品中通过 npm 安装 neuromcp 吗？ 可以。将已发布的 二进制文件用作依赖项不会触发 AGPL 的传染效应。

如果我将 neuromcp 托管为 SaaS 服务呢？ 此时适用 AGPL §13：你必须向 用户提供源代码（包括你的修改）。这是我们为引擎选择的明确反分叉条款， 旨在阻止资金充足的竞争对手拿走代码、将其置于登录墙之后，并作为自己的产品发布。

我可以复制 CLI 脚本或模板吗？ 可以。bin/、 templates/、scripts/、docs/ 和 examples/ 中的所有内容均采用 AGPL-3.0 或 MIT 双重许可。在你的下游项目中选择 MIT 许可证即可。

需要为引擎使用不同的条款吗？ 可提供商业双重许可——请联系维护者。