Compaction and memory
Write a scoped skill package and manage its instructions and references within a task's context budget.
THE IDEA
Compaction and memory
When history grows, compaction replaces older messages with a summary. That frees space (here 900 tokens of old messages become a 110-token summary) but the summary is lossy: details not carried over are gone. Preserve what the task depends on: stable ids, decisions, unresolved issues and pointers to evidence. Then the agent can recover state even though the original wording is not in context.
A summary compresses selected information and loses the rest. Keep stable ids, decisions, open issues and pointers to evidence so the important state can be recovered; do not treat the summary as an archive.
Predict first. Is a summary a perfect lossless archive?
Chapter context
A skill packages reusable task instructions and optional supporting material. Context engineering decides which instructions and evidence are available for a particular operation. Loading more text is not automatically better than selecting the right text.
TRY IT YOURSELF
Part 1. Do it hands-on
Count what compaction saves and loses by hand, then write it.
A summary compresses selected information and loses the rest. Keep stable ids, decisions, open issues and pointers to evidence so the important state can be recovered; do not treat the summary as an archive.
- To do: A conversation has 10 messages. Compaction keeps the last 4 verbatim. How many older messages are compressed into the summary?
- To do: Of those 6, two record decisions and three mention order ids. The summary must keep the decisions and the ids. How many messages' worth of facts must be preserved at minimum (the union, assuming no overlap)?
- To do: The 6 old messages used 150 tokens each; the summary uses 200 tokens. Tokens saved?
- To do: Is a summary a perfect lossless archive? Type yes or no
Part 2. Do it in code
- compact(messages, keep_last): messages are dicts {"text", "ids" (list), "decision" (bool), "tokens"}. The last keep_last messages stay verbatim. The older ones are summarised into {"ids": sorted unique ids mentioned in them, "decisions": the texts of the older messages whose decision is True (in order), "dropped": number of older messages, "tokens": 50 + 10 × number of ids + 20 × number of decisions}. Return {"summary": ..., "recent": the kept messages}.
- tokens_saved(messages, keep_last): tokens of the older messages minus the summary's tokens (can be negative).
- lost_messages(messages, keep_last): the texts of older messages that carried neither ids nor a decision (their details are gone).
- recover(summary, wanted_id): True if the id survived in the summary.
- needs_pointer(message): True if a message with evidence (non-empty ids) should keep a pointer such as its id so the full text can be fetched later.
Stuck, or something not working? You can come back to it any time.
CHECK YOUR UNDERSTANDING
Is a summary a perfect lossless archive?
Chapter reference: math, worked example & code
This section belongs to the whole chapter, so it is the same on every lesson in it and may cover a different lesson's topic. The code for the experiment you just ran is inside the experiment itself.
Math and notation
For a synthetic combined budget W, a bookkeeping model is available = W − instructions − history − tool results − reserved output. Actual provider contracts can separate these limits, so use the chosen model's documented accounting when implementing.
Worked example
A synthetic 8192-token budget reserves 1200 for instructions, 2800 for history, 1600 for tool results and 1500 for output. Remaining space is 1092 tokens. A 900-token skill body fits under this model; adding a 2000-token reference does not. The remedy is to select or retrieve the relevant passage rather than silently dropping task constraints.
Reference code
The following example uses the Python standard library and does not call a remote service.
window=8192
used=1200+2800+1600+1500
remaining=window-used
assert remaining == 1092
assert 900 <= remaining
assert 2000 > remaining
Python examples are provided for study and local execution; this page does not execute Python.
Common mistakes
Compaction can lose evidence and constraints. Skill installation is not task authorization. A context limit and a product's memory feature are different mechanisms.