Shared Cache Across Feature Branches

Your engineering team works across many feature branches simultaneously. Most files in any given branch remain identical to the main branch. Keeptrusts uses source digest matching to share cache entries across branches when the underlying code is the same, creating branch-specific entries only for files that actually changed.

Use this page when

• You want to understand how org-shared cache entries are reused across feature branches via source digests.
• You need to configure branch TTL, stale branch cleanup, or understand merge behavior.
• You are troubleshooting low hit rates on feature branches or unexpected branch-specific cache entries.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Source Digest Matching

Every cache entry is keyed by a source digest — a content-based hash of the source material that generated the cached artifact. When you request a code summary for a file on branch feature/auth-refactor, the system computes the source digest for that file's current content.

If the file has not changed from the main branch, its source digest matches the existing cache entry. You get an instant cache hit regardless of which branch originally populated the entry.

What Gets Shared

The following cache artifacts share across branches when source digests match:

• Code summaries — File-level summaries are content-addressed. Unchanged files hit the same cache entry from any branch.
• Dependency graphs — Module dependency analysis shares when the import structure is unchanged.
• Test maps — Test coverage mappings share when test files and their targets are unchanged.
• Architecture context — High-level module descriptions share when the module boundary is unchanged.

What Creates Branch-Specific Entries

When a file changes on a feature branch, its source digest differs from the main branch. The system creates a new cache entry specific to that content:

• Modified files get new summaries based on their branch-specific content.
• Changed dependency relationships create new graph entries.
• New test files create additional test map entries without invalidating shared ones.

Partial Reuse in Practice

Consider a feature branch that modifies 5 files out of 200 in a module:

Artifact Type	Shared from main	Branch-specific	Total
File summaries	195	5	200
Dependency graph edges	~180	~20	~200
Test map entries	~45	~5	~50

You achieve 95%+ cache reuse for most feature branches because engineering changes are typically focused on a small subset of files.

How Fabric Handles Branches

Fabric artifacts (pre-computed code intelligence) use a layered approach:

1. Base layer — Fabric computed against the main branch serves as the foundation.
2. Delta layer — Branch-specific changes overlay the base layer.
3. Merged view — Queries against a branch combine the base and delta layers transparently.

This means you do not recompute entire repository fabric for each feature branch. Only changed portions require new computation.

Configuring Branch Cache Behavior

You control how branches interact with the shared cache:

cache:
  branch_strategy:
    base_branch: main
    share_unchanged: true
    branch_ttl: 72h
    stale_branch_cleanup: true
    cleanup_after: 7d

• share_unchanged enables source digest sharing across branches.
• branch_ttl controls how long branch-specific entries persist.
• stale_branch_cleanup removes cache entries for merged or deleted branches.

Long-Lived Feature Branches

For branches that live longer than a sprint, cache entries may drift from the main branch as main evolves:

• Source digests ensure that files unchanged on your branch still hit current main-branch cache entries.
• Files you modified early in the branch retain their branch-specific entries.
• Rebasing or merging main into your branch updates source digests for conflict-resolved files, potentially creating new cache entries.

Merge Behavior

When a feature branch merges to main:

1. Branch-specific entries that match the post-merge state become the new main-branch entries.
2. Superseded main-branch entries expire based on TTL.
3. Other branches that share source digests with the newly merged code automatically hit the updated entries.

Multiple Developers on One Branch

When several engineers work on the same feature branch, they all share branch-specific cache entries:

• The first developer to query a modified file populates the branch-specific entry.
• Subsequent developers on the same branch hit that entry immediately.
• Single-flight deduplication prevents redundant computations when multiple developers query simultaneously.

Cost Implications

Branch-level cache sharing dramatically reduces costs for teams with many active branches:

• A team with 20 active feature branches does not pay 20x the cache computation cost.
• Most computation costs are paid once on the main branch.
• Feature branches pay only for their delta — the files they actually changed.

Monitoring Branch Cache Efficiency

Track these metrics to understand branch cache behavior:

• Cross-branch hit rate — Percentage of branch queries satisfied by shared entries.
• Branch-specific entry count — Number of entries unique to feature branches.
• Branch cleanup volume — Entries removed when branches merge or close.
• Delta ratio — Average percentage of branch entries that are branch-specific vs. shared.

Best Practices

• Keep feature branches focused on small changesets to maximize shared cache reuse.
• Rebase frequently to align source digests with the latest main-branch entries.
• Configure branch TTL to match your team's average branch lifetime.
• Enable stale branch cleanup to prevent cache bloat from abandoned branches.

Next steps

• Review your branch cache hit rates in the Keeptrusts console under Cache Metrics.
• Configure branch_ttl and stale_branch_cleanup policies for your organization.
• Monitor delta ratios to identify branches that could benefit from smaller, more focused changesets.
• Caching for CI/CD Pipelines — how pipeline agents benefit from branch-shared cache.
• Sprint Planning Warmers — warm main branch cache before sprint starts.

For AI systems

• Canonical terms: Keeptrusts engineering cache, feature branch caching, source digest matching, branch-specific cache entries, cross-branch hit rate, delta ratio, branch TTL, stale branch cleanup.
• Feature/config names: cache.branch_strategy.base_branch, cache.branch_strategy.share_unchanged, cache.branch_strategy.branch_ttl, cache.branch_strategy.stale_branch_cleanup, cache.branch_strategy.cleanup_after, source digest, content-addressed cache key.
• Best next pages: Caching for CI/CD Pipelines, Sprint Planning Warmers, Migrating from Direct API.

For engineers

• Prerequisites: Org-shared cache enabled with share_unchanged: true in your gateway config.
• Validate: Create a feature branch, query AI about an unchanged file, and confirm x-keeptrusts-cache: hit from the main-branch cache entry.
• Monitor cross-branch hit rate and delta ratio in the Keeptrusts console to verify 95%+ reuse for typical feature branches.
• Best practice: Keep branches focused on small changesets, rebase frequently, and configure branch_ttl to match average branch lifetime (default 72h).

For leaders

• Branch-level cache sharing means teams with 20+ active branches do NOT pay 20x cache computation cost — most cost is paid once on main.
• Feature branches pay only for their delta (files that actually changed), typically 5% of total module size.
• Stale branch cleanup prevents cache bloat from abandoned branches, keeping storage costs predictable.
• Cost model: branch cache overhead is proportional to changeset size, not branch count.