agentmemory commit-context 技能实战：从一行代码回溯到产生它的 Agent 会话

agentmemory commit-context 技能实战从一行代码回溯到产生它的 Agent 会话【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory导读当你在代码库里看到一行来路不明的代码、一个被反复修改的函数或是一次不清楚动机的提交时commit-context技能可以帮你把这段代码精确关联回产生它的那次 Agent 会话——包括当时的会话摘要、观察记录数量与高价值决策。本文基于 plugin/skills/commit-context/SKILL.md 与配套的 EXAMPLES.md结合 agentmemory 的 MCP 服务端、REST API 与 post-commit 钩子源码完整讲解从 git 定位 SHA → 调用memory_commit_lookup→ 呈现会话上下文的实战链路读完即可在任意支持 agentmemory 的编码 AgentClaude Code、Codex、Cursor 等中熟练使用这一追溯能力。为什么需要 commit-context解决这段代码为什么在这里Agent 会话产生的代码修改会被记录在 agentmemory 的观察observation体系中但 git 提交本身并不会自动携带这是哪个会话写的这一信息。当用户问出以下问题时正是commit-context的适用场景Why is this code here这段代码为什么在这里What was the agent doing when this changed改动发生时 Agent 在做什么Who wrote this这是谁写的希望了解代码库中某个具体位置的背景上下文技能定义plugin/skills/commit-context/SKILL.md 的 frontmatter将其描述为Trace a file, function, or line back to the agent session that produced its current commit即把一个文件、函数或行号追溯到产生其当前提交的那次 Agent 会话。它是一个user-invocable: true的独立技能参数提示为[file, function, or line]意味着它可以接收文件路径、函数名或行区间三种输入形态。值得强调的核心原则是只报告 git 与查询接口返回的事实。当查询返回commit: null时说明该提交早于会话关联机制此时绝不能根据 diff 凭空编造 Agent 意图——这是整个技能的行为底线也是它与普通git blame的核心差异它只回答是否有记录在案的会话而不是代码看起来在做什么。前提会话与提交的自动关联post-commit 钩子 KV.commitsmemory_commit_lookup之所以能查到结果是因为 agentmemory 在提交发生时就已经自动建立了提交 → 会话的关联。这一环节由 src/hooks/post-commit.ts 实现读取 stdin 中的钩子载荷直接由.git/hooks/post-commit调用时可能没有 stdin会走兜底逻辑通过git rev-parse HEAD取得当前提交 SHA也支持AGENTMEMORY_COMMIT_SHA环境变量覆盖依次抓取分支git rev-parse --abbrev-ref HEAD、远端仓库地址git config --get remote.origin.url、提交信息git log -1 --pretty%B、作者git log -1 --pretty%an %ae、提交时间git log -1 --pretty%aI以及变更文件列表git diff-tree --no-commit-id --name-only -r将这些字段连同sessionId来自载荷的session_id或AGENTMEMORY_SESSION_IDPOST 到AGENTMEMORY_URL默认http://localhost:3111的/agentmemory/session/commit接口全程 best-effort失败不阻断提交。服务端 src/triggers/api.ts 中的api::session::commit函数收到请求后会在KV.commits命名空间下按完整 SHA键写入CommitLink记录并在重复关联时合并sessionIds用Set去重、保留首次linkedAt时间戳同时反向更新Session.commitShas[]形成双向引用。写入过程使用withKeyedLock(commit:sha)与withKeyedLock(session:sessionId)加锁避免并发提交时的竞态。因此commit-context能正常工作的前提是你的工作目录已安装并启用了 agentmemory 的 post-commit 钩子见 plugin/hooks/post-commit.mjs 等钩子脚本与 plugin/plugin.json 的配置方式且那次提交发生在会话关联机制启用之后。启用之前的历史提交memory_commit_lookup会返回commit: null——这正是技能中反复强调要如实上报的情况。快速上手三步完成一次提交上下文追溯第一步用 git 定位 SHAcommit-context不自己解析 git而是要求先通过标准 git 命令拿到目标提交的完整 SHA。三种输入形态对应三条命令输入形态命令说明行区间git blame -L start,end file定位某几行当前归属的提交如git blame -L 40,52 src/auth/refresh.ts函数git log -L :function:file按函数名追踪其提交历史可加-n 1只取最近一次裸路径git log -n 1 -- file获取该文件最近一次变更的提交第二步调用 memory_commit_lookup拿到完整 SHA 后调用 MCP 工具memory_commit_lookupmemory_commit_lookup { sha: 9a1b2c3d4e5f60718293a4b5c6d7e8f901234567 }注意必须传完整 SHA40 位工具契约要求sha为必填字段见下文工具契约。第三步呈现结果查询返回后按以下结构向用户呈现参考技能 Workflow 的第 3 步提交信息完整 SHA、短 SHA、分支、作者、提交信息关联会话会话 ID、所属项目、起止时间、观察记录数量、会话摘要高价值观察当可用时通过memory_recall即memory_smart_search补充该会话中importance 7的观察记录作为当时到底在做什么的证据。预期的标准输出形态如下9a1b2c3 on main by dev: rotate refresh tokens Linked session 7f3a9c2 Auth refresh rework, 14 obs.工具契约memory_commit_lookup 的入参与返回结构工具定义位于 src/mcp/tools-registry.ts名称memory_commit_lookup描述Look up the agent session(s) that produced a specific git commit, given its SHA. Returns the commit metadata and linked sessions.入参对象类型唯一字段shastring完整 git 提交 SHA必填。返回值包含两部分commitCommitLink记录SHA、短 SHA、分支、仓库、提交信息、作者、提交时间、变更文件、会话 ID 列表、关联时间sessions与该提交关联的会话对象数组ID、项目、工作目录、起止时间、状态、观察记录数量、模型、摘要、commitShas反向引用等。值得注意的边界行为当 SHA 在KV.commits中不存在时服务端返回的不是错误而是{ commit: null, sessions: [] }HTTP 200。这与 REST 接口GET /agentmemory/session/by-commit返回 404 的行为不同是 MCP 层特意设计的可预期的空结果技能层据此输出该提交早于会话关联。底层实现MCP 服务端如何响应 memory_commit_lookup从 src/mcp/server.ts 可以看清完整的调用链case memory_commit_lookup: { const sha asNonEmptyString(args.sha); if (!sha) return { status_code: 400, body: { error: sha required } }; const link await kv.get(KV.commits, sha); if (!link) { return { status_code: 200, body: { content: [{ type: text, text: JSON.stringify({ commit: null, sessions: [] }, null, 2) }] }, }; } const linkRecord link as { sessionIds?: string[] }; const fetched await Promise.all( (linkRecord.sessionIds ?? []).map((sid) kv.get(KV.sessions, sid)), ); const sessions fetched.filter((s) s ! null); return { status_code: 200, body: { content: [{ type: text, text: JSON.stringify({ commit: link, sessions }, null, 2) }] }, }; }实现要点空 SHA 直接 400sha缺失或为空字符串时返回参数错误一次 KV 点查以完整 SHA 为键在KV.commits命名空间查询CommitLink并行拉取会话Promise.all并发按sessionIds逐个读取KV.sessions过滤掉已不存在的会话例如被清理的记录保证不会返回悬空引用响应统一走 MCP 文本内容协议结果以{ type: text, text: JSON.stringify(...) }包装返回给调用方。配套的 REST 实现api::commitssrc/triggers/api.ts与 MCP 的memory_commitssrc/mcp/server.ts则提供了批量视角按branch/repo过滤、limit默认 100 上限 500、按linkedAt倒序输出——它们与commit-context形成单点深入 批量概览的互补关系。数据模型CommitLink 与 Session.commitShas 的双向关联CommitLink的类型定义位于 src/types.tsexport interface CommitLink { sha: string; shortSha: string; branch?: string; repo?: string; message?: string; author?: string; authoredAt?: string; files?: string[]; sessionIds: string[]; linkedAt: string; }同时Session接口src/types.ts新增了commitShas?: string[]反向引用。这意味着正向给定提交 → 通过CommitLink.sessionIds找到会话commit-context使用的方向反向给定会话 → 通过Session.commitShas找到它产出过的所有提交可配合commit-history技能列出某会话的全部产出。关联的合并逻辑在 src/triggers/api.ts 中可见重复对同一 SHA 上报不同会话时sessionIds做并集合并、首次linkedAt保持不变、其余字段新值优先、旧值兜底。也就是说一次提交可能关联多个会话例如人工修正 Agent 修改混合产生呈现时必须把sessions数组完整列出而不是只取第一个。REST 回退方案当 MCP 工具不可用但守护进程在运行时plugin/skills/_shared/TROUBLESHOOTING.md 给出了 REST 直连方案。commit-context对应的回退接口是GET /agentmemory/session/by-commit?shasha要点设置AGENTMEMORY_URL为守护进程地址默认http://localhost:3111仅当设置了AGENTMEMORY_SECRET时才附带Authorization: Bearer secret——默认的本机守护进程是开放的带上多余请求头反而会被拒绝该接口在找不到关联时返回404与 MCP 层的{ commit: null }语义不同回退时需要区分处理。服务端实现见 src/triggers/api.ts校验 auth → 校验sha参数 → 查询KV.commits→ 并行拉取会话 → 返回{ commit, sessions }。批量的GET /agentmemory/commits支持branch、repo、limit查询参数则对应commit-history技能的回退注意给 commit-history 技能 的明确警告拼 REST URL 时必须用URLSearchParams/encodeURIComponent对branch、repo等值做 URL 编码否则含?、、#的分支名会破坏查询串。三个完整实战示例以下示例来自 EXAMPLES.md覆盖了行区间、函数、裸路径三种输入形态以及有会话/无会话两种结果。示例一行区间 已关联会话用户指着refresh.ts的 40-52 行问Why is this retry loop here?第 1 步定位 SHAgit blame -L 40,52 src/auth/refresh.ts # 9a1b2c3d (dev 2026-06-07) ... retry on revoked token第 2 步查询memory_commit_lookup { sha: 9a1b2c3d4e5f60718293a4b5c6d7e8f901234567 }第 3 步得到响应{ commit: { sha: 9a1b2c3d..., short: 9a1b2c3, branch: main, author: dev, message: rotate refresh tokens }, sessions: [ { id: 7f3a9c21, project: app, observationCount: 14, summary: Reworked refresh rotation } ] }向用户呈现9a1b2c3onmainby dev: rotate refresh tokens. Linked to session7f3a9c2Auth refresh rework (14 obs). The retry loop handles a token revoked mid-flight, per the sessions high-importance observations.注意最后一句的措辞它明确标注per the sessions high-importance observations——这是从高价值观察中得到的证据而非 Agent 从 diff 里猜测的意图。示例二函数追溯 早于会话关联的提交用户问What was the agent doing when it wrote validateScope?git log -L :validateScope:src/auth/scope.ts -n 1 # 1122aabb ...memory_commit_lookup { sha: 1122aabbccddeeff00112233445566778899aabb }响应{ commit: null }正确的呈现方式1122aabpredates agent session linking, so there is no recorded session. Fromgit show: it addedvalidateScopeto enforce per-token scopes. I can show the full diff if useful.这里的关键是如实说明该提交早于会话关联没有记录的会话然后用git show的事实而非编造补充 diff 层面的信息。示例三裸路径用户说Give me context on src/middleware/limit.ts.git log -n 1 -- src/middleware/limit.ts取出 SHA运行memory_commit_lookup再按示例一的形态呈现提交 关联会话。反模式绝不编造意图技能明确给出了对错对照这是所有使用者的行为红线错误示范WRONG查询返回{ commit: null }Agent 却仅凭 diff 叙述the agent was refactoring auth当时在重构鉴权。正确示范RIGHTThis commit predates session linking, so there is no recorded agent session. Fromgit show: it changed token rotation in refresh.ts.同理在呈现会话细节时必须逐字引用查询接口返回的内容会话 ID、观察数量、摘要不做转述、不四舍五入、不补充观察里不存在的意图。这一纪律与配套的 recall 技能 完全一致——recall 同样强调只呈现工具返回的结果绝不捏造观察、会话 ID 或重要度分数。输出自检清单每次使用commit-context后按下述清单自检来自 SKILL.md 的 Checklist 节SHA 来自git blame/git log而非猜测commit: null被如实报告为早于会话关联未编造会话会话详情逐字引用查询响应未声称超出观察记录所陈述范围的意图。配套技能与排障批量视角commit-history 技能memory_commits一次性列出多个已关联 Agent 会话的提交支持branch、repo、limit裸数字视为 limit默认 100、上限 500过滤输出按时间倒序深度挖掘recall 技能memory_smart_search搜索关联会话背后的观察记录用importance 7的高价值观察补充为什么排障若memory_commit_lookup不可用先执行TROUBLESHOOTING.md的标准流程——确认宿主/plugin list中agentmemory已启用、重启宿主.mcp.json仅在启动时读取、检查/mcp连接状态最后再走 REST 回退 的GET /agentmemory/session/by-commit?shasha。至此从git 定位 SHA到呈现关联会话与高价值观察的完整链路已经打通commit-context负责单点追溯commit-history负责批量概览recall负责纵深检索三者共同构成了 agentmemory 面向代码 → 会话 → 决策这一完整溯源链的查询体系。而这一切的基础是 post-commit 钩子在每次提交时自动写入的KV.commits关联记录——理解这条写入链路是正确解读查询结果的前提。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考