A method to preserve cumulative context across multiple compaction cycles in AI coding agents (Claude Code, OpenAI Codex, and any LLM agent with context compression).
Every long-running AI agent eventually hits its context limit and compresses (compacts) the conversation. The default compaction summarizer loses critical information: decision reasoning, team state, historical arc. After 2-3 compactions, the agent behaves as if the session just started.
This method fixes that without modifying agent internals — using only the customization points that already exist.
The method is open and free. Use it however you want.
You're working with an AI coding agent on a complex task. After an hour, the context fills up. The agent compacts — compresses the conversation into a summary. You continue working. Another hour — another compaction.
After 2-3 compactions:
- The agent doesn't know why you chose approach A over approach B
- It re-proposes solutions you already rejected
- It doesn't know which agents (sub-processes) are still running
- It lost track of findings from reviews and audits
- It doesn't know what's blocking what
You re-explain. It compacts again. You re-explain again. Each compaction is a mini-amnesia. After 4-5 cycles, you give up and start a new session — losing everything.
The default compaction prompt in both Claude Code and OpenAI Codex is designed for single-compaction scenarios. It says "summarize the conversation" — and the model does exactly that. It summarizes what happened recently.
The problem is structural:
-
No cumulative instruction. The summarizer doesn't know it should look for previous compaction summaries and preserve them. Each compaction overwrites the previous one instead of appending to it.
-
No preservation of reasoning. "What was done" survives compaction. "Why it was done that way" does not. The next instance re-reads the code (what) but can't re-read the conversation where you explained why approach B was rejected (why). So it proposes approach B again.
-
No team awareness. In multi-agent systems, sub-agents may be alive across compaction boundaries. The summarizer doesn't capture their state. Post-compaction, the orchestrator spawns duplicates or says "no agents running" — while 10+ agents are still active.
-
No dependency tracking. "Task A blocks Task B" is critical operational state. Default summaries don't preserve it. Post-compaction, the agent works on B without completing A.
-
No findings preservation. Reviews and audits produce findings (bugs, risks, improvements). These drive the fix cycle. Default summaries mention "a review was done" but drop the specific findings. The fix cycle resets.
In Claude Code's default compaction prompt, the instruction is roughly: "create a detailed summary of the conversation, capturing technical details and code patterns." That's 9 sections covering what was done, files changed, errors encountered, and next steps. It's well-designed for a single compaction.
But there is zero mention of:
- Previous compaction summaries
- Historical context preservation
- Cumulative arc across multiple compressions
- Team/agent state
- Decision reasoning ("why", not just "what")
OpenAI Codex is worse — the default compact prompt is 6 lines. Just "summarize the conversation." That's it.
The result: after 2 compactions, all reasoning is gone. After 3, even the high-level direction is fuzzy. The agent becomes progressively less useful the longer you work — exactly when it should be most useful.
Three components work together:
┌─────────────────────────────────────────┐
│ COMPACT PROMPT │
│ (extended instructions for summarizer) │
│ "preserve history, reasoning, team" │
└──────────────────┬──────────────────────┘
│ defines what to preserve
▼
┌─────────────────────────────────────────┐
│ PRE-COMPACT HOOK │
│ (fires before compaction) │
│ "inject git state + continuity rules" │
└──────────────────┬──────────────────────┘
│ injects into compact prompt
▼
┌─────────────────────────────────────────┐
│ POST-COMPACT HOOK │
│ (fires on first message after) │
│ "warn about live agents" │
└──────────────────┬──────────────────────┘
│ one-shot injection
▼
┌─────────────────────────────────────────┐
│ BRAIN DUMP SKILL │
│ (manual pre-compact preparation) │
│ "structured delta since last compact" │
└─────────────────────────────────────────┘
-
Extended Compact Prompt — tells the summarizer HOW to summarize: preserve historical context cumulatively, capture reasoning, track team state, keep findings with severity.
-
PreCompact Hook — fires before compaction. Injects continuity rules and git context into the compact prompt via stdout. Safety net in case the summarizer forgets the extended instructions.
-
PostCompact Hook — fires on the first user message after compaction. Detects live agents from before compaction and injects a warning. Prevents the "no agents running" blindness.
-
Brain Dump Skill — a manual trigger (
/+) that the user runs before compaction. Forces the agent to output a structured brain dump of everything that happened since the last compaction. This becomes part of the context that the compactor summarizes — so even if the compactor is imperfect, the raw material is there.
Defense in depth. The compact prompt defines the rules. The PreCompact hook reinforces them at the critical moment. The PostCompact hook catches what both missed (agent state). The brain dump skill gives the user manual control when stakes are high.
In practice, the compact prompt alone handles 80% of cases. The hooks handle edge cases. The skill is for critical moments when you want to make absolutely sure nothing is lost.
Add 10 rules to the compaction instructions. These rules transform the summarizer from "summarize what happened" to "maintain a cumulative historical record."
Rule 1: Historical Thread
If this conversation contains text starting with "This session is being continued from a previous conversation" — that is a PREVIOUS compaction summary. Extract its key points (what was done, decisions, outcomes, direction) and include them in a "Historical Context" section at the TOP of your new summary.
This is the critical rule. Without it, each compaction overwrites the previous one. With it, each compaction APPENDS to a growing historical record. The phrase "This session is being continued" is the marker that Claude Code inserts at the start of every post-compaction context — we use it as a detection trigger.
Rule 2: Cumulative Road Map
Your summary must always answer: "What is the full journey of this session?" — not just "what happened recently." A reader should understand the ENTIRE arc from session start to now, even after multiple compactions.
Forces the summarizer to think holistically, not just about the recent segment.
Rule 3: Historical Context Format
Format:
## Historical Context (from previous compactions) - [Compaction 1]: What was done + KEY DECISION with reasoning. 3-5 sentences. - [Compaction 2]: Same format.The WHY behind decisions is MORE important than the WHAT.
Specific format prevents the summarizer from being vague. 3-5 sentences per compaction (not 1-2 — need room for WHY). Newest at the bottom. The section grows but stays compressed.
Rule 4: Team Roster with Context
List agents, their status, AND what they last worked on. Format:
coder: idle, last task: billing endpoint (committed). reviewer: idle, last task: reviewed billing PR (approved with 2 findings).
For multi-agent systems. Without this, the orchestrator post-compaction doesn't know who's alive, who did what, and what context each agent has. With this, it can send follow-up tasks without re-explaining everything.
Additional sub-rules:
- After compaction, ALWAYS check team status before spawning new agents
- Preserve the active team name — new agents join the SAME team
- Resume, don't respawn: agents lose conversation context after compaction but stay alive. Include brief context when sending follow-up tasks.
Rule 5: SCAN Protocol Context
Preserve active SCAN results if a task is in progress.
If using SCAN protocol for instruction drift prevention — don't lose the pre-task analysis across compaction.
Rule 6: Memory Anchors
Note any persistent memory observations saved during this segment — future sessions depend on them.
If using persistent memory (MCP, files, database) — track what was saved so the next segment knows what's available.
Rule 7: Key Decisions & Why
For each significant decision, capture not just WHAT was done but WHY that approach was chosen over alternatives. Format:
Decision: X. Why: Y. Rejected: Z.
This is the most impactful rule after Rule 1. Without it, the next instance re-proposes rejected approaches because it doesn't know they were rejected — or why. With it, decisions stick across compactions. No re-litigation.
Rule 8: Blockers & Dependencies
Explicitly note what depends on what. Format:
[A] blocks [B],[C] waiting on [D from user/external].
Operational state. The next segment must know what can proceed and what's stuck. Without this, the agent works on blocked tasks or ignores critical dependencies.
Rule 9: Findings Tracker
When reviews/audits produce findings, preserve them with severity AND effort estimate. Format:
[P0] critical-bug: description (1-line fix),[P1] risk: description (architectural, needs design),[P2] improvement: description.
Findings drive the fix cycle. Without this rule, a review produces 5 findings, compaction happens, and the findings are gone — replaced by "a review was done." The fix cycle resets to zero.
The effort estimate prevents treating a 1-line fix the same as an architectural rework. Post-compaction, the agent knows not just WHAT to fix but HOW MUCH WORK each fix is.
Rule 10: External Audit Summaries
When external tools produce audit reports, do NOT just save the file path — extract and inline the TOP 3-5 key conclusions with their IDs. The file path is for deep-dive; the inline summary is for immediate action after compaction.
In multi-tool workflows (Codex audits, external reviews), the report is in a file. After compaction, the summary says "audit saved to docs/audit.md" — but the agent doesn't read it automatically. By inlining the top conclusions, they survive compaction and are immediately actionable.
Both Claude Code and Codex support hooks that fire before compaction:
- Claude Code:
PreCompacthook in.claude/settings.local.json. Exit 0 + stdout = text appended to compact prompt. - Codex:
experimental_compact_prompt_filein.codex/config.toml. Points to a markdown file that replaces the default compact prompt entirely.
The PreCompact hook injects two things:
-
Historical continuity rules — a compressed version of Rules 1-4 and 6, as a safety net. Even if the extended compact prompt is somehow not loaded, these rules make it into the compaction.
-
Git context — current branch, recent commits, diff stat. The summarizer can anchor the historical record to specific commits. Post-compaction, the agent knows not just "we worked on feature X" but "we worked on feature X, commit abc123, branch feat/feature-x."
In .claude/settings.local.json:
{
"hooks": {
"PreCompact": [
{
"hooks": [
{
"type": "command",
"command": "python .claude/hooks/precompact_save.py",
"timeout": 10
}
]
}
]
}
}The hook script:
#!/usr/bin/env python3
"""
PreCompact hook: inject historical continuity rules + git context.
stdout → appended to compact prompt. exit 0 = success.
"""
import subprocess, sys
def git_cmd(*args):
try:
result = subprocess.run(
["git", *args], capture_output=True, text=True, timeout=5
)
return result.stdout.strip()
except Exception:
return ""
branch = git_cmd("branch", "--show-current")
log_recent = git_cmd("log", "--oneline", "-5")
rules = [
"IMPORTANT — Historical Continuity Rules:",
"",
"1. If this conversation contains text starting with "
"'This session is being continued from a previous conversation' "
"— that is a PREVIOUS compaction summary. Extract its key points "
"and include them in a 'Historical Context' section at the TOP "
"of your new summary.",
"",
"2. The Historical Context section is CUMULATIVE — each compaction "
"adds a 2-3 sentence entry. Never discard entries from previous "
"compactions.",
"",
"3. Preserve the active team roster (which agents are spawned "
"and their status) to prevent duplicate spawning.",
"",
"4. Preserve any active SCAN protocol results if a task is in progress.",
"",
f"5. Current git branch: {branch}. "
f"Recent commits: {log_recent[:200] if log_recent else 'none'}.",
"",
"6. CRITICAL — After resuming from compaction, IMMEDIATELY check "
"team status before doing anything else. Do NOT spawn new agents "
"without checking first.",
]
print("\n".join(rules))
sys.exit(0)In .codex/config.toml:
experimental_compact_prompt_file = "compact_prompt.md"The file compact_prompt.md contains the full compact prompt — Claude Code's 9-section base prompt (analysis, primary request, technical concepts, files, errors, problem solving, user messages, pending tasks, next steps) PLUS Rules 1-10 as additional sections.
Why replace the entire prompt for Codex? Because Codex's default is only 6 lines — "summarize the conversation." There's nothing to extend. You need to provide the full prompt.
After compaction, the orchestrator loses awareness of live agents. The compacted summary may mention "team was active" but the orchestrator doesn't have the reflex to check. It says "no agents running" and spawns duplicates.
Two hooks working together:
- PreCompact writes a flag file with the active agent roster (reads from task list)
- PostCompact check (a
UserPromptSubmithook) fires on the first message after compaction. If the flag file exists, injects a warning into the agent's context and deletes the flag (one-shot).
The warning:
[!] POST-COMPACT TEAM CHECK: Context was compacted at 2026-03-12 12:26.
There are 5 LIVE agents from before compaction: [coder, reviewer, explorer, critic, debugger].
IMMEDIATELY call TaskList to verify their status.
Do NOT spawn new agents or say 'no agents running' without checking first.
PreCompact writes the flag:
# Inside precompact_save.py, after other work
import json
from pathlib import Path
flag_file = Path(".claude/post-compact-pending.flag")
# Read task list to find active agents
task_dir = Path.home() / ".claude" / "tasks"
active_agents = []
if task_dir.is_dir():
for team_dir in task_dir.iterdir():
if not team_dir.is_dir():
continue
for task_file in team_dir.glob("*.json"):
try:
task_data = json.loads(task_file.read_text())
if task_data.get("status") == "in_progress":
owner = task_data.get("owner", "unknown")
active_agents.append(owner)
except Exception:
continue
flag_data = {
"timestamp": "2026-03-12 12:26:41",
"active_agents": active_agents,
}
flag_file.write_text(json.dumps(flag_data))PostCompact check (UserPromptSubmit hook):
#!/usr/bin/env python3
"""One-shot post-compact team warning."""
import json, sys
from pathlib import Path
FLAG_FILE = Path(".claude/post-compact-pending.flag")
def main():
if not FLAG_FILE.exists():
return 0
try:
flag_data = json.loads(FLAG_FILE.read_text())
except Exception:
FLAG_FILE.unlink(missing_ok=True)
return 0
active_agents = flag_data.get("active_agents", [])
timestamp = flag_data.get("timestamp", "unknown")
FLAG_FILE.unlink(missing_ok=True) # one-shot
if not active_agents:
return 0
agents_list = ", ".join(active_agents)
print(
f"[!] POST-COMPACT TEAM CHECK: Context was compacted at {timestamp}. "
f"There are {len(active_agents)} LIVE agents: [{agents_list}]. "
f"IMMEDIATELY call TaskList to verify their status. "
f"Do NOT spawn new agents without checking first."
)
return 0
if __name__ == "__main__":
sys.exit(main())Hook configuration:
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "python .claude/hooks/postcompact_check.py",
"timeout": 5
}
]
}
]
}
}The compact prompt tells the summarizer what to preserve. But the summarizer works with what's in the conversation. If important context was only in the agent's "head" (implicit understanding, not written down) — it's lost regardless of how good the compact prompt is.
The brain dump skill forces the agent to explicitly output everything it knows — BEFORE compaction happens. This raw output becomes part of the conversation and gets summarized.
A Claude Code skill (or Codex skill) triggered by the user typing /+ before /compact:
---
name: "+"
description: "Pre-compact brain dump. Run before /compact."
disable-model-invocation: true
---The skill prompt instructs the agent to output 9 sections — but ONLY the delta since the last compaction:
# Pre-Compact Brain Dump
Right now /compact is about to happen. Everything not written down is lost forever.
This output is a briefing for the next instance.
IMPORTANT: Do NOT repeat what's already in previous compacts (Historical Context).
The compactor can see that. Output ONLY what happened AFTER the last compaction.
If there were no compactions yet — output everything.
## Output (only fresh):
1. **Road** — what was done AFTER last compact, step by step + WHY + what was rejected.
2. **Now** — branch, files, task, tests.
3. **Decisions and WHY** — reasoning cannot be re-read from code. Including user's decisions.
4. **User** — new priorities, preferences, quotes from this segment.
5. **Blockers** — what depends on what.
6. **Findings** — P0/P1/P2 with effort estimate.
7. **Team** — who's alive, what they know, what they did.
8. **Next** — concrete next steps.
9. **Pitfalls** — dead ends, traps, what doesn't work.
Don't skip sections. More = better. But don't duplicate the past.Why "delta only"? Without this instruction, the agent dumps the entire session including previous compacts. The compactor then has duplicate content — previous history repeated twice. "Delta only" keeps the brain dump focused on new information.
Why disable-model-invocation: true? Prevents the agent from auto-triggering the skill. It should only fire when the user explicitly types /+.
- Compaction 1: Good summary of recent work
- Compaction 2: Summary of recent work. Compaction 1 context reduced to 1 sentence
- Compaction 3: Summary of recent work. All previous context gone
- Compaction 4: Agent behaves as if session just started
- Compaction 1: Summary + Historical Context section started
- Compaction 2: Summary + Historical Context grows (Comp 1 entry preserved + Comp 2 added)
- Compaction 3: Summary + Historical Context grows (Comp 1 + 2 preserved + Comp 3 added)
- Compaction 4+: Full historical arc intact. Agent knows the entire journey.
Tested in daily production use — sessions regularly survive 12+ compactions with full context intact. At that point the context starts getting tight from the accumulated Historical Context entries, but the agent still knows the complete decision history and can work coherently. Without the fix, the session is effectively useless after compaction 3.
Building a complete email infrastructure in a single session. 12+ compactions over the course of the work. After the last compaction, the agent still knew:
- Why a subdomain was used instead of the root domain for sending (root was taken by the hosting provider)
- Why an outbox pattern was chosen over Redis keys for reliability
- API setup details and DNS verification steps
- SMTP configuration choices and the reasoning behind them
- Which approaches were rejected and why
- Findings from multiple review cycles and their resolution status
Without the fix, this reasoning would have been lost after compaction 2. The agent would have proposed Redis keys again (rejected approach) or asked about the domain setup (already decided and explained).
If you only do one thing — add Rule 1 and Rule 7 to your compact prompt:
Rule 1 (Historical Thread): Tell the summarizer to look for previous compaction summaries and preserve them cumulatively.
Rule 7 (Key Decisions & Why): Tell the summarizer to capture decision reasoning, not just outcomes.
These two rules alone prevent the worst degradation — context loss and re-litigation of decisions.
- Add Rules 1-10 to your
CLAUDE.mdfile under a "Compact Instructions" section - Add the PreCompact hook to
.claude/settings.local.json - Optionally add the PostCompact hook (if using multi-agent)
- Optionally add the brain dump skill
- Set
experimental_compact_prompt_file = "compact_prompt.md"in.codex/config.toml - Write the full compact prompt in
compact_prompt.md(Codex's default is too minimal to extend — replace entirely)
The principle applies to any system with context compression:
- Identify the compression point — where does your system summarize/compress context?
- Extend the compression prompt — add the cumulative preservation rules
- Add pre/post hooks if your framework supports them
- Add a manual brain dump — even a simple "before compression, output what you know" instruction helps
Not all 10 rules apply to every system:
| Rule | When you need it |
|---|---|
| 1 (Historical Thread) | Always. This is the core. |
| 2 (Cumulative Road Map) | Always. Reinforces Rule 1. |
| 3 (Format) | Always. Without format, summaries are inconsistent. |
| 4 (Team Roster) | Multi-agent systems only |
| 5 (SCAN Context) | If using SCAN protocol |
| 6 (Memory Anchors) | If using persistent memory |
| 7 (Decisions & Why) | Always. Second most impactful rule. |
| 8 (Blockers) | Complex projects with dependencies |
| 9 (Findings Tracker) | If doing reviews/audits |
| 10 (External Audits) | Multi-tool workflows |
Minimum: Rules 1, 2, 3, 7. Full: all 10.
Compounding compression. Each compaction loses some detail regardless of instructions. Historical Context entries should be 3-5 sentences — not full paragraphs. After 12+ compactions, even compressed entries add up and start consuming meaningful context space. For very long sessions, consider starting a new session with a handoff document — though in practice, 12 compactions is a lot of productive work before you hit that point.
Summarizer quality. The compaction summarizer is the same model you're chatting with. If the model is having a bad day or the context is particularly complex, the summary may miss things. The brain dump skill is the safety net — it puts critical context in the conversation explicitly.
No formal benchmarks. This comes from daily production use, not a research lab. The difference is clear in practice — sessions survive 12+ compactions with full context versus losing everything after 2-3 without the fix. But I don't have controlled A/B test metrics.
Platform-specific. Hook mechanisms differ between Claude Code, Codex, and other tools. The principles are universal but implementation details vary.
This method is the compaction counterpart to SCAN protocol — which prevents instruction drift WITHIN a session. SCAN keeps rules alive while generating. Compaction Memory keeps context alive ACROSS compressions. Together they solve the two main failure modes of long-running AI agents: forgetting rules (SCAN) and forgetting history (Compaction Memory).
Public domain. Use it, adapt it, integrate it, modify it — no restrictions, no attribution required.
If you try this and have results, improvements, or critiques — reach out:
Email: exportil.nick@gmail.com
SCAN and Mogri appear to solve adjacent parts of the same drift problem. SCAN is an active restoration protocol. Mogri is a compressed invariant container. Could we compare minimal forms? I am especially interested in whether SCAN can be reduced to a 50-token or smaller anchor without losing effect.