📈 The stable prefix grows
In a conversation, system + tools + entire history — including the model’s last response — form a stable prefix that grows with each turn. Only your next message is actually new; everything before it is identical to what has already been processed.
What it is
The stable prefix is the portion of the prompt that doesn’t change from one turn to the next: tools, the system prompt, and the accumulated history. It’s the cache’s “raw material” — the larger it is, the more tokens are cheap.
Why learn
Because this is what makes the conversation cheap: every answer Claude Code gives becomes part of the stable prefix for the next turn, so the conversation's "weight" shifts to the cache side (~0.1×) instead of the full price (1×).
Key concepts
Prefix = identical beginning that repeats turn after turn.
Only the end escapes — your new message is the only part that isn't cached.
Order assembly of: tools → system → messages.
Grows — the model’s response enters the history and makes the prefix larger.
The blue box (prefix, read from the cache) grows; the thin band at the top (your new message, written) gets proportionally smaller each turn.
🔁 Hit per turn
With each new message, only the end changes. The API rereads the entire prefix from the cache (read ≈ 0,1×) and writes only that turn's new block. This is called hit: the prefix matched and was served from the cache.
What it is
A hit occurs when the request prefix matches an already processed entry and is read back at ~10% of the price. In practice, each conversation turn is one large hit on the prefix plus a small write for the new part.
Why learn
Because it explains why the 2nd turn onward is much cheaper than the 1st: most of the prompt is already in the cache, and only the difference is reprocessed. This is the mechanism that keeps a long session from costing a fortune.
✓ What counts as a hit
- ✓Identical prefix byte for byte to the previous request.
- ✓Within the TTL window (cache still warm).
- ✓Only the new message at the end is written.
✗ What becomes a miss
- ✗Any different byte anywhere in the prefix.
- ✗TTL expired (its time to live ran out).
- ✗The model was changed (the cache is per model).
Key concepts
Hit = read from the cache (~0.1×).
Write = wrote the new block for the turn (~1.25×).
Miss = not found, processed in full (1×).
Per turn = 1 large hit + 1 small write.
⏱️ 5-minute TTL renewed with use
TTL is the cache entry’s lifetime. The default is 5 minutes, but with one important detail: it is renewed with every use.
In other words: as long as you respond within the ~5 min window, the clock resets and the cache stays warm indefinitely. An active conversation keeps the prefix cheap without you having to do anything special.
What it is
TTL (time-to-live) is how long the entry remains valid. Each read/write resets that clock, so a continuous sequence of messages never lets the cache go cold.
Why learn
Because working at a steady pace is literally cheaper—and because it explains the cost of resuming after a long pause (next topic and topic 6).
Practical tip
There's also a TTL of 1 hour (more expensive write, ~2×) for traffic with long pauses. It only applies when there are gaps > 5 min between requests — otherwise, the 5-minute TTL is enough and costs less.
Key concepts
Default TTL = 5 min.
Renews with use — each turn resets the clock.
Active conversation = cache always warm.
TTL 1h = write ~2×, for traffic with pauses.
📊 The cache % GOES UP every turn
This is the point that causes the most confusion. The cache it’s not a battery that runs down. A turn can mark only 40% from the cache — because a lot of new content was added (e.g., a large skill was loaded). But this new block becomes cheap read on the next turn, and the percentage goes up.
What it is
The “% cached” for a turn is how much of the prompt came from the cache (read) versus how much was new (write + uncached). Since what’s new today becomes cached tomorrow, the fraction read from the cache tends to grow turn by turn.
Why learn
Because it dispels the mistaken intuition that "the cache runs out." Seeing 40% in one turn isn't a problem—it's just a sign that something large was added, which will be cheap from now on.
The new block from the 40% turn (the skill) is exactly what makes the next turn reach ~99%: it becomes a cheap read.
Key concepts
| Turn | Read from cache | New | % cache |
|---|---|---|---|
| now (large skill) | 40k | 60k | 40% |
| next (short message) | ~100k | ~1k | ~99% |
✍️ First message = write
The first message in a conversation there’s nothing to read still — there is no previous prefix. So it writes the cache and pays a little more (write ≈ 1.25× with a 5 min TTL). It’s the only turn that writes the entire prefix.
What it is
The initial write is the "investment" that pays off in later turns. You write once to read cheaply many times.
Why learn
Because it prevents the shock of seeing the 1st turn be "expensive." It's not a bug or waste: it's the write that enables savings for the rest of the session.
1st turn — write
Records tools + system + the 1st message. Costs ~1.25× for what it records. Nothing to read yet.
2nd turn onward — read + small write
Reads the prefix at ~0.1× and writes only the new message. This is where the savings show up.
Key concepts
1st message only writes — doesn’t read.
Write ~1.25× (TTL 5 min).
Investment that makes the rest cheaper.
Starting with the 2nd read ~0.1× predominates.
🧊 Long pause = cold write
If you go over the ~5 min idle, the TTL expires and the entry disappears from the cache. The next message pays the write again — é o cold write. It's not a failure; the cache has just cooled down.
What it is
A cold write is the prefix being written again after the TTL expires. In terms of cost, it’s like restarting the conversation: you pay the initial write cost again.
Why learn
Because it explains why "resuming after lunch" costs: it was a cold write, not a problem. And it points to the solution—the 1 h TTL for workflows with predictable pauses.
Attention
Don’t confuse a cold write with a silent invalidator. A cold write happens because of time (TTL expired). The silent invalidator (Track 2, module 2.3) happens because of bytes that change in the prefix, even with a warm cache.
Key concepts
Pause > TTL = entry expires.
Cold write = rewrites the prefix.
Fix for gaps = 1 h TTL (write ~2×).
It’s not a bug — the cache cooling down.
Copy-run example — audit how much came from the cache
Objective: confirm, in a real API response, how much of the prompt came from the cache — see for yourself how cheap reads dominate the turns.
Numa resposta recente da API que você tem acesso (ou num
log de <caminho do meu log de requests>), leia o objeto
`usage` e me mostre os três campos:
- cache_read_input_tokens (lido do cache, ~0,1x)
- cache_creation_input_tokens (gravado, ~1,25x)
- input_tokens (só o resto não-cacheado, 1x)
Depois calcule e me explique:
1. a SOMA dos três (= tamanho total do prompt);
2. qual % veio do cache (read / soma);
3. se este parece um 1º turno (write alto) ou um turno
posterior (read dominante).How to verify: a sum of the three fields must match the total prompt size. In later turns of a warm conversation, cache_read_input_tokens must be the largest portion, and the cache % must be high (topic 4). In the 1st turn, the portion of cache_creation_input_tokens dominates (topic 5).
Module summary
Next module:
2.2 — Skills and tools: append vs. break