Compact Conversation Context

Compaction summarizes native conversation context so the harness can continue a longer session. It is lossy: verify important facts and tool outcomes after compaction, especially when moving execution to another replica.

The HTTP endpoint checks session ownership before compaction. Claude returns 501: send /compact through its run endpoint instead. Codex supports the session-compaction endpoint when its native thread files are available on the receiving replica.

Claude

With the database-backed transcript store configured, send /compact as the input to an existing session:

# agent is the ClaudeAgent configured with a database in Run Claude.
result = await agent.arun("/compact", session_id="support-demo")
print(result.status, result.content)

The Claude runtime also compacts automatically when its context policy triggers. Native compaction boundaries and summaries are mirrored through the transcript store. A later replica needs that successfully persisted native state to resume from the compacted conversation.

A short conversation may not contain enough context to compact. A successful manual /compact test does not prove that automatic compaction was triggered. Observe the native PreCompact hook's trigger and stored transcript boundaries when validating each path.

Codex

For an existing local native thread:

# agent is the CodexAgent configured with a database in Run Codex.
compacted = await agent.acompact("support-demo")
print(compacted)

Use agent.compact("support-demo") in synchronous code. True means the compaction operation finished. False means there is no usable native thread to compact. An in-flight run raises SessionBusyError; the operation can also time out.

Over HTTP, call POST /agents/{agent_id}/sessions/{session_id}/compact. The response has status, message, compacted, record and metrics. Codex reports compacted=true after native completion, with record and metrics null. status=no_history means the replica has no resumable native thread, even if the database retains run history. Busy sessions return 409; a timeout returns 504 and does not guarantee that the native operation stopped. Coordinate compaction with session turns before retrying. This endpoint is not a durable background job.

Codex's compacted native thread remains filesystem-backed. A replica without those files uses the adapter's bounded-history fallback for a later run; that is not restoration of the native compacted thread.

Validate your recovery path

Seed a unique fact, execute a tool, compact, and ask a follow-up without supplying the original fact again. Then repeat the follow-up from a fresh execution environment. Inspect native session/thread identity, persisted transcript state and actual answers separately.

The Claude compaction cookbook and Codex compaction cookbook include assertions for their respective recovery contracts.