Context: why your agent forgets and how to fix it

Most of the time the agent looks forgetful, the information you expected never reached that turn's context.

That changes the diagnosis. "It forgot" treats one symptom as one problem, and three distinct mechanisms sit behind it: compaction summarized the conversation, Claude Code read the file once when the session opened, or the rule depends on a trigger that never fired. Each has its own fix, and applying the wrong one burns time without solving anything.

The symptom stays the same: you repeat something you already said. The cause changes.

The middle two cost the most time, because they look like a model failure and the documentation describes them as designed behavior.

Compaction is not an indiscriminate sweep. It follows an order: Claude Code clears the oldest tool output first and summarizes the conversation only if it still needs room. Your requests and the relevant code passages stay. Detailed instructions from the start of the conversation run the most risk.

After the summary, each instruction mechanism lands somewhere different:

Two details in that table change how you write the files.

The first: skill truncation keeps the start of the file. An important instruction buried at the end of SKILL.md is the first thing to disappear in a long session. Write top down, with what matters most in the opening lines.

The second: the skill listing does not come back after compaction. Only the ones you invoked return. In a long session the agent loses the list of what it could invoke on its own, which explains why it stops suggesting skills it suggested at the start.

To steer the summary instead of hoping, you have two levers. The first is a Compact Instructions section in CLAUDE.md, which applies to every automatic compaction:

## Compact Instructions

When summarizing, always preserve:
- The data contract we agreed on for the orders API
- The decision to keep the old schema until the migration finishes
- File names already investigated and discarded, with the reason

The second is /compact with a focus, which applies to that pass alone:

/compact focus on the checkout migration, drop the CSS investigation

This is the case that confuses people most, because the behavior looks like a bug and the documentation lists it as design.

Claude Code reads your root CLAUDE.md and your user one once, when the session opens, and holds them in memory. Editing either mid-session neither invalidates the cache nor applies the change. The agent keeps working with the version it loaded when you opened the terminal. The new content arrives at the next /clear, /compact or restart.

The same goes for output style: part of the system prompt, read at startup, swapped only in the next session.

Files that load later behave the other way round. A subfolder CLAUDE.md and a rule with paths: enter the history when Claude reads the first matching file. Editing before that works. Editing after does not, because the content already became a message in the history.

The practical rule that comes out of it: if something has to hold for the whole session, it belongs in the root CLAUDE.md with no paths:. The anatomy of a CLAUDE.md covers the full hierarchy and where each scope earns its place.

Before your first word, the session has loaded the system prompt, CLAUDE.md, automatic memory, environment information, MCP tool names and the descriptions of the available skills.

Automatic memory comes in capped: the first 200 lines or 25 KB of MEMORY.md, whichever comes first. A memory file that grew without pruning loses its bottom half in silence.

MCP tools vary the most. By default, on compatible models, only the names enter, and the full schemas wait until something needs them. With ENABLE_TOOL_SEARCH=auto, the schemas load ahead of time if they fit in 10% of the context window. With false, all of it loads. Across a setup with several servers, the difference between those two settings is the difference between starting the session with room and starting it tight. The post on MCP in practice breaks down the cost per server.

To see your session's real distribution rather than an estimate, /context shows the breakdown by category, including which CLAUDE.md and memory files loaded. /mcp shows the cost per server.

1. Delegate large reads to a subagent. The biggest saving available. The subagent reads inside its own context and returns the final text plus a short metadata footer. In the documentation's own simulation, a subagent reads 6,100 tokens of files and returns 420. Subagents: when to delegate covers where delegating pays off and where it does not.

2. /clear between unrelated tasks. An old conversation does not sit there for free: Claude Code resends it with every following message, and it competes for room with the files you need now. The cost measurement across 48,000 real turns shows the size of that bill.

3. /compact with a focus, at the right moment. Running it between tasks puts the cost where you chose. Waiting for automatic compaction puts it in the middle of the work.

4. Adjust the compaction window. It sets how full the context gets before the automatic pass. The command and the flag accept 100K through 1M, in three equivalent formats:

/autocompact 500k          # k or M suffix
/autocompact 200000        # plain count
/autocompact 200           # bare number from 100 to 1000, in thousands
/autocompact auto          # back to the window matched to the model

claude --autocompact 500k  # this launch only, without saving

/autocompact saves to autoCompactWindow in your settings. In a script or a cloud environment, the CLAUDE_CODE_AUTO_COMPACT_WINDOW variable takes precedence over the command, the flag and the setting.

5. Hide a skill you only invoke by hand. disable-model-invocation: true takes the skill out of the initial listing, and it stays out of context until you type /name. For skills you did not write, skillOverrides does the same through your settings. The walkthrough for writing one is in how to write your first Agent Skill.

On the larger window: Fable 5, Sonnet 5, Opus 4.6 onward and Sonnet 4.6 support 1 million tokens, with availability varying by plan. On the API, Sonnet 5 runs at 1M and compacts around 967,000 tokens. A larger window postpones the problem without changing the mechanism.

This part is not about forgetting, and it explains a good share of the bill.

The model keeps nothing between requests. Claude Code resends the whole context every time, and prefix caching is what stops it reprocessing all of it. The comparison is exact and from the start: a change at any point in the prefix recomputes everything after it. There is no per-file cache and no per-passage cache.

That is why the request comes in layers, from what changes least to what changes most:

A token read from the cache costs about 10% of the normal input rate. That gap is wide enough to make the eight actions that throw the saving away worth knowing. They are: switching models, changing the effort level, turning on fast mode, connecting or disconnecting an MCP server with tools in the prefix, enabling or disabling a plugin that brings MCP along, denying a whole tool through a permission rule, compacting, and updating Claude Code.

Two of them surprise people. The model and the effort level are not prompt text, and they still enter the cache key: switching either recomputes the entire conversation with identical content. And opusplan alternates between Opus and Sonnet as you enter and leave plan mode, which makes each switch a model change.

On the other side, the actions that keep the cache: editing a repository file, editing CLAUDE.md mid-session, changing permission mode, invoking a skill or command, running /recap and creating a subagent.

/rewind deserves its own paragraph. It truncates the conversation back to an earlier point when you want to abandon a whole path, and that prefix is already in the cache. Compaction, in the same situation, builds a new prefix. To throw away bad work, rewinding costs less than summarizing.

And the cost of /compact depends on timing: with a warm cache, the summary call reads the prefix from cache and costs a fraction of what the context size suggests. After a long pause, the cache has expired and the summary reprocesses the whole history. That is why compacting when you resume an old session tends to be the most expensive request of the day.

One scoping detail catches people who use worktrees: the cache works per machine and per directory, because the system prompt embeds the working directory. Two worktrees of the same repository build different prefixes and cannot reuse each other's cache.

One case defeats every lever above: a single file or tool output large enough to fill the context again right after each summary.

Claude Code detects the cycle. After a few attempts it stops compacting on its own and shows an error rather than looping. The way out is to shrink the input: read the file in pieces, filter the command output before sending it, or push the read to a subagent.

The pattern holds as a general diagnosis. The window size is seldom the problem when the context fills too fast. The cause is a read that did not need to be whole. The guide to Claude Code in production treats this as a design constraint rather than a configuration one.

What is the difference between /clear and /compact?

/clear discards the conversation and starts over, reloading CLAUDE.md and memory from disk. /compact replaces the conversation with a structured summary and keeps the thread of the work. Use /clear when you move to something unrelated, and /compact to continue the same task with less weight.

Why did the agent ignore the rule I just added to CLAUDE.md?

Because Claude Code reads the root CLAUDE.md once, when the session opens. Your edit neither invalidates the cache nor takes effect. The new content loads at the next /clear, /compact or restart.

Does a new session start knowing what happened in the last one?

No. Each session opens with a clean context window, without the previous history. The files cross over: CLAUDE.md and automatic memory, capped at the first 200 lines or 25 KB of MEMORY.md. To pick the conversation itself back up, use --continue or --resume.

Does a subagent reuse the main session's cache?

An ordinary subagent does not: it starts with its own system prompt and tool set, and warms its own cache. A fork differs, because it inherits the parent's prompt, tools and history and reads the parent's cache on its first request. A subagent uses a five-minute cache TTL even on a subscription, where the main conversation uses an hour.

• Anthropic — Claude Code Docs: Explore the context window. Accessed 20 August 2026.
• Anthropic — Claude Code Docs: How Claude Code uses prompt caching. Accessed 20 August 2026.
• Anthropic — Claude Code Docs: Model configuration. Accessed 20 August 2026.
• Anthropic — Claude Code Docs: How Claude Code works. Accessed 20 August 2026.
• Anthropic — Claude Code Docs: How Claude remembers your project. Accessed 20 August 2026.

Verified on 20 August 2026.

Review trigger: revisit when (a) the skill reinjection caps change (5,000 per skill, 25,000 in total), (b) Sonnet 5's automatic compaction threshold moves off 967,000 tokens, or (c) the list of cache-invalidating actions gains or loses an item.