lockstep

Compaction

Compaction is summarizing a long agent conversation to free context space, then continuing from the summary. Files reload; chat-only instructions can be lost.

Compaction is how an AI agent keeps working past its context limit. Anthropic's engineering team describes it as taking a conversation that is nearing the context window limit, summarizing it, and starting a new window with the summary.

Compaction in Claude Code

Claude Code compacts automatically as you approach the limit. You can also run /compact yourself, with a focus such as /compact focus on the auth bug fix, so the summary keeps what you choose. Per the context window documentation:

ContentAfter compaction
Project-root CLAUDE.md and unscoped rulesRe-injected from disk
Auto memoryRe-injected from disk
Path-scoped rules and nested CLAUDE.mdReloaded when a matching file is touched
Files Claude read or editedUp to five re-read, most recent first
The conversationReplaced by the summary

Why instructions disappear

An instruction you only typed into the chat lives in the conversation, so compaction summarizes it, and the detail can be lost. That accounts for many reports of Claude Code forgetting rules mid-session. The fix is to put lasting instructions in the project-root CLAUDE.md, or add a SessionStart hook that re-injects context after compaction. More in why Claude Code ignores your CLAUDE.md.

For exactly what Claude Code keeps after compaction, see Claude Code context window.

What is compaction in Claude Code?
When a session nears its context limit, Claude Code summarizes the conversation and continues with the summary in a fresh window. It runs automatically, or you can run /compact yourself, optionally with a focus.
What survives compaction in Claude Code?
The project-root CLAUDE.md, unscoped rules, and auto memory are re-injected from disk. Path-scoped rules and nested CLAUDE.md files reload on demand. Up to five recent files are re-read. Instructions given only in chat are summarized and may be lost.
Why does Claude forget my instructions after compaction?
Because they were in the conversation, not in a file. The conversation is replaced by a summary. Put instructions that must persist in the project-root CLAUDE.md.

Related