jcdavis131 Prompt Caching (Anthropic Messages API)
Caching reuses stable prompt prefixes; writes cost 25% more (5m TTL), reads cost 10% of base input.
Docs: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
Decision
| Mode | When |
|---|---|
| Automatic | Multi-turn chat; growing history should cache itself |
| Explicit | Static prefix + varying suffix (timestamp, user message) |
| Both | Long system/tools + growing conversation |
The one rule
Place cache_control on the last block whose prefix is identical across requests you want to share. Breakpoint on a per-request suffix (timestamp, session ID) → miss every time.
Structure
Order: tools → system → messages. Large stable content first; varying content last.
Verify
Check response.usage: cache_read_input_tokens, cache_creation_input_tokens, input_tokens. Both cache fields zero → not cached (too short, prefix changed, or first request).
Monorepo targets
- worker: cache tools + system; automatic on messages.
- Experiment loops: breakpoint before varying experiment config.
- SME fanout: shared charter cached; per-lane charter after breakpoint.
Do not cache: under minimum tokens, one-shot calls, prefixes that change every request.
API shapes, TTL, invalidation, checklist, model minimums
reference.md
Pair with
cost-transparency·deterministic-core-llm-judgment·agent-guardrails