INTLO— back to the INTLO LABS home pageALL CONCEPTS
09 / 20Context6 MIN READ

Compaction

Compaction replaces the conversation history with a model-written summary so a long session can keep going inside the same context window.

Many conversation blocks compressing into one summarySix stacked message blocks on the left collapse toward a single summary block on the right. A separate re-injected block below shows that CLAUDE.md and auto memory are reloaded from disk after compaction.HISTORYsummarizeSUMMARYCLAUDE.md · memoryre-injected from disk

What it is

When a conversation approaches the auto-compact window, Claude Code sends a separate request containing your system prompt, tools, and full history, plus a summarisation instruction as a final user message. The response becomes the new conversation history. You see a "Conversation compacted" marker where the messages were. You can also trigger it yourself with /compact, optionally passing focus instructions.

Compaction is lossy on purpose, and what it loses is predictable. The system prompt and output style are untouched because they are not part of message history. Project-root CLAUDE.md, unscoped rules, and auto memory are re-injected from disk. Invoked skill bodies are re-injected but truncated — 5,000 tokens per skill, 25,000 total, oldest dropped first. Rules with paths: frontmatter and nested CLAUDE.md files are gone until their trigger file is read again.

/rewind offers two related but different operations. Summarize from here compresses everything after a chosen message; Summarize up to here compresses everything before it and keeps the later messages intact. Both leave files on disk untouched and leave the original messages in the session transcript, so the detail is still on disk even though Claude can no longer see it.

What it does for you

  • It keeps a long session alive. Without it, hitting the context limit would end the conversation instead of shortening it.
  • It lets you choose what to keep. /compact focus on the migration plan and the failing specs produces a summary built around what you named, rather than what the automatic pass guesses.
  • It reclaims the largest kind of waste cheaply. While the cache is warm the summarisation request reads your prefix from cache, so a mid-session compact costs a fraction of what the raw context size would suggest.

How it works

  1. 01A threshold or a command triggers it

    Automatic compaction fires at the auto-compact window: the model’s context limit by default, with earlier thresholds for cloud sessions, Sonnet 5, and models running at 200K. /compact triggers it immediately.

  2. 02Claude Code sends a separate summarisation request

    Same system prompt, same tools, same history, plus a summarisation instruction appended as a final user message. As of v2.1.198 it inherits the session’s extended thinking configuration.

  3. 03The summary replaces message history

    Decisions, task state, and the shape of what happened survive; verbatim tool output and file contents do not. Your focus instructions steer what the summary keeps.

  4. 04Disk-backed context is re-injected

    Project-root CLAUDE.md, unscoped .claude/rules/ files, and auto memory are read from disk again. Lazily loaded instructions are not.

  5. 05The conversation cache is rebuilt

    A shorter history does not share a prefix with the old one, so the conversation layer is invalidated by design. The system prompt layer is reused, and project context cache-hits only if CLAUDE.md and memory are unchanged since the session started. While the cache is still warm the summarisation request itself reads your prefix from cache, which is why a mid-session compact costs a fraction of what the context size suggests.

  6. 06The next turn is cheap

    The turn after compaction rebuilds the cache for the much shorter summary, so it is not the slow part. The cost lands in the summarisation request itself.

How to implement it

  1. 01Write durable state to disk before you get close

    Anything that must survive — a decision, a task list, a constraint — belongs in CLAUDE.md, a file in the repository, or auto memory. Chat-only content is what compaction eats.

  2. 02Set the window so compaction fires early

    Run /autocompact 500k, or set autoCompactWindow in settings, so the automatic pass has room to work instead of firing at the wall.

  3. 03Compact at task boundaries, with a focus

    Run /compact focus on <the thing you are still doing> between tasks. You choose when the overhead happens and what the summary is built around.

  4. 04Add standing compaction instructions to CLAUDE.md

    A line such as "When compacting, preserve the current task list, every architectural decision, and the exact commands that reproduce the bug" shapes the automatic pass too.

  5. 05Use rewind instead when you want to abandon a path

    If the last hour was a dead end, /rewind truncates back to an already-cached prefix. That is cheaper than compacting a history you did not want.

Examples

Compacting deliberatelybash
# Summarize now, built around what you name
/compact focus on the JWT migration: keep the staged plan, the decision to
keep the old cookie for one release, and the two specs still failing

# Compact earlier than the default so it never fires mid-task
/autocompact 500k

# Compress only part of the conversation instead of all of it
/rewind        # then choose "Summarize up to here" on the message you pick

# Abandon a dead end rather than summarizing it
/rewind        # then "Restore code and conversation"
Trigger it yourself at a boundary rather than letting it fire mid-task.
CLAUDE.mdmarkdown
## When compacting

Preserve, in this order:

1. The current task list and which items are done
2. Every architectural decision made in this session, with the reason
3. The exact commands that reproduce the bug under investigation
4. File paths already identified as relevant, even if not yet read

Drop: full file contents, command output, and any exploration that did not
change a decision.
Standing instructions that shape the automatic pass, not just the manual one.

Use it when

  • A long debugging session where the early exploration is finished and only the conclusion matters.
  • Switching from research to implementation inside one task, where the research output is no longer needed verbatim.
  • Freeing space before a large refactor that will read many files.
  • Compressing a verbose stretch in the middle of a session with Summarize up to here, keeping the recent messages intact.
  • Resuming an old session on a Pro or Max plan, where Claude Code offers to resume from a summary instead of the full history.

Avoid it when

  • You want to abandon the last stretch of work. /rewind truncates back to a prefix that is already cached; compaction builds a new one and keeps a summary of work you did not want.
  • You are switching to an unrelated task. /clear is cheaper and cleaner than paying to summarise a conversation you are done with.
  • You are mid-task and the details still matter. Compacting between two steps of a delicate change loses exactly the specifics the next step depends on.
  • You are resuming after a long break with no warm cache. The summarisation request then reprocesses the entire history as uncached input, which is when /compact costs the most.

Common mistakes

  • SYMPTOMClaude forgets a constraint you stated an hour ago and repeats a mistake you already corrected.

    FIXThe constraint lived only in chat. Put it in CLAUDE.md so it is re-injected from disk after every compaction.

  • SYMPTOMA path-scoped rule stops applying and nobody connects it to the compact.

    FIXRules with paths: frontmatter and nested CLAUDE.md files are lost until their trigger file is read again. Remove the paths: key, or move the content to the project-root file.

  • SYMPTOMA long skill body comes back mangled after compaction.

    FIXSkill bodies are re-injected truncated to 5,000 tokens each, keeping the start of the file. Put the instructions that matter at the top of SKILL.md.

  • SYMPTOMAuto-compaction fires in the middle of a multi-step change and the next step goes wrong.

    FIXLower the window with /autocompact 500k and run /compact yourself at boundaries so you control when the loss happens.

  • SYMPTOMResuming a week-old session and running /compact is unexpectedly slow and expensive.

    FIXThe cache expired, so the summarisation request reprocesses the full history uncached. Start a fresh session for new work, or accept the resume-from-summary offer.

Best practices

  • Write anything that must survive to disk before the window fills, not after.
  • Always pass focus instructions to /compact — an unguided summary keeps what the model guesses matters.
  • Compact at task boundaries so you choose when the overhead lands.
  • Add a "When compacting" section to CLAUDE.md so the automatic pass follows the same priorities.
  • Prefer /clear for a new task and /rewind for an abandoned path; reserve compaction for work you are still doing.
  • Put the important instructions at the top of long skill files, because truncation keeps the start.

Try it in five minutes

Make Claude lose an instruction, then make the same instruction survive.

  1. 1.Start a session and tell Claude: "For the rest of this session, prefix every reply with [WIDGET]." Confirm it does.
  2. 2.Run /compact with no focus instructions.
  3. 3.Ask another question. The prefix is gone — it lived only in the conversation.
  4. 4.Add the same instruction to your project CLAUDE.md, run /clear, and confirm the prefix is back.
  5. 5.Run /compact again and confirm it survives this time, because the project-root file is re-injected from disk.

Related concepts

Verified against code.claude.com/docs/en/context-window#what-survives-compaction on 2026-08-09. See content/SOURCES.md for the full table.

← / → MOVE BETWEEN CONCEPTS