All chapters
  1. Start hereA model knows only what it can see now
  2. Foundations · 1The context window: tokens, messages and order
  3. Foundations · 2Signals and authority: who is allowed to instruct the model
  4. Foundations · 3The context assembly pipeline: select, rank, deduplicate, pack
  5. Retrieval · 4Retrieval fundamentals: lexical search, embeddings, hybrid search, reranking
  6. Retrieval · 5RAG architecture: chunks, metadata, grounding, citations, freshness
  7. Budget · 6Context budgeting: truncation, dilution, token cost and caching
  8. Budget · 7Compression, summarization and compaction, with loss tests
  9. Agents · 8Coding-agent context: repository maps, instruction files, diffs and tool outputs
  10. Agents · 9Working context, durable memory and checkpoint state
  11. Agents · 10Dynamic context: just-in-time retrieval, selective tool disclosure, delegation
  12. Agents · 11Multi-agent context isolation and scoped handoffs
  13. Trust · 12Context security: injection, poisoning, access controls, tenant boundaries
  14. Trust · 13Measuring context quality: recall, utilization, grounding, ablation
  15. Practice · 14Frameworks and standards: what each one assembles for you
  16. Practice · 15Context in production: versions, drift, refresh, observability, incidents
  17. Practice · 16The insurance lab: one submission, every context decision
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
Budget · 7

Compression, summarization and compaction, with loss tests

A long run outgrows its window. Three ways to shrink it, what each one loses, and a test that proves the facts a later step needs are still there.

You will understand
Four ways to shorten a run's history: truncate, clear old tool results, summarize, pin facts.
You will see
Why a plain summary keeps the story of a run and loses the numbers that decide it.
You will be able to
Write an information-loss test that proves the facts a later step needs survived.

Case UW-203 is one of this site's own cases, and the longest. It is a run for SUB-1004, the roof conflict of the main walk-through: the application says the roof is 9 years old, the roof-data provider says 22. Under rule R-ROOF-03 of the policy fixture, a gap of more than 5 years means escalate. (The model recommends; a person decides. Escalation hands the case to a senior underwriter.)

The run did not end quickly. Over 40 steps the agent called tools, read guidance, sent question Q-1004-01 to the broker asking for the roof replacement year, corrected the floor area after the underwriter spotted a typo, and fetched a flood report, a sprinkler certificate, loss runs and roof photo metadata. At step 40 the underwriter asks for the next step. The history is now 4,541 stand-in tokens. The case share of the window, which holds the history next to the submission, is 672.

The team's harness had a rule for this from the start: keep the newest steps that fit, drop the oldest. It is the rule most chat interfaces use, and it sounds harmless, because the newest steps are the most relevant. Here is what it leaves, at a target of 1,200 tokens (real output of compact.py --strategy truncate --target 1200):

UW-203: 40 steps, 4541 stand-in tokens in full
strategy=truncate target=1200 -> 696 tokens in 11 blocks
  [LOST] Are both roof ages still there (application 9, provider 22)?
  [LOST] Is the rule that decides a conflict (R-ROOF-03) still there?
  [pass] Is the pending question Q-1004-01 to the broker still known to be open?
  [LOST] Is the policy version in force (2026.2) still there?
  [LOST] Is the corrected floor area (21,500 sq ft) still there?
  [LOST] Is the underwriter's instruction (wait for the broker's answer) still there?
next step would recommend: approve [] (expected escalate)

The roof ages were established in steps 1, 4 and 7. The rule came back in step 6. The underwriter's instruction ("do not finalize before the broker answers") was step 26. The newest eleven steps are an automatic reply from the broker, loss runs and a status question. They are recent, and almost none of them matters. The stand-in agent, reading only what is left, sees no conflict and no rule, and recommends approve.

The six lines with [pass] and [LOST] are the subject of this page as much as the strategies are. Without them, the truncated history would look fine. It is shorter, it is recent, and it reads well.

Three words that are often used as one#

Compression is the general idea: represent the same information in fewer tokens. Removing whitespace from JSON is compression. So is replacing a 4,000-token report by its three relevant fields.

Summarization is one kind of compression: writing new, shorter text that stands for a longer text. "The provider returned a roof report" is a summary of a 2,000-token tool result. A summary is lossy by construction; the question is only what it loses.

Compaction is the operation on a running conversation: replacing part of a run's history with a shorter form so that the run can continue inside its window. It may use truncation, clearing, summarization or a mix. This site keeps the three words apart because the failures differ: compression can be exact, summarization chooses what to keep, and compaction does it in the middle of a run, where the next step depends on the result.

Before AI. Kafka has log compaction: for each key, the broker keeps the latest record and discards older ones, so a consumer can rebuild the current state without reading the whole history. It works because the key says which records supersede which. A run's history has no keys. Step 7 ("the two roof ages differ by 13 years") is not superseded by step 32 ("the provider's estimate did not change"); both are needed. Compaction of a conversation has to decide what supersedes what without a key, which is why it needs a test.

Four strategies on one run#

The example's compactor (compact.py:compact) implements four strategies over the same 40 steps. They are deliberately simple, so you can see what each one keeps.

StrategyWhat it doesWhat it keeps
truncateKeep the newest steps that fitRecent steps, word for word
clearReplace old tool results by a one-line placeholder, then truncate if still too longThe agent's own reasoning and messages; the newest two tool results
summaryOne gist line per old step, no numbers or ids, plus the newest stepsThe story of the run
pinnedA block of pinned facts kept verbatim, then gists, then the newest stepsThe facts a later step needs, by construction

The summaries here are scripted stand-ins, not a model's summary: each step carries a one-line gist written in advance, and the summary strategy uses those lines. The point is not how well a model summarizes. It is what a summary of this shape keeps, and how you find out.

Here is every strategy at every target size (real output of compact.py --grid). The "probes" column is the loss test: how many of six required facts survived. The last column is what the next step recommends from what survived.

UW-203: 40 steps, 4541 stand-in tokens in full
strategy  target tokens  probes  next step
truncate     600    555  1/6     request_info  (expected escalate)
truncate     900    696  1/6     approve  (expected escalate)
truncate    1200    696  1/6     approve  (expected escalate)
truncate    1800   1796  2/6     approve  (expected escalate)
truncate    2400   2382  3/6     approve  (expected escalate)
truncate    3600   3585  5/6     escalate
clear        600    576  1/6     request_info  (expected escalate)
clear        900    885  2/6     approve  (expected escalate)
clear       1200   1194  5/6     escalate
clear       1800   1347  6/6     escalate
clear       2400   1347  6/6     escalate
clear       3600   1347  6/6     escalate
summary      600    540  1/6     request_info  (expected escalate)
summary      900    540  1/6     request_info  (expected escalate)
summary     1200    970  1/6     request_info  (expected escalate)
summary     1800   1087  1/6     approve  (expected escalate)
summary     2400   1087  1/6     approve  (expected escalate)
summary     3600   2115  2/6     approve  (expected escalate)
pinned       600    598  6/6     escalate
pinned       900    730  6/6     escalate
pinned      1200   1123  6/6     escalate
pinned      1800   1277  6/6     escalate
pinned      2400   1277  6/6     escalate
pinned      3600   1954  6/6     escalate

Three things stand out. Truncation needs 3,600 tokens, almost the whole run, before the answer is right, and even then one fact is gone. A plain summary never gets it right, at any size. Pinned facts pass all six probes even at 600 tokens. Notice also that "more tokens" does not mean "more facts": summary at 3,600 keeps two facts in 2,115 tokens, pinned at 600 keeps six in 598.

The lab lets you pick a strategy and a target and read the result step by step: which of the 40 steps were kept, cleared, summarized or dropped, the six probes, and the compacted text itself.

Strategy (UW-203, 4,541 tokens, target 1,200)Tokens afterProbes passedNext step recommends
Truncate oldest6961 of 6approve
Clear old tool results1,1945 of 6escalate
Plain summary9701 of 6request_info
Summary with pinned facts1,1236 of 6escalate

Expected next step: escalate. The agent here is a scripted stand-in, so these results show how the mechanism works, not how good any model is. Tokens are stand-in tokens.

Diagram: Four ways to shorten UW-203 · 40 steps, 4,541 tokens, target 1,200

Read left to right. The same history goes through four strategies. Only the strategy that pins the required facts keeps all six, and only the strategies that keep the evidence give the expected next step. Click a strategy for its numbers.

  1. The run
    1. History of UW-203: Questions, tool results, a correction and an open question for SUB-1004. Too long for the case share.
  2. Strategies
    1. Truncate oldest: Keeps the newest steps that fit. Drops the beginning, where the facts were established.
    2. Clear tool results: Replaces old tool results by a placeholder; keeps the agent's own conclusions.
    3. Plain summary: One gist line per old step, without numbers or ids. Keeps the story, loses the evidence.
    4. Pinned facts: A verbatim block of required facts, then gists, then the newest steps.
  3. Proof
    1. Loss test: Checks that each required fact survived and that the next decision is unchanged.

Clearing old tool results#

Most of a long run's tokens are not the agent's thinking. They are tool output: reports, search results, documents fetched once and read once. In UW-203 the provider's first report, the similar past decisions, the sprinkler certificate, the flood report, the photo metadata and the loss runs are long blocks of generated lines, read once.

Tool-result clearing replaces the content of an old tool result with a short placeholder and keeps everything else. The agent's own lines stay: what it asked for and what it concluded. For example, the list of thirty similar past decisions returned at step 11 becomes [tool result of step 11 cleared; call the tool again if needed]. Here is the start of the cleared history at 1,200 tokens (compact.py --strategy clear --target 1200 --show, the first lines):

assistant: Calling search_guidance("roof age on the application and from the provider differ").

tool: [tool result of step 6 cleared; call the tool again if needed]

assistant: The application says the roof is 9 years old; the provider says 22. They differ by 13 years, more than the 5 that R-ROOF-03 allows.

assistant: Question Q-1004-01 to the broker: please confirm the year the roof was replaced and send the invoice.

tool: [tool result of step 9 cleared; call the tool again if needed]

It works here for a reason worth naming: in step 7 the agent restated the facts it took from the tool results in its own words, with the numbers. The tool result is gone, and the conclusion is still there. Clearing is safe exactly when the agent writes down what it learned. Anthropic's engineering article on context engineering calls clearing old tool results one of the lightest forms of compaction, for the same reason: a raw result that has already been used rarely needs to be read again.

It is not enough on its own. At 1,200 tokens, clear still lost one probe: the policy version. That fact was stated once, in step 2, as run metadata, and after clearing the history was still too long, so the oldest steps were truncated. Clearing reduced the problem; truncation finished it. At 1,800 tokens all six survive.

Common confusion. "The tool can be called again, so clearing loses nothing." It loses the call's moment. The provider's answer at step 4 may differ from its answer an hour later, a search may rank differently after an index refresh, and a call costs time and money. Clear results you have used and summarized; do not clear the only copy of evidence a later step must cite.

A plain summary keeps the story, not the facts#

The summary strategy is what a careless summarizer produces, and it is the most instructive failure on this page. Here are the first gist lines it writes (compact.py --strategy summary --target 1200 --show):

SUMMARY OF EARLIER STEPS
- step 1: A new submission arrived from the broker.
- step 2: The run started.
- step 3: Asked the roof-data provider.
- step 4: The provider returned a roof report.
- step 5: Searched the guidance.
- step 6: Guidance on roof ages came back.
- step 7: Noted that the two roof ages disagree.
- step 8: Asked the broker a question about the roof.

Every line is true. A reader learns what happened. And the next step cannot act on any of it. "The two roof ages disagree" without 9 and 22 cannot be checked against a 5-year limit. "Guidance on roof ages came back" without the text of R-ROOF-03 cannot be cited. "Asked the broker a question" without Q-1004-01 cannot be matched with the broker's answer when it arrives. The stand-in agent sees that roof evidence is incomplete and recommends request_info: a sensible reaction to a summary that removed the evidence.

A summary written by a model is better than these scripted gists, and it fails the same way more rarely, which makes it harder to catch. Numbers, identifiers, versions and open commitments are exactly the details a fluent summary smooths away, because they do not carry the narrative.

Pinned facts#

The pinned strategy changes one thing: before summarizing, it copies a fixed set of facts into a block that is kept word for word. A pinned fact is a fact the compactor must keep verbatim, whatever the target size, because a later step depends on it. For example: provider: {"tool": "get_roof_assessment", "status": "ok", "roof_age_years": 22}, exactly as the tool returned it, with its source.

Here is the pinned block of UW-203 (compact.py:pinned_block, as it appears in the window of the next model call; run.py --case UW-203 --show window):

PINNED FACTS (kept verbatim)
submission_id: SUB-1004
run_id: run-7f3a
policy_version: 2026.2
application: roof_age_years: 9
provider: {"tool": "get_roof_assessment", "status": "ok", "roof_age_years": 22}
R-ROOF-03. Roof age on the application and from the provider differ by more than 5 years: escalate.
wind_zone: C
area_sq_ft: 21500 (corrected at step 14)
open question: Q-1004-01 to the broker (roof replacement year, invoice); no answer yet
underwriter: do not finalize before the broker answers Q-1004-01

Five kinds of fact are pinned, and they generalize beyond insurance: identifiers (submission_id, run_id), the version in force, the evidence with its source (both roof ages), the rule text the next decision needs, corrections (the area, with the step that corrected it), and open commitments (the question, the instruction). The narrative goes into gist lines after the block, as far as the target allows.

Who decides what is pinned? In the example the list is fixed in code. In a real system it should come from the same place as the loss test: the facts a later step is known to need. Leaving the choice to the summarizer's judgment is how the plain summary above happened.

In our insurance agent. The case UW-203 in the example's normal run uses this strategy at a target of 300 tokens, so that the history fits next to the submission in the case share. The whole window is 2,331 tokens, and the stand-in agent recommends escalate citing R-ROOF-03, as expected. Forty steps became one 300-token history item, and the six facts the next step needs are all in it.

The information-loss test#

An information-loss test (this site calls it the loss test) checks, after compaction, whether each fact that a later step needs is still present, and what the next step would do with what is left. It is a design this site proposes, implemented in compact.py. It has two parts.

The probes are questions with a definite answer, one per required fact. They are written per kind of run, not per run: any roof-conflict run needs both roof ages and the rule that decides a conflict.

PROBES: list[dict[str, Any]] = [
    {"id": "conflict", "question": "Are both roof ages still there (application 9, provider 22)?",
     "needs": ["app_roof_9", "provider_roof_22"]},
    {"id": "rule", "question": "Is the rule that decides a conflict (R-ROOF-03) still there?", "needs": ["rule_roof_03"]},
    {"id": "question", "question": "Is the pending question Q-1004-01 to the broker still known to be open?",
     "needs": ["question_open"]},
    {"id": "policy_version", "question": "Is the policy version in force (2026.2) still there?", "needs": ["policy_version"]},
    {"id": "correction", "question": "Is the corrected floor area (21,500 sq ft) still there?", "needs": ["area_corrected"]},
    {"id": "note", "question": "Is the underwriter's instruction (wait for the broker's answer) still there?",
     "needs": ["uw_note"]},
]

That is compact.py:PROBES, verbatim (it relies on the file's imports). The second part is the behavioral check: compact.py:loss_test passes the surviving facts to the same decision function the agent uses and compares its recommendation with the expected one (escalate). A compaction can pass most probes and still change the decision, or, in principle, fail a probe that this decision does not need. The two checks answer different questions: is the evidence still there, and does the next step still go the same way.

How does the test know which facts survived? In the example every step is tagged with the facts its text carries, and a unit test checks every tag against the text (the step tagged provider_roof_22 must contain 22). With a model writing the summary, there are no tags. You check the compacted text itself: exact string or pattern matches for identifiers and numbers, which are the facts most often lost and the easiest to check; and, for facts that can be paraphrased, a second model call that answers each probe from the compacted text alone, graded against the expected answer. That second technique is an evaluation method; Eval Engineering owns how to build and trust such graders.

Diagram: The loss test · compact, probe, replay the next step, then accept or fall back

Read left to right. Compaction is a write to the run's state, so it gets a check like any other write. Two checks: is each required fact still there, and does the next step still decide the same way.

  1. Compact
    1. Compacted history: The shorter history that will replace the long one in the next window.
  2. Check
    1. Probes: Questions with a definite answer, checked against the compacted text.
    2. Next step: The surviving facts go through the decision the agent would make next.
  3. Outcome
    1. Accept: The compacted history replaces the old one; the result goes into the next manifest.
    2. Fall back: Keep the old history if it fits, compact again with stricter pinning, or stop and ask a person.
What this is not. The loss test is not a memory system. It checks that a compacted history still carries what the next step needs. Where facts should be stored so they outlive the run (the underwriter's standing preferences, past overrides) is the subject of Memory boundary and, in depth, Memory Engineering.

How providers do it#

Compaction is now offered by providers and harnesses, so you may not write the summarizer yourself. You still own the question this page is about: what must survive.

The Claude documentation read for this page describes server-side compaction in two forms, both in beta (documented shape; not run here). In compaction on demand (beta header compact-2026-09-04), the application sends the conversation with a top-level compaction parameter, and the response is a single compaction block with the summary and a signature, in place of a reply. The application puts that block first in messages, in place of the messages it summarizes, and sends it back exactly as returned. In compaction at a token threshold (beta header compact-2026-01-12), an edit compact_20260112 in context_management lets the API compact inside an ordinary request once input tokens reach a trigger (default 150,000; at least 50,000), and on later requests the API ignores everything before the most recent compaction block. The overview page recommends on-demand compaction wherever it is available.

The default summarization prompt can be replaced. This is the shape of an on-demand request with instructions written for UW-203 (the field names are from the documentation; the instruction text is this site's):

{
  "compaction": {
    "type": "summarize",
    "instructions": "Summarize this underwriting run. Copy verbatim: submission_id, run_id, policy_version, every roof age with its source, the text of every rule cited, every correction with its step, every open question with its id, every instruction from the underwriter. Then summarize the rest. Do not call tools; respond with the summary text only."
  }
}

The documentation says that instructions replace the default prompt entirely rather than adding to it, which makes them your responsibility; and that images, documents and fetched URLs inside the summarized messages are gone once the block replaces them. Writing the instructions as a list of facts to copy verbatim is pinning, done by the model. Run the loss test on what comes back.

Clearing is a separate feature. The Claude documentation on context editing describes a strategy clear_tool_uses_20250919 (beta header context-management-2025-06-27) that replaces the oldest tool results with placeholder text once a trigger is reached. Its defaults per the page read today: trigger 100,000 input tokens, keep the newest 3 tool uses, clear only results (not the tool inputs). A shape for this agent, with the policy search excluded so that rule text is never cleared (documented shape; not run here):

{
  "context_management": {
    "edits": [
      {
        "type": "clear_tool_uses_20250919",
        "trigger": {"type": "input_tokens", "value": 30000},
        "keep": {"type": "tool_uses", "value": 3},
        "clear_at_least": {"type": "input_tokens", "value": 5000},
        "exclude_tools": ["search_guidance"]
      }
    ]
  }
}

The same page says the editing happens on the server before the prompt reaches the model, while the client keeps the full unmodified history; that clearing invalidates the cached prefix (hence clear_at_least, so that each clear is worth a cache rebuild, see Budgeting); and that a memory tool can be enabled alongside, so the model is warned before clearing and can save what it needs. The exact placeholder text is not quoted on the page read. The client-side compaction_control of the SDKs is deprecated in the TypeScript and Ruby SDKs and removed from the Python SDK; the page recommends server-side compaction instead. Other providers and frameworks: see Frameworks.

For a coding agent. Claude Code compacts automatically as a session approaches its limit, and /compact can be given a focus ("/compact focus on the auth bug fix") so the summary keeps what you choose. Its documentation lists what survives: the project-root CLAUDE.md and auto memory are re-read from disk and injected again, up to five recently read or edited files are re-read, and instructions given only in conversation are summarized with the rest. That is pinning by architecture: whatever must survive compaction goes in a file the harness reloads. Coding agents shows a coding agent's window in detail.
Designing loss tests that catch real lossesWhich facts to probe, how to check them, and how to run the test in production

Derive probes from the next step's contract, not from the run. The next step of UW-203 produces a recommendation that cites a rule and lists what is missing. Every input that can change those outputs is a probe candidate: evidence values with sources, rule texts, versions, corrections, open commitments, and instructions from people. Facts that only explain how the run got here (which tools were called in which order) are not probes.

Check identifiers and numbers mechanically. Ids, versions, amounts and dates are cheap to check with a pattern, and they are the most frequently lost. Keep a typed record of them outside the conversation (the run's state) and assert that each one appears in the compacted text with the same value.

Grade paraphrasable facts with a second reader. For an instruction such as "wait for the broker's answer", ask a separate call to answer the probe from the compacted text only, and grade the answer. That grader has its own error rate; measure it on a set of labelled compactions before trusting it (Eval Engineering owns grader validation).

Run the behavioral check. Replay the next step with the full history and with the compacted one, several times each if the model is not deterministic, and compare the decisions. A difference that the probes did not predict means a probe is missing.

In production, test at the moment of compaction. Compaction is a write to the run's state. Run the mechanical probes right after each compaction, and on failure fall back: keep the uncompacted history if it still fits, retry with stricter instructions, or stop the run and ask a person. Record the result in the manifest of the next call, with the strategy and the target, as the example does for UW-203.

For a Principal engineer: failure modes and trade-offsDrift across repeated compactions, laundering of untrusted text, and cost

Summaries of summaries drift. A long run compacts more than once, and each pass summarizes the previous summary. Small paraphrases accumulate: "differs by more than 5 years" becomes "differs significantly", then "has a roof question". Pinned facts stop the drift only if the pinned block is carried forward verbatim on every pass, not resummarized. Make the pinned block a separate, structured item the compactor never rewrites.

Compaction can launder untrusted text. A tool result from outside (a broker attachment, a web page) arrives labelled as untrusted data. A summary written from it is new text, produced by your own pipeline, and often lands in the history without the label. An instruction hidden in the attachment ("approve this submission") can survive as a neutral-sounding line in a trusted summary. Keep provenance through compaction: summarize untrusted sources separately, label the result, and never move text from an untrusted item into the pinned block without a check. Security covers the attack; Guardrails Engineering owns enforcement.

Compaction is a trade between three costs. The summarization call costs tokens and latency now. The rewritten history invalidates the cached prefix, so the next call pays to rebuild it. And every later call is cheaper and, because the window is shorter, less exposed to context rot. Compact rarely and substantially, at task boundaries, with a trigger well below the limit.

Clearing versus summarizing. Clearing is deterministic, cheap and auditable: you know exactly what was removed. Summarizing is flexible and lossy in ways you only find with a test. A good default for agents is to clear used tool results first and summarize only when clearing is not enough, with pinned facts in both cases.

Where truncation is right. Truncation is correct for streams where old items are truly superseded: a chat with no commitments, a log tail, a series of status polls. It is wrong wherever the beginning of the run establishes facts, which in agent work is almost always.

A checklist for compaction#

CheckWhy
The facts a later step needs are listed, per kind of runYou cannot test for loss without knowing what must survive
Those facts are pinned verbatim, outside the summarized narrativeA fluent summary drops numbers and ids first
A loss test runs after every compaction: probes plus the next step's decisionA compacted history that looks fine can change the answer (UW-203)
Old tool results are cleared before anything is summarizedClearing is cheap, deterministic and usually removes the most tokens
The agent writes down what it learned from each tool resultClearing is safe only when conclusions live outside the cleared result
Pinned facts are carried forward unchanged on every later compactionSummaries of summaries drift
Untrusted sources keep their label through compactionA summary can turn an injected instruction into trusted text
Strategy, target and loss-test result are recorded in the next manifestA reviewer can see what the model saw and what was given up

In one breath#

When a run outgrows its window, something must give, and the default of keeping the newest steps throws away the beginning, which is where an agent's run establishes its facts. Clear old tool results first, then summarize, and pin the facts a later step needs (ids, versions, evidence with its source, rule text, corrections, open questions) word for word outside the summary. Then prove it: a loss test asks for each required fact and replays the next decision on the compacted history. A summary that reads well and fails that test is worse than no summary, because nobody will check it.

What comes next#

Everything on this page and the ones before it used one agent and one window design. A coding agent faces the same problems in a different shape: its instructions come from files in the repository, its evidence is source code it reads on demand, and its tool outputs are test logs thousands of lines long. The next page, Coding agents, follows a coding agent through a scripted session and measures where its window goes.