MemPalace Codex CLI 插件实战：为 Codex 配置持久记忆、MCP 工具与自动保存钩子

本文基于 MemPalace 仓库中的 Codex CLI 插件目录 .codex-plugin/ 展开，完整覆盖插件的安装方式、五个内置 Skill 的工作机制、SessionStart / Stop / PreCompact 三类钩子的调用链路，以及 MEMPAL_DIR 环境变量的语义。读完后，你可以把 MemPalace 以插件形式接入 Codex CLI，实现“会话结束与上下文压缩前自动入馆、语义检索所有已挖掘记忆”的完整闭环。

插件总览与目录结构

MemPalace 的 Codex 插件将“项目与对话挖掘 → ChromaDB 向量存储 → 44 个 MCP 工具 → 自动保存钩子 → 引导式 Skill”打包在仓库根目录的 .codex-plugin/ 下。官方 README 的一句话定位是：

Give your AI a persistent memory — mine projects and conversations into a searchable palace backed by ChromaDB, with 44 MCP tools, auto-save hooks, and guided skills.

当前目录的完整布局如下：

.codex-plugin/
├── README.md                  # 插件说明文档
├── plugin.json                # 插件清单（name / version / skills / mcpServers / interface）
├── hooks.json                 # 钩子注册表（SessionStart / Stop / PreCompact）
├── hooks/
│   └── mempal-hook.sh         # 钩子入口脚本，桥接到 `mempalace hook run`
└── skills/
    ├── help/SKILL.md
    ├── init/SKILL.md
    ├── mine/SKILL.md
    ├── search/SKILL.md
    └── status/SKILL.md

其中 plugin.json 是插件清单，关键事实包括：

• 插件名为 mempalace，当前版本 3.8.0，许可证 MIT，关键字包含 memory、rag、mcp、chromadb 等；
• "skills": "./skills/"：告诉 Codex CLI 从该目录发现 Skill；
• "mcpServers": "./.mcp.json"：声明 MCP 服务配置入口，插件运行时由此拉起 mempalace-mcp 进程；
• interface 段定义了展示名 MemPalace、分类 Coding、能力位 Interactive / Read / Write，以及三条默认提示词（如 “Mine this project into my memory palace”），这些会出现在 Codex 的插件选择界面中。

该 manifest 的结构在测试中受到校验，参见 tests/test_codex_plugin_manifest.py，保证清单字段不漂移。

前置条件

按 README 的 Prerequisites 一节，使用前需要准备：

1. Python 3.9+；
2. 已安装并配置好的 Codex CLI；
3. MemPalace Python 包，推荐：

uv tool install mempalace
# 或
pip install mempalace

之所以要求脚本必须在全局 PATH 上，是因为 plugin.json 与钩子脚本都以裸命令名调用 mempalace / mempalace-mcp，而不是相对 venv 路径。

安装方式一：本地安装（复制目录到目标项目）

适合把插件带入任意现有项目，共三步：

# 1. 将 .codex-plugin 目录复制（或软链）到目标项目根目录
cp -r .codex-plugin /path/to/your/project/.codex-plugin

# 2. 验证插件被 Codex 发现
codex --plugins

# 3. 初始化你的记忆宫殿（palace）
codex /init

Codex CLI 的插件发现机制是扫描项目根目录下的 .codex-plugin/，读到 plugin.json 后注册其中声明的 Skill 与钩子，因此复制即生效，无需额外的注册命令。codex --plugins 输出中应能看到 mempalace 条目，作为检测成功的依据。

安装方式二：Git 安装（从源码检出）

如果直接从 MemPalace 仓库检出使用，README 给出了一条容易踩坑的注意事项：

git clone <MemPalace 仓库地址>
cd mempalace

# 以可编辑方式安装，使 mempalace-mcp 脚本落到 PATH 上
uv tool install --editable .    # 或：pip install -e .

# 在仓库内启动 Codex，.codex-plugin 位于仓库根，会被自动发现
codex /init

README 特别强调：普通的 uv sync 在这里不够用 —— 它只会把脚本装进 .venv/bin/，而 Codex 进程不会激活该 venv，于是找不到 mempalace-mcp。用 uv tool install --editable . 或 pip install -e . 安装，脚本会落到全局工具环境，与 plugin.json 的裸名调用方式保持一致。

五个内置 Skill：对 instructions 的薄封装

插件自带 5 个斜杠命令（README 中的 Available Skills 表）：

Skill	作用
/help	显示可用命令与使用技巧
/init	初始化一个新的记忆宫殿
/search	跨所有已挖掘记忆做语义检索
/mine	把一个项目或会话挖掘入馆
/status	显示宫殿状态、房间数量与健康度

深入每个 Skill 文件会发现一个统一模式：SKILL.md 只是极薄的引导层，真正的“说明书”由 CLI 现取。以 init 的 SKILL.md 为例，其 frontmatter 声明了 name: init、用途描述和 allowed-tools: Bash, Read, Write, Edit，正文只有一条指令：

mempalace instructions init

并要求 Agent “follow the returned instructions step by step”（逐步遵循返回的指令）。其余四个 Skill（help、search、mine、status）结构完全一致，分别调用 mempalace instructions help|search|mine|status。

这种设计的收益在于：Skill 指令的维护集中在 mempalace/instructions/ 目录下的一组 Markdown 中（init.md、mine.md、search.md、status.md、help.md），由 instructions_cli.py 负责渲染输出。升级 MemPalace 包即可让所有 Skill 的引导话术同步更新，而插件目录本身几乎不需要改动。同时 allowed-tools 字段做了最小授权：例如 mine 额外开放了 Glob, Grep 以便扫描文件，而 help / status 只允许 Bash, Read。

自动保存钩子：三条触发链路

钩子注册：hooks.json

.codex-plugin/hooks.json 注册了三个 Codex 生命周期事件，全部使用 matcher: "*"（无条件命中），命令形如：

"hooks": {
  "SessionStart": [ { "matcher": "*", "hooks": [
    { "type": "command",
      "command": "\"${CODEX_PLUGIN_ROOT}/hooks/mempal-hook.sh\" session-start" } ] } ],
  "Stop":       [ { "matcher": "*", "hooks": [
    { "type": "command",
      "command": "\"${CODEX_PLUGIN_ROOT}/hooks/mempal-hook.sh\" stop" } ] } ],
  "PreCompact": [ { "matcher": "*", "hooks": [
    { "type": "command",
      "command": "\"${CODEX_PLUGIN_ROOT}/hooks/mempal-hook.sh\" precompact" } ] } ]
}

${CODEX_PLUGIN_ROOT} 是 Codex 注入的插件根目录变量，使钩子脚本不依赖插件被复制到的具体路径。

钩子脚本：桥接 Python 实现

mempal-hook.sh 全文仅 9 行，职责是把 Codex 以 stdin 传入的 JSON 事件负载转发给 Python 侧的统一入口：

#!/usr/bin/env bash
set -euo pipefail
HOOK_NAME="${1:?Usage: mempal-hook.sh <hook-name>}"
INPUT_FILE=$(mktemp) || { echo "Failed to create temp file" >&2; exit 1; }
cat > "$INPUT_FILE"
cat "$INPUT_FILE" | mempalace hook run --hook "$HOOK_NAME" --harness codex
EXIT_CODE=$?
rm -f "$INPUT_FILE" 2>/dev/null
exit $EXIT_CODE

要点：

• --harness codex 告诉 Python 侧当前宿主是 Codex CLI，钩子处理器会按 harness 差异解析 stdin 负载形态；
• 脚本先落盘临时文件再回放，避免管道消费一次 stdin 后无法复用；
• 退出码原样透传，方便宿主检测钩子执行失败。

Python 侧的挖掘语义（源码佐证）

mempalace hook run 的实现位于 mempalace/hooks_cli.py，其中值得注意的语义有三条：

1. 对话挖掘永远发生，项目挖掘是“加法”。MEMPAL_DIR（见下节）贡献的是一个 "projects" 目标，从源码结构看（hooks_cli.py#L261-L269）：当 MEMPAL_DIR 已设置且可解析时，返回项目挖掘目标列表；空列表表示“本次不跑 MEMPAL_DIR 挖掘”。也就是说，即便不设置 MEMPAL_DIR，钩子仍会自动以 --mode convos 挖掘当前会话转录（CHANGELOG 中亦有对应记录：“Save hook auto-mines transcripts even when MEMPAL_DIR is unset (#840)”）。
2. Stop 与 PreCompact 的时序不同：stop 路径下 MEMPAL_DIR 挖掘以后台任务方式发起（hooks_cli.py#L754 附近），不阻塞会话结束；而 precompact 路径改为同步执行（hooks_cli.py#L800 附近），确保压缩上下文之前项目数据已经入库。
3. 行为有完整测试覆盖：tests/test_hooks_cli.py 覆盖了大量分支，包括“未设置 MEMPAL_DIR 且无转录路径时什么都不做”、“MEMPAL_DIR 支持 ~ 前缀展开”、“设置了 MEMPAL_DIR 时恰好产生一个 projects 目标、绝不产生 convos 目标”、“precompact 走 subprocess.run 同步路径”等。

MEMPAL_DIR 环境变量

README 的 Hooks 一节说明：把 MEMPAL_DIR 设为某个目录，每次保存触发时都会自动对该目录执行 mempalace mine。补充仓库中钩子文档的更精确表述（hooks/README.md）：

• 钩子始终自动挖掘当前会话转录（--mode convos），MEMPAL_DIR 纯粹是增量（additive），永不覆盖或替代转录挖掘；
• 典型配置如 MEMPAL_DIR="$HOME/projects/my_app"，保存触发时额外执行 mempalace mine "$MEMPAL_DIR" --mode projects（可对照 hooks/mempal_precompact_hook.sh 中的同款逻辑）；
• 不需要摄入项目文件时留空即可。

验证与故障排查

• 插件未被发现：先跑 codex --plugins；确认 .codex-plugin/ 位于 Codex 启动时的项目根目录、plugin.json 存在且为合法 JSON（其字段约束由 tests/test_codex_plugin_manifest.py 固化）；
• 钩子报找不到命令：多为 mempalace 不在 PATH 上，用 which mempalace 检查；若此前只执行过 uv sync，请改按上文用 uv tool install --editable . 重装；
• 想确认挖掘是否真的发生：用 /status Skill 查看房间数量变化，或查看插件目录下 hooks 脚本的 stdout/错误输出（脚本以 set -euo pipefail 运行，任何一步失败都会以非零退出码暴露）。

小结

.codex-plugin/ 目录体现了 MemPalace 接入 Codex CLI 的完整形态：plugin.json 负责身份与发现、skills/ 把五个斜杠命令薄封装到 mempalace instructions <name> 的动态引导、hooks.json + mempal-hook.sh 把 SessionStart / Stop / PreCompact 三条生命周期事件桥接到 mempalace hook run --harness codex，而 MEMPAL_DIR 为“会话必挖、项目可加”的自动摄入策略提供了唯一的配置旋钮。所有关键行为均可在 tests/test_hooks_cli.py 与 tests/test_codex_plugin_manifest.py 中找到可回归的验证依据。