D2 · The context window & prompt caching

Every message you send makes Claude Code resend the entire conversation from the very beginning. This lesson explains why that works: the window's three-layer structure, the auto-compaction that kicks in near the limit, and the prefix caching that makes "resending" cheap — ending with /context and /usage, which you can check for yourself at any time.

Why this lesson comes today

D1 covered the agentic loop, and how /context shows what the context contains. D2 answers the next three questions: how big is this window, what happens when it fills up, and why resending everything every turn doesn't end up slow and expensive. The answers map to this lesson's three mechanisms: the window limit, compaction, and prompt caching.

This lesson is the foundation for several that follow: the trade-offs between /clear, /compact, and /rewind in D6 session management all rest on "what breaks the cache and what survives compaction"; the cluster-D tips (cache invalidation, where the quota goes, long-session degradation) are question-shaped quick references to this lesson's mechanisms. Skip it and you will keep tripping over questions like "why did switching models suddenly make things slow" and "why did editing CLAUDE.md do nothing".

Core concepts, explained

Three layers, fully resent every turn

OfficialThe model remembers nothing between two requests. So every message you send makes Claude Code issue a brand-new API request that resends the complete context: the system prompt, project context, every previous message and tool result, plus your new message. New content is always appended at the end, so the vast majority of each request is identical to the one before. To play well with the cache, Claude Code orders the request by how often things change, least-changing first:

OfficialAbout the limit: the official interactive demo uses 200K tokens as its illustrative ceiling; Fable 5, Sonnet 5, Opus 4.6 and later models, plus Sonnet 4.6, support a 1M-token window (availability depends on your plan; you generally select the [1m] model variant, while Sonnet 5 simply runs at 1M). Run /context anytime to see what your current session actually uses, item by item.

Auto-compaction: when it happens and what survives

OfficialFilling the window does not end the session: as it nears the limit, Claude Code automatically performs compaction — replacing the whole conversation history with a structured summary. You can also act first: /compact focus on this topic compacts manually and tells it what to keep; /autocompact 500k (or the --autocompact startup flag, or the CLAUDE_CODE_AUTO_COMPACT_WINDOW environment variable) moves the trigger threshold earlier, settable from 100K to 1M. With nothing configured, the default is to compact only at the model's limit; cloud sessions and some models running with a 200K window trigger earlier.

OfficialAfter compaction, different content meets different fates: the system prompt and output style are untouched (they are not part of the message history); the project-root CLAUDE.md, rules without paths, and auto memory are re-injected from disk; rules with paths: and subdirectory CLAUDE.md files are lost until Claude reads a matching file again; the bodies of skills already invoked are re-injected, but truncated to 5,000 tokens each and 25,000 in total, oldest dropped first. Our takeSo rules that must always be present belong in the project-root CLAUDE.md (D4 expands on this), not in path-scoped rules.

Prompt caching: exact prefix matching

OfficialThe API compares the beginning of each request (the prefix) against recently processed content with an exact match: the matched part is reused directly and billed at the cache-read rate — roughly 10% of the standard input price; only the newly appended tail is processed at full price. Matching is exact, character for character: change anything in the prefix and everything after it must be recomputed; there is no per-file or per-fragment caching. On top of that, each model and each effort level has its own cache (they are part of the cache key), so switching either means rebuilding from scratch.

Our takeAnother way to put it: think of the session as a stack of pages you can never pull a sheet out of. The grader remembers how far they have read and each time only reads the new pages; but change a single character on a middle page and they must reread everything from that page onward — that is what "prefix" means, and why a change costs more the earlier it sits.

OfficialThe cache has a lifetime (TTL): every hit resets the timer, so continuous work keeps it warm. Subscribers automatically get a one-hour TTL (dropping to five minutes when past the limit and running on usage credits); API keys and cloud providers default to five minutes, and ENABLE_PROMPT_CACHING_1H=1 enables one hour. In Claude Code the cache's scope is roughly "one machine + one directory": different worktree directories of the same repo each build their own cache.

What breaks the cache, and what doesn't

OfficialWhat the invalidating actions have in common is changing the prefix or the cache key; what the safe actions have in common is only appending to the end of the conversation:

Misconceptions, cleared up

• "Editing CLAUDE.md takes effect immediately" — in reality it is read once at session start and held in memory; mid-session edits neither break the cache nor take effect. How to check: observe only after /clear, /compact, or a restart. Official
• "Switching models or effort is free" — even with not a single character of content changed, the entire request must be recomputed, and the next turn is noticeably slower and pricier. How to check: after switching, see whether cache write spikes in /usage. Official
• "The cache works per file" — whole-prefix matching is the only mechanism; there is no per-file or per-fragment cache, and file contents only enter the conversation layer when they are read. Official

How the mechanics land on speed and your bill

OfficialThe three most common "where did that cost come from" cases all follow from this lesson's mechanics. One: asking a single "what is this function called" in a long session costs far more than the question itself — every turn carries the full history, and the whole scroll is reread at the cache rate. Two: come back after longer than the TTL and the first message misses the cache entirely, reprocessing everything at full price — which is why the first turn after a break feels noticeably slow. Three: /compact itself has to read the entire stretch of conversation it summarizes, so running it while the cache is still warm is much cheaper — and when you genuinely switch tasks, /clear costs nothing at all. /usage flags behaviors like cache misses and long context when they account for more than about 10% of recent usage.

Hands-on: doable today

1. Start claude, do nothing yet, and run /context. Expected: the conversation layer is near zero, but the system prompt, tool definitions, CLAUDE.md, and memory already take a fair share — D1's "the window isn't empty before you even speak".
2. Send the prompt below verbatim so Claude reads one large file, then run /context again. Expected: the conversation layer (Messages) grows noticeably, mostly from the file's contents.
3. Run /usage and find the per-model breakdown. Expected: cache read far exceeds input — meaning most of the context is being reread at roughly one-tenth the price.
4. Deliberately break the cache once: switch models with /model, send a throwaway "continue", then check /usage again. Expected: cache write spikes, because the whole session was rewritten into the new model's cache. (This step consumes real quota — do it in a small session.)
5. Run /compact keep only the conclusions about that file. Expected: a "Conversation compacted" notice; /context then shows the conversation layer shrunk to a short summary.

Run a context experiment for me:
1. Pick one of the larger source files in this project and read it (your choice - don't ask me);
2. Summarize it in two or three sentences;
3. Estimate roughly how much this read added to the context.
I'll verify with /context and /usage afterwards - keep the summary under five lines.

Commands you will use repeatedly along the way:

/context    # what each kind of content takes up right now
/usage      # this session's token usage, cache read / cache write
/model      # switch models (used here to demo cache invalidation)
/compact keep only the conclusions about X   # focused manual compaction

How to know you've learned it

• You can name the three layers of the context without notes, and say when each one changes.
• You can list three actions that break the cache and three that don't, and explain each in terms of the prefix / cache key.
• You can explain why editing the project-root CLAUDE.md mid-session has no effect, and when it does take effect.
• Hands-on complete: you can point to cache read and cache write in /usage, and explain why cache write spikes right after /model.
• Self-test: in a session that has been open all day, you ask only "what is this function called" — why does it cost far more than the question itself? (Answer: every request carries the full history, reread at the cache rate; and if you were away longer than the cache TTL, the whole thing is reprocessed at full price.)