Cache isn’t permanent—certain situations cause it to become invalid.

Cache Invalidation Scenarios

Tool Changes: Adding or removing MCP tools changes the tool list, and cache becomes invalid.

System Prompt Updates: Version updates change system prompts, and cache becomes invalid.

Model Switching: Different models have different system prompts—switching models invalidates cache.

Session Timeout: Cache has an expiration time—prolonged disuse invalidates it.

Interruption Detection Mechanism

How does Claude Code detect cache invalidation?

Cache Key Comparison: Calculate the cache key of the current prompt and compare with the server.

Prefix Matching: Check if content before cache breakpoints matches.

Version Control: System prompt version number changes trigger invalidation.

Graceful Handling

After cache invalidation:

  • Automatically rebuild cache
  • Inform user (optional)
  • Log for analysis

Optimization Strategies

Reduce Changes: Finalize MCP tools before starting a session.

Maintain Continuity: Ask consecutive questions in the same session for higher hit rates.

Avoid Frequently Switching Models.

Summary

Cache interruption is unavoidable, but can be optimized:

  • Identify invalidation scenarios
  • Detection mechanisms
  • Graceful handling
  • Reduce unnecessary invalidation