Managing Claude Code's context budget like memory

Every long Claude Code session ends the same way if you let it: the agent that was sharp at 10 a.m. is re-reading files it already read, forgetting decisions you made an hour ago, and confidently contradicting its own earlier edits. The model did not get worse over lunch. Its context window filled up, and everything in an agent session competes for that one resource. Tokens are the cost; context is the constraint.

The mental model that fixed this for me is embarrassingly literal: treat the context window like a heap. Everything the agent does allocates. Nothing deallocates automatically. And when allocation outruns capacity you do not get a clean crash. You get degradation, which is worse, because it looks like the model being dumb rather than you leaking memory.

What allocates

Know where the bytes go before you optimize. In a typical session the window holds the system prompt and tool definitions (every MCP server you have connected pays schema rent whether you use it or not), plus your CLAUDE.md, plus every file the agent has read in full, plus every tool result verbatim: the four-hundred-line test log, the build output, the grep with ninety useless hits. Plus the entire conversation so far. Two things follow. First, big allocations dominate: one careless "read the whole file" on a generated five-thousand-line artifact costs more than an hour of conversation. Second, the advertised window is not the usable window: quality sags well before the hard limit, so budget for headroom, not for the spec sheet.

Measure, then free

You cannot manage what you do not measure, and Claude Code will show you the breakdown: the /context view is a profiler for your session. It shows how much is system overhead, MCP tool schemas, CLAUDE.md, message history. The first look is usually humbling. That MCP server you added months ago and never used is still charging thousands of tokens of schema on every session; uninstalling it is the cheapest optimization you will make all year.

Then free deliberately, with tools that behave very differently:

• /clear is free(). Between unrelated tasks, wipe the conversation. New task, fresh heap. It feels wasteful and almost never is. The previous task's residue misleads more than it helps.
• /compact is a lossy GC. It summarizes the history to reclaim space while preserving the thread. Use it at natural boundaries (after a milestone lands, before the next one starts) when the task genuinely needs continuity.
• Auto-compaction is the GC pause you did not schedule. When the window nears capacity, compaction fires mid-task and a summary decides what survives. Compact manually at boundaries you choose, or the system will choose for you.

Context is a heap: every file read is an allocation, nothing frees itself, and auto-compaction is the garbage collector screaming.

Don't leak

The steady-state discipline is stopping slow leaks. Subagents are the context firewall: a search across forty files burns the subagent's window, not yours: the parent session receives a three-sentence answer instead of forty file bodies. Any exploration whose intermediate steps you will not need later belongs behind that wall. Verbose tools are the second leak: prefer quiet flags and filtered output, because a test runner that prints three hundred lines of dots allocates three hundred lines of dots in your window forever. The whole token-diet toolbox applies double here, since wasted context costs twice: once in dollars, once in degraded attention.

And mind the CLAUDE.md tax. Every line of that file loads into every session, forever. It is the one allocation you re-pay hundreds of times, which changes the math: a two-thousand-word CLAUDE.md full of essays is a permanent lien on every future task. Keep commands, constraints, and pointers; move the explanations into docs the agent can read on demand.

Now the honest caveat: compaction loses information, and it does not know which information mattered. The summary can drop the one constraint you stated two hours ago, and the agent will not know it forgot — it will just be confidently wrong. After a heavy compact, the solid move is often to have the agent re-read the two or three files that matter, paying tokens again to restore fidelity. There is no free lunch here, only cheaper ones.

The discipline compounds: measure with /context before you blame the model, /clear at task boundaries, /compact only at milestones you pick, push exploration into subagents, keep CLAUDE.md terse, silence chatty tools. None of it is glamorous. Heap discipline never is. Right up until the session that has been running for six hours is still sharp, and everyone else is wondering why yours works.