Configuring Cache TTL and Expiry

Cache entries do not live forever. You need expiry controls to ensure agents work with fresh data while maximizing cache hit rates. The engineering cache uses two complementary expiry mechanisms: code-aware freshness signals and time-based TTL.

Use this page when

• You need to balance cache hit rate against data freshness by tuning TTL and code-aware expiry signals.
• You are choosing TTL values for different artifact types based on team velocity and compliance needs.
• You want to understand how code-aware expiry interacts with time-based TTL.

Primary audience

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

Code-Aware Expiry

Most engineering cache entries are tied to specific source code. These entries use code-aware freshness signals rather than arbitrary time limits. An entry remains valid as long as its underlying code has not changed.

Freshness Signals

Each cache entry records the freshness signals present at creation time:

Signal	Granularity	Checked Against
Commit SHA	Repository-wide	Latest commit on tracked branch
Tree hash	Directory subtree	Current tree hash for the entry's scope
File digests	Individual files	SHA-256 of each dependent file

When an agent requests a cached entry, the cache validates freshness by comparing stored signals against the current repository state. If any signal has changed, the entry is considered stale and is not served.

# Code-aware expiry is the default for code-scoped entries
engineering_cache:
  expiry:
    code_aware:
      enabled: true
      signals:
        - commit_sha
        - tree_hash
        - file_digests

Advantages of Code-Aware Expiry

• Entries remain valid indefinitely if code does not change.
• No arbitrary TTL guessing — entries expire precisely when they become inaccurate.
• Repositories with infrequent changes benefit from long-lived cache entries.
• Active repositories automatically get fresh entries through commit-triggered warming.

Time-Based TTL

Some cache entries are not tied to specific source files. Examples include:

• recent_change_summary — summarizes recent activity, becomes stale over time.
• Embedding indexes — model drift may make old embeddings less relevant.
• Cross-repository analysis — depends on multiple sources that change independently.

For these entries, you configure a time-based TTL that forces expiry after a fixed duration regardless of code state.

Setting TTL Per Artifact Type

engineering_cache:
  ttl:
    defaults:
      hours: 168  # 7 days global default
    overrides:
      recent_change_summary:
        hours: 24
      embedding_index:
        hours: 336  # 14 days
      known_failure_fingerprint:
        hours: 72  # 3 days
      file_summary:
        hours: 0  # No time-based TTL (code-aware only)
      repo_map:
        hours: 0  # No time-based TTL (code-aware only)

Setting hours: 0 disables time-based TTL for that artifact type, relying entirely on code-aware freshness signals.

How TTL Interacts with Code-Aware Expiry

When both mechanisms are active, an entry expires when either condition is met:

• The code-aware signal detects a change → immediate expiry.
• The TTL duration elapses → time-based expiry.

This provides a safety net: even if freshness signal checks have a gap, the TTL ensures entries do not persist indefinitely.

Impact on Hit Rate vs. Freshness

TTL settings directly trade off between hit rate and freshness:

TTL Setting	Hit Rate	Freshness	Best For
Short (1–6h)	Lower	Higher	Rapidly changing repos, accuracy-critical agents
Medium (24–72h)	Moderate	Moderate	Active development, balanced workloads
Long (7–14d)	Higher	Lower	Stable repos, reference documentation, cost savings
Disabled (code-aware only)	Highest	Code-accurate	Source-tied artifacts with reliable signals

Measuring the Trade-Off

Monitor these metrics in the console under Settings → Engineering Cache → Analytics:

• Hit rate: Percentage of agent requests served from cache.
• Stale serve rate: Percentage of served entries that were later found to be outdated.
• Mean entry age at serve time: Average age of entries when agents consume them.
• Freshness delta: Time between source change and cache update.

Recommendations by Use Case

High-Velocity Development Teams

Teams pushing 20+ commits per day should use shorter TTL values for time-sensitive artifacts while relying on code-aware expiry for structural entries:

engineering_cache:
  ttl:
    overrides:
      recent_change_summary:
        hours: 12
      known_failure_fingerprint:
        hours: 24
      embedding_index:
        hours: 168
      file_summary:
        hours: 0
      dependency_graph:
        hours: 0

Stable Production Codebases

Repositories that change infrequently benefit from longer TTL values to maximize hit rates:

engineering_cache:
  ttl:
    defaults:
      hours: 336  # 14 days
    overrides:
      recent_change_summary:
        hours: 72

Compliance-Sensitive Environments

When accuracy is paramount and stale data carries regulatory risk, use aggressive expiry:

engineering_cache:
  ttl:
    defaults:
      hours: 24
    overrides:
      file_summary:
        hours: 0  # Code-aware only
      dependency_graph:
        hours: 0  # Code-aware only
      embedding_index:
        hours: 48

Cost-Optimized Deployments

When LLM costs for cache regeneration are a concern, extend TTL to reduce warming frequency:

engineering_cache:
  ttl:
    defaults:
      hours: 336  # 14 days
    overrides:
      recent_change_summary:
        hours: 48
      known_failure_fingerprint:
        hours: 168

Expiry and the Warmer Pipeline

When a TTL-expired entry is evicted, the system does not automatically enqueue a warmer job. Re-warming happens through the normal trigger mechanisms:

• The next commit refreshes affected entries.
• A repeated miss on the expired artifact promotes it to the warmer queue.
• You can manually trigger warming from the console.

To ensure critical artifacts are always warm, configure shorter TTL values alongside active commit triggers. This way, entries expire on schedule and are immediately replaced by commit-triggered warming.

Viewing Expiry Status

Check entry expiry status in the console:

1. Navigate to Settings → Engineering Cache → Entries.
2. Filter by repository or artifact type.
3. The Expires column shows the projected expiry time.
4. The Freshness column indicates the current signal status (fresh/stale).

Entries approaching expiry are highlighted in amber. Already-expired entries awaiting eviction are highlighted in red.

Configuration Reference

Setting	Default	Description
ttl.defaults.hours	168	Default TTL for all artifact types
ttl.overrides.<type>.hours	—	Per-artifact-type TTL override
expiry.code_aware.enabled	true	Enable code-aware freshness checks
expiry.code_aware.signals	All	Which signals to validate
expiry.eviction_interval_minutes	60	How often the eviction sweep runs

Next steps

• Cache Invalidation Strategies — Manually force expiry when needed.
• Setting Up Cache Warmers — Ensure expired entries are replenished.
• Per-Agent Cache Policies — Control freshness requirements per agent.

For AI systems

• Canonical terms: Keeptrusts, cache TTL, code-aware expiry, freshness signals, time-to-live, cache retention, engineering cache.
• Config keys: engineering_cache.ttl.defaults.hours, engineering_cache.ttl.overrides.<type>.hours, engineering_cache.expiry.code_aware.enabled, engineering_cache.expiry.code_aware.signals.
• Best next pages: Cache Invalidation Strategies, Setting Up Cache Warmers, Per-Agent Cache Policies.

For engineers

• Code-aware expiry (default) uses commit SHA, tree hash, and file digests — entries remain valid indefinitely if underlying code doesn’t change.
• Set hours: 0 to disable time-based TTL for source-tied artifacts (file_summary, repo_map, dependency_graph).
• Use short TTL (12–24h) for recent_change_summary and known_failure_fingerprint which become stale over time.
• Monitor trade-offs under Settings → Engineering Cache → Analytics: hit rate, stale serve rate, mean entry age, freshness delta.
• When both mechanisms are active, an entry expires when either condition fires.

For leaders

• TTL directly trades off cost savings (higher hit rate) against accuracy risk (stale data).
• Compliance-sensitive environments should use aggressive TTL (24h default) with code-aware only for structural artifacts.
• Cost-optimized deployments extend TTL (14 days) to reduce warming frequency and LLM spend on regeneration.
• Stable codebases benefit most from long TTLs; high-velocity teams need shorter TTLs for time-sensitive artifacts.