MemPalace /mempalace:init 命令全解：从安装、初始化到 MCP 接入的完整配置流程

/mempalace:init 是 MemPalace 为 Claude Code 等 Agent 插件体系提供的斜杠命令，负责一次性完成"安装 Python 包 → 初始化记忆宫殿（palace）→ 注册 MCP 服务器 → 验证可用"的引导式搭建。本文基于仓库中该命令的定义文件 init.md 及其调用的 mempalace skill、init 指令集 与 CLI 源码，完整拆解这个命令的三层分派机制、全部初始化步骤、参数与命令用法，以及背后的实现依据，读完即可独立完成一次可复现的 MemPalace 初始配置。

一、命令本体：一个薄分派器及其 Frontmatter

.claude-plugin/commands/init.md 的全文只有两部分：YAML frontmatter 和一句正文。frontmatter 定义了命令的元信息：

---
description: Set up MemPalace — install the package, initialize a palace, configure MCP server, and verify everything works.
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
---

• description 明确了该命令的职责边界：安装包、初始化宫殿、配置 MCP 服务器、验证一切可用；
• allowed-tools: Bash, Read, Write, Edit, Glob, Grep 声明了执行该命令时 Agent 被允许调用的工具集——初始化过程需要跑 shell 命令（安装、init、status）、读写配置文件（MCP 注册）、按模式检索文件，因此授权面比只读命令（如 status.md 仅允许 Bash, Read）更宽。

正文仅一行：

Invoke the generic mempalace skill (using the Skill tool) with the init command, then follow its instructions.

这句话揭示了 MemPalace 插件的命令设计模式：命令文件本身不承载具体步骤，而是一个"薄分派器"（thin dispatcher）——它指示 Agent 通过 Skill 工具调用通用的 mempalace skill 并传入 init 参数，然后严格跟随 skill 返回的指令执行。同系列的 mine.md、status.md、help.md 全部采用同一模式。

这样设计的好处是：具体操作步骤只需在 skill 与动态指令中维护一份，命令文件保持稳定；同时步骤可以通过 mempalace instructions 随包版本动态下发（见下文第三节），避免插件文档与实际安装的包版本脱节。

二、三层分派链：command → skill → 动态指令

执行 /mempalace:init 后，实际行为由三层文件接力完成：

1. 命令层 init.md：触发 mempalace skill 的 init 模式；
2. skill 层 SKILL.md：定义完整的 7 阶段 Setup 协议，其中第 4 步要求运行 mempalace instructions init 获取"与当前包版本匹配"的初始化指令；
3. 指令层 mempalace/instructions/init.md：随 Python 包分发的 8 步具体初始化流程，是真正落地执行的步骤清单。

skill 层（SKILL.md）在指令层之外还规定了两个前置约束，值得注意：

• 先检查再动手：先探测操作系统与 Agent 运行环境，运行 mempalace --version、uv --version 及 Python 版本检查，并明确"不要假设已安装的 Python 包在 PATH 上可见"；若已存在宫殿与 MCP 注册，绝不为了简化操作而重新初始化或重建已有宫殿；
• 拓扑三选一：初始化前应与用户确认目标形态——① 单机私有宫殿（本地 stdio MCP）；② 共享大脑 hub（本机持有宫殿并为整个 agent 舰队服务）；③ 客户端加入已有 hub（不初始化第二份宫殿副本，而是向用户索取 hub URL 与 bearer token，且 token 严禁打印或写入项目指令、drawers、logstream 事件）。

三、mempalace instructions init：版本匹配的指令下发机制

skill 第 4 步的核心命令是：

mempalace instructions <command>    # <command> ∈ {help, init, mine, search, status}

该子命令在 cli.py 中的入口为 cmd_instructions，内部委托 instructions_cli.run_instructions 读取指令模板并输出到 stdout：

def cmd_instructions(args):
    """Output skill instructions to stdout."""
    from .instructions_cli import run_instructions
    run_instructions(name=args.name)

指令模板即仓库中的 mempalace/instructions/init.md（同目录还有 help.md、mine.md、search.md、status.md）。由于指令随已安装的包版本一起下发，"运行 mempalace instructions init 然后逐步执行"保证了即便包升级改变了命令参数或流程，Agent 拿到的也是与运行时版本一致的步骤——这正是 skill 层称之为 "version-correct instructions" 的原因。

四、初始化八步流程详解（instructions/init.md）

以下是 mempalace/instructions/init.md 定义的标准流程，执行原则是"按序推进，遇错先报告并尝试修复再继续"。

Step 1：确认 Python 版本 ≥ 3.9

运行 python3 --version（Windows 用 python --version），确认版本不低于 3.9，否则要求用户先安装 Python 3.9+ 并停止。这一下限不是随手写的：pyproject.toml 中声明 requires-python = ">=3.9"，且代码库多处针对 3.9 兼容做了显式处理（例如 entity_detector.py 注释说明避免 dict | None 以兼容 3.9、date_window.py 处理 3.9/3.10 上无 fromisoformat Z 后缀解析的日期值、mcp_server.py 在 3.9 上使用 Optional[dict] 以避免导入期求值问题），可以确认 3.9 是贯穿构建与运行时的硬性基线。

Step 2：检查 mempalace 是否已安装（含关键陷阱）

运行 mempalace --version：

• 成功：CLI 在 PATH 上，报告版本号并跳到 Step 4；
• 失败：不能因为 pip show mempalace 或 uv tool list 显示已安装就跳过安装——包可能装在未激活的 venv 里，此时 Step 5 的 mempalace init 会直接 command not found。这种情况按"未安装"处理，进入 Step 3 重新安装到 PATH 可见的位置。

Step 3：安装 mempalace

优先使用隔离式 uv 工具安装（把 CLI 与系统 Python 隔离，规避大多数环境相关问题）：

uv tool install mempalace        # uv 在 PATH 上时
pip install mempalace            # 否则

安装失败时按以下顺序回退：

1. uv tool install 失败则试 pip install mempalace（反之亦然）；
2. 试 pip3 install mempalace；
3. 试 python -m pip install mempalace（或 python3 -m pip）；
4. 若报错涉及缺少构建工具或编译失败（常见于 chromadb 及其原生依赖）：
   • Linux/macOS：sudo apt-get install build-essential python3-dev（Debian/Ubuntu）或 xcode-select --install（macOS）；
   • Windows：安装 Microsoft C++ Build Tools；
   • 然后重试安装；
5. 全部失败则清晰报告错误并停止。

Step 4：确认项目目录

询问用户要用哪个项目目录初始化，默认建议当前工作目录，等待用户确认后再继续。被初始化的目录将作为要挖掘（mine）的语料来源。

Step 5：初始化宫殿

mempalace init --yes <dir>

--yes 跳过交互式确认；<dir> 为 Step 4 确定的目录。此步失败则报告错误并停止。该命令在 cli.py 中对应 cmd_init 处理器。

Step 6：配置 MCP 服务器

按用户所用 AI 客户端执行对应注册命令：

# Claude Code
claude mcp add mempalace -- mempalace-mcp

# Codex CLI
codex mcp add mempalace -- mempalace-mcp

此步失败只报告、不中断（MCP 可以之后手动配置）。补充两点仓库佐证：

• 插件清单 plugin.json 已内置 MCP 服务器声明（"mcpServers": { "mempalace": { "command": "mempalace-mcp" } }），因此 Cursor 插件场景下 mempalace-mcp 会被插件自动注册，无需手改 mcp.json（见 commands/mempalace-init.md 的 Cursor 专属说明）；
• 仓库根目录另提供 mcp.json 与 examples/mcp_setup.md 作为手工接入参考。

Step 7：验证安装

mempalace status

确认输出显示宫殿健康。失败则依据输出逐项排障。

Step 8：后续操作

宣告设置完成，并建议两个自然下一步：

• 用 /mempalace:mine 开始向宫殿灌入数据（项目文件、对话导出，自动分类）；
• 用 /mempalace:search 查询宫殿、检索已存知识。

五、共享大脑场景的额外配置（skill 层第 5–7 步）

当拓扑选择涉及多机协作时，SKILL.md 还规定了三段 init 流程之外的配置：

1. MCP 传输形态。本地 stdio 场景使用 mempalace mcp 打印的命令注册；hub 场景引导用户执行 mempalace serve，并强调"非回环地址暴露的服务必须先配认证"；客户端场景则配置 harness 的 HTTP MCP 传输并注入 bearer token。关键验收标准是：重启/重连 harness 后，实时 MCP 工具列表中必须能看到 MemPalace 工具——"仅安装成功不能证明 MCP 已连通"。

2. 共享大脑身份与协调。为 agent 约定一个稳定的 <machine>-<harness> 身份，用

mempalace rules --agent <machine-harness>

渲染出带标记分隔符的规范规则块，安装进 harness 的持久 agent 指令（替换已有标记块而非重复追加）。随后用只读的 mempalace logstream list（或等价 MCP 事件列表调用）验证协调通道。若 harness 能维护后台 watcher，则准备 mempalace logstream watch --agent ... --state-file ...；纯远程 MCP 客户端则必须用反复 mempalace_event_wait 并把最后事件 id 保存为 since_event_id（切勿指向本地 SQLite watcher）。两者都不能维持时，记录该 agent 为回合制，唤醒时用 mempalace_event_list 清扫收件箱。另有一条安全红线：未经用户告知不得发布测试事件——logstream 事件不可变；若用户批准冒烟事件，需限定范围并以确认事件闭环。

3. 就绪报告。汇总：已装版本、宫殿位置或 hub URL（不含密钥）、MCP 连接状态、稳定 agent 身份、watcher 模式，以及第一个安全的下一步。对于激活的委托任务，移交 mempalace-task skill。skill 层还要求询问用户是否启用每周稳定版检查（默认否），启用时用 mempalace update configure --enable --installer uv-tool（或 pipx/pip）记录实际安装器；检查只联系 PyPI、不上传任何宫殿内容/身份/遥测数据，且永不自动安装。

六、Cursor 场景差异与验证清单

SKILL.md 末尾给出了 Cursor 专属注意事项，可整理成一张 init 完成后的验证清单：

检查项	做法	依据
CLI 可达	mempalace --version 成功	instructions/init.md Step 2
宫殿健康	mempalace status 无错误	Step 7
MCP 工具可见	重连 harness 后核对实时工具列表	SKILL.md 第 5 步
Cursor 自动保存	从克隆的仓库执行 hooks/cursor/install.sh --scope user，参考 website/guide/cursor-hooks.md	commands/mempalace-init.md
日记写入身份	Cursor 会话调用 mempalace_diary_write 时 agent_name 推荐 cursor-ide（与 claude-code、codex 先例一致）	SKILL.md Cursor 说明

七、小结

/mempalace:init 的命令文件本身只是一个声明了工具授权并分派到 mempalace skill 的薄入口，真正的工作量分布在三个可审计的仓库位置：skill 层的 7 阶段协议（.claude-plugin/skills/mempalace/SKILL.md）、随包下发的 8 步初始化指令（mempalace/instructions/init.md，经 cli.py 的 instructions 子命令动态输出）、以及 mempalace init --yes <dir> 等命令的 CLI 实现（mempalace/cli.py#L298）。按"先检查 PATH 可见性、再隔离安装、按序执行八步、以 status 与实时 MCP 工具列表双重验证"的节奏操作，即可在当前仓库 3.8.0 版本（pyproject.toml 中 version = "3.8.0"，Python ≥ 3.9）上完成一次干净、可重复的 MemPalace 初始配置。