agentmemory hooks 完全指南Claude Code 插件如何用 12 个生命周期事件自动捕获 Agent 记忆【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory导读本篇文章聚焦于 agentmemory 的 Claude Code 插件钩子系统hooks即 plugin/skills/agentmemory-hooks/REFERENCE.md 所描述的 12 个生命周期事件。你会看到这些钩子如何在 Session 开始/结束、工具调用、提示词提交、上下文压缩等关键时刻自动把发生了什么、为什么写入记忆库从而让recall、recap、handoff等技能无需手动保存即可工作。读完本文你将掌握钩子的完整注册清单、每个事件的触发时机与底层调用链、相关环境变量的开关含义以及观察丢失时的排查步骤。一、为什么需要钩子从手动保存到自动观察在 Claude Code 中日常开发会话会产生大量有价值的过程信息你执行了哪些工具、工具输出是什么、你提交了怎样的提示词、会话在何时开始与结束。如果这一切都要靠调用memory_save手动保存既繁琐又容易遗漏。agentmemory 的解决方案是在插件层注册生命周期钩子让记忆捕获成为会话的旁路观察者。正如 plugin/skills/agentmemory-hooks/SKILL.md 所述插件安装后钩子即自动注册日常工作中无需手动调用memory_save——钩子会观察工具使用、提示词与会话边界并把观察结果自动写入记忆库。1.1 快速开始/plugin marketplace add rohitg00/agentmemory /plugin install agentmemory安装完成后即可在http://localhost:3113实时看到观察结果落库。二、12 个生命周期事件全览根据 plugin/skills/agentmemory-hooks/REFERENCE.mdClaude Code 插件在以下 12 个生命周期事件上注册了钩子事件触发的生命周期时机对应脚本SessionStart会话开始时注册会话并可选注入历史上下文plugin/scripts/session-start.mjsUserPromptSubmit用户提交提示词时捕获意图plugin/scripts/prompt-submit.mjsPreToolUse工具执行前匹配Edit\|Write\|Read\|Glob\|Grepplugin/scripts/pre-tool-use.mjsPostToolUse工具执行后记录改动与输出plugin/scripts/post-tool-use.mjsPostToolUseFailure工具执行失败时记录错误plugin/scripts/post-tool-failure.mjsPreCompact宿主压缩上下文之前保留关键上下文plugin/scripts/pre-compact.mjsSubagentStart子代理启动时plugin/scripts/subagent-start.mjsSubagentStop子代理停止时plugin/scripts/subagent-stop.mjsNotification宿主发送通知时plugin/scripts/notification.mjsTaskCompleted任务完成时plugin/scripts/task-completed.mjsStop会话停止时plugin/scripts/stop.mjsSessionEnd会话结束时抽取提示词并关闭会话plugin/scripts/session-end.mjs注意REFERENCE.md 顶部标注该清单由 plugin/hooks/hooks.json 自动生成改动手动编辑无效修改注册后需运行npm run skills:gen重新生成。2.1 注册清单的真相hooks.jsonplugin/hooks/hooks.json 是钩子注册的单一事实来源。每个事件都映射到一个 Node 脚本例如{ SessionStart: [ { hooks: [ { type: command, command: node \${CLAUDE_PLUGIN_ROOT}/scripts/session-start.mjs\ } ] } ], PreToolUse: [ { matcher: Edit|Write|Read|Glob|Grep, hooks: [ { type: command, command: node \${CLAUDE_PLUGIN_ROOT}/scripts/pre-tool-use.mjs\ } ] } ] }值得注意的细节PreToolUse带有一个matcher过滤器只匹配Edit、Write、Read、Glob、Grep五类工具避免为无关工具调用产生开销。三、钩子如何工作底层调用链与源码解读所有钩子脚本都遵循同一套模式从 stdin 读取宿主传入的 JSON 事件负载解析出session_id、cwd、工具名等字段再通过 REST API 将观察结果 POST 到本地守护进程daemon默认地址为AGENTMEMORY_URL或http://localhost:3111。3.1 项目归属解析resolveProject几乎每个脚本都内联了resolveProject与hookCwd逻辑见 plugin/scripts/session-start.mjs若设置了AGENTMEMORY_PROJECT_NAME优先使用该显式项目名否则尝试git rev-parse --show-toplevel取仓库根目录名都不是时回退到当前工作目录的basename。这保证了观察结果能按项目正确隔离归档。3.2 SessionStart注册会话与可选上下文注入plugin/scripts/session-start.mjs 会向POST /agentmemory/session/start发送{ sessionId, project, cwd }注册会话。当环境变量AGENTMEMORY_INJECT_CONTEXTtrue时它还会把返回的历史上下文写回 stdoutprocess.stdout.write让宿主把记忆注入到当前会话的额外上下文中默认未开启时仅做注册超时设为 800ms开启后超时放宽到 1500ms。3.3 PostToolUse记录改变了什么、为什么plugin/scripts/post-tool-use.mjs 是记忆原材料的核心生产者向POST /agentmemory/observe发送hookType: post_tool_use的观察包含工具名、输入与输出。有几个值得留意的工程细节输出截断字符串或对象输出超过 8000 字符会被截断并追加[...truncated]标记图像数据提取若工具输出包含 base64 图片data:image/、iVBORw0KGgo或/9j/前缀会单独提取为image_data字段并用[image data extracted]占位避免污染文本记忆静默失败请求超时 3 秒失败时.catch(() {})吞掉异常绝不阻塞宿主主流程。3.4 PromptSubmit 与 SessionEnd捕获意图与会话收尾plugin/scripts/prompt-submit.mjs 在每次提交提示词时向POST /agentmemory/observe发送hookType: prompt_submit记录{ prompt }。plugin/scripts/session-end.mjs 的收尾工作更完整它先从宿主的transcript_pathJSONL 转录文件中解析用户提示词——最多 50 条、每条截断到 8000 字符、并优先提取user_query.../user_query标签内的正文——批量上报为prompt_submit观察最后调用POST /agentmemory/session/end关闭会话。若设置了CLAUDE_MEMORY_BRIDGEtrue还会额外同步一次 claude-bridge。3.5 PreCompact压缩前的上下文保鲜plugin/scripts/pre-compact.mjs 在宿主压缩上下文之前向POST /agentmemory/context提交{ sessionId, project, budget: 1500 }请求若返回context则直接写回 stdout 注入压缩后的会话确保被裁剪掉的记忆在压缩后依然可被检索。若设置了CLAUDE_MEMORY_BRIDGEtrue会先调用/agentmemory/claude-bridge/sync同步桥接数据。3.6 SubagentStart / PostToolUseFailure / TaskCompleted多代理与错误路径plugin/scripts/subagent-start.mjs 记录子代理的agent_id与agent_typehookType: subagent_startplugin/scripts/post-tool-failure.mjs 记录失败的tool_name、tool_input与error各截断 4000 字符hookType: post_tool_failure并且跳过中断类事件is_interrupt以免把用户主动取消误记为失败plugin/scripts/task-completed.mjs 记录任务 ID、主题与描述截断 2000 字符用于团队/任务维度的记忆归档。3.7 PostCommit把提交与会话关联起来SKILL.md 提到的post-commit 钩子将提交与会话关联由 plugin/scripts/post-commit.mjs 实现它通过git命令收集当前 HEAD 的sha、branch、远程仓库地址、提交信息、作者与变更文件列表git diff-tree --name-only然后POST /agentmemory/session/commit。这组数据正是commit-context与commit-history两个技能的数据来源。3.8 统一的网络与环境约定各脚本共享以下约定守护进程地址AGENTMEMORY_URL默认http://localhost:3111认证仅当设置了AGENTMEMORY_SECRET时才附加Authorization: Bearer SECRET头本地默认守护进程是开放的多余的头反而会被拒绝所有 fetch 都带超时800ms30s 不等失败一律静默绝不拖慢宿主。四、捕获策略默认零 LLM 开销按需开启增强SKILL.md 特别强调了一条设计原则记忆捕获默认开启且不消耗任何 LLM token。钩子只做结构化数据的旁路记录写观察、注册会话、关联提交不调用任何模型。而以下两个烧 token的能力是独立开关、默认关闭环境变量作用默认AGENTMEMORY_AUTO_COMPRESS将观察结果用 LLM 汇总压缩成结构化记忆关闭AGENTMEMORY_INJECT_CONTEXT把记忆注入回上下文SessionStart 与 PreCompact 时关闭这两个变量的完整说明见 plugin/skills/agentmemory-config/REFERENCE.md——该文件列出了全部 37 个AGENTMEMORY_*环境变量包括AGENTMEMORY_URL、AGENTMEMORY_SECRET、AGENTMEMORY_PROJECT_NAME、AGENTMEMORY_DATA_DIR、AGENTMEMORY_VIEWER_URL等配置从环境变量与~/.agentmemory/.env无需export前缀中读取。五、谁在消费这些钩子记录的数据SKILL.md 明确指出以下技能消费钩子记录的数据handoffSessionStart/SessionEnd 为每个工作单元划定边界交接时依据这些记录恢复工作现场recap与recall工具使用钩子记录的改了什么、为什么是检索与回顾的原材料commit-context与commit-historypost-commit 钩子关联的提交元数据是其数据源。六、观察缺失时的排查清单如果发现观察记录缺失请按 plugin/skills/_shared/TROUBLESHOOTING.md 的顺序排查确认插件已启用在宿主中运行/plugin list确认agentmemory显示为 enabled重启宿主插件的.mcp.json仅在启动时读取新安装或重新启用的插件不会在会话中途注册工具确认 MCP 连接检查/mcp确认agentmemory服务器处于 live 状态REST 兜底若 MCP 工具始终不可用但守护进程在运行可直接调用 REST API——设置AGENTMEMORY_URL指向守护进程默认http://localhost:3111仅当设置了AGENTMEMORY_SECRET时才附加 Bearer 头。各技能对应的 REST 端点参见 plugin/skills/_shared/TROUBLESHOOTING.md如POST /agentmemory/remember、POST /agentmemory/smart-search、GET /agentmemory/sessions等。另需注意守护进程同样只在启动时读取.mcp.json任何端口或鉴权变更都需要重启守护进程两条传输通道才会生效。七、小结agentmemory 的钩子系统把记忆捕获从显式操作变成了会话的隐形基础设施12 个生命周期事件覆盖了会话的起止、工具的成功与失败、提示词的提交、上下文压缩、子代理的启停、任务完成乃至提交关联全部通过零 LLM 开销的旁路 REST 调用完成。理解 plugin/hooks/hooks.json 中每个事件到脚本的映射以及AGENTMEMORY_AUTO_COMPRESS、AGENTMEMORY_INJECT_CONTEXT等开关的取舍你就能在不手动保存的前提下让recall、recap、handoff拥有完整、可靠的记忆原材料。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
