Codex CLI Replaces Compaction with Token Budget for Active Context Memory Management

Problem: Limitations of Compaction

Codex CLI previously used compaction : when the token limit approached, the conversation history was compressed into a summary and the dialogue continued with that summary. This approach has three core drawbacks:

Lossy compression – Summarization discards details. A 10-turn debugging session reduced to three sentences loses critical context.

Passive model – The model never knows how many tokens remain; it simply waits for the system to trigger compaction. It cannot plan ahead or initiate context reorganization at a suitable moment.

Amnesia after switch – After compaction the full conversation record is gone. The model cannot retrieve earlier details because they were irreversibly summarized.

The article argues that the fundamental issue is that compression is inherently lossy; a better strategy is to switch to a new context window while preserving the complete memory .

Solution: Token Budget Architecture

Codex adopts a token budget model: the model is informed of the remaining token quota and decides when to start a fresh context window. The switch is not a memory wipe because the entire history is stored in history and notes tools, available for lookup at any time.

This brings three shifts:

Passive → Active – Via the <token_budget> tag the model sees the remaining token count on every request and can proactively trigger a context switch.

Amnesia → Memory – history tool lists previous windows and entries, reads specific items, and searches conversation content. notes tool provides persistent, searchable notes for saving work state.

Manual → Automatic – Token budgeting can be enabled automatically through metadata, requiring no user configuration.

Three-Layer Architecture

Perception Layer: Knowing the Budget

The <token_budget> tag injects the current context window's remaining token count into every model request. This awareness is the prerequisite for active management.

Management Layer: Initiating Window Switch

The model calls the new_context tool to request a fresh context window. The new window acts as a no-summary compaction checkpoint – history is not compressed; a new window simply begins.

Memory Layer: Retaining and Querying History

history

tool supports listing windows/items, reading items, and searching dialogue content. notes tool supports listing, reading, searching, appending, and writing persistent notes.

The three layers interlock: perception tells the model when to switch, management lets it execute the switch, and memory ensures nothing is lost after the switch.

Design Philosophy: From Compression to Memory

Long-context management is memory, not compression – Any summarization loses fidelity. Token Budget's “new window, keep memory” mirrors how humans handle long tasks: we flip back to earlier notes rather than rely on a lossy summary.

Passive to active is a key transition – Previously the model was a passive tool waiting for system-triggered compaction. Now it actively monitors its budget and decides when to reorganize context, shifting from “tool” to “partner.”

Tool-to-partner philosophy – Compaction treats the model as a disposable tool; Token Budget equips it with memory and agency. This philosophical shift outweighs the specific implementation details.

Takeaways for Agent Builders

The most transferable insight is active context management : give the model visibility into its token budget, let it decide when to rotate context, and provide durable, queryable history and notes. The three-layer pattern (perception → management → memory) is applicable beyond Codex to any long-running agent system.