feat: branch-scoped memory with git ancestry filtering

[thedotmack]

Summary

• Branch-scoped observations: Observations are tagged with branch and commit_sha at write time via detectCurrentBranch in the hook layer
• Git ancestry filtering: SessionStart context and MCP search results are filtered to only show observations from commits that are ancestors of the current HEAD
• Graceful degradation: Non-git directories, detached HEAD, shallow clones, and resolution errors all fall back to showing all observations (no data loss)

Implementation (6 phases)

Phase	What
01	Schema migration (branch/commit_sha columns), detectCurrentBranch, write path through storeObservation
02	resolveVisibleCommitShas git ancestry utility with git merge-base --is-ancestor batching
03	SessionStart ContextBuilder.generateContext() filters observations by branch ancestry
04	MCP search SearchManager.resolveBranchFilter() filters search/timeline results by ancestry
05	Edge case hardening: shallow clones, detached HEAD, worktrees, resolveViaGitLog fallback
06	Comprehensive integration tests for glue code (27 new tests, 76 assertions)

Test plan

• PendingMessageStore branch/commit_sha lifecycle (enqueue, claim, recovery)
• SearchManager resolveBranchFilter with direct SHAs, auto-resolution, error fallback, comma parsing
• ContextBuilder branch resolution, non-git fallback, error recovery, multi-project aggregation
• SDKAgent branch metadata capture from pending messages
• Hook layer detectCurrentBranch integration (normal, detached HEAD, non-git)
• Git ancestry: shallow clones, detached HEAD, worktrees, batching performance
• Full suite: 1182 tests pass, zero regressions

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR implements branch memory - a git-aware observation filtering system that creates visibility semantics similar to how git works. Observations are now tagged with the current branch and commit SHA when captured, and context generation filters observations to only show those from commits that are ancestors of the current HEAD.

Key changes:

• Added git-branch.ts and git-ancestry.ts utilities for detecting current branch/commit and resolving ancestor relationships
• Extended database schema with migrations 24 and 25 to add branch and commit_sha columns to observations and pending_messages tables
• Updated observation storage path to capture and persist branch metadata through the entire pipeline (hook → pending messages → worker → database)
• Implemented branch ancestry filtering in ContextBuilder and SearchManager using git merge-base for ancestor checking, with performance optimizations for large candidate sets (batching for 100+, git-log optimization for 500+)
• Maintained backward compatibility: observations with NULL commit_sha (pre-migration data) are always visible regardless of current branch
• Added comprehensive test coverage including integration tests, edge case handling (detached HEAD, shallow clones, worktrees), and filtering validation

Confidence Score: 5/5

• This PR is safe to merge with no critical issues found
• Score reflects thorough implementation with comprehensive test coverage (5 new test files), proper error handling throughout, maintained backward compatibility with NULL commit_sha values, performance optimizations for large repos, and clean separation of concerns. All git operations gracefully handle edge cases like non-git directories, detached HEAD, and shallow clones.
• No files require special attention

Important Files Changed

Filename	Overview
src/services/integrations/git-branch.ts	New utility for detecting current git branch and commit SHA, with safe error handling for non-git directories
src/services/integrations/git-ancestry.ts	New utility for resolving ancestor commits with batching optimization for large candidate sets, includes fallback to git-log for 500+ candidates
src/services/sqlite/observations/store.ts	Updated storeObservation to accept and persist branch/commit_sha parameters, includes branch in dedup hash to prevent cross-branch deduplication
src/services/sqlite/observations/get.ts	Added commit_sha filtering to getObservationsByIds with backward compatibility for NULL values, added getUniqueCommitShasForProject helper
src/services/sqlite/PendingMessageStore.ts	Added branch and commit_sha fields to persist branch metadata through the work queue round-trip
src/services/sqlite/migrations/runner.ts	Added migrations 24 and 25 to add branch/commit_sha columns to observations and pending_messages tables
src/services/context/ContextBuilder.ts	Added branch ancestry resolution to filter observations based on visible commit SHAs before rendering context
src/cli/handlers/observation.ts	Added branch/commit detection and passed through to worker via pending message queue
tests/branch-memory-integration.test.ts	New comprehensive integration tests for branch memory write path, backward compatibility, deduplication, and filtering
tests/git-ancestry.test.ts	New tests for git ancestry resolution including shallow clone handling and performance optimization paths

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Start([User works in git repo]) --> Detect[detectCurrentBranch<br/>reads branch + commit SHA]
    Detect --> Hook[Hook captures observation]
    Hook --> Queue[PendingMessageStore<br/>persists branch/commit_sha]
    Queue --> Worker[Worker processes message]
    Worker --> Store[storeObservation<br/>saves to DB with branch/commit_sha]
    Store --> DB[(observations table<br/>with branch + commit_sha columns)]
    
    Request([Context generation request]) --> GetShas[getUniqueCommitShasForProject<br/>fetches all candidate SHAs]
    GetShas --> Resolve{resolveVisibleCommitShas}
    Resolve -->|Not in git repo| ShowAll[Return null<br/>show all observations]
    Resolve -->|In git repo| Ancestry[resolveAncestorCommits<br/>git merge-base checks]
    Ancestry -->|Small set| Concurrent[Concurrent checks]
    Ancestry -->|100-500| Batched[Batched processing]
    Ancestry -->|500+| GitLog[git log optimization<br/>with fallback]
    Concurrent --> Filter
    Batched --> Filter
    GitLog --> Filter
    Filter[Filter observations:<br/>commit_sha IN visible SHAs<br/>OR commit_sha IS NULL] --> Context[Render context]
    ShowAll --> Context
    
    style DB fill:#e1f5ff
    style Filter fill:#fff4e1
    style Context fill:#e8f5e9

Loading

_{Last reviewed commit: a371e2c}