claude-mem 分支记忆的生产化收尾：Git 边界情形、性能守卫与端到端集成测试

本篇基于 claude-mem 仓库中的分支记忆（Branch Memory）工程 playbook 最后一个阶段文档，讲解该功能在生产化落地前如何完成三层加固：Git 边界情形（detached HEAD、shallow clone、worktree、非仓库目录）的防御处理、大候选集下的 git 进程性能守卫，以及覆盖写路径、向后兼容与跨分支去重的端到端集成测试。读完本文，你将掌握把"git 祖先关系"类功能做到生产可用的完整方法论，并了解一次真实的元数据丢失 bug 是如何在数据库工作队列往返中被发现并修复的。

1. 背景：分支记忆与 Phase 05 的目标

claude-mem 的分支记忆功能为每条 observation（AI 压缩后的会话记忆）打上 branch 与 commit_sha 元数据，使上下文注入和 MCP 搜索工具只返回"当前分支祖先链上可见"的记忆，避免未合并的兄弟分支内容污染当前工作上下文。此前的 Phase 01–04 已完成数据列迁移、祖先解析、写路径透传和 MCP 搜索过滤（见同目录下的 BRANCH-MEMORY-04.md）。

Phase 05 文档（BRANCH-MEMORY-05.md）定义的目标是："This final phase hardens the branch memory feature for production use"——处理边界情形、为大 observation 集增加性能守卫、并用集成测试验证完整端到端流程。文档列出的五大任务（加固 git 工具、性能守卫、集成测试、全量回归、最终端到端验证）在文档中均已标记为完成。

需要说明的是：当前仓库快照中未包含该 playbook 所引用的 src/services/integrations/git-branch.ts、src/services/integrations/git-ancestry.ts、tests/branch-memory-integration.test.ts 等文件（已用仓库搜索确认不存在）。因此本文的实现细节与验证结论均以该 playbook 文档本身的记录为准，Git 命令的语义则属于通用事实，可独立成立。

2. 边界情形加固：在昂贵的祖先检查之前先"问清楚环境"

分支记忆的核心计算是：给定当前 HEAD，判断哪些候选 commit 位于其祖先链上（即"对当前分支可见"）。这条路径上依赖多条 git 命令，而 git 在不同仓库状态下行为并不一致。Phase 05 逐一列出了必须处理的边界情形。

2.1 非 git 仓库目录：isGitRepository 早期守卫

文档要求在 src/services/integrations/git-branch.ts 中新增导出工具：

async function isGitRepository(cwd: string): Promise<boolean>

其实现是执行 git rev-parse --is-inside-work-tree，并在 resolveVisibleCommitShas 入口作为早期守卫使用——当工作目录不在 git 仓库内时，直接跳过后续昂贵的祖先检查（ancestry checks），避免对一个必然无结果的方向发起一系列 git 子进程。

这是典型的"前置廉价探测 + 后置昂贵计算"模式：rev-parse 是本地 O(1) 级命令，而祖先判断需要逐候选发起 git 调用，守卫的收益随候选集增大而放大。

2.2 detached HEAD：分支名置 null，commit SHA 照常采集

文档指明：git rev-parse --abbrev-ref HEAD 在 detached HEAD 状态下返回的是字面量字符串 "HEAD"，而不是某个分支名。因此正确的处理是：

• branch 字段置为 null（"HEAD" 不是合法分支名，存入数据库会产生脏数据）；
• commit SHA 仍然要照常采集——即使没有分支名，commit 粒度的可见性判断依然成立。

这体现了分支记忆的两级降级设计：分支名用于粗粒度展示，commit_sha 才是可见性判断的硬依据。

2.3 shallow clone：历史截断下的祖先检查

git merge-base --is-ancestor <A> <B> 在浅克隆（--depth 克隆）中可能直接失败，因为两个 commit 之间的真实历史被截断、命令无从判断。文档要求：把失败的祖先检查当作"不是祖先"处理，而不是抛错（"treating failed ancestry checks as 'not an ancestor' rather than erroring"）。这是一个明确的容错语义选择——宁可保守地少返回一些可见记忆，也不能让一次搜索/上下文注入因为环境形态而整体失败。

2.4 git worktree：共享对象库，命令应照常工作

当 cwd 位于 .claude/worktrees/ 下的 git worktree 时，由于 worktree 与主仓库共享同一套 git 对象库（object store），git rev-parse 系列命令应照常正确工作。文档要求通过一次手动快速测试或补充一个测试用例来验证这一点。这提醒了后续维护者：worktree 是"应当免费工作"的场景，一旦在这里失败，问题多半出在路径解析层而非 git 层。

3. 性能守卫：约束并发 git 进程，并用单次 git log 替代 N 次调用

resolveVisibleCommitShas / resolveAncestorCommits（位于 src/services/integrations/git-ancestry.ts）需要为每个候选 commit 判断祖先关系。候选集一旦增大（一个项目积累上千条 observations、去重后仍有大量不同 commit），逐个发起 git 子进程会成为瓶颈。Phase 05 在 resolveAncestorCommits 中加了两层守卫。

3.1 第一层：按 100 个一批分批并发

• 若 candidateCommitShas 超过 100 个，则按每批 100 个分批处理，批内使用 Promise.all 并发；
• 目的：控制同时存活的 git 子进程数量，避免"一次检查把进程表打满"。

即：并发度被显式封顶在 100，批与批之间串行推进。

3.2 第二层：超过 500 个候选时改用单次 git log 求交集

文档给出了针对超大候选集的另一条路线：

• 用 git log --format=%H HEAD 一次调用取出 HEAD 的全部祖先 commit；
• 再把候选集放入一个 Set 与之求交集，得到"可见候选"；
• 复杂度从 O(n) 次 git 调用降为 1 次 git 调用（文档原话："this is O(n) instead of O(n) git calls"，即线性次数的调用变为线性复杂度的内存运算加单次调用）。

该优化在候选数超过 500 时启用。两层守卫组合起来，小集合走低开销的逐批路径，大集合走单次枚举路径，git 子进程压力始终受控。

3.3 可诊断性：debug 级汇总日志

文档还要求添加一条 debug 级别日志（使用项目既有 logger），报告"检查了多少候选、多少最终可见"。这是典型的"默认安静、诊断时开口"的日志策略：帮助定位性能问题，同时不会在正常运行时制造噪音。

4. 集成测试：写路径、向后兼容与跨分支去重的完整覆盖

Phase 05 要求新建 tests/branch-memory-integration.test.ts，对完整分支记忆流程做端到端断言。五个测试点逐一拆解如下。

4.1 写路径：branch 与 commit_sha 列落库

调用 storeObservation() 时同时传入 branch 与 commitSha 参数，随后把该 observation 查回，断言数据库中 branch 和 commit_sha 两列被正确填充。这是"hook 检测到元数据 → 存储层持久化"链路的最低保证。

4.2 向后兼容：NULL 值必须始终可见

以 branch: undefined、commitSha: undefined 存入的 observation，在数据库中应为 NULL，且在带过滤条件的查询中必须始终可见——实现上依赖 commit_sha IS NULL 子句。也就是说过滤条件形如"匹配给定 SHA 或 NULL（存量数据）"，保证迁移前写入的历史记忆不会因为新过滤逻辑而凭空消失。

4.3 跨分支去重防护：内容哈希必须包含 branch

存入两条 title/narrative 完全相同、但 branch 不同的 observation，断言两条都被存储、不被去重。这反向验证了内容哈希（content hash）的构成中包含 branch 字段——否则同名记忆在不同分支间会被错误合并，分支隔离语义即告失效。

4.4 getObservationsByIds 的 commit SHA 过滤

存入带有不同 commit SHA 的若干 observation，用 commit_sha 过滤数组发起查询，断言只返回 SHA 匹配的 observation——外加 commit_sha 为 NULL 的 observation（再次落实 4.2 的向后兼容语义）。

4.5 getUniqueCommitShasForProject 去重集合

存入含重复值与 NULL 的多种 commit SHA，验证该函数返回正确的去重集合。此函数是后续"项目可见 commit 集"计算的数据基础。

文档记录的全量回归结果：1157 个测试全部通过（0 失败、3 跳过），覆盖 68 个测试文件，且 npm run build-and-sync 构建成功、worker 以最新代码成功重启。

5. 关键 bug 复盘：pending_messages 往返丢失分支元数据

Phase 05 最有价值的产出是它在最终验证时发现并修复的一个真实生产级 bug。

现象：hook 侧已经正确检测到 branch/commit_sha 并发送，但数据库中所有 observation 的 branch/commit_sha 依然是 NULL。

根因（文档原文要点）：

• PendingMessageStore.enqueue() 没有把 branch/commit_sha 写入 pending_messages 表的 INSERT；
• PendingMessageStore.toPendingMessage() 没有把这两列读回来；
• 结果：分支元数据在"数据库工作队列往返"（work queue round-trip）中整体丢失——写路径经过 pending 队列中转时，元数据在入队/出队两端双双漏损。

修复：把 branch/commit_sha 补入 enqueue() 的 INSERT 语句、PersistentPendingMessage 接口、toPendingMessage() 的转换逻辑，并为 pending_messages 表增加迁移 25（migration 25），同时落到 SessionStore.ts 与 migrations/runner.ts 两处。

这个 bug 的工程启示很典型：当数据流经"入队 → 落库 → 出队 → 消费"的管道时，每一端的列映射都必须独立验证；只在源头（hook）和终点（observations 表）做断言，会漏掉中间队列表的映射缺陷。集成测试必须覆盖完整管道，而不能只测管道两端。

6. 最终端到端验证：从 PRAGMA 到新会话的三段式检查

文档记录了 2026-02-25 的最终验证过程与结论。

6.1 验证步骤

1. 检查表结构——确认 observations 表已有 branch 与 commit_sha 列：

   sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA table_info(observations);"
   

2. 产生新数据——启动一个新的 Claude Code 会话，新产生的 observation 应带有 branch 与 commit_sha。

3. 查询验证——查看最近 5 条记录的元数据列：

   sqlite3 ~/.claude-mem/claude-mem.db "SELECT id, branch, commit_sha FROM observations ORDER BY id DESC LIMIT 5;"
   

6.2 验证结论（文档 Verification Summary）

• observations 表已有 branch（第 18 列）与 commit_sha（第 19 列）两列；
• pending_messages 表已有 branch 与 commit_sha 两列（迁移 25 已应用）；
• 全部 1157 个测试通过（0 失败、3 跳过），共 68 个测试文件；
• npm run build-and-sync 构建成功；
• worker 以最新代码成功重启。

7. 已知限制与适用前提

文档在收尾时明确列出了三项已知限制，使用分支记忆功能时应知悉：

1. 修复前写入的存量 observation 其 branch/commit_sha 为 NULL——这是向后兼容设计的一部分：commit_sha IS NULL 子句保证它们仍会出现在带过滤的查询结果中，不会被新逻辑"误杀"；
2. 已弃用的 storeObservationsAndMarkComplete() 方法不包含 branch/commit_sha（SessionStore 中仅现役的 storeObservations() 方法包含），通过弃用路径写入的数据不会有分支元数据；
3. 分支检测的前提条件：hook 输入中必须存在 cwd，且该目录位于一个 git 仓库之内——缺失 cwd 或非仓库目录时，observation 不会带分支元数据（此时依赖 2.1 的早期守卫优雅跳过）。

8. 小结：一个功能"最后一公里"的加固清单

Phase 05 用一页 playbook 演示了功能进入生产前的标准动作，值得作为通用清单复用：

• 边界情形先行：用廉价的 git rev-parse --is-inside-work-tree 守卫昂贵计算；detached HEAD 返回字面量 "HEAD" 时分支置 null、SHA 照采；shallow clone 的祖先检查失败降级为"非祖先"而非报错；worktree 依赖共享对象库免费工作；
• 并发封顶 + 算法换道：100 一批的 Promise.all 封顶 git 进程数，超过 500 个候选改走单次 git log --format=%H HEAD 加 Set 求交；
• 集成测试覆盖完整管道：写路径落库、NULL 向后兼容、内容哈希含 branch 的跨分支去重、按 SHA 数组过滤、去重集合正确性五个断言点；
• 端到端验证落到数据库：PRAGMA table_info 查列、真实新会话产生数据、SELECT 抽查最近记录；
• 把中间层映射缺陷当作一类 bug：pending 队列的 INSERT/转换两端漏字段导致元数据整体丢失，修复需同步补接口、INSERT、转换函数与数据库迁移（migration 25）。

需要再次强调的是，以上涉及具体文件与测试数量的结论均出自 BRANCH-MEMORY-05.md 的验证记录；在当前仓库快照中检索不到文档引用的 git-branch.ts、git-ancestry.ts 等实现文件，若要逐行核对实现细节，需以包含该功能的相应代码版本为准。