🧩 What prompt caching is
One idea, built piece by piece: the API reprocesses everything every time, the cache stores the stable beginning, and the beginning is identified by prefix matching — the exact bytes up to a cutoff point. Each term is defined the first time it appears.
🔁 The problem: reprocessing everything every time
All prompt caching savings start with understanding one pain point: the Claude API is stateless. With each message you send, the model receives the conversation entire again — and processes everything from scratch. In a long conversation, that's expensive and slow.
New here? Two terms first
- stateless — “stateless.” The API doesn’t retain the conversation between calls; the client (Claude Code) keeps the history and resends it on every turn.
- system prompt — the instruction text that comes before of the conversation (who the model is, what it can do). It's stable and always comes first.
Illustration: the bar grows with every turn because everything already said is sent again. It’s this repeated work that caching eliminates.
What it is
Because the API doesn’t store the conversation, the client resends the entire package—system prompt, tool definitions, and full history—with every request. The model then reprocesses that entire package before responding.
Why learn
Until you feel this pain, caching seems like magic without a purpose. Once you understand the reprocessing, each part of the course becomes “oh, that’s what it prevents.”
Key concepts
♻️ The idea: reuse the prefix
Notice one thing: the beginning of the conversation hardly changes. The system prompt is the same, the tools are the same, and the history already shared remains exactly the same. Only the end grows, with the new message. Prompt caching takes advantage of this: it stores that stable beginning — the prefix — already processed, and reuses it instead of processing it again.
New here? What is a "prefix"
prefix = the part at the beginning of the prompt that repeats exactly every turn. Think of the conversation as text that only grows at the end: the prefix is the frozen part at the top.
How reuse unfolds
Turn 1 — the prefix is processed and stored
The first time, there’s nothing to reuse: the model processes the prefix and writes in the cache (you pay a little more for it).
Turn 2 — the prefix is reused
The beginning is identical, so the model reads the already-processed cache prefix (cheaply) and only processes the new message at the end.
Turn N — the prefix only grows and stays cheap
With each turn, the reused prefix gets larger (the previous response is also included), but it continues to be read cheaply from the cache.
What it is
Prompt caching means storing the stable beginning of a conversation after it has been processed and reusing it on every turn, instead of reprocessing it from scratch.
Why learn
It’s the turning point for savings: you pay once for what doesn’t change, then only a fraction to read it again.
Key concepts
🧩 The invariant: prefix matching
Here’s the invariant that explains everything for the rest of the course. The cache recognizes the prefix by prefix matching: the key is the exact bytes of the prompt up to a cutoff point. A single different byte in the middle invalidates the cache from that point onward.
Illustration: the cache matches by prefix, not by “similarity.” It matches as long as the bytes are identical; at the first different byte, everything to the right gets fully processed.
✓ Keeps the prefix (matches)
- ✓Byte-for-byte identical system prompt
- ✓Same list of tools, in the same order
- ✓Only add new content at the end
✗ Breaks the prefix (invalidates it)
- ✗Change a word in the middle of the system
- ✗Inject a date/time or an ID that changes every time
- ✗Reorder the tools between requests
What it is
The cache key is the exact sequence of prompt bytes up to the breakpoint. As long as the bytes match, it’s a hit; at the first different byte, the rest is reprocessed.
Why learn
Because almost every "why didn't my cache hit?" comes down to one byte changing in the prefix. This invariant is the lens for diagnosing everything afterward.
Key concepts
📚 The order: tools → system → messages
If cache is a prefix match, then where where each thing sits in the prompt matters a lot. The prompt is always assembled in this order: tools (the tools), then system (the system prompt), then messages (the conversation history). Stable things go at the beginning; things that change with each request go at the end.
New here? "position 0" and "breakpoint"
- position 0 — the absolute beginning of the prompt. The tools go there; that’s why changing them breaks the cache the most.
- breakpoint — the marker that says “the cache goes up to here.” A breakpoint at the end of the
systemkeeps tools + system together.
Illustration: how tools e system stay before the cutoff; they’re the cheapest part to keep warm. Messages, which change all the time, go after it—where variation doesn’t cost the cache.
[1] tools → definição das ferramentas (posição 0, estável)
[2] system → prompt de sistema (estável)
── cache_control (breakpoint) ── ← cacheia [1]+[2]
[3] messages → histórico + mensagem nova (cresce no fim)What it is
The prompt assembly rule: tools first, then system, then messages. A breakpoint at the end of the system caches everything that came before it.
Why learn
Knowing the order tells you where to put what is stable (beginning) and what varies (end)—the architectural decision that best protects the cache.
Key concepts
🎯 Hit, miss, and write
Three words appear all the time — including in the numbers you’ll read in the next module. Hit is when the cache was read (cheap). Write is when the cache was written (a small premium). Miss is when nothing was found and everything was processed at full cost. The 1st message writes; the following ones read.
Illustration: the happy path is one write and a hit on every subsequent turn. A miss is the state you want to avoid—and the next module shows you how to spot it in the numbers.
✓ Leads to a hit
- ✓Continue the same conversation within the cache window
- ✓Identical to the prefix from a previous turn
✗ Leads to a miss / cold write
- ✗First turn of a new conversation (there’s nothing to read)
- ✗Prefix changed—the old cache no longer matches
What it is
The three outcomes of a request in relation to the cache: read (hit), written (write), or fully processed (miss).
Why learn
It’s the vocabulary you’ll see in the fields of usage and use it to diagnose whether the savings are happening.
Key concepts
✂️ Breakpoint (cache_control)
One piece is missing: how does the system know how far to cache? By the marker cache_control,
o breakpoint — which says "cache up to here." In Claude Code, this is
automatic: you don't mark it by hand, but understanding the concept explains why short segments aren't cached.
New here? "token" and "TTL"
- token — the little piece of text the model counts (roughly a syllable or short word). Price and size are measured in tokens.
- TTL — “time to live,” the cache entry’s lifetime. You’ll take a closer look at this in Module 1.2.
system: "Você é um assistente… (instruções estáveis)"
▲ cache_control: { type: "ephemeral" } ← breakpoint aqui
messages: [ …histórico…, {nova mensagem} ] ← fora do cacheThe breakpoint rules
- Maximum 4 per request — you can't mark as many cutoffs as you want.
- Minimum prefix ~1024–4096 tokens (varies by model) — below this, it isn't cached.
- Silent failure — if the segment is too short, it isn't cached and doesn’t error: you just don't see the savings.
Practical tip
In Claude Code, you don't manage breakpoints—the tool places them for you. What you control is not break the prefix (the rest of the course is about this). Keep the concept in mind; focus your attention on what actually changes.
What it is
The breakpoint (cache_control) defines where the prefix will be cached, with a limit of 4 per request and a minimum prefix size.
Why learn
Explains why short prompts seem to "not cache" and why, in Claude Code, you don't need to mark anything — but you do need to understand the mechanism.
Key concepts
Module summary
Next module
1.2 — Terms and savings: the three fields of usage, the TTL and the calculation of when the cache pays for itself.