Cache Management

Optimize CDK Insights performance with intelligent caching. Learn how to configure, manage, and troubleshoot the analysis cache for your specific workflow.

Local persistence: Outside CI, privacy-safe analysis results are stored in the CDK Insights cache directory and reused for 6 hours by default. Cache keys include the resource content, source-file hashes, model and prompt schema, so relevant changes invalidate an entry. CI intentionally skips the local disk cache.

What is CDK Insights Caching?

How It Works

Analysis results are cached in memory and persisted locally
Subsequent scans reuse cached data
Cache expires based on TTL settings
Local entries survive process restarts outside CI

Benefits

Faster analysis on repeated scans
Reduced CPU and memory usage
Lower network bandwidth usage
Better developer experience

Caching Strategies

Aggressive Caching

TTL: 24 hours

Cache everything for maximum speed

Best for:

Large projects with infrequent changes

Pros:

Fastest analysis
Minimal resource usage

Cons:

May miss recent changes
Requires manual cache clearing

{
  "cache": {
    "enabled": true,
    "ttl": 86400000,
    "maxSize": 2000
  }
}

Balanced Caching

TTL: 2 hours

Balance between speed and freshness

Best for:

Most development workflows

Pros:

Good performance
Reasonable freshness

Cons:

May need periodic clearing

{
  "cache": {
    "enabled": true,
    "ttl": 7200000,
    "maxSize": 1000
  }
}

Conservative Caching

TTL: 30 minutes

Minimal caching for maximum accuracy

Best for:

Critical security analysis

Pros:

Always up-to-date
No stale data

Cons:

Slower analysis
Higher resource usage

{
  "cache": {
    "enabled": true,
    "ttl": 1800000,
    "maxSize": 500
  }
}

No Caching

TTL: N/A

Disable caching completely

Best for:

One-time analysis or when you need every scan to be fully fresh

Pros:

Always fresh
No cache management

Cons:

Slowest analysis
Higher AI credit usage on repeat scans

{
  "cache": {
    "enabled": false
  }
}

Cache Operations

Check Cache Status

View current cache configuration

Command:

cdk-insights cache-status

Example Output:

📊 Cache Status:
⚙️  Cache enabled: Yes
📄 Cache file exists: Yes
📏 Cache file size: 42.50 KB
ℹ️  Results persist on disk outside CI and expire after cache.ttl

Clear Cache

Remove the persistent analysis cache and auth token cache

Command:

cdk-insights clear-cache

Example Output:

🗑️  Clearing analysis cache...
✅ Cache cleared successfully
📊 Cache status: No persistent cache files

Troubleshooting Cache Issues

Cache uses too much memory

Symptoms:

Higher resident memory on long-running CLI sessions
Slow cache lookups

Solution:

Reduce cache.maxSize in .cdk-insights.json

Prevention: Pick a maxSize proportional to project size; clear the disk cache when troubleshooting

Commands:

cdk-insights cache-status

cdk-insights scan --noCache

Stale analysis results

Symptoms:

Missing recent changes
Outdated recommendations

Solution:

Clear cache or reduce TTL

Prevention: Use shorter TTL for active development

Commands:

cdk-insights clear-cache

cdk-insights scan --noCache

Cache corruption

Symptoms:

Analysis errors
Unexpected behavior

Solution:

Clear cache completely

Prevention: Regular cache health checks

Commands:

cdk-insights clear-cache

Cache not being used

Symptoms:

Always slow analysis
Cache shows as disabled

Solution:

Verify cache is enabled in configuration

Prevention: Monitor cache statistics

Commands:

cdk-insights cache-status

Check .cdk-insights.json

Cache Best Practices

Monitor Cache Performance

Regularly check cache status and size

Action:

Run cache-status weekly

Benefit: Identify optimization opportunities

Use Appropriate TTL

Set TTL based on your development cycle

Action:

2-4 hours (7,200,000-14,400,000 ms) for active development

Benefit: Balance performance and freshness

CI Runs Get Fresh Caches

The CLI deliberately skips its local disk cache in CI

Action:

No action needed - every CI job starts with a clean local cache

Benefit: Each CI run analyses current state without inheriting another runner's local entries

Configure Cache Limits

Set appropriate maxSize to control memory usage

Action:

Set maxSize based on project complexity

Benefit: Prevent excessive memory consumption

Ready to Optimize Your Cache?

Start by checking your current cache status and configuring the optimal strategy for your workflow.

Advanced Configuration Performance Guide

Documentation

Cache Management

Docs Home