How memory compaction changes an agent’s next request

A coding agent has just edited a parser and received a failing test result. It needs the failure, the user’s constraints, and enough history to know what to try next. It probably does not need every search result and file read that led there. Memory compaction is the operation that builds that smaller working context.

In the implementations examined here, compaction changes information supplied to inference, not model weights. Its governing operation is a handoff: decide what leaves active context, represent some of it more compactly, retain selected recent work, and construct a request that can continue. The summary is only one component. Persistent history, the working view reconstructed from it, and the messages actually sent to a model can be three different things.

Pi provides the starting walkthrough because its checkpoint names the first historical entry to keep. OpenCode V1 adds a reduction that does not summarize anything; Deep Agents adds a way to read back offloaded material. Cline and OpenHands broaden the comparison with deterministic folding and event-based forgetting. The later consumer-path section distinguishes OpenCode V1 from core V2. These cases are representative of distinct implementation choices, not a ranking of popularity or memory quality. Follow the data from stored history to the next request, and the differences become concrete.

Pi: append a checkpoint, rebuild the working conversation

Pi’s prepareCompaction() in packages/coding-agent/src/core/compaction/compaction.ts starts from the canonical session projection, retrieves any previous summary, and divides the remaining projected messages into material to summarize and a recent region to keep. [1] A projection is the selected working view of the session, rather than the entire stored transcript. Starting from that view matters after an earlier compaction: some messages before the old checkpoint’s storage position may still be active.

The selection records firstKeptEntryId; when a long turn must be split, it also separates that turn’s earlier messages for a turn-prefix summary. [1] Here, a turn can include the user’s request and several assistant/tool exchanges. Keeping an entire long turn would defeat reduction, but summarizing its beginning requires enough context to interpret the tool work retained at its end.

The built-in compact() path generates the prose, then appends deterministic read-only and modified-file lists and returns them separately in checkpoint details. [1, 14] Those path lists are an additional representation, not part of the summarizer’s memory.

AgentSession appends the resulting compaction entry and refreshes agent.state.messages from the session projection. [2] appendCompaction() stores the summary, retained-entry boundary, token accounting, and the current system-message snapshot under the current session leaf. [3] The older history has not been replaced wholesale with the summary.

The decisive selection happens in buildContextEntries(), in packages/coding-agent/src/core/session-manager.ts. The following exact excerpt omits the earlier branch traversal and latest-checkpoint lookup; path is that branch’s ordered entries and compactionIdx is the newest checkpoint’s position. It returns the checkpoint first, then the retained historical entries, then entries written after the checkpoint, excluding historical system messages from the retained range. [3]

const contextEntries: SessionEntry[] = [compaction];
let foundFirstKept = false;
for (let i = 0; i < compactionIdx; i++) {
	const entry = path[i];
	if (entry.id === compaction.firstKeptEntryId) {
		foundFirstKept = true;
	}
	if (foundFirstKept && !(entry.type === "message" && entry.message.role === "system")) {
		contextEntries.push(entry);
	}
}
contextEntries.push(...path.slice(compactionIdx + 1));

The following is an illustration of that selection, not an executed trace. Assume e3 is a valid cut boundary and the summary says “fix empty-input parsing; do not change the public API; latest regression remains unresolved.”

Stored branch, before:
  e1 user request → e2 earlier investigation → e3 recent user turn
  → e4 assistant tool call → e5 failing tool result

Stored branch, after:
  e1 → e2 → e3 → e4 → e5
  → c1 {summary: S1, firstKeptEntryId: e3}

Selected context entries:
  c1(S1) → e3 → e4 → e5

Notice the reordered checkpoint. It was appended after the failure in storage, but it introduces the retained work in the working conversation. That is how the next model can see a compressed account of the earlier investigation without replaying it.

Pi’s convertToLlm() lowers the internal compactionSummary to a user-role message with summary delimiters. [4] The agent loop applies any configured context transform, converts those internal messages, normalizes the context, and passes it to the provider stream. [5] A checkpoint entry does not go directly onto the wire as a special storage object; it becomes model-facing content through a consumer path.

The diagram separates the three representations and their consumers. It projects the illustration above, not a recorded execution; optional context transforms are not expanded.

Conceptual diagram of Pi: branch projection feeds refreshed agent state, then message conversion feeds the provider stream. [3, 2, 4, 5]

Now let the agent do more work. The old retained region may become old enough to summarize. Pi’s preparation takes the previous summary separately and selects from the previously projected tail, while its regression fixture expects previously kept messages to enter the next summary input when the recent window advances. [1, 6] In the illustration, a second handoff can fold e3–e5 into S2 while retaining newer work. “Update the old summary” alone would not describe that operation: the previously verbatim tail must also be accounted for.

When does the caller decide there is not enough room?

Different budgets answer different questions. The trigger decides when reduction starts. The retained-context budget decides how much recent work remains verbatim. The summary-input and generation budgets constrain the separate summarization request. A separate complete-request budget checks whether the assembled request fits. A number attached to one is not automatically a number for the others.

Pi’s built-in defaults reserve 16,384 tokens and retain a recent-context budget of 20,000 tokens; automatic compaction requires enabled and a strict contextTokens > contextWindow - reserveTokens comparison. [1] Its settings resolver can override each token budget by provider/model identity before falling back to ordinary settings and built-in defaults. [7] These are configurable token amounts, not a universal percentage threshold.

Pi combines the last valid assistant usage with estimates for later messages, but invalidates usage recorded before a subsequent compaction or context edit and estimates the current projection instead. [1] Otherwise, an old response’s usage could describe the large pre-compaction request even though the model is about to receive a smaller view. Its next-turn callback checks the canonical projection before the next assistant response and rebuilds that projection after automatic compaction. [2]

OpenCode’s V1 path counts a different object. The V1 prompt loop checks the last finished non-summary assistant’s recorded usage, creates a compaction task, and processes it before returning to ordinary work. [8] Its overflow.ts uses an explicit input limit minus reserved space when that limit exists, but otherwise uses the context limit minus maximum output tokens; it bypasses automatic checks when auto-compaction is disabled or the context limit is zero. [9] That is not equivalent to tokenizing the newly assembled request just before sending it.

Deep Agents chooses an 85% trigger and a 10% retained window when its factory sees an integer max_input_tokens profile, otherwise falling back to a 170,000-token trigger and six retained messages. [10]

The wrapper counts effective messages with the system prompt and, when its counter accepts them, tool schemas; it applies configured old-argument truncation, recounts when needed, and checks summarization or request-budget pressure. [10] Consequently, the same factory configuration can compact earlier because of output reservation or request overhead.

Its separate complete-request budget is max(0, floor(0.95 × max_input_tokens) - configured_output), with configured output taken as the largest recognized output-token setting. [10]

Explicit requests and rejection recovery are separate entry points. Pi’s manual compact() aborts the current operation and does not automatically continue the interrupted turn. [2] Deep Agents attempts an ordinary request when proactive checks say no summary, but recognized provider context overflow can enter summarization and tail-reduction recovery. [10] OpenHands’ summarizing condenser additionally distinguishes token pressure, an unhandled condensation request, and event-count pressure, treating event count as a softer history-management heuristic. [11] To explain a trigger, identify the caller, what it counts, and which mode it is in—not just its threshold.

What survives when history stops being active context?

There are at least four useful representations: exact recent messages, a generated explanation, deterministic metadata, and an address from which larger material might be recovered. Clearing content is a fifth possibility: the conversation can keep its structure while losing a result’s body. The repositories below make those differences operational.

OpenCode V1: preserve a call, clear its old result

V1’s prune() walks backward through completed tool parts, skips the newest user-turn region, protects the skill tool, protects 40,000 estimated output tokens, and marks older candidates only when potential savings exceed 20,000 estimated tokens. [12] The operation sets a compaction timestamp; it does not generate a semantic substitute.

The model-message conversion makes the timestamp consequential. This exact excerpt is from packages/opencode/src/session/message-v2.ts, inside the completed-tool branch; surrounding provider and media conversion is omitted. A marked output becomes a cleared-content placeholder and its attachments are omitted during conversion. [13]

const outputText = part.state.time.compacted
  ? "[Old tool result content cleared]"
  : truncateToolOutput(part.state.output, options?.toolOutputMaxChars)
const attachments = part.state.time.compacted || options?.stripMedia ? [] : (part.state.attachments ?? [])

An illustrative transformation is tool result: “empty input returns null; stack trace …” becoming tool result: “[Old tool result content cleared]”. The call’s place in the conversation survives, but the finding does not survive through this clearing operation. Rereading the current file may help; it is not necessarily recovery of the historical output.

V1’s separate summarization path sends the selected older head, supplies the previous completed summary separately, and records the retained tail’s starting ID. [12] filterCompacted() then explicitly places the completed checkpoint before the retained tail and subsequent messages. [13] Successful automatic compaction can replay a prior user request selected during overflow handling or, when there is no replay, insert a synthetic continuation request subject to its auto-continuation plugin hook. [12] Pruning, summarizing, projection, and continuation are distinct steps even within one implementation.

Pi: a summary cannot preserve text it never received

Pi’s summary serializer keeps only the first 2,000 characters of each tool result and appends a truncation marker. [14] A crucial error near the bottom of a long result can therefore be missing before the summarizing model starts. The ordinary retained tail and the serialized summary input have different fidelity.

Pi’s deterministic file lists come from recognized read, write, and edit calls, with modified paths excluded from the read-only list. [14] A recorded path is useful navigation; it does not prove a successful edit, explain why the edit was made, or preserve the file’s bytes.

There is a subtler interaction with offloading. Pi’s Bash output accumulator can store streamed output in a temporary file, and the Bash formatter appends a full-output-path notice after the displayed result. [15, 16] Because the compaction serializer takes the beginning of tool-result text and does not include the result’s separate details, sufficiently long displayed text can leave that appended recovery notice outside the summarizer’s input. [14, 16] This is a deduction from the producer and serializer, not an observed recovery failure. Saving an artifact and keeping its address reachable are two different responsibilities.

Deep Agents: summary-event context with a route back

Deep Agents stores a private summarization event containing a summary message, an absolute raw-state cutoff, and an optional history-file path, then sends the summary plus preserved messages to the original model handler. [10] Ordinary summarization does not remove all older raw messages: the state update is the event, with message replacements added separately when tail recovery produced them.

The normal event reconstruction is short enough to show directly. This exact excerpt from _apply_event_to_messages() in middleware/summarization.py omits the earlier absent/malformed-event and cutoff-bound checks. The effective conversation is the stored summary message followed by raw messages from cutoff_idx onward. [10]

result: list[AnyMessage] = [summary_msg]
result.extend(messages[cutoff_idx:])
return result

For an illustrative raw list [m0, m1, m2, m3, m4] and event {summary_message: S, cutoff_index: 3}, the next working conversation is [S, m3, m4]; the raw list and event are separate objects. For repeated compaction, the wrapper translates a cutoff in that effective list back to raw state using prior_cutoff + effective_cutoff - 1, accounting for the synthetic summary at effective index zero. [10]

As part of compaction it attempts to append evicted material to a backend Markdown history file, returns a path only after a successful write or edit, and embeds the path only when it is non-null. [10] This lets the active summary carry a route to details instead of carrying every detail itself.

That route has a real consumer. The main Deep Agents factory gives filesystem and summarization middleware the same backend, while read_file validates paths, checks read permissions, and delegates paginated reads to that backend. [17, 18] In the parser example, a summary might say that the latest test is unresolved and provide a history path; a later read could supply an earlier exact error. That last step is a possible action, not an executed demonstration.

The archive is not necessarily a byte-for-byte original transcript. Older write/edit arguments can be truncated before partitioning, offloading, and summary generation, and inline media is converted to references or failed-offload placeholders. [10] Offloading preserves the representation it receives.

A huge recent result needs a different treatment because it may sit in the suffix that summarization preserves. Deep Agents’ overflow-tail helper shortens a matching read_file result to a 4,000-character head plus a pointer to the original path, while other large results can be written to a separate backend file and replaced with a preview/path stub. [19, 20] The first route rereads a potentially mutable input file; the second saves extracted output text. Neither means the complete material remains in every subsequent request.

Cline and OpenHands: two further choices

Cline demonstrates that a handoff need not require another model call. Its runBasicCompaction() selects typed user prompts, a newest suffix of the active turn, and older concluding assistant answers when budget permits, then attaches deterministic dropped-work notices to surviving prompts. [21, 40] This describes dropped activity; it is not an LLM explanation of every discarded result. A later budget projection can truncate non-latest text and drop intermediate prompts while protecting the first and latest typed prompts from removal, and can report an unachievable budget. [22]

Cline’s prepare-turn wrapper uses deterministic basic compaction during built-in overflow recovery and falls back to basic when ordinary agentic compaction fails. [23] That changes the algorithm according to the failure mode: generating another summary is itself a model request that needs room.

Its session sidecar records replacement messages, source-message count and a source-prefix fingerprint; projection validates the boundary before returning replacements followed by later source messages. [24] Here the checkpoint’s validity depends on the source prefix matching, rather than on a retained-entry ID alone.

OpenHands makes the removed identities explicit. A Condensation event names forgotten_event_ids, removes those events from the working view, and inserts a generated summary only when both summary and offset metadata exist. [25] View.from_events() replays the stream in order, applying condensation records and enforcing view properties afterward. [26] The agent prepares messages from state.view; when preparation returns a condensation event, it emits that event and ends the step before sampling another action. [27] This is an event-to-view transformation, not deletion of all corresponding stored history.

The comparison is now sharper than “five agents use summaries.” Pi anchors a retained region in stored entries; OpenCode can clear bodies without replacing their meaning; Deep Agents separates an effective view from optional recovery artifacts; Cline folds deterministically and validates a source prefix; OpenHands replays explicit forgetting events. Each chooses where exact information becomes prose, metadata, a pointer, or nothing.

Which code path actually reaches the model?

A source file called “compaction” establishes an implementation, but not that every client runs it. The reader should follow its output into the consumer and keep revisions aligned.

OpenCode is an instructive case because its V1 and core V2 paths coexist at the inspected revision. The legacy HTTP session handler invokes the V1 compaction service and prompt loop for summarization, and the V1 loop reloads the filtered conversation on each iteration. [8, 28] An SDK directory named v2 is not enough to identify the core runner used by a particular request.

Core V2 also changes what “keep recent context” means. Its packages/core/src/session/compaction.ts serializes entries before selecting a recent suffix and emits a completed compaction event containing summary text and that recent string. [29] The message updater turns the ended event into a compaction message, and the history query selects rows at or after the latest checkpoint, plus eligible system updates. [30, 31] The runner converter puts both <summary> and <recent-context> inside one user-role checkpoint, rather than restoring the recent suffix as its original assistant/tool objects. [32] Thus [summary, native recent messages] and [user checkpoint containing summary + serialized recent text] are different model interfaces.

V2 builds the request with system context, converted history and tools before checking compaction; a successful compaction raises an internal transition that rebuilds the request. [33] This is a source-level consumer chain, not a claim that an arbitrary installed OpenCode client selected it.

Deep Agents needs a dependency boundary as well as a repository boundary. Its package permits LangChain versions from 1.4.3 up to but excluding 2.0.0, while its committed lock selects 1.4.3. [34, 35] In the corresponding LangChain helper, cutoff selection moves backward to retain a matching assistant tool call when the boundary lands on tool results, or advances past the result batch when no match is found. [36]

Deep Agents’ factory defaults to no extra trimming of the selected summary input, unlike the direct middleware constructor’s documented 4,000-token default. [10] Copying the constructor’s number into an explanation of the factory would describe the wrong path.

For navigation, the immutable source links below identify the exact revisions and paths used here. A productive reading order is the caller, selection/serialization, checkpoint write, and request consumer—not the summary prompt alone. For Cline, follow compaction.ts → basic-compaction.ts → session-compaction.ts; for OpenHands, follow agent.py → condenser → Condensation.apply() → View. OpenHands’ base agent allows a condenser to be absent, so the summarizing class’s policy is conditional on the agent’s configuration. [37]

What makes the handoff safe to continue?

A good-looking summary does not establish a valid, smaller, useful request. Those are separate tests.

First, a checkpoint should not become authoritative merely because generation produced some text. Pi’s built-in summarization path rejects a length-stopped response before returning a checkpoint, and its faux-response regression expects manual compaction to reject with zero persisted compaction entries. [1, 38] Manual and automatic session paths also check cancellation before appending the checkpoint. [2] These guards address incomplete generation and lifecycle state, not whether the prose omitted an important constraint.

Second, the retained boundary must respect conversational dependencies. A tool result is an answer to a particular call. The LangChain cutoff policy shown above protects that boundary locally; it is not a proof that every malformed history or custom extension produces valid provider messages. Repeated compaction adds another dependency: the old retained tail must either survive again or enter the next summary input. Pi’s moving-window fixture checks that selection property; it does not grade what a real summarizer would remember.

Third, the entire retry must improve on the rejected request. Deep Agents checks the reduced request through that complete-request counter, requires strict reduction after overflow, rejects a known oversized result, and terminates repeated context failure rather than retrying indefinitely. [10] Its recovery fixtures assert replacement message and tool-call identities using mock components. [39] A fit estimate still depends on the counter and model profile; structural assertions are not provider-tokenization measurements.

Finally, availability is not successful retrieval. Deep Agents history offload catches write failures and can continue without a history pointer, whereas its generic result-eviction helper returns no replacement for a returned write error or None but does not catch thrown write exceptions in that helper. [10, 20] A mutable original file may have changed; a saved output may have lost its address; a valid pointer may still require a read the model never chooses.

A useful evaluation would seed a task with an exact error, an unresolved step, and a constraint that must govern the next action. Check message pairing and complete request size deterministically. Then compact more than once and test the next tool choice or final artifact against those planted facts. If a recovery path is part of the design, test the actual read and the bytes it returns. This is a proposed evaluation procedure, not a reported result for these repositories.

Conclusion

Memory compaction is best understood as a change in the agent’s working representation. A summary can be excellent while the next request is still too large, a crucial tool body has been cleared, or a saved artifact is no longer reachable from active context.

The practical question is therefore: after the checkpoint is committed, what exact input does the next model receive, and what can it recover only by taking another action? Following that input through real callers, stored boundaries, projections and converters reveals how compaction actually works.

Limitations

These are static interpretations of the linked revisions. The excerpts were inspected, but repository tests and agent sessions were not executed; all before/after examples are illustrations. Mocked assertions establish intended local contracts, not measured continuation quality, successful retrieval, or comparative task performance.

The case selection covers distinct designs, not an exhaustive survey or a popularity claim. Client dispatch, enabled middleware, plugins, model overrides, backend permissions and installed dependencies can change the active behavior. In particular, the exact generated OpenCode SDK endpoint mapping and arbitrary deployed configurations are not established here. A lockfile identifies a reproducible dependency choice, not every installation.

No universal semantic-retention guarantee follows from these mechanisms. Saved history can contain transformed rather than original data; backend lifetime, mutation, failed appends, late interruptions and correct recovery choices need separate validation.