Claude Code context management

Why the agent forgets

Claude Code works inside a finite context window - the running transcript of your conversation, the files it has read, and its own reasoning. As you work, that window fills. When it gets close to full, the tool compacts: it replaces older turns with a shorter summary so the session can keep going.

Compaction is necessary, but it is lossy. A summary keeps the gist and drops the specifics - the exact file path you were editing, the decision you made an hour ago and the reason behind it, the half-finished step you were on. The agent does not announce this. It simply continues with a thinner picture, and a few turns later it re-reads a file it already knew, re-asks a question you answered, or quietly undoes a choice you made together. That is the “it forgot everything” moment, and it is not a bug - it is the context window doing exactly what it is designed to do.

The three levers that actually help

You cannot stop compaction, but you can control how much it costs you. Three levers do most of the work:

• Keep the always-loaded context lean. Your CLAUDE.md and any files it pulls in are paid for on every turn. A bloated instruction file is not just ignored - it crowds out the working room you need. This is why CLAUDE.md best practices lean hard on brevity: write the file lean enough that it stays cheap as the codebase grows.
• Scope what you load. Reading an entire directory “to be safe” burns context you will want later. Point the agent at the specific files and let it search for the rest on demand. Loading less, more deliberately, is half of good context management.
• Carry durable state out of the conversation. The most important lever: anything you cannot afford to lose should not live only in the transcript. Write decisions, progress, and open questions to files on disk, where compaction cannot touch them.

State belongs on disk, not in the transcript

The transcript is the most fragile place to keep important information, because it is the first thing summarized away. The fix is to treat the conversation as scratch space and the filesystem as memory. A short state file - what we are building, what is decided, what is in progress, what is next - is something the agent can re-read at the start of any session and rebuild the picture in seconds.

This is also why the cleanest version of context management is a gated session handoff: at the end of a working block you capture state to disk and verify it, so the next session cold-boots from facts rather than from a lossy summary. The handoff is the moment context management pays off - when a fresh session opens the file and continues without you re-explaining the codebase.

Setup discipline, not a memory plugin

It is tempting to reach for a “memory” plugin that promises to remember things for you. Be skeptical. A bolt-on memory layer adds a moving part that can drift, go stale, or silently feed the agent the wrong recollection - and you still have to trust a summary you cannot see. Worse, it papers over the real problem instead of solving it.

Durable context is not a feature you install after the fact; it is a property of how the project is set up. When state lives in plain files in the repo, both you and the agent can read it, diff it, and correct it. That is the same instinct behind a project set up right and the broader Claude Code best practices: put the things that must survive into files the next session is guaranteed to read, and stop hoping the conversation remembers them.

How claudesetup handles it

This is exactly what claudesetup builds in from the first command. The scaffold ships a lean CLAUDE.md, a small docs charter for the reasoning behind your decisions, and a gated session handoff that writes verified state to disk - so context discipline is part of the project rather than a plugin you remember to add later. You start with a setup that already keeps its memory where compaction cannot reach it.