企业官网建设流程全解析

MemPalace × Antigravity 手工接线指南：hooks.json 与 mcp_config.json 独立配置实战

【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And it's free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalace

MemPalace 为 Google Antigravity IDE 提供了一等公民的插件集成：通过生命周期钩子（Stop 事件后台挖掘会话、PreInvocation 事件注入记忆）和 MCP 服务器实现“对话结束自动入库、新对话自动召回”。本文聚焦仓库中 examples/antigravity 目录提供的两套独立配置文件，讲解不想运行安装脚本的用户如何手工把 MemPalace 接入 Antigravity，覆盖 hooks.json、mcp_config.json 的完整 JSON 结构、落盘位置、验证方法，并结合 hooks/antigravity 下的 hook 脚本与公共库源码，深入解释钩子的触发门控、stdout 契约、kill switch 与 Python 解释器解析机制。读完本文，你将掌握手工接线与自动安装两条路径，并具备独立排障能力。

一、两套集成方案的定位

仓库对 Antigravity 的接入有两种粒度：

1. 完整插件：运行 hooks/antigravity/install.sh，一次性注册 MCP 服务器、skill 与两个生命周期钩子，安装到~/.gemini/config/plugins/mempalace/。
2. 独立配置（本文主角）：examples/antigravity/目录下的 hooks.json 与 mcp_config.json —— 面向“不想使用安装器”的用户提供的两套standalone配置。

原文档用一张表界定了两个文件的分工：

从源码目录结构看，examples/antigravity/与hooks/antigravity/（真实 hook 脚本与安装器）分开存放：前者是“可复制到 IDE 配置目录的成品片段”，后者是“仓库内维护的源实现”。二者最终都会被 Antigravity 发现，只是走的路不同。

二、手工接线 hooks.json：注册 Stop 与 PreInvocation 钩子

examples/antigravity/hooks.json 的完整内容如下：

{ "mempalace-save": { "Stop": [ { "type": "command", "command": "/ABSOLUTE/PATH/TO/mempalace/hooks/antigravity/mempal_save_hook_antigravity.sh", "timeout": 30 } ] }, "mempalace-wake": { "PreInvocation": [ { "type": "command", "command": "/ABSOLUTE/PATH/TO/mempalace/hooks/antigravity/mempal_wake_hook_antigravity.sh", "timeout": 5 } ] } }

两个命名空间对应两类钩子：

• mempalace-save→Stop事件：每次 Agent 执行循环终止时触发，负责把会话转录后台挖掘进记忆库。
• mempalace-wake→PreInvocation事件：每次模型调用前触发，负责注入唤醒记忆。

2.1 必须改写占位绝对路径

示例使用占位绝对路径/ABSOLUTE/PATH/TO/mempalace/...。原文档明确警告：必须把两个command字段改写为克隆仓库中 hook 脚本的真实绝对路径（或你存放这些脚本的位置），因为Antigravity 不会可靠地解析相对路径。两个脚本的真实位置是：

• hooks/antigravity/mempal_save_hook_antigravity.sh
• hooks/antigravity/mempal_wake_hook_antigravity.sh

例如把仓库克隆在/home/me/projects/mempalace，则command应写成/home/me/projects/mempalace/hooks/antigravity/mempal_save_hook_antigravity.sh。

2.2 两种落盘位置

改写路径后，将文件放到以下任一位置：

• ~/.gemini/config/hooks.json——全局配置，对所有 workspace 生效；
• <workspace>/.agents/hooks.json——workspace 级配置，仅对当前工程生效。

放置后重启 Antigravity才会被拾取。与官方用户指南 website/guide/antigravity.md 描述的插件路径（~/.gemini/config/plugins/mempalace/hooks.json）不同，手工配置写入的是 hooks.json 自身的发现位置，等价于只注册钩子、不注册 skill 与 MCP 的“轻量模式”。

2.3 两个 timeout 的语义

示例中mempalace-save的 Stop 钩子 timeout 为30 秒，mempalace-wake的 PreInvocation 钩子 timeout 为5 秒。结合 hooks/antigravity/STDIN_SHAPE.md 的说明：钩子执行超时默认 30 秒，MemPalace 插件在渲染出的 hooks.json 里把 Stop 设为 30s、把 PreInvocation 收紧到 5s（实际运行中 wake 内部还叠加了 500ms 硬超时，见下文）。

2.4 想自动绝对化路径？直接用安装器

如果希望路径自动绝对化而不手工编辑，可运行安装器：

bash hooks/antigravity/install.sh

它会渲染一份完整的hooks.json到~/.gemini/config/plugins/mempalace/hooks.json。渲染模板即仓库中的 .antigravity-plugin/hooks.json.tmpl——安装脚本在安装期把占位符__PLUGIN_DIR__替换为安装目录的绝对路径（逻辑见 install.sh 的render_template函数），从而规避了相对路径无法解析的问题。这也是插件版与手工版 hooks.json 的唯一本质差异：手工版要求你亲手填绝对路径，安装器替你填。

三、钩子背后的事件模型与 stdout 契约

理解手工接线“为什么这么写”，需要先掌握 Antigravity 的 wire format。hooks/antigravity/STDIN_SHAPE.md 完整记录了该契约，核心要点：

通用输入字段（每个事件都有），全部为camelCaseJSON，经 stdin 传入、以 JSON 输出到 stdout：

Stop 事件附加字段：executionNum（执行序号）、terminationReason（如model_stop、max_steps_exceeded、error）、error（可选）、fullyIdle（必填，后台命令与异步任务是否全部完成）。

PreInvocation 事件附加字段：invocationNum（当前模型调用序号，从 1 起）、initialNumSteps（当前轨迹的步数）。

stdout 契约与 MemPalace 策略——这是整个集成里最重要的一条安全红线：

• Stop 事件的 stdout 可携带decision；若值为"continue"，会强制 Agent 继续运行。MemPalace 的 save 钩子永远输出{}并以 0 退出，在任何代码路径上都不会构造含"continue"的 decision（mempal_save_hook_antigravity.sh 中有显式拒绝逻辑），否则会造成 Agent 无限循环。
• PreInvocation 事件的 stdout 可携带injectSteps数组，每个元素形如{"ephemeralMessage": "..."}。MemPalace 的 wake 钩子用这一形式把mempalace wake-up的逐字输出注入首轮，且不落盘到转录，避免后续调用重复注入。wake 钩子绝不输出decision字段——那是 Stop 事件的专属字段。

若只想快速体验手工接线的效果，这份契约无需深究，但了解它对你判断“钩子是否工作正常”至关重要。

四、手工接线 mcp_config.json：注册 mempalace-mcp

examples/antigravity/mcp_config.json 内容极简：

{ "mcpServers": { "mempalace": { "command": "mempalace-mcp" } } }

它注册的是名为mempalace的 stdio MCP 服务器，启动命令为mempalace-mcp。这意味着mempalace-mcp可执行文件必须位于 Antigravity 进程可见的$PATH上（安装方式见“验证”一节）。

原文档给出两种接入选项：

选项 A —— 合并进用户级 Antigravity MCP 配置

Antigravity 的用户级 MCP 配置位于~/.gemini/antigravity/mcp_config.json。把本示例中的mcpServers.mempalace条目合并进该文件（注意是合并键，而不是覆盖整个文件），然后重启 Antigravity。

选项 B —— 放进插件目录

如果你已按官方插件规范创建了自定义插件目录，直接把本mcp_config.json复制到插件根目录即可：

<plugin-root>/mcp_config.json

Antigravity 在启动时会自动合并插件级 MCP 条目与用户级配置。这与安装器把 .antigravity-plugin/mcp_config.json（内容与本示例完全一致）复制到~/.gemini/config/plugins/mempalace/mcp_config.json的行为等价。

两种选项可以只选其一，也可以都做——Antigravity 会做合并去重。

五、验证接线是否生效

按原文档的步骤，接线完成后（无论 hooks、MCP 或两者都做了）执行：

mempalace-mcp --version # 确认二进制在 PATH 上 ls ~/.mempalace/ # 确认 palace 已存在（不存在则先运行 mempalace init）

随后重启 Antigravity：

1. mempalaceMCP 服务器应出现在 MCP store（工具面板）中；
2. Stop 与 PreInvocation 钩子应自动开始触发。

补充一点更深的验证手段（源自 website/guide/antigravity.md）：检查~/.mempalace/hook_state/antigravity_hook.log——每次钩子触发都会写一行日志。开始新会话应看到[event=preInvocation]，结束一轮对话应看到[event=stop]。若日志为空，说明钩子根本没被 IDE 调用，应回头检查 hooks.json 的路径与放置位置。运行钩子脚本所需的mempalace包安装，可用uv tool install mempalace或pip install mempalace。

六、底层行为解析：两个钩子究竟做了什么

手工接线只是把两个脚本挂到了事件上，脚本本身的行为值得展开，因为它们决定了“何时挖矿”“何时注入”“何时静默”。

6.1 save 钩子（Stop 事件）

触发流程（对应 mempal_save_hook_antigravity.sh）：

1. kill switch 检查：任一 kill switch 生效则输出{}直接退出（见下文表格）。
2. 解析 stdin：用公共库 hooks/antigravity/lib/common.sh 中的mempal_parse_stdin把 camelCase JSON 解析为带哨兵标记的多行字段（bash 3.2 安全，不依赖mapfile/readarray）。解析失败时把原始输入（截断 4KB、权限 0600）落盘到antigravity_last_input.log便于排障。
3. defer 判定：fullyIdle == false（后台任务还在跑，转录仍在变化）或terminationReason == "error"（转录可能损坏）时跳过本次保存。
4. 计数：每会话计数器antigravity_save_count_<conversationId>加 1（原子写：同目录临时文件 +mvrename）。
5. 模运算门控：仅当count % MEMPAL_SAVE_INTERVAL == 0（默认 interval =15，即每 15 次 Stop 触发一次挖矿）才真正保存。
6. pending 去重：若该会话已有进行中的保存（marker 文件存在且 <1 小时），跳过本次；过期 marker（>1 小时）会被回收后重试。
7. 校验转录路径：必须是以.json/.jsonl结尾且不含..穿越的现有文件（mempal_is_valid_transcript_path，与mempalace.hooks_cli校验一致）。
8. 后台挖矿：派生一个完全脱离前台的后台子 shell执行：

"$MEMPAL_PYTHON_BIN" -m mempalace mine "$TRANSCRIPT_DIR" \ --mode convos \ --wing "$WING"

其中 wing 由 workspace 首路径推断（mempal_infer_wing：取路径叶子目录，小写化、连字符/空格转下划线，前缀wing_，空输入回退wing_sessions）。前台随即输出{}并退出——整个前台耗时控制在毫秒级，挖矿在后台不阻塞用户。之所以把可运行性探测（-m mempalace --version）也放进后台子 shell，是因为该探测要付出 chromadb/onnx 冷启动导入成本，放前台会打爆 500ms 保存预算（源码注释对此有专门说明）。

6.2 wake 钩子（PreInvocation 事件，门控）

流程（对应 mempal_wake_hook_antigravity.sh）：

1. kill switch 检查，同 save。
2. 解析 stdin 取得conversationId、workspace 路径与invocationNum。
3. invocationNum == 1门控：PreInvocation 在每次模型调用前都触发，若不门控，每轮对话都会重复注入记忆。只在会话首次模型调用时注入——这是 Antigravity 场景下最接近 CursorsessionStart语义的时机。
4. 原子 mkdir 循环守卫：antigravity_woke_<conversationId>目录作为“已唤醒”标记；mkdir原子性保证同一会话只注入一次。
5. 调用mempalace wake-up --wing <inferred>，以500ms 硬超时（Pythonsubprocess.run(timeout=0.5)实现，跨平台，不依赖 GNUtimeout）运行。超时、非零退出、空输出任一情况都输出{}，会话正常开始、只是无注入——fail-open 是硬性要求。
6. 成功时输出：

{ "injectSteps": [ { "ephemeralMessage": "<mempalace wake-up 的逐字输出>" } ] }

ephemeralMessage只对当前这一轮模型可见、不写入持久转录，所以同一会话后续调用不会看到重复记忆。输出前还有一层保险：若 stdout 含decision键则拒绝输出（防未来改动误把 Stop 形状的对象泄漏给 PreInvocation）。

6.3 两个钩子的共同基础设施

所有状态与日志位于~/.mempalace/hook_state/（可用$MEMPAL_STATE_DIR覆盖），并以antigravity_前缀命名，与 Claude Code、Cursor、Codex 的钩子状态同目录共存：

陈旧状态有自动 GC：mempal_gc_stale_state每 24 小时至多清扫一次（MEMPAL_STATE_TTL_DAYS，默认 30 天），只清理计数器、pending marker、woke 目录这三类 glob，绝不触碰共享日志文件。

6.4 kill switch：一键静默禁用

任一条件成立即静默禁用两个钩子（stdout 输出{}、退出码 0，相当于 no-op 通过而不卸载插件）：

逻辑在 common.sh 的mempal_kill_switch_tripped中实现（palace 目录不存在是最强信号，最先检查）。

6.5 钩子如何找到你的 mempalace 安装

钩子以"$MEMPAL_PYTHON_BIN" -m mempalace方式运行 CLI，因此需要一个能 import mempalace 包的 Python 解释器。mempal_resolve_python的解析顺序（首中即停）：

1. $MEMPAL_PYTHON显式指定；
2. 读$PATH上mempalace-mcp/mempalaceconsole script 的shebang，从中提取解释器——覆盖uv tool install/pipx install的隔离环境（这正是 MCP 服务器用的同一个解释器，MCP 能起来钩子就能用）；
3. $PATH上的python3（覆盖已激活的 venv 或 editable 开发安装）；
4. 裸python3兜底。

仅当 GUI 启动的 Antigravity 无法继承 shell PATH 导致上述启发式失效时，才需要显式导出，例如：

export MEMPAL_PYTHON="$(uv tool dir)/mempalace/bin/python"

并加入~/.bashrc/~/.zshrc使 GUI 应用可见。

七、常见故障排查速查

综合原文档与仓库内两份排障材料（hooks/antigravity/README.md、website/guide/antigravity.md），常见问题如下：

钩子完全不触发：

1. 打开 IDE 的 Customizations 页面，确认mempalace出现在插件列表；手工接线时确认 hooks.json 落在~/.gemini/config/hooks.json或<workspace>/.agents/hooks.json。
2. 查看~/.mempalace/hook_state/antigravity_hook.log——每次触发都会写行，无日志即未被调用。
3. 验证渲染后的 hooks.json 里command路径指向可执行文件：bash -n ~/.gemini/config/plugins/mempalace/hooks/*.sh。

save 触发了但没有挖矿：

1. 日志中应见count与interval，挖矿只在count % interval == 0时发生；测试期可设MEMPAL_SAVE_INTERVAL=1每次触发。
2. 若日志出现ERROR: mempalace is not runnable via <python> -m mempalace; install mempalace or set MEMPAL_PYTHON，说明解析到的解释器里没有该包，按 6.5 节设置MEMPAL_PYTHON后重启。

wake 注入不出现：

1. wake 只在invocationNum == 1注入；
2. 注入成功后存在~/.mempalace/hook_state/antigravity_woke_<conversationId>目录，删除它可手动重测；
3. mempalace wake-up --wing <inferred>返回空通常是因为 wing 尚不存在，运行mempalace status核实。

仓库另有自动测试覆盖这两套钩子的安装与执行语义（tests/test_antigravity_hooks_install.py、tests/test_antigravity_hooks_shell.py），可作为行为契约的参考实现。

八、深入阅读

• hooks/antigravity/README.md——Antigravity 钩子脚本的完整说明（安装产物布局、workspace 级安装进阶用法、排障全表）
• hooks/antigravity/STDIN_SHAPE.md——两个事件的精确 wire format 与逐步示例
• hooks/antigravity/lib/common.sh——共享工具库：解析器、kill switch、wing 推断、解释器解析
• hooks/antigravity/install.sh——一键安装器：模板渲染、绝对化、幂等性、卸载安全护栏
• website/guide/antigravity.md——面向用户的完整接入指南（含共享大脑/多 Agent 章节）

【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And it's free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalace