Context Lifecycle: Editing, Compaction, and Memory

An agent forty tool calls into a task is carrying a transcript that is mostly dead weight: file contents it read and already acted on, search results it rejected, thinking blocks from decisions long since made. The window fills, cost per turn climbs because every request resends the whole history, and quality degrades before the hard limit is reached (see context rot). Three distinct mechanisms address this, they are frequently confused, and they are not substitutes for one another.

Clearing: context editing

Context editing prunes. It removes old tool results and thinking blocks from the transcript before the model sees it, leaving the conversation's structure intact. It is configured per request through context_management.edits with a strategy — clear_tool_uses_20250919 for tool results, optionally including the tool inputs, and clear_thinking_20251015 for thinking blocks — behind the context-management-2025-06-27 beta as of mid-2026.

Use it when old tool output is genuinely finished business: a file you read, edited, and verified does not need its original contents in context. The failure mode is clearing something the agent still needed, which produces a peculiar amnesia where the model refers confidently to a result it can no longer see.

Summarising: compaction

Compaction condenses. When the conversation approaches a trigger threshold (150K tokens by default), the API summarises earlier context server-side and returns a compaction block in the response. It is enabled with context_management type compact_20260112 behind the compact-2026-01-12 beta.

There is one implementation detail that decides whether this works at all: append the entire response.content back into your messages array, not just the extracted text. The compaction block is what the API uses to substitute for the compacted history on the next request. A client that pulls out content[0].text and appends that string silently discards the compaction state, and the conversation behaves as though nothing was ever compacted — with the cost profile to match. This is the single most common way compaction is deployed wrongly.

Persisting: the memory tool

Memory persists across sessions. The memory tool (memory_20250818) is client-side: the model issues view, create, str_replace, insert, delete, and rename commands against a memory directory, and you implement the storage. Nothing about it is automatic, which is the point — you decide where files live, who can read them, and what retention applies.

Because you own the backend, you also own its security. Per-user memory directories and path validation are your responsibility; a shared directory in a multi-tenant product is a cross-tenant data leak waiting to be discovered. Never let credentials be written there: memory is replayed verbatim into every future session that mounts it.

Choosing between them

The three compose, and long-running agents typically use all of them: edit aggressively to keep the transcript lean, compact as a backstop near the limit, and write durable conclusions to memory so the next session does not rediscover them.

When it breaks

• Every one of them invalidates prompt cache downstream of the change. Editing or compacting rewrites the middle of the prefix, so the next request pays full price for everything after the edit point. The saving is real but it is not free (see ccaf prompt caching economics).
• Compaction is lossy in ways that are invisible at the time. A summary keeps what the summariser judged important; a specific identifier, an exact error string, or a constraint stated once may not survive, and the failure surfaces twenty turns later as a confidently wrong action.
• Memory accumulates errors with no expiry. A wrong conclusion written once is replayed into every subsequent session and reinforced. Memory needs a correction path and a review discipline, not just a write path.
• These are beta surfaces with dated identifiers. Beta headers and strategy type strings carry dates precisely because they change; treat them as configuration to verify against current documentation rather than constants to memorise.
• Clearing is not always cheaper than carrying. If the cleared span was sitting inside a warm cached prefix, you were paying roughly a tenth of list price to keep it. Measure before pruning aggressively.