Editor's note (November 2026): This article adapts a research note originally written against Claude Code v2.1.220. The basic agent-loop model is supported by current Claude Code and Claude API documentation. Exact internal message wrappers, token budgets, and cache behavior can change; examples below are conceptual, not a promise about every version or model. The two unpublished Part 0 notes have been skipped, so this is the first public article in the Context series.
If we want to discuss cache, compaction, or project instructions, first we need to know what “context” is. The answer starts with the agent loop, not with a settings file.
Questions worth asking
In Claude Code, you type in a chat window. Claude may read files, run commands, edit code, and then answer. But what actually happens between the interface and the model?
- Does the model remember earlier turns, or does the application supply them again?
- Does a
Readcall happen inside one model response, or does execution require another request? - Is a context-window limit a lifetime quota for a session, or a limit on a model request?
- Do earlier turns remain visible as a session grows?
- Does your typed message reach the model alone, or alongside instructions and other context assembled by Claude Code?
Without these answers, discussions of caching and compression are built on an unstable foundation.
The short version
| Question | Working answer |
|---|---|
| Is the model stateful across API calls? | No. A subsequent request must provide the relevant prior context. |
| How many model calls can one user turn involve? | More than one. Tool results can lead to additional calls; several tools may also be requested in parallel. |
| What is context? | The request-visible combination of tool definitions, instructions, and conversation content—not just the text you typed. |
| Is a context-window limit cumulative across a session? | No. It applies to a request/model context window; the actual size depends on the model and product configuration. |
| Does conversation history always grow unchanged? | In a straightforward loop it grows by appending turns. Compaction, context editing, and other transformations can replace or omit earlier material. |
| What happens to project instructions? | Claude Code assembles applicable instructions and other context into the request. Exact internal wrappers are version-specific. |
1. The model does not carry session memory between calls
The most important distinction is between the model and the harness—the application running the conversation.
A misleading picture is:
You speak for ten turns
↓
The model remembers all ten internally
↓
It answers turn eleven from stored state
A better picture is:
Turn 1: the harness sends the initial request
Turn 2: the harness sends relevant earlier turns plus the new message
Turn 3: it does so again
...
The model's response depends on what the harness includes this time. When Claude seems to remember a decision, that decision is generally present in supplied conversation history, a summary, an instruction file, memory, or retrieved material. Similarly, when it can refer to a previously read file, the relevant tool result or a representation of it has been made available to the current request.
This is why context management is primarily a harness problem: deciding what the next model invocation should contain.
The simple “send the whole history again” description is useful for understanding an ordinary loop, but not universal. The harness may compact old turns, trim or edit tool results, defer tools, or retrieve material just in time. What matters is the request-visible context, not an assumption that every earlier byte is always retransmitted unchanged.
2. One user turn can contain several model calls
Suppose you ask Claude to investigate an authentication bug. It may need to:
- Read
auth.py; - Read
login.py, whichauth.pyreferences; - Search for related calls;
- Edit a file;
- Run tests.
A simplified sequence looks like this:
Model call 1
input: user asks about the bug
output: assistant requests Read(auth.py)
Harness executes Read
result: auth.py content
Model call 2
input: prior exchange + Read result
output: assistant requests Read(login.py)
Harness executes Read
result: login.py content
Model call 3
input: prior exchange + both results
output: next reasoning or tool request
...
Final model call
output: a response without another tool request
The actual API represents tool use with an assistant tool_use block and a corresponding tool_result supplied afterward. Anthropic's tool-use guide documents this loop. A single assistant response can request multiple tool uses, so it is inaccurate to say that every individual tool call always requires a separate model invocation. The key point is that after tool execution, the model needs another opportunity to see the results before it can continue from them.
From the user's perspective this can appear to be one reply. Underneath, it may contain a sequence of model calls and tool executions.
3. The message list is a useful model, not an immutable ledger
In the simplest case, a conversation grows like this:
user message
assistant tool_use
user tool_result
assistant continuation
user's next message
...
Each new user input, assistant response, and tool result extends the context that the harness can use. This explains why long sessions become expensive and why old content may occupy space even when it is no longer relevant.
But “append-only forever” is not a hard rule. Compaction can summarize and replace older material; context editing can remove selected content; a branch or subagent may have a different history. Tool-use and tool-result relationships must remain coherent in the request, yet the harness may transform the history before sending it. We will examine message structure in Part 2 and compaction later in the series. Until those parts are published, the official Claude Code overview is the safer reference.
The practical question is therefore not “How big is the chat transcript?” but “What will the next model request actually contain?”
4. A context window limits a request, not the lifetime of a session
A common statement is: “This session has used 150K of its 200K context, so it will soon be over.” That can be a useful shorthand, but it can be misunderstood.
A context window constrains what a model can process for a request, including relevant input and room for output. It is not a counter that permanently accumulates every token ever used by the session. A session can last much longer than one window if older material is compacted, omitted, or reintroduced selectively.
The original research note used 200K as its working example. Treat that number as an example, not a universal Claude Code ceiling: available context windows and output limits depend on the chosen model and configuration. Check the current context-window documentation for the model you are using.
A simplified request budget includes:
┌───────────────────────────────────────────────┐
│ Tool definitions and available capabilities │
├───────────────────────────────────────────────┤
│ System and other governing instructions │
├───────────────────────────────────────────────┤
│ Conversation messages │
│ user input │
│ assistant replies and tool requests │
│ tool results │
│ applicable project context and retrieved │
│ material, when included │
└───────────────────────────────────────────────┘
Do not interpret the boxes as a guaranteed byte-for-byte serialization or fixed token allocation. The point is that tools, instructions, and messages compete for a finite request budget. MCP tool definitions, Skill metadata or bodies, project instructions, file reads, and long tool results can all affect that budget. Claude Code may defer some capabilities or load some content only when needed.
5. Your text is not the only thing in the request
If you type “Please investigate this bug,” your words are only one component of the request. Claude Code may also include applicable CLAUDE.md instructions, other selected guidance, tool descriptions, prior turns, and dynamically retrieved context.
In the v2.1.220 research note, one implementation path was described as prepending a synthetic, meta-marked user-context message containing a <system-reminder> wrapper around project instructions and the date. Conceptually:
application-supplied context
project/user instructions
date or environment information
actual user message
“Please investigate this bug.”
That internal wrapper is version-specific implementation detail, not a public Messages API contract. The durable lesson is that the harness can supply context alongside your message. When debugging why Claude followed an instruction, inspect the applicable instruction files and session context rather than assuming your typed words were the complete input. See Claude Code's memory and instruction documentation for supported file-loading behavior.
6. The agent loop in one diagram
User request
│
▼
Harness assembles the next model request
tools + instructions + selected conversation/context
│
▼
Model generates an assistant response
│
├─ final answer ────────────────► wait for user
│
└─ tool_use request(s)
│
▼
Harness executes tools
│
▼
Tool result(s) become available
│
└──────────────► assemble another model request
This diagram is the base for the rest of the series:
- Compaction changes how much old conversation survives in the next request.
- Project instructions and memory provide durable context outside the immediate user message.
- Subagents run a separate loop and usually return a narrower result to the parent.
- Just-in-time retrieval avoids loading all files, Skill bodies, or tool definitions up front.
- Prompt caching lets stable request prefixes reuse prior computation when the API's cache conditions are met.
- Meta-context mechanisms tell the model about changes or constraints without pretending they were typed by the user.
These are not separate replacements for the loop. They shape what the loop sends next.
7. Why prompt caching matters to cost
Consider an illustrative five-call task. Suppose the first request has a large stable prefix—tool definitions and instructions—followed by a smaller conversation. Subsequent calls add new messages and results. Without reuse, repeatedly processing the unchanged prefix makes the total input work grow quickly.
Call 1: stable prefix + initial messages
Call 2: stable prefix + earlier messages + result 1
Call 3: stable prefix + earlier messages + results 1–2
...
Prompt caching can reduce the cost and latency of qualifying repeated prefixes. But there is no honest universal “7× cheaper” or “one tenth of the whole request” claim: cache-write and cache-read prices, eligible blocks, TTL, and newly added tokens all matter. The original note's numerical example was a teaching illustration, not a measured bill.
The architectural conclusion survives the correction: a tool-using loop repeatedly sends related context, so preserving reusable prefixes is valuable. Caching helps make long-running, tool-heavy interactions practical, while compaction and retrieval control what must be included at all.
Summary
- The model does not carry a private conversation state from one API call to the next; the harness supplies relevant context.
- A single user turn can involve several model calls, with one response potentially requesting multiple tools.
- A growing message list is a useful baseline model, but compaction and other transformations mean it is not immutable or literally append-only forever.
- Context-window limits apply to model requests, not to a session's lifetime total; 200K is an example, not a universal limit.
- Tool definitions, instructions, messages, tool results, and retrieved content all affect the next request's context.
- Prompt caching can reuse stable prefixes, but exact savings depend on actual cache usage and pricing.
In one sentence: Claude Code repeatedly assembles a request for a stateless model, handles the response, executes any requested tools, and assembles the next request. Context management is the art of choosing what each iteration contains.
Next we will zoom in on the message structure itself: what a message contains, how tool-use and tool-result blocks relate, and what can safely change between calls.
Top comments (0)