MemPalace Claude Code 插件指南：为 Claude Code 配置可搜索的持久记忆系统

MemPalace 以 Claude Code 插件的形式，为 AI 编程助手提供持久记忆：把项目文件与会话内容「挖掘（mine）」进由 ChromaDB 支撑的可搜索记忆宫殿，并通过 45 个 MCP 工具、自动保存钩子与 5 个引导式斜杠命令，让模型在跨会话场景下记住此前的工作。读完本篇，你将掌握该插件的安装与初始化、5 个斜杠命令与 3 个自动钩子的运行机制、底层 skill/MCP/CLI 的协作调用链，以及本地私有宫殿与 shared-brain 多机拓扑的配置要点。

插件概览：Claude Code 里的一站式记忆层

MemPalace 的 Claude Code 插件不是一个独立的记忆程序，而是一组将 Python 记忆系统嵌入 Claude Code 会话的装配件。它以插件清单（plugin manifest）、5 个斜杠命令、3 个自动触发钩子、1 个 MCP 服务器和 3 个 Agent Skill 的形式组织，全部位于仓库的 .claude-plugin 目录。

从该目录的元数据文件可以看到插件的完整自描述结构：

• .claude-plugin/plugin.json：插件核心清单，name 为 mempalace（当前仓库内版本为 3.8.0），license 为 MIT，mcpServers 字段声明了一个名为 mempalace 的本地 MCP 服务器，启动命令是 mempalace-mcp；keywords 覆盖 memory/ai/rag/mcp/chromadb/palace/search 等检索关键词。
• .claude-plugin/marketplace.json：插件市场清单，owner.name 与 plugins[].source 指向 .claude-plugin，供 claude plugin marketplace add 使用。
• .claude-plugin/.mcp.json：MCP 服务器别名清单，同样把 mempalace 指向 mempalace-mcp 命令，是本地工作区级 MCP 注册的入口。

一句话总结插件的分工：斜杠命令负责引导用户完成安装/挖掘/搜索/体检，钩子负责在会话生命周期内自动保存上下文，MCP 服务器负责把记忆读写能力暴露给模型，skill 负责告诉模型"按什么协议使用这些能力"。

环境前提

根据 .claude-plugin/README.md，安装插件仅需一个硬性前提：

• Python 3.9 及以上

注意该插件依赖的 mempalace Python 包本身并未随插件捆绑分发，而是由 /mempalace:init 阶段通过 uv tool 或 pip 按需安装（见下文初始化章节），因此宿主环境需要在 PATH 上能找到 uv 或一个可见的 Python 3.9+ 解释器。

安装插件：两种途径

方式一：通过 Claude Code Marketplace

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

--scope user 表示对当前用户全局生效，而不是只对某个项目生效，这与"跨项目共享记忆"的设计目标一致。该命令对应仓库中 .claude-plugin/marketplace.json 描述的市场插件元数据。

方式二：本地克隆直接添加

如果你已经克隆了本仓库，可以直接以本地路径注册插件：

claude plugin add /path/to/mempalace

其中 /path/to/mempalace 应指向本仓库的克隆根目录。两种方式安装完成后都会获得同样的 5 个命令、3 个钩子与 skill 集。

安装后的初始化：/mempalace:init

插件安装成功并不代表记忆系统已可用——mempalace Python 包与 MCP 服务器还需要配置。官方流程要求在安装插件后运行一次初始化命令完成收尾：

/mempalace:init

该命令会依次完成：安装 mempalace 包（优先 uv tool install mempalace，uv 不可用时回退到 python -m pip install mempalace）、初始化本地宫殿（palace）、配置 MCP 服务器并验证一切可用。

从命令定义文件 .claude-plugin/commands/init.md 可以看出斜杠命令的真实执行方式：每条命令本身只是一段带 front matter 的提示词，内容是"Invoke the generic mempalace skill（通过 Skill 工具）并携带 init 命令，然后遵循其指令"。也就是说，斜杠命令→Skill→CLI 是一条分层的调用链，命令本身不含任何硬编码的 shell 逻辑，全部行为由 skill 与 CLI 动态决定。

初始化背后的 Skill 协议

真正承载初始化逻辑的是通用技能 .claude-plugin/skills/mempalace/SKILL.md，它定义了 7 步安装协议，值得逐条理解：

1. 先检查再动手：探测 OS 与宿主 harness；运行 mempalace --version、uv --version 与 Python 版本检查（不能假设已安装的包一定在 PATH 上）；检查是否已存在宫殿与 MCP 注册——绝不为了图省事而重新初始化或重建已有宫殿。
2. 按需安装 CLI：优先隔离的 uv tool install mempalace；uv 不可用时用 PATH 可见的 Python 执行 python -m pip install mempalace；装完必须用 mempalace --version 验证。
3. 与用户确认拓扑：a) 私有本地宫殿（单机 + stdio MCP）；b) shared-brain hub（本机拥有宫殿并为多 Agent 提供服务）；c) 加入既有 hub 的客户端。客户端不应在本机再初始化一份宫殿副本。
4. 执行与版本匹配的初始化：MemPalace 通过 CLI 提供"随版本动态更新、永远正确"的指令，即 mempalace instructions <command>，其中 <command> 取值 help/init/mine/search/status。
5. 配置 MCP：stdio 集成使用 mempalace mcp 打印的命令注册。
6. 配置 shared-brain 身份与协调（仅共享大脑模式）。
7. 报告就绪状态：汇总版本号、宫殿位置/hub URL（不含密钥）、MCP 连接、稳定 Agent 身份、watcher 模式与首个安全的下一步动作。

其中 mempalace instructions 机制的底层实现位于 mempalace/instructions_cli.py：它把每条指令保存为包内 instructions/ 目录的 Markdown 文件（仓库根目录另有配套的 commands 目录，文件名一一对应，例如 commands/mempalace-init.md），CLI 只负责读取并原样打印；AVAILABLE = ["init", "search", "mine", "help", "status"] 定义了合法取值，未知命令会直接报错退出。这意味着 skill 永远执行的是与当前安装版本匹配的说明文字，而不是仓库里可能过期的静态脚本。

5 个斜杠命令

安装完成后，Claude Code 会话内可用下表 5 个命令：

命令	说明
/mempalace:help	展示可用的工具、技能与架构
/mempalace:init	初始化 MemPalace——安装、配置 MCP、引导上手
/mempalace:search	跨整个宫殿搜索你的记忆
/mempalace:mine	把项目和对话挖掘进宫殿
/mempalace:status	展示宫殿概览——翼（wings）、房间（rooms）、抽屉（drawers）计数

每个命令在其定义文件里都声明了参数提示与允许使用的工具白名单，这构成了"命令能做什么"的边界：

• .claude-plugin/commands/help.md：allowed-tools: Bash, Read，纯展示类。
• .claude-plugin/commands/init.md：allowed-tools: Bash, Read, Write, Edit, Glob, Grep，需要读写与文件操作。
• .claude-plugin/commands/mine.md：参数提示为"要挖掘的项目或对话导出路径"，支持项目文件、对话导出与自动分类，同样开放 Bash, Read, Write, Edit, Glob, Grep。
• .claude-plugin/commands/search.md：参数提示为"搜索查询词，可附带 wing/room 过滤器"，只需 Bash, Read。
• .claude-plugin/commands/status.md：展示翼/房间/抽屉计数与建议，只需 Bash, Read。

搜索与挖掘命令背后的语义

/mempalace:search 与 /mempalace:mine 并不只是包一层 CLI。从配套的 recall 技能 .claude-plugin/skills/mempalace-recall/SKILL.md 可以看到，搜索遵循"先搜后答（search-before-answer）"协议：

• 当用户问及过往工作、之前决定、某个人的身份、上次讨论过的话题时，Agent 必须先调用 mempalace_search（可通过 wing/room 过滤并指定 limit，默认 5），而不是用模型记忆直接作答；
• 关系型/带时间限制的事实用 mempalace_kg_query，单值事实的更替用 mempalace_kg_supersede，已结束且无替代的事实用 mempalace_kg_invalidate，独立共存事实用 mempalace_kg_add；
• 返回结果必须逐字引用抽屉里的原文，不得转述或概括——这是该系统"verbatim recall"的设计初衷；
• 反过来，纯绿地任务（如"重命名变量"）不应触发搜索，以免浪费每次请求的延迟，破坏"记忆应感觉即时"的预算。

该技能还定义了异常路径的处理：搜索为空时如实告知并建议放宽 wing 过滤或录入新信息；MCP 未连接时不静默降级为凭模型记忆作答，而是提示用户运行 mempalace status 或重新执行初始化。

自动钩子：会话生命周期的三次自动保存

MemPalace 注册了三个自动运行的钩子，钩子清单定义在 .claude-plugin/hooks/hooks.json：

• Stop——每 15 条消息保存一次会话上下文（timeout 30s）。
• SessionEnd——在正常退出时于后台执行最后一次保存（timeout 10s），确保那些从没达到 Stop 间隔也没触发压缩的短会话仍被捕获。
• PreCompact——在上下文压缩（compaction）前保留重要记忆（timeout 90s）。

三个钩子在 hooks.json 中都以 type: "command" 注册，执行的命令格式统一为 bash "${CLAUDE_PLUGIN_ROOT}/hooks/mempal-*-hook.sh"，其中 CLAUDE_PLUGIN_ROOT 是 Claude Code 注入的插件根目录环境变量，保证脚本无论插件克隆到何处都能被正确定位。

钩子脚本：薄封装 + 统一 CLI 入口

插件钩子脚本本身是"薄封装"。以 Stop 钩子 .claude-plugin/hooks/mempal-stop-hook.sh 为例，脚本依次尝试三种执行方式：

1. PATH 上存在 mempalace 命令 → 执行 mempalace hook run --hook stop --harness claude-code；
2. 否则若 python3 可导入 mempalace 模块 → python3 -m mempalace hook run ...；
3. 否则若 python 可导入 → python -m mempalace hook run ...；
4. 都失败则打印错误并返回非零退出码。

真正的钩子逻辑全部收敛在 Python 侧 mempalace.hooks_cli 中。从 mempalace/hooks_cli.py 的函数定义可以看到与钩子类型一一对应的处理器：hook_stop（第 1305 行）、hook_session_end（第 1464 行）、hook_precompact（第 1564 行），所有处理器都以 harness 参数标识宿主（这里是 claude-code），以实现"跨 harness 复用同一套逻辑"的扩展性——这正是脚本注释里"All logic lives in mempalace.hooks_cli for cross-harness extensibility"的含义，仓库中同构的 Cursor/Antigravity 钩子都共享这条调用链。

用 MEMPAL_DIR 触发目录自动挖掘

钩子还提供一个可选的环境变量开关：设置 MEMPAL_DIR 环境变量为某个目录路径后，每次保存触发时都会自动对该目录执行 mempalace mine。这让钩子从"只保存会话上下文"升级为"连项目文件一起入库"，适合把日常工作的项目目录常驻挖掘，例如：

export MEMPAL_DIR=/path/to/your/active/project

MCP 服务器：45 个工具免手动配置

插件会自动配置一个本地 MCP 服务器，暴露 45 个工具，覆盖记忆的存储、搜索、管理以及 Agent 任务协调。无需手动配置 MCP——/mempalace:init 会全权处理。注册到 Claude Code 的服务器命令是 mempalace-mcp，这一声明同时存在于 .claude-plugin/plugin.json 的 mcpServers 字段与 .claude-plugin/.mcp.json 中，即插件级与工作区级两份 MCP 声明都指向同一个可执行命令。

skill 协议对此有一个重要提醒：包安装成功不等于 MCP 已连接。stdio 集成注册命令由 mempalace mcp 打印；典型的手工注册形如：

claude mcp add mempalace -- mempalace-mcp

对 shared-brain hub 拓扑，则走 HTTP MCP 传输（对应 mempalace serve），客户端加入既有 hub 时需携带 bearer token 配置 harness 的 HTTP MCP 传输，且 token 严禁写入项目指令、抽屉或 logstream 事件。配置完重启或重连 harness 后，必须确认实时工具列表里已出现 mempalace_* 工具才算连通。

三个内置 Skill 的分工与共享大脑配置

插件随附三个 Agent Skill，对应记忆系统的三个职能：

Skill	定位	仓库路径
mempalace	安装、配置、挖掘与状态维护的通用引导技能，init/mine/status 命令的执行后端	.claude-plugin/skills/mempalace/SKILL.md
mempalace-recall	"先搜后答"的召回协议，覆盖人员/项目/历史决定类提问	.claude-plugin/skills/mempalace-recall/SKILL.md
mempalace-task	任务委派与协调（shared-brain 场景下的活动委派交接）	.claude-plugin/skills/mempalace-task/SKILL.md

当选用 shared-brain（共享大脑）模式时，setup 技能要求完成一套严谨的身份与协调配置：

• 为每个 Agent 约定一个稳定的 <machine>-<harness> 身份；
• 用 mempalace rules --agent <machine-harness> 渲染规范规则，并将带 HTML 注释标记（marker）的规则块安装进宿主 Agent 的持久指令中——已有标记块时替换而非追加。该标记机制的源码实现同样位于 mempalace/instructions_cli.py：输出包裹在 <!-- mempalace-shared-brain:start/end --> 标记之间，便于后续重新渲染时原位替换，规则正文从 shared_brain_rules.md 模板渲染并将 <AGENT_ID> 占位符替换为真实身份；--agent 参数仅接受 [A-Za-z0-9._-]+ 形式的单一 token，从根上防止注入；
• 用只读的 mempalace logstream list（或 MCP 事件列表）验证协调通道可用；
• 确认宿主能否维持后台 watcher：能则使用 mempalace logstream watch --agent ... --state-file ...（本地宫殿拥有者或同步副本）；纯远端 MCP 客户端则必须改用重复的 mempalace_event_wait 调用并以上次事件 id 作为 since_event_id；若两者都不行，则记录该 Agent 为"轮次制"，在每次唤醒时用 mempalace_event_list 清扫 MCP 收件箱。

此外，日志流事件（logstream events）不可变，因此除非用户批准，否则不得擅自发布测试事件。

更新策略与正确的健康检查方式

setup 技能还规定了版本升级的纪律：默认不开启每周稳定版检查（开启会联系 PyPI 但不上传任何宫殿内容、身份或遥测）；开启时用 mempalace update configure --enable --installer uv-tool（或 pipx/pip）记录实际安装器，用 --disable 退出。检查只报告、绝不自动安装。在 mempalace_status 输出里，updates.server 指提供宫殿服务的运行时、updates.client 指本地代理运行时，二者版本与安装器不能混淆；客户端只能使用本地 mempalace update plan，远端服务器的升级计划仅作展示，需由 hub 运营者在承载宫殿的机器上另行准备与授权——绝不能用客户端生成的计划升级服务器，也绝不能未经明确批准执行任何计划。

日常健康检查的推荐入口包括：

mempalace status           # 查看翼/房间/抽屉、服务与更新状态
mempalace --version        # 确认 CLI 可执行且版本正确
claude mcp list            # 确认 mempalace 服务器已注册

若 MCP 工具缺失，优先复跑 /mempalace:init 或 mempalace status 诊断，而不是猜测。

更进一步：主文档与其他集成

本文所有安装、命令、钩子与 MCP 内容都可在仓库中一一对照验证。插件的完整架构说明、高级用法与 Python 包文档，请参见仓库根目录的 README；hooks.json 的三种钩子声明见 .claude-plugin/hooks/hooks.json；同样基于"薄钩子封装 + Python 统一入口"模式的 Cursor/Antigravity 钩子实现位于 hooks 目录，可作为跨编辑器扩展的对照参考。把插件理解为一套"命令引导 + 钩子自动保存 + MCP 读写 + Skill 约束行为"的四层装配，你就能在任何新的宿主环境中快速复现这套持久记忆能力。