claude-mem 分支记忆 Phase 03在 SessionStart 上下文注入中实现提交祖先可见性过滤【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem导读本文基于 claude-mem 仓库的 Branch Memory 实施 playbook 中 Phase 03 文档BRANCH-MEMORY-03.md完整讲解该阶段的技术目标、四个核心任务的实现方式、SQL 过滤语义以及失败即全显fail-open的容错设计。读完本文你可以理解 claude-mem 是如何在每次会话启动SessionStart生成上下文时按 git 提交祖先关系过滤 observations让已合并分支的记忆自然可见、未合并兄弟分支的记忆保持不可见并了解其从 hook 输入到 worker 上下文生成接口的完整 cwd 传递链路。一、背景上下文注入管线与分支可见性问题claude-mem 的工作方式是记录 Agent 在会话中做过的一切用 AI 压缩为 observations观察与会话摘要再在后续会话启动时把相关上下文重新注入。上下文生成由 ContextBuilder 负责——它在数据库初始化、项目解析完成后调用queryObservationsMulti等查询函数拉取 observations再经时间线渲染、token 经济学计算后产出最终注入文本。在 Branch Memory 特性之前一个项目的 observations 对所有分支无差别可见。Phase 03 的目标是把祖先解析能力接入这条管线当新会话启动时ContextBuilder 只保留 commit SHA 是当前 HEAD 祖先的那些 observations。由此得到符合直觉的可见性规则已合并分支上的记忆随合并自然出现在祖先链上正常可见尚未合并的兄弟分支上的记忆保持不可见避免跨分支污染上下文迁移前创建的 observationscommit_sha为 NULL为保证向后兼容始终可见。这一设计刻意对齐 git 历史本身的语义而不是引入一套独立的分支作用域模型。二、任务一在 generateContext() 中解析分支可见性文档给出的实现方案是在generateContext()的前段数据库初始化、项目解析之后插入一步可见性解析调用两个工具函数getUniqueCommitShasForProject(db, project)来自 observations/get.ts 所在的查询模块取某项目下所有候选 commit SHAresolveVisibleCommitShas(candidates, cwd)来自src/services/integrations/git-ancestry.ts基于当前工作目录解析 git 祖先关系返回可见 SHA 集合。解析结果以visibleCommitShas: string[] | null的形式传递给 observations 查询函数。对于多项目worktree路径文档给出了一条重要推论worktree 共享同一份 git 历史因此按当前 cwd 做一次解析即可覆盖所有 worktree 项目无需逐项目重复解析。该任务完成时的实际实现状态文档标注已把getUniqueCommitShasForProject与resolveVisibleCommitShas导入 ContextBuilder跨项目收集全部唯一 SHA按 cwd 一次性解析出错时 fail-open返回 null即显示全部——这一点很关键上下文注入是会话启动路径上的功能解析失败时宁可见得多也不能让用户拿到空上下文。从源码结构看generateContext()的入口类型 ContextInput 本身就带有cwd?: string字段同时包含session_id、transcript_path、source、projects、platformSource等这意味着 cwd 作为祖先解析的锚点早已具备类型层面的通道Phase 03 的工作重点是把真实 cwd真正传到生成端而非合成路径。三、任务二observations 查询函数支持 commit SHA 过滤这一任务要求为查询函数增加visibleCommitShas?: string[] | null参数并定义了三种语义明确的过滤行为——这是整个 Phase 03 中最值得细读的部分visibleCommitShas取值过滤语义适用场景null不做任何过滤全部可见非 git 仓库 / 解析失败向后兼容、fail-open空数组[]仅显示commit_sha IS NULL的 observationsgit 仓库中 HEAD 无任何带 SHA 的观察非空数组追加 SQL 子句AND (commit_sha IS NULL OR commit_sha IN (?, ?, ...))参数化占位常规分支场景其中commit_sha IS NULL这一子句是文档特别强调的关键子句它保证迁移前创建的 observations早于分支记忆功能存在时写入在任何分支上永远可见。无论过滤结果如何变化历史记忆不会因引入分支可见性而消失这是向后兼容的直接落点。文档同时给出了该任务的完成状态新增buildCommitShaFilter()辅助函数位于 ObservationCompiler.ts使queryObservations与queryObservationsMulti均接受可选的visibleCommitShas参数并通过了 7 个单元测试。对照当前仓库中的 ObservationCompiler.ts可以看到多项目查询的既有形态queryObservationsMulti按project IN (...)/merged_into_project IN (...)圈定项目范围叠加platformSource过滤、type IN (...)类型过滤以及通过json_each(o.concepts)展开 concepts JSON 数组做概念匹配最后按created_at_epoch DESC排序并LIMIT到配置上限。Phase 03 的 SHA 过滤子句即叠加在这套 WHERE 结构之上遵循同样的参数化占位符风格projects.map(() ?).join(,)的写法与既有 SQL 构建模式保持一致。需要说明的一点证据边界在当前仓库快照中git-ancestry.ts与buildCommitShaFilter相关的实现及测试文件已不在源码树内全库检索无visibleCommitShas、commit_sha等匹配该 playbook 位于.maestro/playbooks/实施目录下属于某次实施周期的记录。本文对完成状态的转述均严格依据文档中的 Done 标注而对上述具体函数与测试可以推断它们曾按文档描述存在但在当前 checkout 中已被移除或重构阅读时应以文档为设计依据、以现存源码为现状依据。四、任务三让 cwd 从 hook 输入真实流入 ContextBuilder过滤能否生效取决于祖先解析的锚点 cwd是否真实可用。文档要求核对 session-init 流程ContextInput已有cwd?字段需确认 hook 输入的input.cwd来自 Claude Code JSON payload被实际传入而不是走合成路径。该任务完成的结论是上下文生成走 worker API 的/api/context/inject端点。改造后的数据流为hook 处理函数 context.ts 现在以cwd查询参数把真实 cwd 传给 workerworker 端 SearchRoutes.ts 提取该参数并传入generateContext()改造前这里使用的是一条合成路径/context/{project}——对 git 祖先解析毫无意义这正是必须修复的断点。当前源码可以印证该链路的关键环节context.ts 中const cwd input.cwd ?? process.cwd()之后调用getProjectContext(cwd)解析项目随后经 worker 路由触达上下文生成session-init.ts 同样以input.cwd ?? process.cwd()作为项目判定基准。这与文档描述cwd 从 hook 的 JSON payload 一路流到 worker 端点完全吻合。五、任务四构建与验证文档给出了完整的验证清单全部标记完成运行npm run build-and-sync并修复 TypeScript 编译错误通过日志确认 worker 启动后下一次 SessionStart 时 context builder 无错误运行分支过滤的端到端验证标准当前分支上创建的 observations 出现在上下文中而另一个未合并分支上的 observations 被排除测试结果npm run build干净通过7 个分支过滤测试20 个断言通过git-ancestry 与 observation-compiler 相关的既有 17 个测试继续通过无回归。这套验证方式体现了该项目的测试分层习惯既跑针对性新增测试也跑相邻模块的回归集确保在查询函数上加参数这类侵入式改动不破坏既有行为。六、设计要点总结把 Phase 03 的四项任务合起来看可以提炼出 Branch Memory 上下文侧的三个设计原则可见性语义对齐 git 本身不做额外的分支模型而是commit SHA 是否为 HEAD 祖先这一个判定。合并即可见未合并即可见性隔离与开发者对分支的直觉一致。NULL 兼容是兼容性的核心commit_sha IS NULL子句让预迁移数据永远可见null参数让非 git 场景与解析失败场景退回全可见。两条路径共同保证引入该特性不会造成任何既有记忆的不可见。fail-open 优先于过滤精度祖先解析发生在会话启动路径上任何错误都降级为null显示全部确保上下文注入这一核心功能的可用性优先于过滤的正确性。对于想深入仓库的读者建议的追踪路径是从 ContextBuilder.ts 的generateContext()主流程入手看 ObservationCompiler.ts 中queryObservationsMulti的 WHERE 子句组装方式再顺着 context.ts → SearchRoutes.ts 的/api/context/inject端点确认 cwd 传递链路同目录下的 BRANCH-MEMORY-01/02/04/05 文档则分别覆盖该特性的其他阶段可对照阅读。【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考