ContextQMD
Back to Planning With Files

Claude Code lost context after compaction: how to recover and prevent it

docs/claude-code-lost-context-after-compaction.md

3.8.14.5 KB
Original Source

Claude Code lost context after compaction: how to recover and prevent it

Compaction replaces your conversation with a summary. The summary keeps the broad strokes and drops the working state: which phase you were in, which fixes were already applied, which approaches already failed. If Claude Code seems to have amnesia after /compact or an automatic compaction, that is what happened. This page explains why it happens, how to recover the current task, and how to make the next compaction a non-event.

The mechanism described here is planning-with-files, a skill that keeps the plan on disk in three markdown files and re-injects it into context every turn. Overview: README.

Why did Claude Code forget my plan after /compact?

Because the plan lived only in the context window. Compaction, whether manual /compact or autoCompact when the window fills, summarizes the transcript to free space. Summaries compress, and exact phase status, error history, and decisions are the first details to go. Afterwards the model knows roughly what the task was, but not where you were in it.

The context window is volatile memory. Anything that exists only there is equally lost to /clear, crashes, and compaction. The durable fix is the same for all three: write the working state to disk and read it back mechanically.

The 3-file pattern

For every complex task, the skill maintains three files in your project root:

task_plan.md      → phases and checkboxes; the resume point
findings.md       → research notes and decisions
progress.md       → session log and test results

Plain markdown, gitignored by default. Because the files live on the filesystem and not in the transcript, compaction cannot touch them. Claude Code runs 5 lifecycle hooks around them: UserPromptSubmit, PreToolUse, PostToolUse, Stop, and PreCompact.

The PreCompact flush hook

The skill registers a PreCompact hook with matcher *, so it fires on both manual /compact and autoCompact. When task_plan.md is present, the hook:

  • reminds the agent to flush in-context progress to progress.md before compaction completes
  • prints the active Plan-SHA256 when the plan is attested, so the post-compaction session can verify it resumes the approved plan
  • stays silent when no plan exists, and always exits 0, so it never blocks compaction

The protection model is deliberate: the plan does not survive compaction unchanged inside the context. The plan is on disk, and it is re-read after compaction. On the next turn the UserPromptSubmit hook re-injects the current plan between ===BEGIN PLAN DATA=== and ===END PLAN DATA=== markers, so the compacted session starts anchored to the same phases.

How do I recover context after compaction or /clear?

If the planning files were on disk before the wipe, recovery is mechanical rather than conversational:

  1. Session catchup checks the IDE session store for the previous session (~/.claude/projects/ for Claude Code).
  2. It finds when the planning files were last updated and extracts the conversation that happened after that point, the part most likely lost.
  3. It shows a catchup report. Then run git diff --stat, read the three files, update them, and continue.

Scope note: session catchup replays transcript and points at the files; the durable phase state itself comes from reading task_plan.md. In the project's internal recovery benchmark (v1, author-run), a fresh session with the files on disk resumed in 5.0 turns on average against 13.3 for a raw agent. Method and disclosed limits: docs/evals.md.

Can I reduce how often compaction happens?

Yes. Disable auto-compact in Claude Code settings and compact or /clear on your own schedule:

json
{ "autoCompact": false }

With the planning files on disk this is a safe default, because clearing stops being fatal.

Install

Claude Code, plugin route (ships the skill, hooks, and slash commands):

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

Every other agent, one line via the Agent Skills standard:

bash
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

Full route matrix and verification: README and docs/installation.md.