Codex's Context Management Redesign: Four-State Architecture for Long-Running Agents

Introduction

On August 30, Nico Ritschel posted about Codex CLI experimenting with a context management approach that goes beyond compaction: switching to a new context window when needed, supplemented by task notes and history for retrieving old content. Teknium from Nous Research compared this with Hermes' compaction system, which recently added the ability to look back at pre-compaction content. The author examined official configuration, changelogs, and source code to understand how a long task continues after the context window fills.

As of today, this context management feature in Codex CLI 0.153.0 remains an experimental feature disabled by default. It is only available for certain ChatGPT Plus, Pro, and Pro Lite sessions using the Codex backend; API keys, custom model providers, and ephemeral structured threads are not supported. Official configuration still retains compaction-related options, and the 0.150.1 changelog includes a fix for remote compaction. The author concludes that Codex is trialing an alternative long-task continuation mechanism, but public materials are insufficient to determine whether it will replace compaction.

In the author's view, these changes superficially address "memory" but fundamentally restructure state management. From an implementation perspective, information needed now, cross-window handoff, historical lookup, and external facts produced by the task reside in separate carriers. From an agent architecture perspective, this is more interesting than merely discussing how much longer the context window can grow.

A Summary Carrying Too Many Responsibilities

The article illustrates with a common task: migrating a cross-module authentication middleware. The agent traces call chains, confirms the old interface cannot be deleted yet, rules out a unified SDK upgrade, completes the main path, then hits intermittent auth failures in integration tests. The task is unfinished but the context window is nearly full.

Traditional compaction compresses prior conversation, tool calls, and results into a shorter summary to continue working. This is practical and lets many long tasks proceed. The problem: the summary must guess what will be needed later. "Old interface must be retained" may be included, but the compatibility rationale might be dropped; "integration test failed" may be kept, but the full log from the first failure might be lost; a discarded approach might be re-attempted if its rejection reason was compressed away.

The summary simultaneously tries to do three things:

Shorten current input

Preserve task progress

Replace past raw records

These three goals conflict: aggressive compression speeds recovery but loses detail; retaining detail quickly fills the window with old content. Codex's changes appear to separate these concerns.

Four Types of State Mixed in "Memory"

In agent discussions, conversation, notes, history, and workspace files are often called "memory." Convenient, but in system design they differ in who writes, retention duration, overwrite rules, and conflict resolution. The author identifies four distinct state categories:

Figure 1: States, actions, and evidence must align separately; this is an architectural schematic for understanding, not an official Codex diagram.

1. Current Working Set: What the Model Needs Right Now

The current context window is the model's immediate workbench: system instructions, user requests, recent dialogue, tool results, and information required for the next step. Token budget only answers resource questions—which window number, how much space remains. It does not save task progress but lets the model know when to wrap up the current phase and leave room for handoff.

In the auth migration example, once testing and fixing begin, the current step revolves around failing cases, relevant code, and compatibility constraints. Every file previously read would continue consuming inference space if left in the window.

2. Handoff State: Where the Next Window Picks Up

Notes store information that must persist across windows: why the old interface cannot be deleted, which files are already modified, which approach was tried and failed, current failure hypothesis, and where to resume next.

Source code reminder templates are specific: goal, key decisions, current progress, confirmed facts, next steps—all should be retained. Ongoing user requests and important tool calls carry window IDs and item IDs so the new window can return to original records. This is less a "previously on" recap and more a checkpoint left when the task reaches a certain point.

Analogous to an on-call handover: the incoming engineer reads the handover log, doesn't replay all prior chat; for a specific alert's history, they check original records; to verify service recovery, they check monitoring and business metrics.

This checkpoint is model-curated and still loses information. If the model forgets to write a constraint, the new window won't know; if task state changes but notes aren't updated, stale notes may mislead subsequent reasoning.

3. Session History: Raw Records for Verification

History preserves raw entries from old windows. The new window can list historical windows and their entries, read specific content, and search past conversations and tool results.

For example, if notes only say "unified SDK upgrade infeasible," later verification can return to history to find the original user request, commands, and error output—rather than guessing from a second-hand summary.

However, "raw content exists" and "retrievable when needed" are different. Current source code uses case-sensitive literal substring matching, not semantic retrieval. Wrong keywords or rephrased concepts may miss the target.

4. External Authoritative Facts: What the Task Actually Achieved

Another state category lives outside model context: code, Git, test reports, CI, tickets, and real state in business systems. new_context swaps the model context but does not clear the working directory, roll back files, or undo external requests already sent. Notes stating "tests passed" only record the model's belief; actual pass/fail depends on exit codes and reports. The model remembering "refund submitted" does not replace the payment system's transaction state.

Each state type answers a distinct question:

Current working set : materials needed for immediate inference

Notes : handoff information for the next window to pick up quickly

History : original records available for verification

External systems : ground truth of what the task actually accomplished

This implementation does not give the agent a free-floating "permanent memory"; it separates states with different lifecycles and trust levels.

How Codex Executes a Window Switch

With states separated, the actions during a window switch become clearer: who decides when the window is nearly full, what gets written before switching, and how recovery works after the switch.

Chaining several consecutive PRs reveals a protocol jointly executed by the model and the Harness.

Expose Budget to the Model, Give It a Proactive Switch Entry

At runtime, the current window identity and token headroom are exposed to the model. It doesn't have to wait for sudden system compaction; it can judge whether the current step is suitable for wrap-up and decide when to prepare handoff.

The model can call new_context to proactively start a new model context. If it never acts, the runtime issues a reminder once headroom crosses a threshold; when the base budget is exhausted, a fallback prompt is injected with a buffer allowing the model to write notes and initiate the switch. If the model already called new_context, the fallback is skipped; only when the buffer is also exhausted does the runtime force a switch.

Two layers of judgment handle different problems: the model judges whether the current step is done and what information deserves handoff; the Harness watches headroom, reminder state, and the latest switch deadline.

After Switching, the New Window Relocates the Task

"New" means a fresh model context; the task does not revert to a blank slate. Source code discards the old window's conversation history, then rebuilds the context the Harness still needs based on the current runtime state (world state); code in the working directory, Git state, and executed external actions do not roll back.

Each time a full window context is built, the history-notes extension attempts to fetch a thread_hint from the backend. Only on successful request, non-empty content, and size ≤ 4000 bytes does this hint enter the model context; the old window's raw content is not bulk-reloaded. When more detail is needed, the model uses notes and history tools to look up.

The 4000-byte limit reveals a trade-off. Codex's own review rules require incremental context construction to avoid cache invalidation from frequent changes; all injected items have hard caps, no single item exceeding 10k tokens. Under these constraints, the system does not refill the window with old content relocated elsewhere; instead it restores within budget: handoff stays concise, history is read on demand, and the model's context always has boundaries.

Then Restore Details on Demand

Returning to the auth migration task, the new window first reads handoff from notes; when gaps appear or details need verification, it searches and reads raw entries from history. Remaining old content is not stuffed back into the current window.

The entire chain simplifies to:

See budget headroom → wrap up current phase → write handoff → switch to new window → rebuild runtime context → read notes → query history if necessary → verify against external facts → continue execution

Figure 2: Runtime chain from current working set to handoff, lookup, and acceptance; "compaction still allows continuation" corresponds to the old mechanism, while Codex's experimental switch provides an alternative window-switch path.

The model judges "is this phase done" and "which decisions to hand over"; the Harness enforces resource caps, records window numbers, handles switch conditions, and provides history storage and recovery entry points.

The model can proactively wrap up, while the runtime retains hard boundaries and fallbacks. Long-running agents therefore need not rely entirely on the model "remembering to proactively organize."

An Architect's Familiar Problem: Who Owns State

In architecture design we often discuss service boundaries, data ownership, and failure recovery. Agent context management is the same problem, except part of the state lands in the model window.

If the auth migration task ran in a production-grade Harness, the author would first examine ownership of each state type rather than maximum model recall. A simple state table clarifies what the model writes, what the runtime writes, who can overwrite, when old values expire, and who wins conflicts.

For instance, the model may record "current failure hypothesis," but real test results won't change because of it; notes may say "main path modified," but actual diff scope lives in Git; history can prove a command ran, but the external service's current state must be confirmed from the service itself.

If state ownership is unclear, problems rarely manifest as outright "amnesia." More commonly the task slowly drifts: stale constraints persist, failed approaches are retried, external actions repeat, while the system believes it's continuing normally.

Beyond Smooth Switching: Exception Recovery

Proactive wrap-up, good notes, then continue from the new window is the happy path. Real tasks encounter moments without completed handoff.

Examples: sudden window overflow, process cancellation, model call failure, or external request sent but response not returned. Recovery differs per failure type.

Lost model context can be rebuilt from notes and history; local edits can be confirmed via Git diff and test results. When external action results are unknown, the safer sequence is to query the authoritative system first, then decide retry based on idempotency keys. Absence of a result in handoff notes does not prove the previous action didn't happen.

Figure 3: Context can be rebuilt, but external side effects cannot be guessed from notes; when result is unknown, query authoritative system first, then decide whether to continue.

This mirrors database failure recovery and workflow resumption: model context is reconstructible, but external side effects must be confirmed in business records.

In Short Tasks, Differences May Not Show

Based on current public materials, one cannot judge whether the new mechanism outperforms compaction.

Benefits of notes + history: current window stays cleaner, key details retain a lookup entry. Costs: new system questions—will handoff leak, can search hit targets, will recovery slow down, is history storage cost controllable.

If validating in a team, the author would select tasks that genuinely undergo multiple window switches, enable the experiment on a small traffic slice while keeping the existing compaction fallback. Beyond token consumption, they would record:

After multiple switches, how much user constraint, current progress, and failed approaches remain

Whether the agent proactively looks back when information is insufficient, and whether literal search finds the target

Time from new window to effective work

Cache reuse and first-response latency changes after window rebuild

Occurrence of duplicate submissions, duplicate calls, or missed executions

Extra tokens and latency spent writing notes, searching, and reading history

Only together do these data reveal trade-offs. Looking only at context savings misses recovery quality and side-effect risk; looking only at final task completion hides intermediate trial-and-error cost.

The author would focus validation on post-multiple-switches: can the task still continue correctly, what did recovery cost, and can issues be diagnosed when they arise.

What Summary, Notes, and History Each Do

Compaction and hard window switching are often seen as mutually exclusive paths. Placed in the actual runtime chain, they serve different work and incur different read costs.

Back in the same chain, they resemble different-cost retrieval tiers.

Summary suits rapid global recovery; notes suit preserving explicit handoff state; raw history suits verifying critical details. Only summary makes omitted information hard to retrieve; only raw records may force the new window to spend many retrievals to reconstruct the task panorama.

Codex's current experiment uses "short handoff + raw history" combination, while compaction remains in the official product. Which path becomes mainline ultimately depends on real task data; a single post and a few PRs cannot decide yet.

Teknium noted Hermes is also adding compaction recall. The two projects' implementations differ, but both leave an entry to inspect original records after compaction or handoff.

How to Enable Currently

Codex CLI 0.153.0 public configuration:

Add two lines to ~/.codex/config.toml:

[features.context_management]
experimental_mode = true

It is disabled by default and subject to the account, backend, and thread-type limits mentioned earlier. During development, [features] token_budget = true and earlier granular switches appeared; the current public configuration uses the entry above.

Recently a claim appears: "must enable if using GPT-6 Astra." This conflates two layers: GPT-6 Astra is a model choice; experimental_mode is the Codex CLI context management switch. Official configuration describes the latter's experimental scope, does not list Astra as a prerequisite, and does not promise that enabling it will definitely save tokens or perform better.

In practice, the author treats it as a long-task experiment switch: write config to ~/.codex/config.toml, exit and restart Codex to reload, then run a few task types that experience multiple window switches for comparison. It lets notes and searchable history participate in cross-window recovery, reducing reliance on repeatedly compressing full history into a single summary; this does not equal fully canceling compaction, and actual benefit depends on whether the task truly needs multiple window switches.

Config names, tool behaviors, and data formats may still change. At current maturity, the author would keep it in experimental and validation environments, not in critical pipelines.

Conclusion

Initially seeing "Codex to abandon compaction," the author thought the focus was swapping one compression method for another. After unfolding the implementation, the focus shifts to how state is separated: transient working set stays in the current window, notes save handoff, history keeps raw records, code and external systems continue holding task facts.

Whether this division loses less state than existing compaction without shifting cost to retrieval, latency, and side-effect risk awaits real long-task data. At least up to 0.153.0, public materials have not provided an answer.

References

OpenAI: Codex Configuration Reference

OpenAI: Codex Changelog (CLI 0.150.0, 0.150.1, 0.153.0)

OpenAI: Compaction (API Guide)

openai/codex PR #27438: Add token budget context feature

openai/codex PR #27488: Add new context window tool

openai/codex PR #33255: Add a fallback phase before automatic context rollover

openai/codex PR #39827: Add history and notes tools for token-budget sessions

openai/codex PR #40539: Inject history notes hints into context windows

openai/codex PR #41803: Allow models to enable token budgeting by default

openai/codex PR #42385: Add experimental context management activation

Nico Ritschel: Codex CLI context cutover discussion

Teknium: Hermes compaction recall discussion

Anthropic: Effective context engineering for AI agents

Anthropic: Effective harnesses for long-running agents