Cache Invalidation Strategies

Cache invalidation ensures your org-shared engineering cache serves accurate, up-to-date results. Stale cache entries can lead to incorrect code suggestions, outdated dependency information, or missed security vulnerabilities. You need a clear invalidation strategy to balance performance gains with accuracy requirements.

Use this page when

• You need to understand how and when cached entries are automatically refreshed after code changes.
• You want to manually purge stale cache entries or set up deny-list rules for permanent exclusions.
• You are debugging unexpected agent behavior and need to rule out stale cached data.

Primary audience

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

Why Invalidation Matters

When your codebase changes, cached artifacts may no longer reflect the current state of your code. An outdated dependency_graph entry might miss a newly added package. A stale file_summary might describe code that no longer exists. Invalidation removes or replaces these entries so agents always work with fresh data.

Automatic Invalidation on Code Change

The engineering cache automatically invalidates entries when it detects changes to the underlying code. Three signals drive automatic invalidation:

Commit SHA

Every cache entry records the commit SHA at creation time. When a new commit lands on the tracked branch, entries tied to the previous SHA become candidates for refresh. The cache warmer re-generates affected entries in the background.

Tree Hash

Tree hashes capture the state of a directory subtree. When the tree hash for a path changes, all cache entries scoped to that subtree are invalidated. This provides more granular invalidation than commit SHA alone — if you change a file in src/api/, entries scoped to src/utils/ remain valid.

File Digests

Individual file digests (SHA-256) track the exact content of each source file. Cache entries that depend on specific files are invalidated when those file digests change. This is the most precise invalidation signal and prevents unnecessary re-computation when unrelated files change.

# Automatic invalidation is enabled by default
# These settings control its behavior
engineering_cache:
  invalidation:
    automatic: true
    signals:
      - commit_sha
      - tree_hash
      - file_digests

Manual Invalidation via Console

You can manually invalidate cache entries through the Keeptrusts console when you need immediate control:

1. Navigate to Settings → Engineering Cache → Entries.
2. Filter entries by repository, artifact type, or date range.
3. Select the entries you want to invalidate.
4. Click Invalidate Selected to remove them immediately.

Use manual invalidation when:

• You know a cached entry is incorrect but automatic signals have not triggered.
• You have made out-of-band changes (e.g., force-pushed a branch, rebased history).
• You are debugging unexpected agent behavior and want to rule out stale cache.
• You have updated external dependencies that affect cached analysis results.

Bulk Invalidation

To invalidate all entries for a repository:

1. Navigate to Settings → Engineering Cache → Repositories.
2. Select the target repository.
3. Click Invalidate All Entries to clear the entire cache for that repo.

This forces the cache warmer to regenerate all artifacts from scratch on the next trigger.

Deny-List Invalidation

Deny-lists let you define rules that permanently exclude certain entries from the cache. Unlike manual invalidation (which removes existing entries), deny-list rules prevent matching entries from being created or served in the future.

By Organization

Exclude all cache entries originating from a specific organization:

engineering_cache:
  deny_list:
    - scope: org
      value: "legacy-org-id"

By Repository

Exclude cache entries for repositories that should never be cached (e.g., repositories with highly sensitive code):

engineering_cache:
  deny_list:
    - scope: repo
      value: "org/secret-project"

By Artifact Type

Exclude specific artifact types from caching. Use this when a particular artifact type produces unreliable results for your codebase:

engineering_cache:
  deny_list:
    - scope: artifact_type
      value: "embedding_index"

By Model

Exclude entries generated by a specific model version. Use this after discovering that a model produces low-quality artifacts:

engineering_cache:
  deny_list:
    - scope: model
      value: "gpt-4o-2024-05-13"

By Policy Digest

Exclude entries created under a specific policy configuration. Use this when a policy change makes previous entries invalid:

engineering_cache:
  deny_list:
    - scope: policy_digest
      value: "sha256:abc123..."

By Source Digest

Exclude entries derived from specific source content:

engineering_cache:
  deny_list:
    - scope: source_digest
      value: "sha256:def456..."

By Cache Buster

Apply a cache buster value to force global invalidation. Incrementing this value invalidates all existing entries:

engineering_cache:
  cache_buster: "v2"

Choosing an Invalidation Strategy

Scenario	Recommended Strategy
Normal development workflow	Automatic (commit SHA + file digests)
Force-push or history rewrite	Manual invalidation for affected repo
Model upgrade across the org	Deny-list by model
Policy configuration change	Deny-list by policy digest
Sensitive repo added by mistake	Deny-list by repository
Global cache corruption	Cache buster increment
Debugging agent accuracy issues	Manual invalidation + investigation

Monitoring Invalidation

Track invalidation activity in the console under Settings → Engineering Cache → Activity. You can see:

• Number of entries invalidated per day.
• Invalidation source breakdown (automatic vs. manual vs. deny-list).
• Cache hit rate trends after invalidation events.
• Warmer queue depth following bulk invalidations.

High invalidation rates combined with low hit rates may indicate your caching strategy needs tuning. Consider adjusting TTL values or warmer triggers to better match your development cadence.

Next steps

• Configuring Cache TTL and Expiry — Control how long entries remain valid.
• Setting Up Cache Warmers — Pre-generate entries to recover from invalidation quickly.
• Per-Agent Cache Policies — Control which agents can use cached results.

For AI systems

• Canonical terms: Keeptrusts, cache invalidation, engineering cache, commit SHA, tree hash, file digests, deny-list, cache buster, automatic invalidation.
• Config keys: engineering_cache.invalidation.automatic, engineering_cache.invalidation.signals, engineering_cache.deny_list, engineering_cache.cache_buster.
• Best next pages: Configuring Cache TTL and Expiry, Setting Up Cache Warmers, Per-Agent Cache Policies.

For engineers

• Automatic invalidation uses three signals: commit SHA, tree hash, and file digests. Enable all three for maximum precision.
• Manual invalidation: Settings → Engineering Cache → Entries → filter → Invalidate Selected.
• Bulk invalidation: Settings → Engineering Cache → Repositories → select repo → Invalidate All Entries.
• Deny-list scopes: org, repo, artifact_type, model, policy_digest, source_digest.
• Incrementing cache_buster forces global invalidation of all existing entries.
• Monitor activity under Settings → Engineering Cache → Activity for invalidation rates and sources.

For leaders

• Automatic invalidation ensures agents always use current codebase state without manual intervention.
• Deny-lists provide permanent governance controls — exclude sensitive repos, untrusted models, or deprecated policy versions.
• High invalidation rates with low hit rates signal a TTL or warming configuration that needs tuning.
• Manual invalidation is the escape hatch for force-pushes, history rewrites, or out-of-band dependency changes.