MemPalace Hooks 实战指南为 Claude Code、Codex 与 Antigravity 配置 AI 对话自动记忆保存【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And its free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalaceMemPalace 是面向终端 AI 工具的本地记忆系统本文讲解它的生命周期 Hook 体系通过在编辑器/CLI 的会话事件Stop、SessionEnd、PreCompact上挂载脚本让对话记忆自动落库彻底告别手动执行save命令。读完本文你将掌握三类 Hook 各自的触发时机与作用、Claude Code / Codex / Antigravity 三套环境的接线方法、SAVE_INTERVAL等关键参数调优以及基于 mempal_save_hook.sh、hooks_cli.py 的底层运行原理与排障手段。一图看懂三个 Hook 如何覆盖会话全生命周期MemPalace 的 Hook 脚本统一放在仓库根目录 hooks/ 下Cursor 专属版本位于 hooks/cursor/Antigravity 版本位于 hooks/antigravity/。它们的目标只有一个让 MemPalace 自动保存无需手动 save 命令。三个 Hook 从不同时间点覆盖了会话的三种命运Hook触发时机发生什么Save Hookmempal_save_hook.sh每 15 条人类消息自动挖掘会话转录含工具输出然后阻断 AI要求其保存主题/决策/引文SessionEnd Hookmempal_session_end_hook.sh干净地退出会话时在后台完成最后一次转录挖掘有转录时保住短会话不丢失立即返回绝不让退出流程被拖慢。轻量级日记检查点由分离出的子进程写入PreCompact Hookmempal_precompact_hook.sh上下文压缩发生前自动挖掘转录然后紧急保存——在上下文即将丢失前强制 AI 保存一切这套设计遵循双层捕获two-layer capture策略Hook 先把 JSONL 转录直接自动挖掘进 palace原始工具输出Bash 结果、搜索结果、构建报错由此被完整留存同时Hook 用一条 reason 消息阻断 AI要求其逐字保存工具输出与关键上下文。即便 AI 最终用摘要代替了原文引用工具输出也已经独立落库——双保险。关于三个 Hook 的归属hooks/README.md 特别说明该文档面向平铺在hooks/根目录下的Claude Code 与 Codex CLIHookCursor IDE的 Hook 请见 hooks/cursor/README.md 或渲染文档 website/guide/cursor-hooks.md。两者可叠加共存共享同一个~/.mempalace/hook_state/目录。安装Claude Code在.claude/settings.local.json中注册三个事件{ hooks: { Stop: [{ matcher: *, hooks: [{ type: command, command: /absolute/path/to/hooks/mempal_save_hook.sh, timeout: 30 }] }], SessionEnd: [{ hooks: [{ type: command, command: /absolute/path/to/hooks/mempal_session_end_hook.sh, timeout: 10 }] }], PreCompact: [{ hooks: [{ type: command, command: /absolute/path/to/hooks/mempal_precompact_hook.sh, timeout: 30 }] }] } }然后赋予执行权限chmod x hooks/mempal_save_hook.sh hooks/mempal_session_end_hook.sh hooks/mempal_precompact_hook.sh关于timeout的取值差异mempal_session_end_hook.sh 的源码注释给出了关键依据Claude Code 文档中 SessionEnd Hook 的默认超时是1.5 秒通过settings.local.json的timeout可以上调上限 60 秒但plugin 提供的 Hook 无法上调超时预算。冷启动一次mempalace就可能超过 1.5 秒因此 SessionEnd Hook 把工作放到后台并立即返回绝不在前台挖掘转录——这也是为什么用插件接线时该 Hook 必须后台化的根本原因。配置好后会话在干净退出时触发一次 SessionEnd 后台保存而 Stop 与 PreCompact 的同步挖掘则由 mempalace/hooks_cli.py 中的 per-target PID 锁~/.mempalace/hook_state/mine_pids/基于O_CREAT | O_EXCL原子认领防止同目标并发重复挖掘。安装Codex CLIOpenAI在.codex/hooks.json中注册 Stop 与 PreCompact 两个事件Codex 尚无 SessionEnd 事件见下文其他 Harness说明{ Stop: [{ type: command, command: /absolute/path/to/hooks/mempal_save_hook.sh, timeout: 30 }], PreCompact: [{ type: command, command: /absolute/path/to/hooks/mempal_precompact_hook.sh, timeout: 30 }] }Save Hook 的消息计数逻辑对Codex CLI 的转录格式同样兼容_count_human_messages除了解析 Claude Code 的{message: {role: user, ...}}结构还处理 Codex 的{type: event_msg, payload: {type: user_message, ...}}事件见 hooks_cli.py 的count_human_messages。两种格式均会跳过含command-message的系统消息。其他 Harness干净退出时的保存走的是与 Harness 无关的入口mempalace hook run --hook session-end。本版本将其接线给了 Claude CodeAntigravity 不暴露独立的 session-end 事件其生命周期 Hook 为 PreToolUse/PostToolUse/PreInvocation/PostInvocation/StopMemPalace 已通过Stop完成保存Cursor 与 Codex 可在各自具备 session-end 事件后接入同一入口。CLI 侧由 cli.py 的cmd_hook转调hooks_cli.run_hook--harness目前支持claude-code与codex定义于 hooks_cli.py 的SUPPORTED_HARNESSES。安装AntigravityGoogleAntigravity 集成因为线格式不同camelCase JSON、injectSteps[]输出以及事件名不同Stop、PreInvocation而放在独立子目录使用专用安装器bash hooks/antigravity/install.sh安装器会把插件装到~/.gemini/config/plugins/mempalace/注册 MCP server、内置mempalaceskill并接好 Stop PreInvocation 两个 Hook。完整指南见 hooks/antigravity/README.md关于该集成使用哪些 Antigravity 表面surface的事实审计见 hooks/antigravity/INVESTIGATION.md。它同样支持--dry-run与--uninstall。从源码看Antigravity 的两个 Hook 有独特的分流逻辑Stop 事件 Hook 在fullyIdle false后台任务仍在运行、terminationReason error转录可能损坏、上一轮保存仍在运行或任一 kill switch 生效时都会主动跳过PreInvocation 唤醒 Hook 仅在invocationNum 1会话第一次调用时注入记忆通过mempalace wake-up --wing inferred以 500ms 硬超时运行并把输出作为ephemeralMessage呈现避免污染持久转录。配置调优保存节奏与捕获范围编辑 mempal_save_hook.sh 顶部即可修改核心行为配置项默认值作用SAVE_INTERVAL15两次保存之间间隔多少条人类消息。越小保存越频繁、打断越多越大打断越少STATE_DIR~/.mempalace/hook_state/Hook 状态存储位置计数文件、日志、PID 锁等MEMPAL_DIR空可选的项目目录代码/笔记/文档每次保存触发时额外用--mode projects挖掘。Hook始终自动以--mode convos挖掘当前会话转录——MEMPAL_DIR是纯增量绝不覆盖转录挖掘。留空即不摄入项目文件MEMPALACE_PYTHON自动探测可选环境变量指定装有 mempalace chromadb 的 Python 解释器。自动探测顺序MEMPALACE_PYTHON环境变量 → 仓库venv/bin/python3→ 系统python3。虚拟环境在非标准位置时请显式设置其中MEMPAL_DIR的增量而非覆盖语义有测试背书tests/test_save_hook_mines.py 的TestSaveHookAutoMines断言 Hook 必须依据TRANSCRIPT_PATH用dirname推导父目录并以--mode convos挖掘同时要求即便MEMPAL_DIR也存在不依赖它的替代挖掘路径。与之呼应hooks_cli.py 的_ingest_transcript在 v3 实现中把转录挖进wing_sessions并把项目文件挖掘_maybe_auto_ingest与转录挖掘拆开避免同源重复入库。关于 Python 解释器解析Hook 还维护一条独立的MEMPAL_PYTHON解析链注意与文档配置节的MEMPALACE_PYTHON相区分mempal_save_hook.sh$MEMPAL_PYTHON若已设置且可执行→$(command -v python3)→ 裸python3。该解释器只需标准库的json与sys不必在其中安装 mempalace——因为 JSON 解析与消息计数由 Python 模块 hook_shell.py 完成parse-stop、parse-precompact、count-human-messages三个子命令shell Hook 通过$MEMPAL_PYTHON_BIN -m mempalace.hook_shell ...调用它。静默模式禁止自动保存想保留 Hook 安装但彻底关闭自动保存的阻断行为将hooks.auto_save置为false方式一——配置文件~/.mempalace/config.json{ hooks: { auto_save: false } }方式二——环境变量export MEMPALACE_HOOKS_AUTO_SAVEfalse关闭后stop hook 与 precompact hook 都会直接透传而不阻断。你仍可随时手动保存mempalace mine dir --mode convos配置优先级在 config.py 的hooks_auto_save属性中有明确实现环境变量优先false/0/no视为关闭否则读取配置文件里的hooks.auto_save默认True。同一文件里的hooks.silent_save默认True与hooks.desktop_toast默认False经notify-send弹桌面通知也由该配置节控制。静默保存 vs 阻断保存verbose从 hooks_cli.py 的hook_stop实现看v3 之后的 Stop Hook 有两条保存路径静默模式默认v3.3.0Hook 直接通过 Python API 调用_save_diary_direct写入日记检查点还会抽取最近消息的主题词themes并触发_ingest_transcript转录挖掘随后向终端输出一条systemMessage形如✦ N memories woven into the palace — theme1, theme2全程不阻断 AI对话零打扰。传统阻断模式hooks.silent_save: false时Hook 返回{decision: block, reason: ...}reason 里写明Use mempalace_diary_write (session summary) and mempalace_add_drawer (quotes, decisions, code) to save session content. Do NOT use native auto-memory files.要求 AI 借助 MCP 工具写入wing_project项目翼由转录路径推导见_wing_from_transcript_path。此路径会先推进保存标记属于尽力而为即便 AI 保存失败也不无限重试。与 write-routing / daemon 的关系Hook 的写入并非总是直连向量库。从 hooks_cli.py 可见每次 Hook 触发都会基于配置的写路由策略direct / prefer / require与 daemon 存活探测做决策策略为require且本地 daemon 不可用时Hook 会跳过写入并通过systemMessage提示mempalace daemon start策略为prefer且 daemon 在跑时挖掘任务会提交给 daemon 去重执行dedupe_key由源目录模式哈希生成否则退回直连路径。这也是~/.mempalace/config.json中hooks段与写路由策略联动的原因——详见仓库的 write-routing-policy.md。工作原理技术拆解Save HookStop 事件Claude Code 在 AI 每次回复后向 Hook 的 stdin 发送 JSON包含session_id、stop_hook_active、transcript_path三个字段。Hook 的执行流如下User sends message → AI responds → Claude Code fires Stop hook ↓ Hook counts human messages in JSONL transcript ↓ ┌─── 15 since last save ──→ echo {} (let AI stop) │ └─── ≥ 15 since last save ↓ Auto-mine transcript → palace (tool output captured) ↓ {decision: block, reason: save tool output verbatim...} ↓ AI saves to palace (topics, decisions, quotes) ↓ AI tries to stop again ↓ stop_hook_active true ↓ Hook sees flag → echo {} (let it through)stop_hook_active标志用于防止死循环阻断一次 → AI 保存 → 再次尝试停止 → 标志为真 → 放行。消息计数与状态推进的实际执行细节值得展开计数count-human-messages遍历 JSONL 转录中的每条role user消息跳过含command-message的内部命令消息hook_shell.py。文件以 UTF-8 显式打开Windows 默认 cp1252 会出错路径必须通过扩展名.jsonl/.json与..穿越双重校验。状态每个会话的计数快照以~/.mempalace/hook_state/session_id_last_save文件保存内容为纯整数读取时先用正则^[0-9]$校验再做算术防止经由构造路径的命令注入。挖掘触发保存时Hook 对dirname $TRANSCRIPT_PATH执行后台挖掘mempalace mine ... --mode convosMEMPAL_DIR非空时再对项目目录执行--mode projects两条挖掘互相独立、并行运行。Hook 脚本内的 JSON 解析采用防御性设计见脚本中 #1231/#1440 评审注释输出以__MEMPAL_PARSE_OK__哨兵行开头用于区分Python 正常解析但值被置空与Python 崩溃没输出两种失败用sed -n Np而非 bash 4 才有的mapfile以兼容 macOS 冻结在 GNU bash 3.2.57 的环境解析失败时把原始载荷上限 4KB、umask 077创建、chmod 600收尾写到last_input.logPython stderr 写入last_python_err.log供排障使用。PreCompact Hook上下文窗口将满 → Claude Code 触发 PreCompact → 找到转录从 stdin 输入或 session_id 反查→同步挖掘转录到 palace捕获原始工具输出→ 返回{decision: block, ...}强制 AI 保存 → 压缩继续Context window getting full → Claude Code fires PreCompact ↓ Find transcript (from input or session_id lookup) ↓ Auto-mine transcript → palace (tool output captured) ↓ {decision: block, reason: save tool output verbatim...} ↓ AI saves everything ↓ Compaction proceeds无需计数——压缩总是值得先保存一次。与 Save Hook 的区别在于mempal_precompact_hook.sh 里的挖掘是前台同步执行subprocess.run确保记忆在压缩发生前落盘Hook 本身只回显{}靠同步挖掘而非Stop 阻断协议来保证语义。其紧急保存 reason 措辞也更强硬MemPalace emergency save — compaction imminent. Use mempalace_diary_write (thorough summary) and mempalace_add_drawer (ALL quotes, decisions, code, context) to save ALL content before context is lost.在 Python 侧hook_precompact则是先_ingest_transcript转录入库、再_mine_sync同步挖掘MEMPAL_DIR。SessionEnd HookSessionEnd 关闭了短会话丢失记忆的缺口源码注释引用 #1341一段从未跨过SAVE_INTERVAL、也从没触发 PreCompact 的会话在干净退出时若无此 Hook 将什么都不会保存。其实现要点mempal_session_end_hook.sh hook_session_end先在前台捕获 stdin 载荷父进程一旦返回其 stdin 即消失再把载荷转交给mempalace hook run --hook session-end --harness ...的分离子进程执行通过disown与重定向保证 Hook 立即返回不让 harness 阻塞在退出流程上子进程内先写轻量级日记检查点_save_diary_direct在进程内直写 ChromaDB抢在任何脱离进程之前执行以避免争用 palace 写锁再触发脱离的转录挖掘任何退出原因包括/clear、resume都值得这次 flush因此不区分reason全部执行执行完毕后清理session_id_last_save标记文件避免hook_state/堆积死标记。调试与状态查看所有 Hook 的运行日志统一追加到cat ~/.mempalace/hook_state/hook.log典型输出[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日志目录里还有几个排障产物前文已述均为失败覆盖、绝不追加防磁盘无限增长last_input.log— stdin 解析失败时的原始载荷转储上限 4KB0600 权限last_python_err.log— Python 解析器的 stderr 捕获用于区分坏输入JSONDecodeError与解释器损坏/脚本回归ImportError 等session_id_last_save— 每会话的保存计数快照mine_pids/— 每目标目录模式的挖掘 PID 槽位用于同目标并发去重由子进程经MEMPALACE_MINE_PID_FILE环境变量在退出时自清理。Cursor 的日志独立为~/.mempalace/hook_state/cursor_hook.log带 ISO 8601 时间戳与[event...]、[conv...]结构Antigravity 的日志则是~/.mempalace/hook_state/antigravity_hook.log三者相互隔离、避免跨工具日志搅动——但共享同一状态目录。已知限制与规避① 安装后需重启会话。Claude Code 只在会话启动时从settings.json加载 Hook。若你在会话中途执行mempalace init或手工编辑 Hook 配置Hook 要到下次重启 Claude Code 才会生效。这是 Claude Code 的机制限制。Cursor 相对友好编辑hooks.json后 Cursor 会 watch 到并自动重载若仍未生效可重启 Cursor 并在 Settings 的 Hooks 面板确认。②MEMPAL_PYTHON覆盖 Hook 内部 Python 调用。Save Hook 解析 JSON 输入并用python3计数转录消息。当 macOS 上 harness 由 GUI 启动open -a、Spotlight、Dock 图标时其PATH是来自launchd的最小集合/usr/bin:/bin:/usr/sbin:/sbin而非你 shell 的 PATH。若python3不在其中这些内部调用失败、Hook 无法计数交互。解决方法是指向任意 Python 3 解释器export MEMPAL_PYTHON/usr/bin/python3 # system Python is fine export MEMPAL_PYTHON$HOME/.venvs/mempalace/bin/python # or your venv解析优先级为$MEMPAL_PYTHON若已设置且可执行→$(command -v python3)→ 裸python3。该解释器只需标准库的json与sys——memPalace 本体无需装在其中。③mempalace mine自动入库也需要在 PATH 上。自动挖掘经由mempalaceCLI 执行因此该命令必须在 Hook 的PATH上。用pipx install mempalace或uv tool install mempalace安装会落到稳定的全局位置否则需扩展 Hook 环境的PATH以包含你虚拟环境的bin/目录。此外SessionEnd 的 shell 包装器还提供三级探测链mempalace命令 → 能import mempalace的 python3 → 能import mempalace的python都找不到时才报错退出见 mempal_session_end_hook.sh。④ 每目标挖掘并发去重与卡死超时。后台挖掘对同一源目录模式目标只允许一个存活进程防 HNSW 索引损坏与重复 upsert 撑爆磁盘引用 #1212/#1206不同目标互不阻塞、可并行。PID 槽位带时间戳超过默认 2 小时的运行视为卡死可被回收——通过MEMPALACE_MINE_TIMEOUT_HOURS0可禁用超时hooks_cli.py。⑤ 显式关闭的另类开关palace 核弹开关。Python 侧 Hook 在~/.mempalace/目录不存在时用户显式清空会短路一切副作用——包括写日志、建状态目录、挖掘与入库。_palace_root_exists()用is_dir()而非exists()避免一个游离的普通文件误充当目录存在而绕过开关hooks_cli.py。回填历史会话Hook 只捕获从现在起的会话。要把过去的 Claude Code 会话挖进 palace执行一次性回填mempalace mine ~/.claude/projects/ --mode convos这会扫描以往所有会话的 JSONL 转录归档到conversations翼。在积累了数月历史的典型开发机上此操作可能产出 5 万到 20 万个抽屉drawers。Codex CLI 会话同理mempalace mine ~/.codex/sessions/ --mode convos只需执行一次——此后 Hook 会在每个会话进行中自动挖掘。成本与安全性零额外 token。Hook 只在后台完成保存后通知 AI 一声——AI 无需在聊天里写任何内容所有归档自动完成。早期版本要求 AI 在聊天窗口写日记条目与抽屉内容每次会话因重传 token 要花费约 1 美元现版本静默模式已完全消除这笔开销。为保护既有 Claude Code 转录可先参考 website/guide/claude-code-retention.md 的快速清单涵盖 Hook 接线、JSONL 备份与一次性回填。安全层面Hook 对 harness 输入做了三层防护均有对应测试tests/test_save_hook_mines.py 验证 shell 层的is_valid_transcript_path校验器拒绝无扩展名路径与..穿越确实被调用且行为与 Python 侧一致hook_shell.py 负责 session_id 清洗仅保留[A-Za-z0-9_-]防止路径穿越写入状态文件名与 Windows 路径归一化保留盘符冒号、反斜杠转正斜杠供 Git Bash 定位同一文件日志与转储文件一律 0600/0700 权限避免含transcript_path可反推用户主目录与项目布局的载荷被本机其他用户读取。【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And its free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalace创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考