agentmemory Hooks 深度指南：让 AI 编码 Agent 全生命周期自动捕获记忆

agentmemory Hooks 深度指南：让 AI 编码 Agent 全生命周期自动捕获记忆

【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory

agentmemory 为 Claude Code 等 AI 编码 Agent 提供了一套基于插件生命周期钩子（lifecycle hooks）的自动记忆捕获机制。本文将围绕plugin/skills/agentmemory-hooks/SKILL.md展开，深入讲解 12 个钩子事件如何在你无需手动调用memory_save的情况下，自动记录工具使用、用户提示词与会话边界，并解释“零 LLM 开销捕获”与可选的压缩、上下文注入开关。读完你不仅能快速安装启用 hooks，还能理解每个钩子背后的 REST 调用链路与排查思路。

快速开始：安装插件并自动注册钩子

在 Claude Code 中安装 agentmemory 插件后，全部生命周期钩子会自动注册，无需任何额外配置：

/plugin marketplace add rohitg00/agentmemory /plugin install agentmemory

安装完成后，打开实时观测面板http://localhost:3113，即可看到钩子捕获的观测（observations）实时落地。常规开发工作中你不需要手动调用记忆保存工具——钩子会替你完成工具调用、提示词与会话边界的观测写入。

从插件清单 plugin/plugin.json 可以看到，该插件还同时提供 54 个 MCP 工具、17 个技能与实时查看器；钩子系统只是其中自动采集数据的部分。

12 个生命周期钩子事件总览

钩子的注册配置集中在 plugin/hooks/hooks.json，每个事件绑定一个node脚本（通过${CLAUDE_PLUGIN_ROOT}定位插件根目录）。REFERENCE.md 记录了完整事件清单，共 12 个：

值得注意的是PreToolUse钩子带有matcher: "Edit|Write|Read|Glob|Grep"过滤器，只对这些核心文件/搜索类工具生效。REFERENCE.md 由 scripts/skills/generate.ts 从hooks.json自动生成，修改注册后需运行npm run skills:gen重新生成，不应手工编辑。

各钩子职责详解：从“记什么”到“怎么记”

会话边界：SessionStart / SessionEnd / Stop

会话开始与结束钩子为每一段工作划定边界，使handoff技能能够在后续会话中恢复它。查看 scripts/session-start.mjs 的实现：

• 从 stdin 读取 JSON 载荷，提取session_id/sessionId/conversation_id，缺省时生成ses_前缀的临时 ID；
• 通过hookCwd解析工作目录（优先取载荷中的cwd，其次workspace_roots，再次DEVIN_PROJECT_DIR/CLAUDE_PROJECT_DIR环境变量）；
• 调用resolveProject确定项目名：优先AGENTMEMORY_PROJECT_NAME，否则尝试git rev-parse --show-toplevel取仓库根目录的 basename，最后退回当前目录名；
• 向 daemon 的/agentmemory/session/start端点 POST{ sessionId, project, cwd }完成注册。

SessionEnd（scripts/session-end.mjs）还会尝试从transcript_path指向的 JSONL 转录文件中抽取最多 50 条用户文本提示（支持<user_query>标签包裹格式），逐条以hookType: "prompt_submit"补录，然后通知/agentmemory/session/end关闭会话。Stop钩子（scripts/stop.mjs）与 SessionEnd 行为类似，也会 POST/agentmemory/session/end——由于 Stop 在每个代理轮次都会触发，daemon 侧对这类高频结束信号做了合并去重（详见下文“压缩冷却”）。

工具使用：PreToolUse / PostToolUse / PostToolUseFailure

工具调用钩子是recall与recap技能的原始素材来源，记录“改了什么、为什么改”。以 scripts/post-tool-use.mjs 为例：

• 兼容多种载荷字段（tool_name/toolName、tool_input/toolArgs、tool_response/tool_output/tool_result等），适配不同宿主；
• 调用extractImageData识别 base64 图片输出（data:image/前缀或 PNG/JPEG 特征头），将图片数据与文本输出分离，文本位置替换为[image data extracted]，图片单独放入image_data字段；
• 输出经truncate截断到 8000 字符（对象则序列化后截断），避免超大工具输出撑爆记忆存储；
• 最终以hookType: "post_tool_use"POST 到/agentmemory/observe，超时 3 秒。

所有钩子脚本采用“尽力而为”策略：fetch失败即静默吞掉（.catch(() => {})），超时后短暂延时退出，绝不阻塞宿主主流程。这也意味着钩子离线不会导致 Agent 报错，只是观测丢失。

意图与上下文保全：UserPromptSubmit / PreCompact

UserPromptSubmit（scripts/prompt-submit.mjs）把用户提示原文（data.prompt/data.userPrompt）以hookType: "prompt_submit"写入/agentmemory/observe，保留“用户当时想要什么”的意图锚点。

PreCompact则在宿主压缩/裁剪上下文之前争取最后机会保全关键内容。scripts/pre-compact.mjs 会：

1. 若设置CLAUDE_MEMORY_BRIDGE=true，先同步 Claude 记忆桥/agentmemory/claude-bridge/sync；
2. 再向/agentmemory/contextPOST{ sessionId, project, budget: 1500 }，把预算内的相关上下文写入 stdout，供宿主在压缩前吸收。

提交关联：post-commit 钩子

虽然hooks.json未直接列出 post-commit（它由宿主侧的 git 钩子机制触发），scripts/post-commit.mjs 的实现说明它如何把提交与会话绑定：

• 解析AGENTMEMORY_COMMIT_SHA或执行git rev-parse HEAD取提交 SHA；
• 通过多条git命令收集分支、远端仓库 URL、提交信息、作者与变更文件列表（git diff-tree --no-commit-id --name-only -r）；
• 整体 POST 到/agentmemory/session/commit，为commit-context与commit-history技能提供数据基础——这两个技能正是通过GET /agentmemory/session/by-commit?sha=<sha>与GET /agentmemory/commits查询提交维度的记忆。

默认零 LLM 捕获与两个付费开关

SKILL.md 强调了一个核心设计原则：捕获默认开启，且零 LLM 开销。从 src/config.ts 的注释可以还原完整演进逻辑：

• 自 0.8.8 起，逐条观测的 LLM 压缩默认关闭。关闭时观测通过“合成压缩”（synthetic compression）路径完成索引，recall/search依然可用；
• 自 0.8.10 起，会话级上下文注入默认关闭。关闭时 pre-tool-use 与 session-start 钩子仍会 POST 观测用于后台捕获，但不再向 stdout 写入上下文，避免 Claude Code 在每个工具轮次都吞入约 4000 字符的额外内容，烧掉模型输入窗口的 token。

因此以下两个能力都是独立选配，开启后才会消耗 token：

配置写入~/.agentmemory/.env。开启注入会收到明显的启动警告，提醒你正在为上下文注入付费。

钩子底层的环境变量与 REST 协议

所有钩子脚本共享同一套连接配置（见各脚本开头的_project.ts片段）：

AGENTMEMORY_URL默认指向 3111 端口（REST daemon），而实时观测面板在 3113 端口；二者端口不同，不要混淆。daemon 只在启动时读取.mcp.json，因此修改端口或鉴权后必须重启 daemon，两个传输层（MCP 与 REST）才能感知变更。

排查：观测缺失时按顺序检查

SKILL.md 明确给出两条排查线索，完整恢复步骤见 plugin/skills/_shared/TROUBLESHOOTING.md：

1. 确认插件已启用且 daemon 在运行。钩子脚本对 daemon 的请求是尽力而为的（失败静默），所以 daemon 挂掉不会报错，只会丢观测——这正是观测“消失”最常见的隐性原因。
2. 若 MCP 工具缺失，则按序执行：/plugin list确认agentmemory处于 enabled → 重启宿主（.mcp.json仅在启动时读取，中途启用插件不会注册工具）→/mcp确认agentmemory服务器连接为 live。

当 MCP 工具不可用但 daemon 在跑时，可回退到 REST 直连：设置AGENTMEMORY_URL（默认http://localhost:3111），仅在设置了AGENTMEMORY_SECRET时才附加Authorization头。不同技能对应 REST 端点可查阅 TROUBLESHOOTING 中的端点映射表（如remember→POST /agentmemory/remember，recall→POST /agentmemory/smart-search）。

相关技能与进一步阅读

钩子产出的数据由以下技能消费，形成完整的“自动采集 → 主动利用”闭环：

• agentmemory-config：捕获与注入相关的全部配置项；
• handoff、recap、session-history：直接消费本钩子系统记录的会话与观测；
• commit-context、commit-history：依赖 post-commit 钩子建立的提交-会话关联。

若要基于真实事件验证钩子行为，可参考仓库中的钩子实现源码（plugin/scripts/ 目录）与注册配置 plugin/hooks/hooks.json，并配合实时面板观察观测落库过程。

【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory