在 Claude Code 中接入 MemPalace：Marketplace 插件、手动 MCP 与会话记忆回填实战指南

MemPalace 是一款面向 AI Agent 的本地语义记忆系统，而 Claude Code 是它最直接的消费方之一。本文以仓库 website/guide/claude-code.md 为核心，完整讲解在 Claude Code 中接入 MemPalace 的两条路径（官方 Marketplace 插件与手动 MCP 注册）、插件安装后自动获得的“开箱即用”能力，并结合 website/guide/claude-code-retention.md 与 website/guide/hooks.md，补齐 hooks 自动保存与存量会话转录回填的完整操作。读完你可以独立完成从“插件安装 → 验证 → 日常回忆 → 会话记忆不丢失”的整套接入闭环。

接入方式概览：为什么官方推荐插件

在 Claude Code 中让 Claude 具备“持久记忆”的前提，是它能在启动时拉起 MemPalace 的 MCP server，并通过 MCP 工具读写你的 palace。仓库提供两种等价接入方式：

1. Claude Code Marketplace 插件（推荐）：通过 claude plugin marketplace add 一键注册，插件会在 Claude Code 每次启动时自动拉起 MemPalace MCP server，无需任何手动配置；
2. 手动 MCP 注册（替代方案）：用 claude mcp add 手动注册 stdio 服务，适合不依赖 Marketplace、希望完全掌控进程生命周期的用户。

按 website/guide/claude-code.md 的表述，两种方式功能完全一致（“Both approaches give identical functionality”），差别只在于：插件方案会自动管理 MCP server 的生命周期，而手动方案需要你自行保证 mempalace 包已安装且可被 python -m mempalace.mcp_server 启动。若是首次使用 MemPalace，可先按 website/guide/getting-started.md 完成 palace 初始化，再回来接入 Claude Code。

方式一：通过 Claude Code Marketplace 插件接入（官方推荐）

安装步骤

在本地克隆了 MemPalace 仓库、且已安装 Claude Code 的环境里，执行两条命令即可完成插件注册与安装：

claude plugin marketplace add MemPalace/mempalace
claude plugin install --scope user mempalace

• marketplace add 将 MemPalace 的 marketplace 源加入 Claude Code 的插件源列表；
• plugin install --scope user 以当前用户作用域安装 mempalace 插件，使该用户所有 Claude Code 会话可用。

校验插件是否生效

安装后必须重启 Claude Code，然后在会话内输入斜杠命令：

/skills

若输出列表中出现 mempalace，说明插件已被正确加载。这个校验步骤不能跳过——插件安装成功不代表 MCP 已连接，正如 skills/mempalace/SKILL.md 所强调的：“Package installation alone is not proof that MCP is connected”。

插件安装后，你还可以在会话中继续看到由仓库打包进 marketplace 的三个技能：

• skills/mempalace/SKILL.md —— 安装、配置与运维向导；
• skills/mempalace-recall/SKILL.md —— 强制“先搜索 palace 再回答”的回忆技能；
• skills/mempalace-task/SKILL.md —— 面向委派任务的技能。

仓库用一条测试 tests/test_claude_marketplace_skills.py 专门守护 marketplace 打包内容：它断言 .claude-plugin/skills/ 下打包的每个技能与仓库根目录 skills 下的权威版本逐字节一致（assert bundled[name].read_bytes() == canonical[name].read_bytes()），一旦打包内容与 skills/ 目录发生漂移（drift）测试即失败。也就是说，你在 /skills 里看到的内容与仓库源文件是一一对应的，可以直接反向查看其实现。

安装后自动获得的能力

按 website/guide/claude-code.md 的说明，插件安装后 Claude Code 会在每次启动时自动完成以下四件事，全程无需手动配置：

1. 启动时自动拉起 MemPalace MCP server——会话一开启，记忆读写通道就绪；
2. 获得完整的 MCP 工具集——原文档写作时标注为 36 个工具，仓库最新版 website/reference/mcp-tools.md 已持续扩充到 45 个工具并给出全部参数 Schema（工具数量随版本增长，请以安装后 tools/list 或 mempalace_status 实际暴露为准）；
3. 从 mempalace_status 的响应中学习 AAAK 方言与记忆协议——mempalace_status 会返回 palace 概览与 protocol、aaak_dialect 等元数据，Claude Code 据此理解记忆的书写规范（AAAK 方言的完整说明见 website/concepts/aaak-dialect.md）；
4. 在回答关于过往工作的问题前，先搜索 palace——把记忆检索前置到作答之前，避免“凭空猜”。

随后你只需像平时一样提问即可，例如：

"What did we decide about auth last month?"

Claude 会自动调用 mempalace_search（语义搜索，返回抽屉原文与相似度分数）来完成回答，而不是依赖自己可能已被截断的上下文。这正是 integrations/shared/recall-protocol.md 描述的“search-before-answer”召回协议在 Claude Code 上的落地形态。

方式二：手动注册 MCP（不依赖 Marketplace）

如果你希望绕开插件机制、只做最轻量的 MCP 注册，可执行：

claude mcp add mempalace -- python -m mempalace.mcp_server

该命令在 examples/mcp_setup.md 与 website/guide/mcp-integration.md 中都有同源记载（后者还提供 --palace /path/to/palace 指定 palace 路径的变体）。python -m mempalace.mcp_server 是 MCP server 的官方入口，其 __main__ 分支位于 mempalace/mcp_server.py；若你通过 pip install mempalace 安装，也可直接使用等价的 mempalace-mcp 控制台命令（见 skills/mempalace/SKILL.md 中的注册示例）。

与插件方案相比：

• 功能面完全一致（同一套 MCP 工具）；
• 区别在于 server 的拉起与停止由 claude mcp 配置管理，而非插件自动托管；
• 需要你自行确认 mempalace 包已正确安装且 python -m mempalace.mcp_server 可正常启动（可用 mempalace --version 先行验证，详见 skills/mempalace/SKILL.md 的排查指引）。

Hooks：让长会话的记忆自动落盘

接入 MCP 只是打通了“读写通道”，真正的记忆保鲜还需要解决一个问题：Claude Code 的上下文会滚动丢弃，超长会话里早段的决策若不及时写进 palace 就会彻底蒸发。website/guide/claude-code.md 在末尾明确要求为长会话接上自动保存 hooks（它链向了 website/guide/hooks.md）。

MemPalace 为 Claude Code 提供两只 hooks，作用分别如下：

Hook	触发时机	行为
Save Hook（mempal_save_hook.sh）	每 15 条人类消息	拦截 AI 停止动作，要求它把关键话题、决策与引语写入 palace
PreCompact Hook（mempal_precompact_hook.sh）	上下文即将压缩前	紧急保存——在上下文被压缩丢失之前强制 AI 先落盘

要点在于：执行“归档”动作的是 Claude 自己（它最清楚对话上下文，能正确把记忆分门别类到 wing/room/closet），hooks 只负责在正确的时机“叫停并提醒”。因此 hooks 本身是纯本地 bash 脚本，不调用任何远程 API，额外 token 成本为零（详见 website/guide/hooks.md 的 Cost 小节）。

在 .claude/settings.local.json 中接线

从仓库克隆目录执行（先赋予可执行权限）：

chmod +x hooks/mempal_save_hook.sh hooks/mempal_precompact_hook.sh

然后将以下配置写入 ~/.claude/settings.local.json（把两处 command 替换为本仓库的绝对路径）：

{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "/absolute/path/to/mempalace/hooks/mempal_save_hook.sh",
        "timeout": 30
      }]
    }],
    "PreCompact": [{
      "hooks": [{
        "type": "command",
        "command": "/absolute/path/to/mempalace/hooks/mempal_precompact_hook.sh",
        "timeout": 30
      }]
    }]
  }
}

编辑 settings 文件后必须重启 Claude Code——Claude Code 只在会话启动时加载 hooks 配置（“Claude Code loads hooks at session start”）。也就是说，hooks 只保护重启之后的会话，重启之前的历史会话不在保护范围内。仓库同时用 tests/test_claude_plugin_hook_config.py 验证插件携带的 hook 配置结构与上方 settings 写法的一致性，配置格式有测试背书。

hooks 可调参数

编辑 hooks/mempal_save_hook.sh 可调整：

• SAVE_INTERVAL=15——相邻两次保存之间的人类消息条数。调小则保存更频繁、AI 被打断更多；调大则相反；
• STATE_DIR——hook 状态存放目录，默认 ~/.mempalace/hook_state/；
• MEMPAL_DIR（可选）——设为某个会话目录后，每次触发保存会自动运行一次 mempalace mine。

调试与确认 hook 是否触发过，可查看运行日志：

cat ~/.mempalace/hook_state/hook.log

典型输出形如（来自 website/guide/hooks.md）：

[14:30:15] Session abc123: 12 exchanges, 12 since last save
[14:35:22] Session abc123: 15 exchanges, 15 since last save
[14:35:22] TRIGGERING SAVE at exchange 15
[14:40:01] Session abc123: 18 exchanges, 3 since last save

Save Hook 内部用 stop_hook_active 标志位避免“保存后再次触发保存”的无限循环；PreCompact Hook 则无条件拦截（压缩必然意味着上下文将丢失，无需计数判断）。

存量会话转录：先备份，再回填

hooks 只保护未来会话。对于已经发生过的 Claude Code 对话，website/guide/claude-code-retention.md 给出了一条时间敏感的提醒：Claude Code 的会话转录以 JSONL 形式存放在 ~/.claude/projects/，但不要假设它是永久保存的。如果你有重要的历史工作成果，应尽快按下述流程备份并回填。

第一步：只读备份现有转录

在仓库克隆目录执行：

tools/backup_claude_jsonls.sh

该脚本把 ~/.claude/projects/ 下的转录复制到 ~/Documents/Claude_JSONL_Backup/，并校验 JSONL 数量；它是只读的，不会修改或删除 ~/.claude/ 内的任何文件。

若你曾使用云同步或手工备份，还可能存在散落在其他目录的“孤儿”转录。可用另一只只读脚本扫描常见备份位置、输出候选 JSONL 及简短话题预览：

tools/find_orphan_claude_jsonls.sh

第二步：把转录回填进 palace

备份完成后，用 mempalace mine 的 convos 模式挖掘会话转录：

mempalace mine ~/.claude/projects/ --mode convos

如果还备份了更早的历史转录，则连同备份目录一起挖掘：

mempalace mine ~/Documents/Claude_JSONL_Backup/ --mode convos

注意 mempalace mine ... --mode convos 是幂等的（re-running it is safe），重复执行不会产生重复抽屉；mempalace/convo_miner.py 与 mempalace/convo_scanner.py 即负责这类 JSONL 转录的扫描与结构化挖掘，其行为由 tests/test_convo_miner.py、tests/test_convo_scanner.py 覆盖。

临时兜底：手动 /save 命令

若 hooks 尚未接线、又急需保存当前会话，可使用 tools/save.md 中描述的 /save 斜杠命令模板。它会引导 Claude 挖掘当前 Claude Code JSONL 转录写入 palace——但这只是临时兜底方案（stopgap），不能替代 hooks。

验证记忆真的生效

回填或接线完成后，用一条你确定存在于旧会话中的短语做检索验证：

mempalace search "phrase from an old Claude Code session"

新会话结束一轮后，检查 hook 是否真的触发过保存：

cat ~/.mempalace/hook_state/hook.log

运维与排查要点

• 修改 settings 或安装插件后务必重启 Claude Code，否则 hooks/MCP 不会随新会话加载；
• hooks 只保护重启之后的会话，存量会话必须依靠上面的备份 + mine --mode convos 流程；
• 若在会话中发现写工具报错 -32005，通常表示 MCP server 仍在运行旧版本库文件、与磁盘上已升级的包不一致——按 website/reference/mcp-tools.md 的说明，mempalace_status 返回的 library_versions.stale: true 即此信号，重启 MCP server 即可恢复写能力；
• 隐私红线：~/.claude/projects/ 下的转录包含你的私有对话，切勿把 JSONL 上传到公开 issue、讨论区或 gist；
• 若你在多个仓库/项目间切换，每条记忆都会按 wing（项目）隔离归档，可用 mempalace search --wing <wing> 限定检索范围。

至此，你已完成 MemPalace × Claude Code 的完整接入：插件或手动 MCP 打通读写，hooks 保障长会话自动落盘，备份 + 回填流程兜底历史转录。更完整的 MCP 工具参数可查阅 website/reference/mcp-tools.md，回忆协议与 hooks 教程分别见 integrations/shared/recall-protocol.md 与 website/guide/hooks.md。