Branch Aware Context Retrieval Pipelines Design Tradeoffs: practical systems guide

# Branch Aware Context Retrieval Pipelines Design Tradeoffs: practical systems guide

When your AI coding assistant suggests editing `user_controller.rb` but grabs context from main while you're working in a feature branch that refactored it to `users/profile_controller.rb`, you've hit the branch awareness problem. Most context retrieval systems index a single revision, then watch as developers debug phantom conflicts and stale suggestions.

Branch-aware retrieval means your context pipeline knows which commit or branch state to search when assembling code context for LLM prompts. This isn't exotic—any team running parallel feature work needs it. But the implementation involves real tradeoffs between indexing cost, query latency, and correctness guarantees that shape how your AI tooling actually behaves in practice.

The naive approach fails fast

The simplest context retrieval pipeline indexes main once: build embeddings for every function and class, store them in a vector database, retrieve top-k matches when the LLM needs context. This works fine until a developer creates a branch, renames three modules, and asks the AI to "add validation to the payment flow." The retriever surfaces code that no longer exists in their working tree.

You could re-index on every branch checkout, but that burns 30-90 seconds per switch for a medium codebase—enough to break flow. You could index every branch, but with 200 active feature branches you're maintaining 200× the storage and background reindexing cost. The design space opens up when you treat branches as deltas, not isolated worlds.

Layered indexes: main plus branch diffs

One practical pattern layers a stable main index with branch-specific overlay data. When a developer works on `feature/payment-v2`, the retrieval pipeline:

1. Queries the shared main index (updated every few hours)

2. Applies a diff overlay capturing files changed in the branch

3. Re-ranks or filters results based on which files exist in the current HEAD

The overlay can be lightweight—just changed file paths and their new embeddings, not the entire repo. If your branch touches 40 files out of 3,000, you index 40, not 3,000. A simple heuristic: if a file hash differs between branch HEAD and main HEAD, it's in the overlay.

def retrieve_context(query: str, branch: str, main_index: Index):

    changed_files = get_changed_files(branch, base="main")

    

    # Fast path: query main index

    main_results = main_index.search(query, top_k=50)

    

    # Overlay: re-embed changed files and prepend matches

    branch_embeddings = embed_files(changed_files)

    branch_results = search_embeddings(query, branch_embeddings, top_k=10)

    

    # Merge and dedupe, prioritizing branch state

    return merge_with_priority(branch_results, main_results, limit=20)

This cuts indexing work dramatically. The tradeoff: queries now do two lookups and a merge. In practice, the overlay search is small enough (tens of files) that latency stays under 100ms. The real cost is complexity—you're now managing index versioning and merge logic.

Git-native retrieval: treat the DAG as ground truth

A more principled approach uses Git's object model directly. Instead of maintaining separate indexes, store embeddings keyed by blob SHA. When you need context for a file in `feature/payment-v2`, you:

1. Resolve the file path to its blob SHA in that branch's tree

2. Look up embeddings by SHA

3. Fall back to re-embedding if the SHA is new

This naturally deduplicates: if `utils.rb` hasn't changed across 15 branches, all 15 share the same embedding. The index grows only with unique content, not branch count. Storage scales with distinct blobs, not branch × file combinations.

# Example: resolve file to blob SHA

$ git rev-parse feature/payment-v2:app/models/payment.rb

a3f8d9c... 



# Lookup embedding for that blob

$ vector_db.get("blob:a3f8d9c...")

The downside: you need to walk Git trees on every query. For small changes this is negligible (modern Git is fast), but checking out an old commit or comparing against a stale base branch requires more tree traversal. You're trading index duplication for query-time Git operations.

Handling renames and moves without hallucination

Renames break naive retrieval. The LLM asks about "PaymentService" but it's been moved from `lib/payment_service.rb` to `app/services/billing/payment_service.rb` in your branch. Path-based lookups fail; semantic search might find it, but only if the content changed enough to warrant re-indexing.

One technique: maintain a rename map per branch, built from `git diff --name-status`. When a file shows as renamed (status `R`), store the old path → new path mapping. Query-time, check the rename map before looking up blobs:

def resolve_file_path(branch: str, path: str) -> str:

    rename_map = get_rename_map(branch)

    return rename_map.get(path, path)

This keeps retrieval deterministic. The cost is building and caching rename maps—trivial for recent branches, slower if you're comparing against a base from 200 commits ago. In Goatfied's agent loop, we cache these maps at plan time so subsequent validation and retry steps don't recompute the DAG walk.

Deciding what to index and when

You can't index every intermediate commit. Real systems pick anchor points:

• **Main/master only**: simplest, breaks on active branches
• **Main + active feature branches**: works if "active" is well-defined (last commit within 7 days, open PR)
• **Main + HEAD of every branch a user has checked out recently**: scales per developer, not per branch
• **On-demand indexing**: index a branch the first time a developer requests AI help in it, cache for 24 hours

Goatfied's managed offering uses the third approach—index what developers actually work with, expire unused branches after a week. Self-hosted teams often prefer scheduled indexing (nightly for main, hourly for branches with open PRs) to control compute cost.

The tradeoff is staleness. If you index only on push, a developer working locally for two hours has stale context. If you index on every file save, you're burning CPU on half-finished edits. A middle ground: index on commit, which signals "this is coherent enough to share."

Cache invalidation for multi-branch workflows

When main merges a breaking change, every feature branch's cached context is suspect. Aggressive cache invalidation (bust all branch overlays on main update) is correct but wasteful—most branches don't touch the affected code. Selective invalidation (track which files changed in main, invalidate only branches that also modified those paths) saves work but adds bookkeeping.

One pattern: tag embeddings with the main commit SHA they were derived from. On retrieval, if the developer's branch base is newer than the embedding's base, re-fetch. This bounds staleness to the merge-base lag, which for active branches is usually a day or two.

Where this matters in practice

Branch-aware retrieval shows up in three high-stakes moments:

1. **Merge conflict assistance**: the LLM needs to see both sides of the conflict as they exist in their respective branches, not a stale main snapshot

2. **Cross-file refactors**: when a developer renames an interface, the AI must suggest updates in files that import it, using the current branch's import paths

3. **Validation gates**: Goatfied's compile/lint/test loop runs against the branch HEAD; context for retry steps must match that exact state or the LLM chases phantoms

Getting this wrong means the agent loop suggests code that won't compile because it references moved symbols or missing imports. Getting it right means the first edit attempt uses accurate context, reducing retry cycles.

Related reading

• [Goatfied vs Cursor vs GitHub Copilot: a benchmark across 50 real PR tasks](/blog/goatfied-vs-cursor-vs-github-copilot-benchmark-50-pr-tasks)
• [The Goatfied agent loop: how we ship code that actually compiles first try](/blog/goatfied-agent-loop-compiles-first-try)