MemPalace Init 技能：在 Codex 插件中引导式初始化 AI 记忆宫殿

MemPalace 的 /init 技能（init/SKILL.md）是 Codex CLI 插件的引导式入门入口：它把一条 CLI 命令 mempalace instructions init 展开成完整的 8 步初始化流程——从 Python 版本检查、CLI 安装、宫殿创建，到 MCP 服务器注册与安装验证。读完本文，你将掌握如何在任意 AI 客户端中完成 MemPalace 的从零搭建，并理解每一步背后 mempalace/cli.py 与 mempalace/instructions_cli.py 的源码实现机制。

技能本体：一条命令拉取完整引导流程

.codex-plugin/skills/init/SKILL.md 的内容极简，这是刻意为之的插件技能设计模式——技能文件本身不写死流程，而是要求 Agent 执行：

mempalace instructions init

并逐步遵循返回的指令。这样做的好处是指令文本（mempalace/instructions/init.md）随 PyPI 包版本更新，插件技能永远指向最新版流程，无需重新分发技能文件。

从源码看，这条命令的链路是：CLI 子命令解析（mempalace/cli.py 中 cmd_instructions 调用 instructions_cli.run_instructions），后者按 AVAILABLE = ["init", "search", "mine", "help", "status"] 校验名称，然后原样打印 mempalace/instructions/ 目录下对应的 Markdown 文件（mempalace/instructions_cli.py）。也就是说，Agent 拿到的就是随包分发的 instructions/init.md 全文。

该技能属于 Codex 插件 mempalace 的五个技能之一（/help、/init、/search、/mine、/status），插件元数据在 .codex-plugin/plugin.json 中声明，其中 skills 字段指向 ./skills/ 目录。技能文件 frontmatter 还声明了 allowed-tools: Bash, Read, Write, Edit，即执行初始化只依赖这四个工具。

8 步初始化流程详解

以下完整继承 mempalace/instructions/init.md 的引导步骤，并补充源码级佐证。

Step 1：检查 Python 版本

运行 python3 --version（Windows 上为 python --version），确认版本 ≥ 3.9。若 Python 缺失或版本过低，提示用户安装 Python 3.9+ 并停止。这与 .codex-plugin/README.md 中的前置条件（Prerequisites: Python 3.9+）一致。

Step 2：检查 mempalace 是否已安装

运行 mempalace --version。成功则报告已安装版本并跳到 Step 4。

这里有一条重要的反直觉规则：如果 mempalace --version 失败，不能仅凭 pip show mempalace 或 uv tool list 报告已安装就跳过安装——包可能装在一个未激活的 venv 里，此时 Step 5 的 mempalace init 会因 command not found 失败。这种情况应视为未安装，继续 Step 3，用 uv tool install 或 pip 重新安装到 PATH 可见的位置。

Step 3：安装 mempalace

优先使用 uv——它把 CLI 与系统 Python 隔离，能避免多数环境问题：

1. 若 PATH 上有 uv（uv --version），运行 uv tool install mempalace；
2. 否则运行 pip install mempalace。

安装失败的降级顺序（按序尝试）：

1. uv tool install 失败则试 pip install mempalace（或反过来）；
2. 试 pip3 install mempalace；
3. 试 python -m pip install mempalace（或 python3 -m pip install）；
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：询问项目目录

询问用户要把哪个项目目录初始化为 MemPalace 宫殿，默认提供当前工作目录，等待用户回复后再继续。

Step 5：初始化宫殿

运行 mempalace init --yes <dir>，<dir> 来自 Step 4。失败则报告错误并停止。

cmd_init 的实现位于 mempalace/cli.py，其中几个关键行为值得了解：

• --palace 指定宫殿位置：若用户传了 --palace，init 会将其解析为绝对路径并写入环境变量 MEMPALACE_PALACE_PATH，使后续所有 cfg.palace_path 读取（Pass 0、cfg.init()、post-init mine）都路由到用户指定位置；不传时默认 ~/.mempalace（源码注释对应 issue #1313）。
• LLM 实体检测默认开启：--llm 默认 ON，--no-llm 是显式退出开关；提供商优先级为 Ollama 本地优先，其次 openai-compat、再是 anthropic。没有任何 LLM 可用时不会阻塞 init，只打印一行提示并回退到纯启发式检测。
• 外部 LLM 隐私保护：若配置的端点会向外部发送数据，init 会打印警告说明内容将发送到该提供商；当 API key 来自环境变量而非显式 --llm-api-key 时，还会弹出同意确认（y/N），可用 --accept-external-llm 在 CI/非交互场景跳过。
• Git 仓库自动 .gitignore 保护：若目标目录是 git 仓库，_ensure_mempalace_files_gitignored 会把 MemPalace 的每项目文件（mempalace.yaml、entities.json 等）追加进 .gitignore，防止被误提交（源码注释对应 issue #185）。

init 还会做实体/房间发现（discover_entities、detect_rooms_local），并可检测语料是否为 AI 对话并写入 .mempalace/origin.json。

Step 6：配置 MCP 服务器

按用户正在配置的 AI 客户端执行对应命令：

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

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

若失败，报告错误但继续下一步（MCP 配置可以稍后手动完成）。mempalace-mcp 脚本由 Python 包安装后落到 PATH 上；.codex-plugin/README.md 特别提示：仅 uv sync 不够——它把脚本装进 .venv/bin/，Codex 不激活 venv 就找不到，所以 git 安装方式应使用 uv tool install --editable .。

Step 7：验证安装

运行 mempalace status，确认输出显示健康（healthy）的宫殿；若失败或报告错误，则根据输出引导用户排障。

Step 8：展示后续步骤

告知用户设置完成，并建议两个后续动作：

• 用 /mempalace:mine 开始向宫殿添加数据；
• 用 /mempalace:search 查询宫殿并检索已存知识。

插件级视角：init 技能在插件中的位置

/init 只是 Codex 插件体验的起点。.codex-plugin/README.md 描述了插件整体：把项目与会话挖掘成由 ChromaDB 支撑的可搜索宫殿，提供 44 个 MCP 工具、自动保存 hooks 与引导式技能。安装路径有两条：

• 本地安装：把 .codex-plugin 目录复制或软链到项目根，用 codex --plugins 验证被检测，然后 codex /init 初始化宫殿；
• Git 安装：克隆仓库后 uv tool install --editable .（或 pip install -e .），在仓库内运行 Codex 会自动检测根目录的 .codex-plugin，再执行 codex /init。

插件还包含 hooks 机制（.codex-plugin/hooks.json）：SessionStart、Stop、PreCompact 三个事件都调用 mempal-hook.sh 的对应子命令，在会话停止（每 15 条消息）与上下文压缩前自动把对话上下文存入宫殿；设置环境变量 MEMPAL_DIR 指向某目录后，每次保存触发时还会自动对该目录执行 mempalace mine。

小结

MemPalace 的 init 技能把“首次搭建”沉淀为一份随包分发、版本可控的引导脚本：技能文件负责触发 mempalace instructions init，instructions/init.md 负责 8 步流程（版本检查 → 安装检查 → 安装 → 选目录 → mempalace init --yes → MCP 注册 → mempalace status 验证 → 后续动作），而 cmd_init 的源码保证了 LLM 检测可优雅降级、外部 API 有隐私闸门、git 仓库有 .gitignore 自动保护。按此流程走完后，宫殿即就绪，可以直接进入 /mine 与 /search 的日常使用循环。