mcp-memory-graph

MCP Memory Graph

适用于 Claude Code 及其他任何 MCP 客户端的记忆服务。它为 AI 助手提供永久、可搜索的记忆，存储在你电脑上的一个 SQLite 文件中。今天记录一项决定，下个月询问，便能得到答案。一切都在本地运行：嵌入模型、搜索索引和知识图谱。无需云账户、API 密钥，也没有按 token 计费。

**许可证：**源代码可见，非商业用途免费（PolyForm Noncommercial 1.0.0）：个人项目、爱好、学习、研究、慈善、教育和政府用途。商业用途需要付费许可证（COMMERCIAL.md）。

**适用对象：**希望 Claude（或 Cursor、Codex 及任何 MCP 客户端）能跨会话记住决策的开发者。个人开发者和业余爱好者可以免费使用。团队可以通过 git 共享知识库。也适合任何希望用完全运行在自己电脑上的工具，替代云端记忆服务（mem0、Zep、Letta、Supermemory）的人。

效果一览

运行 npx mcp-memory-graph serve，即可获得一个本地 Web 控制面板，在 Claude 之外浏览和搜索记忆。

搜索依据含义，而非关键词。下面的查询（“我们如何处理付款”）可以找到 Stripe、GDPR 和 Postgres 相关笔记，即使它们都不包含这个短语——每条结果都会显示置信度评分和匹配类型徽标：

在一个表格中浏览和排序整个存储库——范围、类型、标签、质量评分，以及每条记忆被读取的次数：

对比

mem0、Zep、Letta 和 Supermemory 是 AI 记忆领域常见的名称，其中几个拥有开源核心。这个项目采用了不同的默认方式：数据不会离开你的设备，也无需运行任何基础设施。

	MCP Memory Graph	常见的托管记忆服务
运行位置	设备上的一个 SQLite 文件	托管云服务（有些也可自托管）
嵌入	Node 中的本地模型（MiniLM），无需 API 密钥	通常使用云端嵌入 API
每个 token 的费用	$0——不计量用量	按用量计费，或需要你运行服务器
额外基础设施	无	通常需要 Postgres/pgvector、Redis 或 Python 服务
Claude Code 集成	一流支持：hooks 自动捕获和检索	手动接入
基准测试	提交的语料库和运行器，可在本地复现	大多由项目自行报告

取舍很明确：单进程 SQLite 服务的容量上限是数十万条向量（见限制），而托管服务可以扩展到更大规模，无需你操心。如果你是独立开发者或小团队，想要私密、免费且无需运维的记忆功能，那么这个上限很少会是你最先遇到的问题。

为什么要做这个项目

AI 助手会在会话之间忘记所有内容。你的决策、习惯、上周二修复的 bug：对话一结束，就全都不见了。这个服务可以解决这个问题。

• 今天存储的知识，明天、下周乃至明年都能搜索到。
• 搜索依据的是含义，而不只是关键词。“合同通知期限”也能找到“90 天续约条款”。
• 它会自我改进。它会跟踪哪些内容被使用、评估质量、从会话中提取经验，并按计划清理自身。
• 它能保护隐私。本地嵌入，不调用云端 API，也不进行遥测。唯一例外是可选的 Stop hook：它会将会话记录发送给你本地安装的 Claude Code（claude -p），用于提取经验。你可以通过 review_on_stop: false 关闭此功能。
• 它适用于各种知识。工程师可以存储架构决策，律师可以存储合同模式，会计师可以存储审计流程。

快速开始（约 5 分钟）

你需要安装 Node.js 20 或更高版本，以及 Claude Code。

1. 获取服务。 从 npm 安装（最简单）：

npm install -g mcp-memory-graph

或者从源代码安装：

git clone https://github.com/YonasValentin/mcp-memory-graph.git
cd mcp-memory-graph
npm install
npm run build

2. 将服务注册到 Claude Code （可选——第 3 步中的 init 会为你在用户范围内完成此操作）：

# npm install:
claude mcp add memory-server -- npx -y mcp-memory-graph

# from source:
claude mcp add memory-server node /path/to/mcp-memory-graph/dist/index.js

3. 安装 hooks（推荐）：

npx mcp-memory-graph init

这条命令会完成所有配置：注册 MCP 服务（用户范围）、安装自动捕获和检索 hooks 及用法技能、写入配置，并安排每晚清理。请按提示操作，或传入 --yes 接受默认设置。（如果你自行管理 claude mcp，可使用 --no-register 跳过自动注册。）

4. 试用。 打开 Claude Code 会话并输入：

Remember this: we use Postgres for the main app database. Decided 2026-06-01,
because we need JSONB and full-text search in one place.

然后，在之后的某个会话中输入：

What database did we decide to use, and why?

Claude 会搜索其记忆，并根据存储的决策作答。整个流程就是这样。

5. 验证安装。 询问 Claude：

What memory tools do you have available?

它应该列出全部 51 个工具（45 个 memory_*、3 个 vault_*、3 个 core_memory_*）。

首次运行记忆工具时，会从 HuggingFace 下载嵌入模型（约 30 MB），并缓存到 ~/.cache/huggingface/。此后每次启动都是即时完成。

如需撤销所有更改：npx mcp-memory-graph uninstall。

升级

npm install -g mcp-memory-graph@latest   # or just let `npx -y mcp-memory-graph` pull it
npx mcp-memory-graph init                # re-run to refresh on-disk hooks + the nightly schedule

升级软件包会更新每次会话运行的代码（钩子、工具和服务），因此服务端修复会在下次运行工具时生效——无需为此做其他操作。

但软件包升级不会重写 init 之前写入的文件：settings.json 中的 Claude Code 钩子注册项，以及 macOS launchd plist ~/Library/LaunchAgents/com.mcp-memory.consolidate.plist。如果你在 2.6.3 之前安装，plist 中使用的是裸 node 命令，而 launchd 的最小 PATH 不包含 nvm，因此无法运行它——夜间整合任务就会悄无声息地一直没有触发。升级后重新运行一次 npx mcp-memory-graph init，以使用绝对 node 路径和输出日志重新生成该文件。随后确认任务能够运行：

launchctl start com.mcp-memory.consolidate
cat ~/.mcp-memory/consolidation.log      # should show a "Consolidation complete" report

若要清除任务未运行期间累积的冲突噪声，请运行：npx mcp-memory-graph consolidate。

简明说明其工作原理

存储记忆时，服务会使用在 Node.js 内运行的小型模型，将文本转换为向量（一组包含 384 个数字、用于表达文本含义的列表）。它还会为文本建立索引，以便进行关键词搜索。两者都存储在同一个 SQLite 文件中，默认路径为 ~/.mcp-memory/memory.db。

搜索时，服务会同时执行这两种搜索，合并排名，并返回带有置信度标签的最佳匹配结果。随后，第二个模型可以重新排列排名靠前的结果，以提高精确度（这就是重排序器；默认对 MCP 客户端启用，耗时约 200 ms）。

此外还有一个知识图谱：记忆会关联到实体，也会彼此关联，因此服务能够回答需要多次跳转才能解答的问题，例如“支付服务依赖什么？”。每晚的“梦境周期”会执行去重、重新评分、剪枝并报告知识缺口。

基准测试及其解读方式

下面的所有数据均在本地生成：使用真实的嵌入模型和生产环境处理程序，不进行网络访问。你可以在自己的机器上重新运行全部测试。

如果你不熟悉基准测试，先快速了解几个概念。黄金集是一组答案已预先确定的问题。Precision@1 用于判断排名第一的结果是否正确。Recall@5 用于判断正确答案是否出现在前 5 个结果中。MRR（平均倒数排名）会奖励正确答案排名靠前。重排序器是用于重新排列排名前 50 个结果的第二个模型；它速度较慢，但准确度明显更高。

本地黄金集

	precision@1	precision@3	MRR	search p95
混合（RRF）	0.563	0.750	0.704	~4 ms
+ cross-encoder 重排序（MCP 默认）	0.813	0.875	0.867	~230 ms

运行 npm run bench 即可复现。完整的方法说明、黄金集本身以及每个错误案例，都会输出并记录在 docs/BENCHMARKS.md 中。

规模

使用真实的嵌入模型和基于文件的 SQLite 数据库时，向量数量为 10,000 时，检索 p95 为 9.1 ms；向量数量为 50,000 时，为 30 ms。重排序步骤还会额外增加约 200 ms，且该耗时基本恒定。大多数记忆产品发布的都是自行报告的云端托管数据；这里的数据是在本地测量的，可通过已提交的语料库和运行程序复现。

公开基准测试

使用未经调优的设置（原版 MiniLM 嵌入器、生产级处理器、未做任何基准测试专属调整）运行四项公开记忆基准测试，在全部四项中均达到或超过 MemPalace：

基准测试	我们的结果	对比
LongMemEval-S	R@5 = 97.8%	对比已公布的 96.6%
ConvoMem	R@10 = 93.5%	对比 92.9%
LOCOMO	session R@10 = 82.2%，R@50 = 100%	对比 60.3% 的基线
MemBench	hit@5 = 78.7%	对比其经过调优的 80.3%

亲自运行：npm run bench:longmemeval、bench:locomo、bench:convomem、bench:membench。诚实的说明（重排器在哪些情况下有帮助、在哪些情况下会造成影响、MemBench 上的去重上限、黄金集大小方面的注意事项）见 docs/BENCHMARKS.md。

功能

核心功能

• 51 个 MCP 工具：CRUD 和检索、带置信度标签的知识图谱、自我纠正的写入门控、签名溯源与验证、带 SSRF 防护 Webhook 的事件总线、变更传播与顾问界面、可恢复的会话状态、专业知识档案、记忆分层、Obsidian 库往返同步，以及符合 GDPR 标准的遗忘和历史记录。完整列表见下文。
• 混合搜索：向量相似度（含义）加关键词匹配（精确词项），并通过 Reciprocal Rank Fusion 合并。rerank: true 会添加交叉编码器处理阶段。use_graph: true 会融合 HippoRAG Personalized PageRank 多跳评分。as_of: <timestamp> 可搜索图谱在过去某个时刻的状态。
• 本地嵌入：Transformers.js 在 Node.js 中运行 all-MiniLM-L6-v2（384 维）。无需 Python、云端 API 或 GPU。
• SQLite 存储：单个文件，使用 better-sqlite3，并搭配两个扩展：sqlite-vec 用于向量近邻搜索，FTS5 用于采用 BM25 排名的关键词搜索。
• 感知结构的分块：文本按段落拆分，Markdown 按标题拆分（每个块保留标题上下文），代码按函数和类边界拆分，法律文本按句子拆分。
• 作用域：将记忆整理到 global、project、user、team、department 中。
• 版本历史：每次更新都会保存前一个版本。完整记录谁在何时更改了什么。
• 时间衰减：可选的基于时间的评分，让近期记忆获得更高权重（指数或线性）。
• 置信度评分：每条结果都带有 0 到 1 的置信度，以及直观的标签（高、中、低）。
• 过期机制：有时效性的记忆可设置到期日期，并自动从搜索结果中移除。

自我改进

• 访问跟踪：每次搜索、获取和相关记忆调用都会记录所访问的记忆。
• 质量评分：根据访问频率、近期程度和内容信号，自动为每条记忆计算 importance_score 和 confidence_score。
• 学习提取：会话结束时，无头模式的 claude -p 会审查对话记录，并存储 0 至 5 条精选的学习内容。（这取代了旧的 type: "agent" Stop 钩子；该钩子在 macOS 上会静默失效，详见 anthropics/claude-code#39184。）
• 梦境周期：按计划或按需进行去重、重新评分、修剪、过期处理和知识缺口检测。
• 缺口检测：未返回结果的搜索会被记录，以便你了解缺少哪些知识。

Claude Code 钩子

通过 init 安装的五个可选钩子：

钩子	触发时机	功能
SessionStart	会话开始时	状态检查（记忆数量、过期内容、陈旧文档），并显示项目中排名靠前的记忆
UserPromptSubmit	每条包含任务信号（工单/PR ID 或 ≥2 个关键词）的提示词提交时	对存储内容进行关键词搜索，并显示匹配的记忆，帮助你回忆之前的工作，避免重新推导；对于简单提示词则保持静默
PostToolUse	记忆搜索后	将命中和未命中情况记录到 search-log.jsonl
PreCompact	上下文压缩前	可选的学习内容提取（默认关闭）
Stop	会话结束时	启动无头模式的 claude -p 来审查会话并保存所学内容

Stop 钩子会在约 30 毫秒内脱离，并在后台进行 10 到 60 秒的审查。需要 $PATH 中（或 $CLAUDE_BIN 指定）的 claude CLI，且已完成身份验证。要关闭此功能，请在 ~/.mcp-memory/config.json 中设置 review_on_stop: false。

每条记忆的元数据

字段	用途	示例
scope	隔离级别	global、project、user、team、department
namespace	子范围分组	"my-project"、"legal-team"、"q4-audit"
department	组织部门	legal、engineering、hr、sales、finance
document_type	内容分类	contract、policy、code、incident、decision、report
access_level	数据敏感级别	public、internal、confidential、restricted
tags	灵活分类	["renewal", "notice-period", "compliance"]
language	内容语言（ISO 639-1）	"en"、"da"、"de"
source	来源	文件路径、URL、系统名称
author	创建者	人员或系统名称
metadata	特定领域的 JSON	{contract_type: "NDA", parties: ["A","B"]}
expires_at	自动过期日期	ISO 8601 时间戳

scope 和 namespace 用于在单个数据库中对内容分组。共享数据库的 MCP_API_NAMESPACE 固定值支持按命名空间进行多租户隔离（schema v14）；为每个租户使用单独的数据库文件则能提供最强的隔离边界。参见 docs/MULTI-TENANCY.md。

知识图谱与双时态模型

• 双时态有效性：每条记忆都同时记录有效时间（valid_from、valid_to）和事务时间。更新会使旧记录失效，而非将其删除：旧事实会加上 valid_to 时间戳，而不是被覆盖，因此历史记录不会丢失。读取默认返回当前有效的记录，但也接受 as_of: <timestamp>，用于回溯指定时间点的记忆。memory_history 会返回单条记忆的完整时间线。
• 带置信度标签的链接：记忆通过 wikilink、共现和相似度边相连，每条边都带有置信度权重。memory_graph 最多遍历 3 跳的实体和关系。memory_extract_entities 会存储由大模型提取的实体和关系。
• HippoRAG 多跳检索：搜索中设置 use_graph: true 后，会在实体和链接图上运行 Personalized PageRank，以进行联想式检索。
• 基于令牌预算的回答：memory_query 会通过紧凑的子图回答问题。它以混合搜索结果为起点，在避开枢纽节点的同时遍历图，最多达到 max_hops，并返回受令牌预算限制的上下文字符串，而不是让窗口充斥信息。
• 社区：memory_communities 会查找连接紧密的实体集群，适用于“这里的主要主题是什么？”这类问题。

自我纠正写入

• 写入门控：存储操作会经过 ADD、UPDATE、DELETE 或 NOOP 决策（on_conflict），使新事实与已有事实协调，而不是不断累积重复内容。
• 矛盾检测：交叉编码器 NLI 模型会标记新传入的记忆是否与已存储内容矛盾。
• 遗忘曲线：记忆带有 stability 信号，因此很少得到强化的知识会在排序中逐渐下沉，就像人类记忆会逐渐消退一样。

Agent-OS 记忆

• 核心记忆块：每个 (scope, namespace) 对应一个小型、有边界且始终在上下文中的笔记，由 Agent 自行维护（core_memory_get、core_memory_append、core_memory_replace）。追加内容若会超出限制，则会被拒绝，从而促使有意识地精简内容。
• 层级：memory_tiers 会报告 MemGPT 式的热记忆／回忆／归档分布，并列出热记忆工作集。
• 反思：memory_reflect 会收集最值得反思的记忆；在存储模式下，会保存综合得出的见解，并将其关联回来源。

Obsidian 知识库

• 双向同步：vault_sync 会读取知识库。memory_export_vault 会将记忆写出为 .md 文件，并附带 YAML frontmatter，确保每个用户编写字段（id、scope、namespace、tags、access_level、importance、timestamps）都能无损往返。两个派生评分不包含在 frontmatter 中，重新导入时会重置：confidence_score（重置为 0.6）和 stability（重置为 1.0）。请使用 memory_export（JSON）进行逐字节完美备份。一个元数据键为保留键：metadata._vault 用于保存内部同步记录，不会出现在工具输出或导出的文件中。
• JSON Canvas：memory_canvas 会将图谱导出为 JSON Canvas 1.0 .canvas 文件，可在 Obsidian 中以空间看板形式打开。
• 只读 Wiki：serve 会将 /publish/:namespace（索引、页面、搜索、图谱）作为只读 Wiki 提供服务。它有意不启用 Bearer 身份验证，但会严格限定为已发布的访问级别（MCP_PUBLISH_ACCESS_LEVELS，默认为 public）。
• 会话笔记和模板：memory_session_note 会将内容追加到每个会话的一篇“每日笔记”中。memory_template 会根据文档类型返回结构化笔记框架。

团队与个人共享（git）

• memory init 向导：交互式设置（或使用 --yes 应用默认设置），写入 ~/.mcp-memory/config.json（或项目级配置）以及 Claude Code 接线配置。
• 可提交的图谱产物：memory export-graph 会生成确定性的 memory-graph.json，可提交并共享。memory git-setup 会安装 .gitattributes 条目和 memory-union 合并驱动程序，以便并行提交时进行合并，而不是产生冲突。
• 归属信息：设置 MCP_AGENT_ID（或在每次存储时传入 agent_id），然后 memory_attribution 会报告每个 Agent 写入的有效记忆数量。

信任与治理

• 待询问的问题：memory_questions 会展示图谱擅长发现的内容：待确认的模糊链接、频繁提及但文档不足的实体，以及孤立和过时的记忆。
• 符合 GDPR 级别要求的遗忘功能：memory_forget 默认软删除（通过 valid_to 创建墓碑，可恢复，且仍可通过 as_of 查看）。使用 hard: true 时，它会先返回可携带性导出，然后永久擦除数据。memory_delete 保持不变。
• 输出净化：每个工具结果都会经过统一检查点，在离开服务前清除 ANSI 和 VT 转义序列、控制字符，以及零宽字符或双向文本（BiDi）Trojan Source 欺骗字符。存储内容在静态存储时仍保持原始状态。
• 热重载：配置更改无需重启即可生效。

Web 仪表板

服务器提供浏览器仪表板，可在 Claude 外查看和管理记忆。仪表板运行在与 MCP HTTP 传输相同的 Express 服务器上，因此无需单独的进程。

共六个页面：

• 仪表板：显示记忆数量、内容大小、按范围、部门和类型划分的统计，以及最近更新的 10 条记忆。
• 搜索：提供带置信度和匹配类型徽标的混合搜索，并在输入时即时显示模糊匹配建议。
• 浏览：可排序、分页的全部记忆表格，支持按范围筛选并显示质量指标。
• 记忆详情：显示完整内容、元数据、版本历史和相关记忆，并支持行内编辑和删除。
• 知识图谱：D3 力导向视图。节点大小表示重要性，颜色表示范围。支持缩放、平移、拖动和双击导航。
• 工具：完整工具集的控制台。它会列出服务器公布的每个工具，根据各工具的架构生成表单，并通过经过身份验证的 MCP 端点运行工具。具有破坏性的工具会先要求确认。

技术栈：React 19、Vite、Tailwind CSS v4、shadcn/ui、Fuse.js、D3、Recharts。

运行：

# Development (hot reload)
npm run build && npm run serve   # Terminal 1: server on :3100
npm run dev:web                   # Terminal 2: Vite on :5173 (proxies /api to :3100)

# Production (single process)
npm run build:all                 # Builds server + frontend
npm run serve                     # http://localhost:3100 serves both API and UI

**Docker：**镜像中包含构建好的前端。运行 docker compose up 后，可通过 http://<host>:3200 访问仪表板，MCP 端点也位于此处。团队成员可以使用任意浏览器浏览共享存储，无需 Claude Code。

REST API（16 个端点）

REST 接口用于读取和管理。创建记忆通过 MCP 完成（通过 POST /mcp 调用 memory_store）；这里特意不提供 POST /api/memories。

方法	路径	说明
GET	/api/stats	记忆数量和分类统计
GET	/api/search?q=...	支持筛选条件的混合搜索
GET	/api/memories	分页并支持排序的列表
GET	/api/memories/:id	单条记忆及其元数据
GET	/api/memories/:id/versions	版本历史
GET	/api/memories/:id/related	语义相关的记忆
PATCH	/api/memories/:id	更新内容或元数据
DELETE	/api/memories/:id	删除记忆
GET	/api/graph	图可视化所需的节点和边
GET	/api/manifest	完整性清单（Merkle 根及每条记忆的哈希）
GET	/api/insights	趋势和主题摘要
GET	/api/health	知识缺口报告（反复出现的零结果搜索）
GET	/api/webhooks	列出 webhook 目标（由 MCP_WEBHOOKS 控制）
POST	/api/webhooks	注册经过 SSRF 验证的出站目标
DELETE	/api/webhooks/:id	移除 webhook 目标
POST	/api/webhooks/dispatch	清空持久化的 HMAC 签名投递队列

前九个端点供仪表板使用。所有 REST 端点都调用与 MCP 工具相同的处理程序，不会重复业务逻辑。

深入了解自我改进

服务器会跟踪知识的使用情况、评估质量、从会话中学习，并随着时间推移自行整合知识。

学习循环

 ┌──────────────────────────────────────────────────────────┐
 │                    SESSION                                │
 │  Claude searches → access_count++ on matched memories     │
 │  Claude stores   → new memory with initial scores         │
 │  Zero results    → knowledge gap recorded                 │
 └─────────────┬────────────────────────────────────────────┘
               │
               ▼
 ┌──────────────────────────────────────────────────────────┐
 │            SESSION END (Stop command hook)                │
 │  Hook spawns detached `claude -p` headless review         │
 │  --allowedTools restricts to memory_store only            │
 │  Claude judges → 0-5 curated entries via memory_store     │
 │  Deduplicates against existing memories                   │
 └─────────────┬────────────────────────────────────────────┘
               │
               ▼
 ┌──────────────────────────────────────────────────────────┐
 │              DREAM CYCLE (nightly or manual)              │
 │  1. Score    : Recalculate importance from access data    │
 │  2. Expire   : Enforce expiration dates                   │
 │  3. Prune    : Remove low-quality, never-accessed items   │
 │  4. Dedup    : Merge near-duplicate memories              │
 │  5. Gaps     : Surface zero-result search patterns        │
 └──────────────────────────────────────────────────────────┘

质量评分

每条记忆都会获得一个介于 0 和 1 之间的 importance_score：

importance = 0.3 * current_score + 0.4 * normalized_access_frequency + 0.3 * recency_factor

时效性系数：

年龄	系数
< 7 天	1.0
< 30 天	0.7
< 90 天	0.4
> 90 天	0.1

从未被访问的记忆会逐渐降低重要性。自动提取的记忆初始评分较低，如果始终未证明有用，就会被清理。

**访问强化说明。**上面的公式是整合流程中 Score 阶段定期重新计算的结果。每次读取（memory_get、memory_search、memory_related）也会立即小幅提升评分（importance_score += 0.03，最高为 1.0），搜索则会将重要性作为轻微的排名乘数（1 + importance * 0.5）。仅通过读取，一条被读取 20 次或更多的记忆就会接近上限；下次运行整合流程时会重新设定基准。这种基于热度的加权是有意为之。如果希望评分固定，不随读取而变化，可在 memory_store 或 memory_update 中设置明确的 importance_score。

知识缺口检测

搜索没有结果时，查询会被记录。梦境周期的缺口阶段会呈现这些记录，让你了解存储中缺少什么。

安装参考

前提条件

• Node.js 20+，适用于任何客户端。
• MCP 客户端。 Claude Code 提供一流体验；自动捕获和回忆钩子仅适用于 Claude Code。其他 MCP 客户端（Codex、Cursor 等）可以使用全部 51 个工具，但需要手动驱动。请参阅下文“其他 MCP 客户端”。
• 仅适用于 Stop 钩子： $PATH（或 $CLAUDE_BIN）中有 claude 二进制文件，且已完成身份验证，无需提示。此项为可选；设置 review_on_stop: false 可禁用。

init 的作用

npx mcp-memory-graph init                  # user scope: hooks apply to all projects
npx mcp-memory-graph init --scope project  # this project only

用户范围会将钩子写入 ~/.claude/settings.json，使其在每个 Claude Code 会话中触发。项目范围会将钩子写入当前目录下的 .claude/settings.json，并创建 .mcp.json 以自动发现服务；克隆项目的协作者会自动注册记忆服务。

Init 会执行七项操作：

1. 验证钩子脚本是否存在于 dist/hooks/ 中。
2. 在 settings.json 中注册五个钩子。
3. 使用合理的默认值创建配置文件：~/.mcp-memory/config.json（用户范围）或 <project>/.mcp-memory/config.json（项目范围；生成的 .mcp.json 通过 MCP_MEMORY_CONFIG_PATH 指定该文件）。
4. 将记忆使用说明写入 .claude/CLAUDE.md（项目范围），或打印一段说明（用户范围）。
5. 向 Claude Code 注册 MCP 服务——用户范围会替你运行 claude mcp add -s user memory-server -- npx -y mcp-memory-graph（幂等；尽力执行——如果 claude CLI 不在 $PATH 中，则会显示警告并提供手动命令；使用 --no-register 跳过）。项目范围则通过可提交的 .mcp.json 注册。这样，“快速开始”的第 2 步就变成可选步骤。
6. 将 mcp-memory-graph 使用技能安装到 ~/.claude/skills/，让 Claude Code 获得关于全部 51 个工具、注意事项和工作流的内联指导。使用 --no-skill 跳过。
7. 设置每晚整合计划（macOS：使用 launchd，并立即加载，无需重新登录即可运行；Linux：打印 cron 建议；项目范围不执行此操作）。

在非交互式 shell（Agent/CI）中会跳过向导：应用默认值，并打印报告，说明设置内容以及如何更改各项值。传入 --yes 会静默应用默认值（不生成报告）。

主要标志：--scope user|project、--schedule HH:MM[,HH:MM]（每晚整合时间，默认为 03:00）、--vault <path>（启用 Obsidian 知识库双向同步）、--no-review-on-stop（禁用会话结束时的学习回顾）、--no-skill（跳过技能安装）、--no-register（跳过用户范围的 claude mcp add）、--remote <url>（团队服务模式）。

npx mcp-memory-graph uninstall 会撤销 init 执行的所有操作：移除钩子、每晚计划、CLAUDE.md 区块以及已安装的技能。

无人值守设置（CI、配置、Agent）

每个步骤都可以通过脚本执行。不存在仅限交互式的路径：

git clone https://github.com/YonasValentin/mcp-memory-graph.git
cd mcp-memory-graph
npm install && npm run build
npx mcp-memory-graph init --scope project --yes   # local: hooks + .mcp.json, no prompts
# or point at a shared self-hosted server instead:
# npx mcp-memory-graph init --remote https://memory.example.com --token-env MEMORY_MCP_TOKEN

其他 MCP 客户端（Codex、Cursor 等）

Claude Code 使用钩子；其他客户端则使用相同的 51 个工具，但需要手动调用。该服务是标准 MCP 服务，因此任何客户端都能使用。在客户端的规则文件中添加一行指引，即可让使用过程近乎自动化。

注册服务。以下是 Codex 的示例，配置文件可以是 ~/.codex/config.toml（全局）或 .codex/config.toml（项目级，仅限受信任项目）：

[mcp_servers.memory-graph]
command = "node"
args = ["/abs/path/to/mcp-memory-graph/dist/index.js"]
tool_timeout_sec = 180   # the first call downloads the ~30 MB model once; the 60s default can be tight

[mcp_servers.memory-graph.env]
MCP_MEMORY_DB_PATH = "/abs/path/to/.mcp-memory/memory.db"

# or a shared self-hosted server over HTTP (see Self-hosting below):
# url = "https://memory.example.com/mcp"
# bearer_token_env_var = "MEMORY_MCP_TOKEN"

或者运行 codex mcp add memory-graph -- node /abs/path/to/mcp-memory-graph/dist/index.js。Cursor、Windsurf 和其他客户端使用各自的 MCP 配置格式，但服务命令（node .../dist/index.js）和 HTTP 选项相同。

然后在 Agent 的指令文件中添加提示（Codex：AGENTS.md；Cursor：项目规则）：

在回答有关架构、决策、模式或过往修复的问题前，先调用 memory-graph 服务上的 memory_search；使用 memory_store 保存新的决策、模式和修复。

自托管并共享知识库

该服务有三种运行方式，从单用户缓存到多台机器共享的知识库皆可。三种方式都以本地为先：数据不会离开你选择运行服务的机器。

1. 本地（单用户），默认方式

npx mcp-memory-graph init 会注册本地 stdio 服务和钩子。记忆数据保存在你机器上的一个 SQLite 文件中。无需运行其他组件。适合个人使用。

2. 共享服务（多台机器或团队）

运行一个服务，让多个客户端通过 HTTP 连接。所有人实时共享同一个知识库。

启动服务（任选一种）：

# From source: build the server (and the dashboard, if you want it) first
npm run build:all
MCP_AUTH_TOKEN=$(openssl rand -hex 32) MCP_BIND=0.0.0.0 npm run serve
# MCP at /mcp, REST at /api, dashboard at /, all on :3100

# Or with Docker (frontend included; publishes host port 3200 by default)
MCP_AUTH_TOKEN=$(openssl rand -hex 32) docker compose up -d

只要服务可通过回环地址以外的地址访问，就设置 MCP_AUTH_TOKEN。这是一个供所有客户端共用的 bearer token。若绑定到非回环地址但未进行身份验证，服务将拒绝启动，除非设置 MCP_AUTH_OPTIONAL=1。若要从主机外访问，请通过反向代理或隧道终止 TLS。

在每台机器上运行一条命令来连接客户端：

npx mcp-memory-graph init --remote https://memory.example.com --token-env MEMORY_MCP_TOKEN
export MEMORY_MCP_TOKEN=<the server token>     # in your shell or .env

对于 Claude Code，这会写入一个指向共享服务的项目 .mcp.json。令牌以环境变量引用的形式存储（"Authorization": "Bearer ${MEMORY_MCP_TOKEN}"），因此已提交的 .mcp.json 永远不会包含密钥。非 Claude 客户端通过各自的 MCP 配置连接到同一服务。

标志	作用
--token-env <NAME>	引用此环境变量作为令牌（默认值为 MEMORY_MCP_TOKEN）
--token <value>	直接写入字面令牌（避免将其提交）
--no-auth	不添加身份验证标头（仅限回环地址或受信任网络）

在远程模式下，不会安装本地捕获和回忆钩子。记忆数据保存在服务端，而不是钩子可读取的本地文件中。Agent 会直接使用 memory_search 和 memory_store（仍会写入 CLAUDE.md 指引）。

3. Git 仓库（异步、版本控制式共享）

想把知识库放在 Git 中，通过拉取请求审核，且无需运行服务？将记忆导出为纯 Markdown，并通过 Git 仓库共享该文件夹：

npx mcp-memory-graph vault-init                    # make the vault a git repo (union merge driver + rebuild hook)
git add -A && git commit -m "memory snapshot" && git push
# collaborators, once after cloning:
#   npx mcp-memory-graph vault-init                # registers the union merge driver + post-merge hook in THEIR clone
# collaborators, thereafter: git pull && npx mcp-memory-graph rebuild

每位协作者都必须在自己的克隆仓库中运行一次 vault-init。 合并驱动和合并后重建钩子位于本地 Git 配置（.git/）中，不在仓库里。未运行 vault-init 的全新克隆仓库，在首次并发拉取时会在 .memory/graph.json 中遇到原始冲突标记。重复运行 vault-init 不会造成问题，也不会覆盖已提交的旁文件。

团队知识库的两条恢复说明：

• 如果你手动解决了合并冲突（合并后钩子只会在无冲突合并时触发），memory rebuild 可能会因 .memory/manifest.json 过期而报错 VaultIntegrityError。删除该文件并重新运行 rebuild；它是派生状态，会自动重新生成。
• 如果你手动编辑了 .md 文件，但数据库中的状态更新，则应先导入（vault_sync 或 rebuild），再导出（memory sync）。如果数据库中的状态已过期，执行完整导出会覆盖知识库文件，包括你的手动编辑。

安全说明

• MCP_AUTH_TOKEN 是一个由可信群组共用的密钥；要轮换密钥，请使用新值重启服务。若要实现按密钥的 RBAC（一个服务、N 个密钥，每个密钥固定一组命名空间，并设定访问级别上限），请使用 memory keys create|list|revoke（schema v16）。旧版共享令牌仍可使用，且会优先检查。请参阅 docs/MULTI-TENANCY.md。
• 切勿提交令牌。--remote 默认会按设计将其保存在环境变量中。
• 除非在服务前部署一个负责终止 TLS 的代理，否则请绑定到 127.0.0.1（默认值）；若部署了代理，则设置 MCP_BIND=0.0.0.0。

正在构建组织级 AI 大脑？只需一个服务，为每位员工分配一个密钥，并构建一份 AI 可遍历的组织架构图（将人员、团队、SOP 和工具作为带类型的图节点），同时强制执行可见范围控制。基于现有基础功能的实现方案见 docs/ENTERPRISE-BRAIN.md。

配置

环境变量

变量	默认值	说明
MCP_MEMORY_DB_PATH	~/.mcp-memory/memory.db	数据库文件位置。目录会自动创建。
MCP_MEMORY_MODEL	Xenova/all-MiniLM-L6-v2	HuggingFace 嵌入模型名称。必须是与 Transformers.js 兼容的 ONNX 模型。
MCP_MEMORY_DIMENSIONS	384	嵌入向量维度。必须与模型的输出维度一致。
MCP_MEMORY_CONFIG_PATH	~/.mcp-memory/config.json	配置文件的自定义位置。

完整的环境变量参考（身份验证、速率限制、webhook、保险库、发布）见 docs/ENV.md。

自定义数据库位置

claude mcp add memory-server --env MCP_MEMORY_DB_PATH=/path/to/project/.memory.db node /path/to/dist/index.js

替代嵌入模型

# Swap the embedding model (same 384 dimensions; drop-in for the existing index
# AFTER a re-embed; see the warning below)
claude mcp add memory-server \
  --env MCP_MEMORY_MODEL=Xenova/bge-small-en-v1.5 \
  --env MCP_MEMORY_DIMENSIONS=384 \
  node /path/to/dist/index.js

会记录并强制校验模型身份。 数据库会记住用于构建它的嵌入模型（schema_meta.embedding_model）。如果使用不同的 MCP_MEMORY_MODEL 启动服务，会明确报错，而不会悄悄降低每次搜索的效果（维度相同不代表向量空间相同）。若要切换模型：设置新模型并运行 memory rebuild（从保险库重新生成嵌入），或导出后重新导入。

配置文件

配置文件用于控制自我改进行为、钩子设置和各项目的覆盖选项。解析顺序：先读取环境变量 MCP_MEMORY_CONFIG_PATH，然后是 <cwd>/.mcp-memory/config.json（项目级初始化会写入此文件），最后是 ~/.mcp-memory/config.json。运行 npx mcp-memory-graph init 可创建该文件，也可以手动编写：

{
  "defaults": {
    "scope": "project",
    "namespace": "auto"
  },
  "projects": [
    {
      "path": "~/Documents/MyApp",
      "namespace": "my-app",
      "watch": ["README.md", "docs/**/*.md"]
    }
  ],
  "consolidation": {
    "similarity_threshold": 0.85,
    "prune_after_days": 30,
    "min_importance_to_keep": 0.1,
    "max_operations": 100,
    "schedule": [
      { "hour": 11, "minute": 30 },
      { "hour": 16, "minute": 0 }
    ]
  },
  "hooks": {
    "extract_on_compact": false,
    "extract_on_session_end": false,
    "track_searches": true,
    "review_on_stop": true
  },
  "extraction": {
    "categories": ["decision", "pattern", "error_fix", "convention"],
    "min_confidence": 0.4
  }
}

部分	键	默认值	说明
defaults	scope	"project"	新记忆的默认范围
defaults	namespace	"auto"	默认命名空间（"auto" 根据项目目录名确定）
projects[]	path		项目根目录
projects[]	namespace		此项目的命名空间覆盖值
projects[]	watch		用于跟踪文件变更的 Glob 模式
consolidation	similarity_threshold	0.85	用于去重的余弦相似度阈值（0.5-1.0）
consolidation	prune_after_days	30	清除低质量记忆前的天数
consolidation	min_importance_to_keep	0.1	保留记忆所需的最低重要性分数
consolidation	max_operations	100	每次整合运行的最大操作数
consolidation	schedule	[{ "hour": 3, "minute": 0 }]	一个或多个 { hour, minute } 条目（24 小时制）。更改后重新运行 init，以重新生成 launchd plist。
hooks	extract_on_compact	false	压缩上下文前挖掘对话记录（基于正则表达式，默认关闭）
hooks	extract_on_session_end	false	会话结束时提取经验（基于正则表达式，默认关闭）
hooks	track_searches	true	将搜索命中和未命中记录到 search-log.jsonl
hooks	review_on_stop	true	会话结束时启动无头模式的 claude -p，以审查对话记录并保存经验。设为 false 可禁用此功能，但保留钩子。
extraction	categories	["decision", "pattern", "error_fix", "convention"]	要提取的经验类别
extraction	min_confidence	0.4	提取经验所需的最低置信度
storage	db_path	取决于范围	SQLite 文件位置（用户范围为 ~/.mcp-memory/memory.db，项目范围为 <project>/.mcp-memory/memory.db）。MCP_MEMORY_DB_PATH 可覆盖此设置。
vault	path	未设置	未显式传入路径时，vault_sync、memory_export_vault 和 rebuild 使用的 Obsidian 知识库根目录。MCP_VAULT_PATH 和 --vault <path> 可覆盖此设置。
vault	write_through	true	配置知识库后，将记忆写入同步到知识库，保存为 .md 文件。MCP_VAULT_WRITE_THROUGH=0 可覆盖此设置。

CLI 命令

命令	描述
npx mcp-memory-graph	通过 stdio 启动 MCP 服务（默认）
npx mcp-memory-graph serve	启动 HTTP 服务：MCP 传输、REST API、Web 控制面板
npx mcp-memory-graph init	交互式设置向导：钩子、配置、夜间计划（用户范围）。添加 --yes/-y 以非交互方式运行
npx mcp-memory-graph init --scope project	仅为当前项目设置（创建 .mcp.json 和 .claude/settings.json）
npx mcp-memory-graph uninstall	撤销 init：移除钩子和计划
npx mcp-memory-graph consolidate	手动运行梦境周期
npx mcp-memory-graph export-graph [--out <path>] [--scope <s>] [--namespace <n>]	写入可提交且确定性的 memory-graph.json，用于 git 共享
npx mcp-memory-graph git-setup	安装 .gitattributes 条目和 memory-union 合并驱动，以便无冲突地共享图
npx mcp-memory-graph merge-graphs <ours> <theirs> <out>	用于 memory-graph.json 的 Git union 合并驱动（由 git 调用，而非手动调用）
npx mcp-memory-graph vault-init [--vault <path>]	将 vault 初始化为 git 仓库：配置 union 合并驱动、pull.rebase=false，以及 post-merge 和 post-checkout 重建钩子
npx mcp-memory-graph sync	将所有有效记忆及图的 sidecar 导出到 vault（.md 文件）
npx mcp-memory-graph rebuild [--vault <path>]	从 vault 的 .md 文件重建 SQLite 索引（协作者在执行 git pull 后运行此命令）
npx mcp-memory-graph migrate	将数据库升级到当前架构版本
npx mcp-memory-graph backup [--out <path>]	创建 WAL 安全的在线快照（保留数量：MCP_MEMORY_MAX_BACKUPS，默认 10）
npx mcp-memory-graph keys create|list|revoke	按密钥进行 RBAC：创建、查看、撤销 API 密钥（命名空间集合加访问权限上限）

工具参考

1. memory_store

存储一条新记忆。自动生成向量嵌入。

参数	类型	必填	默认值	描述
content	string	是		要存储的文本内容
title	string	否		记忆的简短标题
scope	enum	否	global¹	global、project、user、team、department
namespace	string	否	¹	子范围（例如，项目名称）
importance_score	number	否	计算得出	0-1 的手动重要性覆盖值
agent_id	string	否	MCP_AGENT_ID env	用于 memory_attribution 汇总的归属信息
on_conflict	enum	否	add	add、supersede、skip：近似重复项的写入门控行为
document_type	string	否		contract、policy、code、incident、decision 等
source	string	否		此内容的来源
author	string	否		创建者
department	string	否		legal、engineering、hr、sales、finance
tags	string[]	否		用于分类的标签
access_level	enum	否	internal	public、internal、confidential、restricted
language	string	否	en	ISO 639-1 语言代码
metadata	object	否		特定领域的键值对
expires_at	string	否		ISO 8601 到期日期

¹ 如果省略，则优先采用已加载配置文件中的 defaults.scope 和 defaults.namespace（"auto" = 项目目录名称）；硬编码的回退值为 global，且不设命名空间。

提示词示例：

Store this memory with department=legal and tags=["compliance","gdpr"]:
"All customer data processing agreements must include a GDPR Article 28 addendum effective January 2025."

2. memory_search

在已存储的记忆中进行向量与关键词混合搜索。

工作原理：

1. 将查询转换为向量，并与所有已存储的向量进行比较（语义相似度）。
2. 使用 FTS5 在记忆文本中匹配关键词（精确匹配）。
3. 使用倒数排名融合合并两组结果。
4. 可选的时间衰减会优先显示较新的记忆。
5. 为结果添加置信度分数和标签。
6. 记录访问情况，以用于质量评分。

参数	类型	必填	默认值	描述
query	string	是		自然语言查询或关键词
scope	enum	否		按范围筛选
namespace	string	否		按命名空间筛选
department	string	否		按部门筛选
document_type	string	否		按文档类型筛选
tags	string[]	否		筛选：必须包含所有指定标签
access_level	enum	否		按访问级别筛选
language	string	否		按语言筛选
limit	number	否	10	最大结果数（1-100）
offset	number	否	0	分页偏移量
search_mode	enum	否	hybrid	hybrid、vector 或 keyword
temporal_decay	object	否		{type: "exponential", half_life_days: 30} 或 {type: "linear", max_age_days: 365}
date_from	string	否		仅包含此日期之后的记忆
date_to	string	否		仅包含此日期之前的记忆
min_confidence	number	否		最低置信度阈值（0-1）

提示词示例：

Search memories for "contract renewal notice requirements" in the legal department

Search memories for "authentication" with search_mode=keyword

Search memories for "deployment patterns" with temporal_decay={type:"exponential", half_life_days:60}

每条结果都包含记忆内容和元数据、合并后的 RRF score、归一化的 confidence（0-1）、confidence_level 标签（0.7 及以上为高，0.4 及以上为中，低于此值为低），以及 match_type（hybrid、vector 或 keyword）。

默认的 detail_level: "summary" 投影会返回 confidence_level，但为节省令牌，不包含数值型 confidence 和完整的 content。需要这些内容时，请传入 detail_level: "full"。

3. memory_get

按 ID 获取指定记忆。对于已摄取的文档，还可选择包含所有子块。

参数	类型	必填	默认值	描述
id	string	是		记忆 UUID
include_chunks	boolean	否	false	包含已摄取文档的子块

4. memory_update

更新现有记忆。如果内容发生变化，系统会自动重新生成嵌入。之前的版本会保存到历史记录中。

参数	类型	必填	默认值	描述
id	string	是		要更新的记忆 ID
content	string	否		新内容（会触发重新嵌入）
title	string	否		新标题
metadata	object	否		替换元数据
tags	string[]	否		替换标签
expires_at	string/null	否		新的过期时间，或设为 null 以移除
changed_by	string	否		执行此更改的人

5. memory_delete

按 ID 或筛选条件删除记忆。必须提供 id 或 filter 中的至少一个。

参数	类型	必填	描述
id	string	否	删除指定记忆
filter.scope	enum	否	删除范围内的所有记忆
filter.namespace	string	否	删除命名空间内的所有记忆
filter.department	string	否	删除部门内的所有记忆
filter.before_date	string	否	删除早于指定日期的记忆
filter.expired_only	boolean	否	仅删除已过期的记忆

6. memory_list

浏览记忆，支持筛选、分页和排序。

参数	类型	默认值	说明
scope	enum		按范围筛选
namespace	string		按命名空间筛选
department	string		按部门筛选
document_type	string		按类型筛选
limit	number	20	最大结果数（1-100）
offset	number	0	分页偏移量
sort_by	enum	created_at	created_at、updated_at 或 title
sort_order	enum	desc	asc 或 desc

7. memory_ingest

摄取完整文档：根据内容类型将文档拆分成多个片段，为每个片段生成嵌入，并存储所有内容及其父子关系。适用于大型文档。

参数	类型	默认值	说明
content	string		完整文档文本（必填）
title	string		文档标题
content_type	enum	text	分块策略：text、markdown、code、legal、structured
chunk_size	number	512	目标分块字符数（约每个 token 4 个字符）
chunk_overlap	number	50	分块之间的重叠长度，用于保留上下文
source	string		来源文件或 URL
document_type	string		文档分类
department	string		部门
author	string		作者
tags	string[]		标签
metadata	object		特定领域的元数据

按内容类型分块：

类型	策略	分割依据
text	段落	两个换行符（\n\n）
markdown	根据标题	#、##、### 标题
code	根据函数	function、class、const、interface 边界
legal	句子	句号、感叹号、问号
structured	段落	两个换行符（与 text 相同）

8. memory_related

查找与指定记忆在语义上相关的记忆。使用向量相似度，因此能够发现关键词搜索会遗漏的关联。

参数	类型	默认值	说明
id	string		要查找相关记忆的记忆 ID（必填）
limit	number	5	最大结果数（1-50）
min_similarity	number		最低相似度阈值（0-1）

9. memory_versions

查看记忆的版本历史。每次更新都会创建一条版本记录。

参数	类型	默认值	说明
id	string		记忆 ID（必填）
limit	number	10	最大版本数（1-50）

10. memory_stats

已存储记忆的使用统计信息。

参数	类型	说明
scope	enum	按范围筛选统计信息
namespace	string	按命名空间筛选统计信息
department	string	按部门筛选统计信息

返回记忆、文档和分块的总数，按范围、部门和类型细分的统计信息，存储大小以及已过期的数量。

11. memory_export

将当前记忆内容导出为 JSON，以便移植或迁移。这不是完整备份：它仅序列化当前有效的顶层记忆，不包含编辑历史、知识图谱、压缩撤销原始内容、摄取的子分块以及软删除的记录。灾难恢复时，请复制 SQLite 文件（cp ~/.mcp-memory/memory.db ...，参见 RUNBOOK）；导入时会以确定性方式重新计算嵌入。

参数	类型	默认值	说明
scope	enum		筛选导出内容
namespace	string		筛选导出内容
department	string		筛选导出内容

每次最多导出 1000 条记录。

12. memory_import

从 JSON 导入记忆。每个条目都会经过嵌入并存储。

参数	类型	默认值	描述
data	数组		记忆对象数组（必填）
overwrite	布尔值	false	覆盖现有 ID

13. vault_sync

扫描 Obsidian 知识库，解析 Markdown，进行嵌入并存储。请参阅下文的 Obsidian 知识库集成。

14. vault_status

知识库的同步状态：已同步、待同步和已更改的文件，以及上次同步时间。

15. vault_search

限定在单个知识库记忆范围内的混合搜索。

默认情况下，此搜索会查询以知识库文件夹名称命名的命名空间。从其他命名空间导出的记忆会在 frontmatter 中保留其原始命名空间。如果刚同步的知识库搜索不到任何结果，请传入显式的 namespace（和/或 scope）覆盖值。

16. memory_consolidate

梦境周期：去重、评分、修剪、过期处理并检测知识缺口。

参数	类型	必填	默认值	描述
scope	枚举	否		将整合范围限定为某个范围
namespace	字符串	否		将整合范围限定为某个命名空间
similarity_threshold	数字	否	0.85	用于去重的余弦相似度（0.5-1.0）
prune_expired	布尔值	否	true	移除已过期的记忆
prune_low_quality	布尔值	否	false	移除重要性低于最低值的记忆
dry_run	布尔值	否	false	预览更改，但不应用
max_operations	数字	否	100	限制每次运行的操作总数

按顺序运行五个阶段：评分（重新计算重要性）、过期处理（执行 expires_at）、修剪（启用后移除低质量记忆）、去重（合并近似重复项）、缺口检测（显示搜索结果为零的查询）。返回一份报告，其中包含各阶段的计数。

示例提示词：

Run a dream cycle consolidation with dry_run=true to preview what would change

Consolidate memories in namespace=my-project with similarity_threshold=0.9

Run consolidation with prune_low_quality=true to clean up unused memories

17. memory_extract_learnings

使用启发式模式匹配，从会话记录中提取决策、模式、错误修复和约定。无需外部大模型。

参数	类型	必填	默认值	描述
transcript	字符串	是		要提取内容的会话记录文本
scope	枚举	否		提取出的记忆的范围
namespace	字符串	否		提取出的记忆的命名空间
department	字符串	否		提取出的记忆的部门
tags	字符串[]	否		附加标签
source	字符串	否		来源归属信息
categories	枚举[]	否	all	筛选为 decision、pattern、error_fix、convention
auto_store	布尔值	否	true	自动存储提取出的经验

提取时会查找决策类措辞（“我们决定”“解决方法是”）、模式类措辞（“始终使用”“绝不这样做”）、错误修复类措辞（“问题在于”“通过……解决”）和约定类措辞（“我们的约定是”“标准做法”）。每个匹配项都会与现有记忆去重，并以较低的初始置信度存储。

18-42. 图谱、Agent-OS、保管库往返转换和治理工具

其余工具的参数由 src/schemas/ 中的 Zod 架构验证；每项注册的完整说明位于 src/server.ts。

#	工具	用途
18	memory_tiers	MemGPT 风格的热层／召回层／归档层分布，以及热工作集
19	memory_export_vault	将记忆写入 Obsidian 保管库，保存为带有 YAML frontmatter 的 .md 文件（与 vault_sync 方向相反）
20	memory_canvas	将图谱导出为供 Obsidian 使用的 JSON Canvas 1.0 .canvas 文件
21	memory_manifest	轻量级、不含内容的索引（标题、类型、标签、分数），用于发现现有内容
22	memory_graph	查询知识图谱：实体、关系、关联记忆、多跳遍历（深度为 1-3）
23	memory_extract_entities	存储从记忆中由 LLM 提取的实体和关系
24	memory_condense	应用由 Agent 生成的摘要来精简旧记忆（保留原文）
25	memory_restore	将精简后的记忆还原为原始内容并重新嵌入
26	memory_query	使用经过严格令牌预算控制的子图回答问题，而非将大量内容灌入上下文
27	core_memory_get	读取 (scope, namespace) 对应的固定核心记忆块，该内容始终保留在上下文中
28	core_memory_append	追加到核心记忆块（若会超出 char_limit，则拒绝操作）
29	core_memory_replace	替换核心记忆块中的文本（用于更新或精简内容）
30	memory_reflect	Generative Agents 风格的反思：收集素材，或存储综合得出的洞见
31	memory_communities	对实体图谱进行 GraphRAG 社区检测，以发现语料级主题
32	memory_template	按文档类型获取结构化笔记模板
33	memory_session_note	每个会话的“每日日记”（每个 session_id 追加到一条记忆中）
34	memory_attribution	汇总每个 agent_id 写入的有效记忆数量
35	memory_questions	“待询问问题”摘要：含义模糊的链接、文档记录不足的实体或孤立项
36	memory_forget	达到 GDPR 级别的遗忘：默认软删除（可恢复），也可选择 hard，先导出再擦除
37	memory_history	单条记忆的指定时间点双时态时间线及编辑版本历史
38	memory_unlinked_mentions	记忆文本中提及但尚无图谱边连接的实体名称（建议链接）
39	memory_query_structured	对顶层记忆进行精确的元数据筛选查询（不进行语义排序）
40	memory_version_diff	对比记忆两个已存储版本之间逐行的差异
41	memory_version_restore	将记忆回滚到先前版本（先为当前版本创建快照）
42	memory_verify	验证记忆的签名来源信封（对 content_hash 和来源使用 ed25519）：逐条返回 ok／unsigned／content_mismatch／bad_signature／untrusted 状态及汇总信息。可通过 MCP_SIGN_MEMORIES 启用签名；多机器允许列表使用 MCP_TRUSTED_PUBKEYS／trusted_pubkeys

43-50. 活跃基础设施与类型化结构

#	工具	用途
43	memory_webhook	管理事件总线（由 MCP_WEBHOOKS 控制）：注册、列出或删除经过 SSRF 验证的出站目标，或分发持久化的 HMAC 签名投递队列（重试、断路器、死信）。变更会触发 created/updated/superseded/deleted/forgotten 事件
44	memory_insights	顾问摘要：未解决的冲突、过时记忆、最常被质疑的事实、缺少证据的决策
45	memory_health	存储健康状况汇总：当前/已退役/过时记忆数量、老化分布、未解决的冲突、Webhook 投递健康状况
46	memory_revalidate	变更传播：列出过时记忆、预览变更的影响范围（试运行），或确认记忆仍然有效
47	memory_session_state	可恢复的“我刚才进行到哪一步”会话状态，支持保存和恢复（带版本）
48	memory_expertise	每位用户的专业知识档案：记录主题、获取档案
49	memory_export_dataset	将经验和反思导出为 JSONL 训练对（pairs/chatml/alpaca），用于微调
50	memory_lesson	一次调用即可记录结构化经验教训或事件：根据你提供的字段填充匹配的章节模板（事件 → Symptom/Root Cause/Fix/Prevention；经验教训 → What/Why it matters/How to apply），并通过常规去重写入流程存储

架构

系统概览

Claude Code ──stdio──> MCP Memory Graph
                            │
                    ┌───────┴───────┐
                    │               │
              Transformers.js   SQLite DB
              (embeddings)    (~/.mcp-memory/memory.db)
                                    │
                       ┌────────────┼────────────┐
                       │            │            │
                   memories    memories_fts  memories_vec
                   (data +     (FTS5 index)  (vec0 index)
                    scores)
                       │
              ┌────────┼────────┐
              │        │        │
        memory_    memory_    ingest_
        versions   access_    source_
                   log        tracking


Claude Code Hooks (opt-in)
    │
    ├── SessionStart ──> memory_stats (status check)
    ├── PostToolUse ───> search-log.jsonl (hit/miss tracking)
    ├── PreCompact ────> learning extraction (disabled by default)
    └── Stop ──────────> spawn detached `claude -p` headless review
                              │
                              └─> --allowedTools mcp__memory-server__memory_store
                                  Claude reviews transcript → memory_store calls

Nightly Schedule (opt-in)
    └── 3:00 AM ───────> memory_consolidate (dream cycle)

混合搜索的工作原理

Query: "contract renewal notice"
         │
    ┌────┴────┐
    │         │
 Embed     Tokenize
    │         │
    ▼         ▼
 sqlite-vec  FTS5
 (semantic)  (keyword)
    │         │
    │  rank   │  rank
    │  1: A   │  1: A
    │  2: C   │  2: B
    │  3: B   │  3: D
    │         │
    └────┬────┘
         │
   Reciprocal Rank Fusion
   RRF(d) = Σ 1/(60 + rank)
         │
         ▼
   [A: 0.033, B: 0.026, C: 0.016, D: 0.016]
         │
   Temporal Decay (optional)
         │
   Confidence Scoring
         │
   Access Tracking (record hit)
         │
         ▼
   Final ranked results

数据库架构

SQLite 数据库的架构版本为 18，并可从任何更早版本自动升级。核心表：

• memories：所有记忆数据，TEXT 主键（UUID），支持文档块的父子关系，并包含 access_count、last_accessed_at、importance_score 和 confidence_score。
• memories_fts：用于关键词搜索的 FTS5 虚拟表，采用 BM25 排名，并与 memories 表同步。
• memories_vec：用于向量搜索的 vec0 虚拟表。包含 384 维 float32 嵌入，以及用于预筛选的范围和命名空间元数据。
• memory_versions：记录每次变更的版本历史。
• memory_access_log：记录每次搜索、获取和相关记忆访问，以及时间戳和查询上下文。
• ingest_source_tracking：记录摄取的文件，用于在重新摄取时检测变更。

后续架构版本增加了知识图谱表（实体、链接、冲突、社群）、Webhook、会话状态和 RBAC api_keys 表。每次变更都会在 SQLite 事务中原子性地保持三个核心表同步；repository.ts 层负责强制执行此规则，其他任何代码都不会直接访问这些表。

项目布局

src/
├── index.ts        # Entry point (stdio transport)
├── server.ts       # All 51 tool registrations
├── config/         # Config file loading + validation
├── db/             # Connection, schema, migrations, repository (three-table sync)
├── embeddings/     # Embedding providers (Transformers.js, registry, Ollama)
├── search/         # Hybrid search, reranker, temporal decay, scoring
├── chunking/       # Per-content-type chunking strategies
├── graph/          # Entities, links, PageRank, communities
├── vault/          # Obsidian round-trip, write-through, bookkeeping
├── tools/          # One handler per MCP tool
├── api/            # REST routes + security middleware
├── events/         # Webhook bus (SSRF guard, HMAC, retry)
├── cli/            # init, serve, vault, backup, keys, migrate, ...
├── hooks/          # Claude Code lifecycle hooks
└── schemas/        # Zod schemas for every tool input

各部门的使用场景

工程：

Store memory: "We chose event sourcing over CRUD for the order service because
we need full audit trail and the ability to replay events for debugging.
ADR-042, decided 2026-03-15."
department=engineering, document_type=decision, tags=["architecture","event-sourcing"]

法务：

Ingest this contract template with content_type=legal, department=legal,
document_type=contract, tags=["template","nda","standard"]

财务：

Store memory: "Q4 2025 revenue recognition policy change: SaaS contracts
over 12 months now recognized ratably per ASC 606 guidance."
department=finance, document_type=policy, tags=["revenue-recognition","asc-606"]

人力资源：

Ingest the employee handbook with department=hr, content_type=text,
document_type=policy, tags=["handbook","onboarding"]

销售：

Store memory: "When prospect objects on price vs CompetitorX, lead with
our 99.9% uptime SLA and dedicated support. This converted 3 deals in Q1."
department=sales, document_type=pattern, tags=["objection-handling","pricing","competitorx"]

Obsidian Vault 集成

将服务指向一个 Vault 文件夹，其中的每个 Markdown 文件都会成为可搜索的记忆，并提取 frontmatter、标签和 wiki 链接。无需 Obsidian 应用；它会直接从磁盘读取文件。

工具	描述
vault_sync	扫描 Vault、解析文件、生成嵌入并存储。增量同步（基于 mtime）。
vault_status	同步状态：已同步、待处理和已更改的文件数，以及上次同步时间。
vault_search	在 Vault 的记忆范围内进行混合搜索。

提取内容：

Obsidian 功能	记忆字段
YAML frontmatter title:	title
YAML frontmatter tags: [...]	tags（与行内标签合并）
YAML frontmatter author:	author
YAML frontmatter（所有字段）	metadata.frontmatter
内容中的行内 #tags	tags（与 frontmatter 合并）
[[wiki-links]]	metadata.links 数组
相对于 Vault 的文件路径	source
Vault 目录名称	namespace

使用示例：

Sync my Obsidian vault at ~/Documents/my-vault

Check vault sync status for ~/Documents/my-vault

Search my vault for "meeting action items about hiring"

Sync vault but only the notes/ and projects/ folders:
  vault_sync with include_patterns=["notes/**", "projects/**"]

Force re-sync everything (ignore modification times):
  vault_sync with force=true

vault_sync 参数：

参数	类型	默认值	描述
vault_path	string		Vault 目录的绝对路径（必填）
chunk_size	number	1024	大文件的目标分块大小
chunk_overlap	number	50	分块之间的重叠长度
force	boolean	false	无论 mtime 如何，重新同步所有文件
include_patterns	string[]		仅同步与 glob 模式匹配的文件（例如 ["notes/**"]）
exclude_patterns	string[]		跳过与 glob 模式匹配的文件（例如 ["templates/**"]）

同步方式：递归扫描 Vault 中的 .md 文件（跳过 .obsidian/、.trash/、.git/），将文件修改时间与上次同步时进行比较，从新增或已更改的文件中提取 frontmatter、wiki 链接和标签，生成嵌入并存储。已删除文件对应的记忆也会被删除。大于分块大小的文件会采用 Markdown 感知分块方式拆分。未更改的 Vault 再次同步耗时不到 1 毫秒。

安全与隐私

• 除一次性模型下载外，不会进行网络调用（模型会在本地缓存）。
• 无遥测、无分析、无跟踪。
• Hooks 默认不启用。仅在运行 npx mcp-memory-graph init 时安装。
• 夜间计划任务也默认不启用，并可通过 npx mcp-memory-graph uninstall 移除。
• 所有数据都存储在一个 SQLite 文件中：易于备份、迁移或删除。
• 提供 access_level 元数据（public、internal、confidential、restricted），便于组织层面的管理。
• 数据不会离开你的计算机。

备份：

# WAL-safe online snapshot with retention
npx mcp-memory-graph backup

# Or a simple file copy
cp ~/.mcp-memory/memory.db ~/.mcp-memory/memory.db.backup

重置：

# Delete the database to start fresh
rm ~/.mcp-memory/memory.db

夜间整合

通过 npx mcp-memory-graph init 安装后，夜间任务会运行梦境周期的全部五个阶段，并轮换访问日志（删除超过 90 天的条目）。

在 macOS 上，会在 ~/Library/LaunchAgents/com.mcp-memory.consolidate.plist 创建一个 launchd plist，计划于凌晨 3:00 运行。在 Linux 上，init 会打印一条 cron 建议：

# Add to crontab -e
0 3 * * * /usr/local/bin/npx mcp-memory-graph consolidate

可随时手动运行：

npx mcp-memory-graph consolidate

局限性

• 规模上限。 向量搜索采用精确扫描：10K 个向量时 p95 为 9.1 ms，50K 个时约为 30 ms，此后性能会线性下降。几十万以内都能轻松应对；超过这个规模就需要专用的 ANN 索引，而此服务目前还没有。
• 针对英语优化。 默认的 MiniLM 模型在实际使用中仅支持英语；跨语言匹配效果较弱。可以通过 MCP_MEMORY_MODEL 配置多语言模型（需要重建），但随附的基准测试仅验证了默认模型。
• 首次调用冷启动。 首次使用时，嵌入模型加载需要 3 到 5 秒。此后会缓存。
• 启发式提取。 memory_extract_learnings 使用模式匹配，而非大模型。它能识别常见表述，但会漏掉不明显的表述。（Stop 钩子中的 claude -p 审查才是大模型质量的处理路径。）
• 单进程。 RBAC 密钥和撤销信息保存在服务进程中。要实现水平扩展，可以将各租户分片到不同进程，或为每个租户单独使用一个数据库文件。

路线图

接下来实际要做的事项，大致按顺序排列：

• 可选的多语言嵌入。 提供多语言 ONNX 模型选项（嵌入器注册表和模型标识保护机制已经存在，因此替换安全且会明确提示）。
• Office 文档摄取。 将 PDF、DOCX、XLSX 等格式作为摄取模式，仅使用本地提取。
• Vault 文件监视器。 .md 文件发生变化时自动重建，而非手动执行 rebuild。
• as_of 内容重建。 目前，指定时间点的查询可以重建有效性（哪些事实当时有效）；还需要补全另一部分：重建该时间点已编辑记忆的内容。
• 面向数十万个以上向量语料库的 ANN 索引。
• 移植 Windows 测试套件。 此服务可在 Windows 上运行，但测试套件依赖 POSIX 路径假设；在完成移植前，Windows CI 阶段不会阻塞构建。

技术栈

组件	软件包	用途
MCP SDK	@modelcontextprotocol/sdk ^1.29	Model Context Protocol 服务框架
嵌入	@huggingface/transformers ^3.8	在 Node.js 中进行本地 ONNX 模型推理
数据库	better-sqlite3 ^12.10	通过原生绑定实现的同步 SQLite
向量搜索	sqlite-vec 0.1.10-alpha.4	用于 KNN 搜索的 vec0 虚拟表
验证	zod ^3.25	工具输入的模式验证
TypeScript	typescript ^5	严格模式，ES2022 目标
前端	React 19、Vite、Tailwind CSS v4	Web 仪表板 SPA
UI 组件	shadcn/ui	无障碍组件原语
模糊搜索	fuse.js ^7	客户端自动补全建议
图可视化	d3-force、d3-zoom、d3-drag	知识图谱布局

许可证

可获取源代码，但并非开源。根据 PolyForm Noncommercial License 1.0.0 授权：可免费用于任何非商业用途（个人项目、爱好、学习、研究、慈善、教育、公共研究和政府用途）。商业用途需要付费许可证；请参阅 COMMERCIAL.md。

如果你不确定自己的用途是否属于商业用途，请查看许可证中的安全港条款，或直接咨询：[email protected]。

关键词

MCP 记忆服务 · Model Context Protocol · Claude Code 记忆 · 持久化 AI 记忆 · 大模型长期记忆 · AI Agent 记忆 · 本地优先记忆 · $0/token 记忆 · 混合向量 + 关键词搜索 · 语义搜索 · 知识图谱 · 双时态记忆 · HippoRAG / Personalized PageRank · 交叉编码器重排序 · RAG 记忆 · SQLite 向量数据库 · sqlite-vec · FTS5 / BM25 · 本地嵌入（all-MiniLM-L6-v2、Transformers.js）· Obsidian Vault 同步 · JSON Canvas · GDPR 遗忘 · 已签名溯源信息 · 可自托管记忆。

也可通过以下描述搜索：作为 mem0、Zep、Letta、Cognee 和 Supermemory 的可自托管、隐私优先替代方案 · 面向 Claude / Cursor / Codex 的长期记忆 · 为 AI Agent 提供由 Obsidian 支持的知识库 · 永不离开你设备的本地知识图谱记忆。