agentmemory Hooks 深度指南让 AI 编码 Agent 全生命周期自动捕获记忆【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemoryagentmemory 为 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 个钩子事件触发时机对应脚本SessionStart会话开始scripts/session-start.mjsUserPromptSubmit用户提交提示词scripts/prompt-submit.mjsPreToolUse工具调用前匹配Edit\|Write\|Read\|Glob\|Grepscripts/pre-tool-use.mjsPostToolUse工具调用后scripts/post-tool-use.mjsPostToolUseFailure工具调用失败scripts/post-tool-failure.mjsPreCompact宿主压缩上下文前scripts/pre-compact.mjsSubagentStart子代理启动scripts/subagent-start.mjsSubagentStop子代理结束scripts/subagent-stop.mjsNotification收到通知scripts/notification.mjsTaskCompleted任务完成scripts/task-completed.mjsStop代理停止/每次轮次结束scripts/stop.mjsSessionEnd会话结束scripts/session-end.mjs值得注意的是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 }完成注册。SessionEndscripts/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_usePOST 到/agentmemory/observe超时 3 秒。所有钩子脚本采用“尽力而为”策略fetch失败即静默吞掉.catch(() {})超时后短暂延时退出绝不阻塞宿主主流程。这也意味着钩子离线不会导致 Agent 报错只是观测丢失。意图与上下文保全UserPromptSubmit / PreCompactUserPromptSubmitscripts/prompt-submit.mjs把用户提示原文data.prompt/data.userPrompt以hookType: prompt_submit写入/agentmemory/observe保留“用户当时想要什么”的意图锚点。PreCompact则在宿主压缩/裁剪上下文之前争取最后机会保全关键内容。scripts/pre-compact.mjs 会若设置CLAUDE_MEMORY_BRIDGEtrue先同步 Claude 记忆桥/agentmemory/claude-bridge/sync再向/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?shasha与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_AUTO_COMPRESStrue用 LLM 为每条观测生成更丰富的摘要Claude API token 用量随工具调用频率线性上升AGENTMEMORY_INJECT_CONTEXTtrue把相关记忆注入会话上下文每次工具轮次额外增加约 4000 字符输入配置写入~/.agentmemory/.env。开启注入会收到明显的启动警告提醒你正在为上下文注入付费。钩子底层的环境变量与 REST 协议所有钩子脚本共享同一套连接配置见各脚本开头的_project.ts片段环境变量默认值说明AGENTMEMORY_URLhttp://localhost:3111daemon 基础地址钩子所有请求都打到这个 base URLAGENTMEMORY_SECRET空非空时钩子为每个请求附加Authorization: Bearer SECRET头默认本地 daemon 开放且拒绝多余请求头AGENTMEMORY_PROJECT_NAME空显式指定项目名优先级高于 git 仓库推断AGENTMEMORY_INJECT_CONTEXTfalse是否把记忆注入会话上下文见上文AGENTMEMORY_AUTO_COMPRESSfalse是否启用 LLM 逐条压缩摘要AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS3000005 分钟Stop 钩子触发/session/end后合并语料的防抖窗口设为 0 关闭防抖AGENTMEMORY_URL默认指向 3111 端口REST daemon而实时观测面板在 3113 端口二者端口不同不要混淆。daemon 只在启动时读取.mcp.json因此修改端口或鉴权后必须重启 daemon两个传输层MCP 与 REST才能感知变更。排查观测缺失时按顺序检查SKILL.md 明确给出两条排查线索完整恢复步骤见 plugin/skills/_shared/TROUBLESHOOTING.md确认插件已启用且 daemon 在运行。钩子脚本对 daemon 的请求是尽力而为的失败静默所以 daemon 挂掉不会报错只会丢观测——这正是观测“消失”最常见的隐性原因。若 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/rememberrecall→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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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/agentmemoryagentmemory 为 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 个钩子事件触发时机对应脚本SessionStart会话开始scripts/session-start.mjsUserPromptSubmit用户提交提示词scripts/prompt-submit.mjsPreToolUse工具调用前匹配Edit\|Write\|Read\|Glob\|Grepscripts/pre-tool-use.mjsPostToolUse工具调用后scripts/post-tool-use.mjsPostToolUseFailure工具调用失败scripts/post-tool-failure.mjsPreCompact宿主压缩上下文前scripts/pre-compact.mjsSubagentStart子代理启动scripts/subagent-start.mjsSubagentStop子代理结束scripts/subagent-stop.mjsNotification收到通知scripts/notification.mjsTaskCompleted任务完成scripts/task-completed.mjsStop代理停止/每次轮次结束scripts/stop.mjsSessionEnd会话结束scripts/session-end.mjs值得注意的是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 }完成注册。SessionEndscripts/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_usePOST 到/agentmemory/observe超时 3 秒。所有钩子脚本采用“尽力而为”策略fetch失败即静默吞掉.catch(() {})超时后短暂延时退出绝不阻塞宿主主流程。这也意味着钩子离线不会导致 Agent 报错只是观测丢失。意图与上下文保全UserPromptSubmit / PreCompactUserPromptSubmitscripts/prompt-submit.mjs把用户提示原文data.prompt/data.userPrompt以hookType: prompt_submit写入/agentmemory/observe保留“用户当时想要什么”的意图锚点。PreCompact则在宿主压缩/裁剪上下文之前争取最后机会保全关键内容。scripts/pre-compact.mjs 会若设置CLAUDE_MEMORY_BRIDGEtrue先同步 Claude 记忆桥/agentmemory/claude-bridge/sync再向/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?shasha与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_AUTO_COMPRESStrue用 LLM 为每条观测生成更丰富的摘要Claude API token 用量随工具调用频率线性上升AGENTMEMORY_INJECT_CONTEXTtrue把相关记忆注入会话上下文每次工具轮次额外增加约 4000 字符输入配置写入~/.agentmemory/.env。开启注入会收到明显的启动警告提醒你正在为上下文注入付费。钩子底层的环境变量与 REST 协议所有钩子脚本共享同一套连接配置见各脚本开头的_project.ts片段环境变量默认值说明AGENTMEMORY_URLhttp://localhost:3111daemon 基础地址钩子所有请求都打到这个 base URLAGENTMEMORY_SECRET空非空时钩子为每个请求附加Authorization: Bearer SECRET头默认本地 daemon 开放且拒绝多余请求头AGENTMEMORY_PROJECT_NAME空显式指定项目名优先级高于 git 仓库推断AGENTMEMORY_INJECT_CONTEXTfalse是否把记忆注入会话上下文见上文AGENTMEMORY_AUTO_COMPRESSfalse是否启用 LLM 逐条压缩摘要AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS3000005 分钟Stop 钩子触发/session/end后合并语料的防抖窗口设为 0 关闭防抖AGENTMEMORY_URL默认指向 3111 端口REST daemon而实时观测面板在 3113 端口二者端口不同不要混淆。daemon 只在启动时读取.mcp.json因此修改端口或鉴权后必须重启 daemon两个传输层MCP 与 REST才能感知变更。排查观测缺失时按顺序检查SKILL.md 明确给出两条排查线索完整恢复步骤见 plugin/skills/_shared/TROUBLESHOOTING.md确认插件已启用且 daemon 在运行。钩子脚本对 daemon 的请求是尽力而为的失败静默所以 daemon 挂掉不会报错只会丢观测——这正是观测“消失”最常见的隐性原因。若 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/rememberrecall→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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考