Environment-Specific Cache Configuration

Your engineering cache should behave differently across environments. Development needs fast iteration with relaxed constraints. Staging should mirror production for realistic testing. Production demands strict accuracy, full audit trails, and optimized performance. You achieve this through environment-specific YAML overlays and environment variables.

Use this page when

• You are setting up cache configuration that differs between development, staging, and production environments.
• You need to understand the layered override model (base → environment overlay → environment variables).
• You want recommended settings for each environment stage.

Primary audience

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

Configuration Strategy

The engineering cache configuration follows a layered approach:

1. Base configuration — shared defaults that apply everywhere.
2. Environment overlay — values that override the base for a specific environment.
3. Environment variables — runtime overrides that take highest precedence.

Base config (policy-config.yaml)
  └── Environment overlay (policy-config.{env}.yaml)
       └── Environment variables (KEEPTRUSTS_*)

Base Configuration

Your base configuration defines the shared structure and sensible defaults:

# policy-config.yaml
engineering_cache:
  enabled: true
  warmers:
    on_connect:
      enabled: true
      artifacts:
        - repo_map
        - dependency_graph
        - test_map
        - api_inventory
        - symbol_index
        - embedding_index
        - file_summary
    on_commit:
      enabled: true
      debounce_seconds: 30
    on_miss:
      enabled: true
      threshold: 5
      window_hours: 24
  ttl:
    defaults:
      hours: 168
  expiry:
    code_aware:
      enabled: true

Development Environment

In development, you want fast iteration, minimal warming overhead, and easy debugging. Relax caching constraints so changes are immediately visible:

# policy-config.development.yaml
engineering_cache:
  enabled: true
  warmers:
    on_connect:
      enabled: true
      artifacts:
        - repo_map
        - dependency_graph
    on_commit:
      enabled: false  # Skip commit warming in dev
    on_miss:
      enabled: false  # No adaptive warming in dev
  ttl:
    defaults:
      hours: 1  # Short TTL for rapid iteration
  default_agent_policy:
    semantic_replay: false  # Always fresh responses in dev
    max_staleness_hours: 1
  audit:
    enabled: false  # No audit trail overhead in dev
  deny_list: []  # No deny-list restrictions

Development Environment Variables

KEEPTRUSTS_CACHE_WARMER_CONCURRENCY=1
KEEPTRUSTS_CACHE_WARMER_POLL_INTERVAL_SECS=30
KEEPTRUSTS_ENGINEERING_CACHE_TTL_HOURS=1
KEEPTRUSTS_ENGINEERING_CACHE_AUDIT=false

Why Relax Caching in Development

• You frequently change code and need to see immediate effects on agent behavior.
• Cached responses from stale code confuse debugging sessions.
• Reduced warming keeps your local machine responsive.
• You can manually trigger warming when testing cache-specific features.

Staging Environment

Staging mirrors production behavior to catch issues before they reach users. Enable full caching with production-like settings, but add extra observability:

# policy-config.staging.yaml
engineering_cache:
  enabled: true
  warmers:
    on_connect:
      enabled: true
      artifacts:
        - repo_map
        - dependency_graph
        - test_map
        - api_inventory
        - symbol_index
        - embedding_index
        - file_summary
    on_commit:
      enabled: true
      debounce_seconds: 30
    on_miss:
      enabled: true
      threshold: 5
      window_hours: 24
  ttl:
    defaults:
      hours: 168
  default_agent_policy:
    semantic_replay: true
    max_staleness_hours: 168
  audit:
    enabled: true
    verbose: true  # Extra detail for debugging
  alerts:
    queue_depth_warning: 25  # Lower thresholds to catch issues early
    queue_depth_critical: 50
    oldest_job_age_warning_seconds: 300
    oldest_job_age_critical_seconds: 600

Staging Environment Variables

KEEPTRUSTS_CACHE_WARMER_CONCURRENCY=4
KEEPTRUSTS_CACHE_WARMER_POLL_INTERVAL_SECS=5
KEEPTRUSTS_ENGINEERING_CACHE_TTL_HOURS=168
KEEPTRUSTS_ENGINEERING_CACHE_AUDIT=true
KEEPTRUSTS_ENGINEERING_CACHE_AUDIT_VERBOSE=true

Why Mirror Production in Staging

• Cache-related bugs (stale responses, warming gaps) surface under production-like conditions.
• Performance testing requires realistic cache behavior to measure latency accurately.
• Integration tests validate cache interaction patterns before production deployment.
• Lower alert thresholds catch degradation earlier than production would.

Production Environment

Production configuration prioritizes accuracy, auditability, and performance. Every cache interaction is logged, strict freshness is enforced, and alerts fire at the first sign of degradation:

# policy-config.production.yaml
engineering_cache:
  enabled: true
  warmers:
    on_connect:
      enabled: true
      artifacts:
        - repo_map
        - dependency_graph
        - test_map
        - api_inventory
        - symbol_index
        - embedding_index
        - file_summary
    on_commit:
      enabled: true
      debounce_seconds: 15  # Tighter debounce for faster freshness
    on_miss:
      enabled: true
      threshold: 3  # Lower miss threshold for faster adaptation
      window_hours: 12
      max_jobs_per_hour: 50
  ttl:
    defaults:
      hours: 168
    overrides:
      recent_change_summary:
        hours: 24
      known_failure_fingerprint:
        hours: 48
  expiry:
    code_aware:
      enabled: true
      signals:
        - commit_sha
        - tree_hash
        - file_digests
  default_agent_policy:
    semantic_replay: true
    max_staleness_hours: 168
  audit:
    enabled: true
    verbose: false  # Standard detail level for production volume
    retention_days: 90
  alerts:
    queue_depth_warning: 50
    queue_depth_critical: 200
    oldest_job_age_warning_seconds: 600
    oldest_job_age_critical_seconds: 1800
    hit_rate_warning_percent: 60
    stale_serve_warning_percent: 5

Production Environment Variables

KEEPTRUSTS_CACHE_WARMER_CONCURRENCY=8
KEEPTRUSTS_CACHE_WARMER_POLL_INTERVAL_SECS=3
KEEPTRUSTS_ENGINEERING_CACHE_TTL_HOURS=168
KEEPTRUSTS_ENGINEERING_CACHE_AUDIT=true
KEEPTRUSTS_ENGINEERING_CACHE_AUDIT_RETENTION_DAYS=90

Why Strict Configuration in Production

• Accuracy affects real user workflows — stale cache entries cause incorrect agent responses.
• Audit trails support compliance requirements and incident investigation.
• Tight alert thresholds enable rapid response to cache degradation.
• Higher warmer concurrency and lower debounce keep cache fresh under production load.

Applying Environment Overlays

File-Based Overlays

Place environment-specific files alongside your base configuration. The gateway loads the appropriate overlay based on the KEEPTRUSTS_ENV environment variable:

KEEPTRUSTS_ENV=production  # Loads policy-config.production.yaml
KEEPTRUSTS_ENV=staging     # Loads policy-config.staging.yaml
KEEPTRUSTS_ENV=development # Loads policy-config.development.yaml

Docker Compose Per-Environment

Use Docker Compose override files for environment-specific service configuration:

# docker-compose.override.development.yml
services:
  keeptrusts-cache-warmer:
    environment:
      KEEPTRUSTS_CACHE_WARMER_CONCURRENCY: "1"
      KEEPTRUSTS_ENV: "development"

# docker-compose.override.production.yml
services:
  keeptrusts-cache-warmer:
    environment:
      KEEPTRUSTS_CACHE_WARMER_CONCURRENCY: "8"
      KEEPTRUSTS_ENV: "production"
    deploy:
      replicas: 3

Validating Your Configuration

After applying environment overlays, verify the effective configuration:

# Show the merged configuration for the current environment
kt config show --effective

# Validate configuration without applying
kt config validate --env production

The console also displays the effective cache configuration under Settings → Engineering Cache → Configuration with the active environment clearly labeled.

Next steps

• Per-Agent Cache Policies — Layer agent-specific policies on top of environment config.
• Tuning Cache Warmer Concurrency — Size warmers per environment.
• Configuring Cache TTL and Expiry — Set TTL appropriate to each environment.

For AI systems

• Canonical terms: Keeptrusts, environment-specific config, YAML overlays, KEEPTRUSTS_ENV, policy-config.development.yaml, policy-config.staging.yaml, policy-config.production.yaml.
• Config keys: KEEPTRUSTS_ENV, KEEPTRUSTS_CACHE_WARMER_CONCURRENCY, KEEPTRUSTS_CACHE_WARMER_POLL_INTERVAL_SECS, KEEPTRUSTS_ENGINEERING_CACHE_TTL_HOURS, KEEPTRUSTS_ENGINEERING_CACHE_AUDIT.
• Best next pages: Per-Agent Cache Policies, Tuning Cache Warmer Concurrency, Configuring Cache TTL and Expiry.

For engineers

• Layering order: base config → environment overlay (policy-config.{env}.yaml) → environment variables (KEEPTRUSTS_*).
• Development: disable commit/miss warming, set short TTL (1h), disable audit for fast iteration.
• Staging: mirror production settings with lower alert thresholds and verbose audit for early issue detection.
• Production: enable all warmers, strict freshness, full audit trails (90-day retention), tight alerting.
• Validate merged config: kt config show --effective or kt config validate --env production.
• Docker Compose: use override files per environment for service-level config.

For leaders

• Environment layering ensures production accuracy and compliance while allowing developers fast iteration in dev.
• Staging mirrors production to catch cache-related bugs before they affect users.
• Audit trails in production support compliance requirements and incident investigation (configurable retention).
• Dev environments can safely relax all caching to avoid confusion during debugging sessions.