MemPalace MCP 集成指南：让 Claude Code 通过 mempalace-mcp 直连 AI 记忆宫殿

关联文档：examples/mcp_setup.md · 核心实现：mempalace/mcp_server.py · 扩展阅读：website/guide/mcp-integration.md

MemPalace 是一个本地优先的开源 AI 记忆系统，以「宫殿（Palace）—翼楼（Wing）—房间（Room）—抽屉（Drawer）」的分层结构组织记忆。通过 MCP（Model Context Protocol） 服务器 mempalace-mcp，Claude Code 等任意 MCP 客户端都能在会话中直接检索、写入与维护这套记忆——实现「先查记忆再作答」的持久记忆能力。本篇以官方 MCP 接入文档为主体，结合仓库源码与配置逐层展开：先完成服务器启动与 Claude Code 注册，再认识其暴露的完整工具面，最后深入阅读模式、常用环境变量与多进程写入安全机制，让你能直接落地一个可用的「AI 记忆查询 / 写入」工作流。

一、理解 mempalace-mcp：一个 MCP 服务器的入口解剖

1.1 控制台脚本与懒加载代理

mempalace-mcp 并不是一个独立的二进制，而是在 pyproject.toml 中声明的 console script：

[project.scripts]
mempalace-mcp = "mempalace.mcp_proxy:main"

关键点在于入口落在了 mempalace/mcp_proxy.py，而不是直接落在 mcp_server。从源码注释看这是刻意的工程取舍：完整导入 mempalace.mcp_server（进而触发 chromadb / onnxruntime 等重依赖）大约要消耗 77 MB 内存，而代理模块只依赖标准库，把完整服务器延迟到首个请求时才真正导入，使一个空闲的 stdio 会话只占约 22 MB。这也意味着：

• mempalace-mcp 的进程本身极其轻量，冷启动快；
• 完整服务器在首次收到 MCP 请求时才被加载，因此客户端首个工具的返回可能略慢（源码 #1495 记录过客户端的 -32000 冷加载超时问题，可通过日志文件观测，见下文 MEMPALACE_LOG_FILE）。

从模块注释可见，代理进程的职责还包括在真正导入前向后台调度更新检查（schedule_update_check）、为完整服务器准备好它期望的后台服务等。

1.2 真正的服务器本体：mcp_server.py

mempalace/mcp_server.py 是 MCP 服务器本体（约 8000+ 行），它实现了：

• stdio 帧协议：默认以 stdio 传输层跑 JSON-RPC 循环，这是 Claude Code / Claude Desktop 等宿主启动子进程后最常用的方式；
• HTTP 传输：--transport http 时在进程内以 /mcp 路径接收 JSON-RPC POST，避免长时间 stdio 会话的帧错位问题（源码 #1801 记录）；
• 完整的 TOOLS 注册表（源码 TOOLS 字典起点）：每个工具都声明 JSON Schema 风格的 input_schema 与 handler，供客户端做 tools/list 发现与参数校验。

服务器在模块加载早期即有一段「stdio 保护」代码（源码文件头注释关联 issue #225）：由于 MCP 协议规定 stdout 只能承载合法 JSON-RPC 消息，而 chromadb → onnxruntime、posthog 遥测等传递依赖可能在 C 层直接向 stdout 打印横幅或错误，会破坏 Claude Desktop 的 JSON 解析器。因此在重导入之前先把文件描述符级别的 stdout 重定向到 stderr，并在进入协议循环前恢复真实 stdout。

二、Setup：把服务器挂到 Claude Code

关联文档给出了两种最基本的启动方式，实践中可按场景选用。

2.1 方式一：直接运行服务器

mempalace-mcp

此时服务器以默认配置启动，使用 stdio 传输、读取标准配置（~/.mempalace/config.json 或环境变量）中指定的 palace 路径。它适合在终端里做一次冒烟验证——但由于 MCP 走 stdio JSON-RPC，直接这样运行并不会有可读输出，除非你手动构造 JSON-RPC 帧。

2.2 方式二：注册进 Claude Code（推荐）

claude mcp add mempalace -- mempalace-mcp

claude mcp add 让 Claude Code 在每次会话启动时把 mempalace-mcp 作为子进程拉起，并通过 stdin/stdout 与之通信。之后在对话中即可直接使用其工具。

2.3 方式三：自定义 palace 路径与模块调用

如果你的 palace 不在默认位置，或需要精确控制参数，可以给 mempalace-mcp 追加启动参数。查看 服务器参数解析 可确认它支持的完整参数面：

参数	默认值	作用
--palace PATH	配置/环境变量决定	显式指定 palace 目录，会覆盖配置文件并回写环境变量 MEMPALACE_PALACE_PATH
--backend NAME	自动探测（chroma）	指定存储后端（chroma / pgvector / qdrant / milvus / sqlite_exact），并写入 MEMPALACE_BACKEND 与 MEMPALACE_BACKEND_EXPLICIT
--transport {stdio,http}	stdio	stdio（默认）或进程内 HTTP 服务
--host	127.0.0.1	HTTP 传输绑定的主机
--port	8765	HTTP 传输绑定的端口
--tls-cert PATH / --tls-key PATH	无	HTTP 传输终止 TLS 所需 PEM 证书与私钥（也支持环境变量 MEMPALACE_MCP_TLS_CERT / MEMPALACE_MCP_TLS_KEY）
--read-only	关	只读工具面：隐藏并拒绝所有会改变状态的工具

例如把 palace 显式指向一个项目目录：

claude mcp add mempalace -- mempalace-mcp --palace /path/to/palace
# 等价于使用模块入口
claude mcp add mempalace -- python -m mempalace.mcp_server --palace /path/to/palace

更省事的方式是用 MemPalace 自带的配置助手 mempalace mcp（见 website/guide/mcp-integration.md），它会把适配你当前环境的完整注册命令打印出来，直接复制粘贴即可。

2.4 使用仓库内的 mcp.json 与宿主示例配置

仓库根目录提供了标准 mcp.json：

{
  "mcpServers": {
    "mempalace": {
      "command": "mempalace-mcp"
    }
  }
}

这是许多 MCP 客户端（Claude Code 的 --mcp-config 等）都能读取的通用清单格式。仓库里还收录了不同宿主的现成配置示例可供对照：

• examples/cursor/mcp_config.json（Cursor）
• examples/antigravity/mcp_config.json

2.5 验证连接

注册完成后，最简单的验证方式是直接问 Claude Code 一个涉及你记忆库的问题（比如“我们上个月关于认证做了哪些决定”）。若它自动调用了 mempalace_search 并带回原文引用，就说明整条链路已打通。也可以在支持 MCP 调试的客户端里调用一次 mempalace_status，确认返回包含翼楼（wing）/房间（room）/抽屉（drawer）计数的 palace 概览。测试侧可以参考仓库的 tests/test_mcp_server.py 与 tests/test_mcp_stdio_protection.py，它们覆盖了服务器核心工具与 stdio 纯净性保障。

三、Available Tools：可用的 MCP 工具面

关联文档提到「服务器暴露了完整的 MemPalace MCP 工具集，常见入口包括 mempalace_status、mempalace_search、mempalace_list_wings」。事实上 mcp_server.py 顶部文档 将全部工具按用途分为三类：

• 读工具（read）：mempalace_status、mempalace_list_wings、mempalace_list_rooms、mempalace_get_taxonomy、mempalace_search、mempalace_check_duplicate 等；
• 写工具（write）：mempalace_add_drawer、mempalace_delete_drawer、mempalace_delete_by_source 等；
• 维护工具（maintenance）：mempalace_reconnect。

再结合扩展文档 website/guide/mcp-integration.md 的分类与 TOOLS 注册表，可以把完整工具面归纳为下面几组。

3.1 宫殿 / 抽屉基础工具（关联文档点名的入口）

工具	说明	关键入参
mempalace_status	Palace 总览：抽屉总数、翼楼/房间分布	无入参（见 TOOLS 定义）
mempalace_list_wings	列出所有翼楼（即各项目）及抽屉计数	无入参
mempalace_list_rooms	列出某翼楼下的房间，不传 wing 则列出全部	wing（可选）
mempalace_get_taxonomy	返回 wing → room → drawer count 完整树	无入参
mempalace_get_drawer	按 ID 取回单个抽屉原文	drawer_id
mempalace_list_drawers	分页列出抽屉	分页参数

其中 mempalace_status 的返回除了统计信息，还按扩展文档说明会携带 Memory Protocol（记忆协议）与 AAAK 压缩格式规范，指导 AI 何时检索、何时写入（详见本文第四节）。

3.2 mempalace_search：语义检索核心（重点）

mempalace_search 是文档点名的三大入口之一，也是整个记忆系统的查询中枢。查看其 Schema 定义 可以拿到精确的参数约束：

• query（必填，≤250 字符）：只放检索关键词或问题。工具描述特别强调：query 里绝不能塞背景说明，背景一律放 context，因为 query 会被拿去生成向量 embedding；
• limit（整数，默认 5，范围 1–100）：最多返回条数；
• wing / room：可选，把检索范围收窄到某个翼楼/房间；
• source_file：精确匹配单个来源文件的全路径（注意：不是 glob、不做 basename 模糊匹配，应直接回传结果里的 source_path 字段）；
• since / before：按 created_at（filed_at）墙钟时间过滤抽屉，since 含当天、before 严格早于；
• max_distance（默认 1.5）：余弦距离阈值（0=完全相同，2=完全相反），超过即被丢弃，设 0 关闭过滤、调低则更严格；
• candidate_strategy（vector | union）：候选来源策略，vector 保持纯语义检索；union 会先把后端 BM25 词法候选合并进来再重排，适合召回既有精确词又需要语义近义结果的场景；
• context（可选）：检索背景，仅用于未来重排，不参与 embedding。

返回结果是带相似度分数的抽屉原文（verbatim，不做转述），语义检索由 mempalace/searcher.py 的 search_memories 提供底层支撑。

3.3 写入与去重工具

• mempalace_check_duplicate：入库前先做相似度查重，content 必填、threshold 默认 0.9；
• mempalace_add_drawer：把内容按原样归档进 wing/room，必填 wing、room、content（content 必须逐字保存、绝不总结），可选 source_file 与 added_by（默认 mcp），写入前会自动做一次查重；
• mempalace_update_drawer / mempalace_delete_drawer / mempalace_delete_by_source：更新、按 ID 删除、以及按来源文件批量清除；
• mempalace_checkpoint：一次调用完成「逐条语义去重 → 非重复项入库 → 写入一条日记」的整段会话保存，在宿主 UI 里只渲染为一张工具调用卡片；
• mempalace_diary_write / mempalace_diary_read：会话日记的写与读。

3.4 知识图谱、隧道与日志流工具

• 知识图谱：mempalace_kg_query（支持 as_of 时点查询与 direction 方向）、mempalace_kg_add（支持 valid_from/valid_to 时间窗与 source_closet 等出处）、mempalace_kg_invalidate（标记事实不再成立）、mempalace_kg_supersede（单值事实在时间边界上的原子替换）、mempalace_kg_timeline、mempalace_kg_stats；
• 导航与隧道：mempalace_traverse、mempalace_find_tunnels、mempalace_graph_stats、mempalace_create_tunnel、mempalace_list_tunnels、mempalace_delete_tunnel、mempalace_follow_tunnels，以及走廊相关 mempalace_list_hallways / mempalace_delete_hallway；
• Agent 协调（RFC 003/004 相关）：mempalace_event_*、mempalace_task_create、mempalace_artifact_*、mempalace_patch_submit 等事件/日志流工具；
• 系统维护：mempalace_hook_settings（读写 hook 行为）、mempalace_memories_filed_away（查询上次 checkpoint 是否落盘）、mempalace_reconnect（外部写入后强制清缓存重连）。

更完整的参数 Schema 与逐工具说明见 website/reference/mcp-tools.md；工具按读写性质归类还可参考 _MUTATING_TOOLS、_READ_ONLY_REFUSED_TOOLS 两组常量（源码定义）。

四、Usage in Claude Code：让「记忆协议」真正生效

关联文档对使用方式只有一句概括——「配置完成后，Claude Code 可以在对话中直接检索你的记忆」。要让这从「能用」变成「好用」，关键在于 Memory Protocol（记忆协议）。它并非文档里的软性建议，而是服务器在 mempalace_status 返回中主动下发给客户端的操作守则（见 website/guide/mcp-integration.md），内容包括：

1. 唤醒时：先调用 mempalace_status 载入 palace 概览，获得翼楼/房间地图；
2. 作答前：只要话题涉及某人、某项目或某段历史，先搜索（mempalace_search）再开口，绝不凭记忆猜；
3. 不确定时：明说“让我查一下”并实际查询；
4. 会话结束后：用 mempalace_diary_write 写入日记，沉淀本次会话；
5. 事实变化时：mempalace_kg_invalidate 旧事实、mempalace_kg_add 新事实（单值变迁用 mempalace_kg_supersede）。

一个典型工作流示例：

1. 用户打开新会话并描述手头项目；
2. Claude Code 自动调用 mempalace_status 定位对应 wing；
3. 讨论某个历史决策时调用 mempalace_search（query 只放关键词）拿回抽屉原文；
4. 需要确认某实体当前状态时调用 mempalace_kg_query 并可用 as_of 指定时间点；
5. 会话中产生的结论由 Claude Code 通过 mempalace_checkpoint / mempalace_add_drawer 归档进相应 wing/room。

这与仓库配套的唤起规范一脉相承：参考 rules/mempalace-recall.mdc、skills/mempalace-recall/SKILL.md 以及 examples/cursor/hooks.json 中注册的 save / wake 钩子，可把“会话中写入”与“会话开始唤醒”都自动化。记忆写入侧的完整格式与挖掘入口，可进一步阅读 website/guide/mining.md 与 commands/mempalace-mine.md。

五、进阶运行参数：环境变量与多进程写保护

把 MCP 服务器接入日常开发后，以下运行参数值得了解。它们的解析逻辑都集中在 mcp_server.py，可作为排障依据。

5.1 常用环境变量

环境变量	默认	作用
MEMPALACE_PALACE_PATH	配置值	palace 目录；--palace 会覆盖它
MEMPALACE_BACKEND / MEMPALACE_BACKEND_EXPLICIT	探测结果	指定存储后端
MEMPALACE_MCP_READ_ONLY	关	等价 --read-only：隐藏并拒绝写工具
MEMPALACE_MCP_IDLE_HOURS	8.0	空闲自动退出：超过 N 小时无请求即退出进程，避免 Windows 上 ChromaDB/HNSW 文件句柄堆积；设 0 关闭（issue #1552）
MEMPALACE_LOG_FILE	无	追加写日志文件（仅收 mempalace 自身记录），用于排查客户端未呈现的冷启动失败
MEMPALACE_MCP_ALLOW_PEER_WRITER	关	允许旁路 peer-writer 保护（对本地后端无效，见下）
MEMPALACE_STARTUP_INTEGRITY_MAX_MB	512	超过该体积（MB）时跳过启动期 SQLite quick_check，避免巨库阻塞 MCP 握手；设 0 关闭限制、总是探测

5.2 多进程写入保护（peer-writer guard）

在 Claude Code 长驻的 MCP 服务器之外，你可能还会用 CLI 手动执行 mempalace mine 之类的写操作。MemPalace 对这类「多写者」场景内置了保护（源码 #1818）：

• MCP 写工具（定义在 _MUTATING_TOOLS，源码 L420-L442）调用前必须先取得 palace 的进程级写锁；若被其他写进程占用，会返回 -32001 “Peer MCP writer active” 错误，而不是冒险写入已分叉的 HNSW/FTS 索引；
• 该锁是自愈的：每次写调用都会用非阻塞 flock 重试，一旦原持有者退出（进程死亡即由内核释放锁），下一次写调用会自动提升为写者，无需重启宿主；
• 真正触碰 Chroma 向量段的写工具被单独圈进 _VECTOR_WRITE_TOOLS（源码），因为写进分叉的 HNSW 段会无超时地阻塞；索引分叉时返回 -32004；
• 只读模式（--read-only / MEMPALACE_MCP_READ_ONLY）隐藏并拒绝的范围更宽（返回 -32003），让一个共享服务器能为无权改状态的客户端服务召回；
• 进程内升级 mid-session（pip install -U mempalace 等）会被「陈旧库写入门禁」捕获并返回 -32005，提示重启服务器（issue #899，避免静默以旧代码写新格式）。

对日常用户的实际含义是：如果你看到 -32001，通常说明此时另有一个 mempalace 写进程在占用 palace；要么等它结束，要么把 CLI 类写入错开到不同进程，MCP 服务器会自动恢复写权限。若要追求高可用与更详细的恢复路径，可参考 website/guide/remote-server.md 与 deploy/docker-compose.server.yml 的部署形态。

六、小结：从配置到一套可持续的 AI 记忆工作流

回到 examples/mcp_setup.md 的三步骨架，我们把它扩充成了完整落地路径：

1. 启动：mempalace-mcp 单命令即可；需要自定义时用 --palace/--backend/--transport，或直接抄仓库里的 mcp.json / Cursor 示例；
2. 注册：claude mcp add mempalace -- mempalace-mcp，或用 mempalace mcp 打印环境专属命令；
3. 使用：Claude Code 按 Memory Protocol 先 mempalace_status 载入宫殿地图、mempalace_search 语义召回原文、知识图谱工具核对事实，再以 checkpoint/add_drawer/kg_add 沉淀新记忆。

这套机制的核心源码都在 mempalace/mcp_server.py（工具注册、参数解析、传输循环与写保护），配套回归测试见 tests/test_mcp_server.py、tests/test_mcp_stdio_protection.py、tests/test_mcp_http_transport.py。如需更全的工具参数，随时对照 website/reference/mcp-tools.md。