---
name: context-compression
description: "Keeping long LLM agent sessions on track: what a summary must preserve, incremental structured summaries, state in files, compact versus restart versus subagent. Use when an agent session outgrows its context."
metadata:
  risk: safe
  source: multi-agent-pipeline
  date_added: "2026-09-25"
---

# Context Compression for Agent Sessions

A long agent session fills its context window with tool output, file contents
and dead ends. At some point the history has to shrink. The goal is not the
smallest summary; it is finishing the task with the fewest total tokens. A
summary that drops a file path or an error message costs more later, when the
agent re-reads, re-runs or repeats the mistake.

## What must survive a compression

Treat these as mandatory fields. If a summary cannot fill one, it says so
explicitly rather than leaving it out.

| Field | Why it matters | Example |
|-------|----------------|---------|
| Goal and acceptance criteria | Without it the agent optimises the last message instead of the task | "Add CSV export to the orders page; export must respect active filters; tests green" |
| Decisions and their reasons | Prevents re-litigating settled questions | "Stream rows instead of building the file in memory: exports reach 400k rows" |
| File trail | The most commonly lost item; the agent must know what it touched | "Created `export/csv_writer.py`; modified `orders/views.py` (new `export` action); read but unchanged `orders/filters.py`" |
| Exact errors still open | Paraphrased errors cannot be searched or matched | The literal failing assertion and test id |
| Ruled-out approaches | Stops loops | "Tried pandas `to_csv`: 3x memory, rejected" |
| Open tasks, in order | Tells the next turn what to do first | Checklist with the current item marked |
| Environment facts | Hard-won and cheap to store | Branch name, how to run the tests, a flaky test to ignore |

What can go: full file contents that can be re-read, verbose tool output once
its conclusion is recorded, superseded plans, conversational back-and-forth.

## Structured, incremental summaries

Free-form "summarise the conversation so far" prompts drift: each pass rewrites
from scratch and quietly loses details that seemed minor. Two habits prevent
that.

**A fixed template.** Give the summariser named sections matching the table
above. Empty sections are visible gaps, which is the point.

```markdown
## Goal
## Acceptance criteria
## Decisions (with reason)
## Files
- created:
- modified (what changed):
- read only:
## Open errors (verbatim)
## Ruled out
## Next steps
## Environment
```

**Merge, do not regenerate.** When compression triggers again, summarise only
the span being dropped and merge it into the existing summary section by
section. Earlier facts are carried forward unchanged unless the new span
explicitly supersedes them. Regenerating the whole summary each time compounds
loss across cycles.

Keep verbatim anything that will be matched against later: identifiers, paths,
command lines, error strings, version numbers. Summarise reasoning; never
summarise literals.

## Externalise instead of remembering

The cheapest context is the one that lives on disk and is re-read on demand.

- **Progress file.** A `NOTES.md` or task file the agent updates as it works:
  plan, checklist, decisions. After compression or restart, reading one file
  restores the working state.
- **Git as a log.** Small commits with clear messages record what changed and
  why. `git diff` and `git log` recover the file trail exactly, which no summary
  can match.
- **Test output files.** Write long test or build output to a file and keep only
  the failing lines in context.
- **Scratch artefacts.** Search results, API responses and generated data go to
  files that are referenced by path.

An agent that externalises well can survive aggressive compression, because the
summary only needs pointers.

## Compact, restart or delegate

| Situation | Choose | Reason |
|-----------|--------|--------|
| Same task, history cluttered with resolved detail | Compact | The thread of reasoning is still valuable |
| Task finished, next task unrelated | Restart | Old context only adds noise and cost |
| Session derailed: repeated failures, contradictory instructions piling up | Restart with a hand-written brief | A clean start with the lessons outperforms a summary of confusion |
| A sub-question needs lots of reading but only a short answer (search a codebase, read long docs, review a diff) | Delegate to a subagent | The reading stays in the subagent's context; only the conclusion returns |
| Independent pieces of work | Parallel subagents | Each gets a focused context; the parent keeps the plan |

When delegating, give the subagent a self-contained brief: goal, constraints,
where to look, and what shape the answer should take. Ask for conclusions with
file and line references, not dumps.

## Triggering compression

- Compress before the window is full, not at the limit. Leave room for the next
  tool results and for the model to reason; compressing at the last moment
  forces a rushed summary.
- Prefer natural boundaries: after a subtask completes, after tests pass, before
  starting a new phase. Mid-edit compression is where file trails get lost.
- Clear stale tool results first (old file reads, superseded searches). That
  often buys enough room without summarising reasoning at all.

## Measuring whether compression loses too much

Compression quality is measured by what the agent can still do, not by how
readable the summary is.

- **Probe questions.** After compressing, ask the agent questions whose answers
  were in the dropped span: which files did you modify, what was the exact
  error, why did we reject approach X. Score the answers.
- **Task completion.** Run the same set of long tasks with and without the
  compression strategy; compare success rate and total tokens.
- **Re-work signals.** Count re-reads of files already read, repeated commands
  and re-attempts of ruled-out approaches after each compression. A rising count
  means the summary is dropping something the agent needs.

## Common failure shapes

- **The forgetting editor.** After compression the agent re-creates a file it
  already created, or edits the wrong copy. Cause: missing file trail. Fix: the
  Files section plus `git status` after every restore.
- **The loop.** The agent retries a rejected approach. Cause: no ruled-out list.
- **Goal drift.** The agent finishes a side quest and stops. Cause: goal and
  acceptance criteria summarised away or reworded until vague.
- **Paraphrased errors.** "A type error in the export module" cannot be matched
  against the next test run. Keep the literal text.