<!-- source: https://deepwiki.com/openclaw/openclaw/3.6-context-compaction -->

# Context Compaction

- extensions/codex/src/app-server/dynamic-tool-build.test.ts
- extensions/codex/src/app-server/dynamic-tool-build.ts
- extensions/memory-core/src/dreaming-narrative.test.ts
- extensions/memory-core/src/dreaming-narrative.ts
- extensions/memory-core/src/dreaming-repair.test.ts
- src/agents/command/cli-compaction.test.ts
- src/agents/command/cli-compaction.ts
- src/agents/embedded-agent-runner/compact.hooks.harness.ts
- src/agents/embedded-agent-runner/compact.ts
- src/agents/embedded-agent-runner/compact.types.ts
- src/agents/embedded-agent-runner/run/attempt-session.ts
- src/agents/embedded-agent-runner/run/attempt-trajectory-flush-cleanup.test.ts
- src/agents/embedded-agent-runner/run/attempt-trajectory-flush-cleanup.ts
- src/agents/embedded-agent-runner/run/attempt.spawn-workspace.test-support.ts
- src/agents/embedded-agent-runner/run/attempt.ts
- src/agents/embedded-agent-runner/system-prompt.test.ts
- src/agents/embedded-agent-runner/system-prompt.ts
- src/agents/harness/selection.test.ts
- src/agents/harness/selection.ts
- src/agents/runtime-plan/tools.test.ts
- src/agents/runtime-plan/tools.ts
- src/agents/sessions/agent-session.ts
- src/agents/sessions/sdk.test.ts
- src/agents/tool-schema-projection.test.ts
- src/agents/tool-schema-projection.ts
- src/agents/tool-schema-quarantine.test.ts
- src/agents/tool-schema-quarantine.ts
- src/agents/tools-effective-inventory-build.ts
- src/agents/tools-effective-mcp-inventory.ts
- src/auto-reply/reply/commands-compact.test.ts
- src/auto-reply/reply/commands-compact.ts
- src/gateway/server-methods/sessions.ts
- src/gateway/server.sessions.list-changed.test.ts

Context compaction is a critical lifecycle mechanism in OpenClaw designed to manage AI agent memory by summarizing and condensing session conversation histories. This process prevents context overflow when sessions approach model token limits, ensuring long-running interactions remain coherent and efficient while staying within the provider's context window.

## Overview

OpenClaw performs **automatic context compaction** to keep conversation transcripts within the constraints of the underlying LLM's context window. When the estimated token count for a session exceeds defined thresholds, or when a model provider returns a context-overflow error, the system triggers a compaction operation that replaces older messages with a concise summary.

### Key Implementation Features

- Overflow Detection: Monitored during the execution pipeline in runEmbeddedAgent src/agents/embedded-agent-runner/run.ts 136 and handled via classifyFailoverReason src/agents/embedded-agent-runner/run.ts 53-54
- Exclusive Locking: Uses acquireSessionWriteLock to prevent concurrent modifications to the session JSONL file during truncation src/agents/embedded-agent-runner/compact.ts 108-111
- Checkpointing: Captures state before and after compaction via captureCompactionCheckpointSnapshotAsync and persistSessionCompactionCheckpoint src/agents/embedded-agent-runner/compact.ts 8-11
- Durable Memory Sync: Flushes pending tool results and ensures the transcript remains valid via repairSessionFileIfNeeded src/agents/embedded-agent-runner/compact.ts 104
- Successor Transcripts: Supports rotating to a new transcript file after compaction via rotateTranscriptAfterCompaction src/agents/embedded-agent-runner/compact.ts 141-143 to avoid in-place corruption.
- Memory Flush Integration: Pre-compaction logic includes runMemoryFlushIfNeeded to preserve long-term memory before the active transcript is truncated src/auto-reply/reply/agent-runner-memory.ts 14
- CLI Runtime Passthrough: For CLI-based runtimes (like claude-cli ), OpenClaw handles the compaction of the local transcript and clears external resume state via runCliTurnCompactionLifecycle src/agents/command/cli-compaction.ts 141

### Context Compaction Data Flow

The following diagram illustrates the transition from the high-level "Natural Language" intent to the "Code Entity" execution path within the runner.

Title: Compaction Lifecycle Data Flow

```

```

Sources:
[src/agents/embedded-agent-runner/run.ts53-62](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/run.ts#L53-L62) [src/agents/embedded-agent-runner/run.ts136](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/run.ts#L136-L136) [src/agents/embedded-agent-runner/compact.ts121-124](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/compact.ts#L121-L124) [src/agents/embedded-agent-runner/compact.ts126-132](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/compact.ts#L126-L132) [src/auto-reply/reply/agent-runner-memory.ts14](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L14-L14)

## Trigger Conditions and Safeguards

### Token Thresholds

OpenClaw uses a tiered approach to context management.

- Default Trigger: 32,768 tokens (defined by DEFAULT_CONTEXT_TOKENS ) src/agents/embedded-agent-runner/compact.ts 77
- Dynamic Calculation: The system estimates tokens using estimateTokens from the session manager src/agents/embedded-agent-runner/compact.ts 112
- Model-Specific Window: Resolves the context window via resolveContextWindowInfo src/agents/embedded-agent-runner/compact.ts 75
- Memory Flush Threshold: Memory flushes are triggered when resolveEffectivePromptTokens exceeds the model's soft threshold src/auto-reply/reply/agent-runner-memory.ts 163-174
- Preemptive Compaction: The system checks if a prompt will fit before sending via shouldPreemptivelyCompactBeforePrompt src/agents/command/cli-compaction.ts 128

### Safeguard Mode

To prevent infinite loops or hangs, the system implements a safeguard mode:

- Timeout Protection: Configured via resolveCompactionTimeoutMs and enforced by compactWithSafetyTimeout src/agents/embedded-agent-runner/compact.ts 136-137
- Cancel Reason: Hooks can cancel compaction using setCompactionSafeguardCancelReason src/agents/agent-hooks/compaction-safeguard-runtime.js 45
- Post-Compaction Loop Guard: createPostCompactionLoopGuard tracks consecutive compactions to detect failures where the model still reports overflow immediately after summarization src/agents/embedded-agent-runner/run.ts 121-124

Sources:
[src/agents/embedded-agent-runner/compact.ts75-77](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/compact.ts#L75-L77) [src/agents/embedded-agent-runner/compact.ts136-137](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/compact.ts#L136-L137) [src/agents/embedded-agent-runner/run.ts121-124](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/run.ts#L121-L124) [src/auto-reply/reply/agent-runner-memory.ts163-174](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L163-L174) [src/agents/agent-hooks/compaction-safeguard-runtime.js45](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/agent-hooks/compaction-safeguard-runtime.js#L45-L45)

## Implementation Lifecycle

### 1. Pre-Compaction Hooks

Before summarization begins, the system executes `runBeforeCompactionHooks` [src/agents/embedded-agent-runner/compact.ts131](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/compact.ts#L131-L131) This allows plugins to prepare data or adjust metrics via `buildBeforeCompactionHookMetrics` [src/agents/embedded-agent-runner/compact.ts128](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/compact.ts#L128-L128)

### 2. Checkpointing

OpenClaw captures a snapshot using `captureCompactionCheckpointSnapshotAsync` [src/agents/embedded-agent-runner/compact.ts8](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/compact.ts#L8-L8) This ensures session recovery if compaction fails. The reason is recorded via `resolveSessionCompactionCheckpointReason` [src/agents/embedded-agent-runner/compact.ts11](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/compact.ts#L11-L11)

### 3. Summarization and Truncation

The core logic resides in `compactEmbeddedAgentSession`.

- History Limiting: Respects session history limits via limitHistoryTurns src/agents/embedded-agent-runner/compact.ts 147
- Truncation: If rotation is enabled, the system rotates the transcript via rotateTranscriptAfterCompaction src/agents/embedded-agent-runner/compact.ts 141-143
- Real Conversation Check: Verifies meaningful content using hasMeaningfulConversationContent src/agents/embedded-agent-runner/compact.ts 72-74
- Context Engine Execution: The contextEngine.compact method is the primary driver for generating the summary src/agents/command/cli-compaction.test.ts 29-40

### 4. Post-Compaction Sync

After successful truncation, `runPostCompactionSideEffects` is triggered [src/agents/embedded-agent-runner/compact.ts132](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/compact.ts#L132-L132) This typically involves:

- Memory Sync: Forcing a memory search index update or running post-compaction hooks src/agents/embedded-agent-runner/run.ts 104
- Context Engine Maintenance: runContextEngineMaintenance is invoked to cleanup engine-specific state after the turn src/agents/embedded-agent-runner/run.ts 111
- Follow-up Sync: refreshQueuedFollowupSession ensures that any pending automated replies are associated with the new session ID src/auto-reply/reply/agent-runner-memory.ts 62

### System Entity Relationship

Title: Compaction System Class Relationships

```

```

Sources:
[src/agents/embedded-agent-runner/compact.ts121-143](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/compact.ts#L121-L143) [src/agents/embedded-agent-runner/run.ts104-111](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/run.ts#L104-L111) [src/agents/embedded-agent-runner/compact.ts8-13](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/compact.ts#L8-L13) [src/auto-reply/reply/agent-runner-memory.ts39-40](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L39-L40)

## Memory Flush Triggers

Compaction acts as a synchronization barrier for the agent's memory and external state.

Sources:
[src/agents/embedded-agent-runner/compact.ts153](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/compact.ts#L153-L153) [src/agents/embedded-agent-runner/compact.ts108-111](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/compact.ts#L108-L111) [src/agents/embedded-agent-runner/run.ts104](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/run.ts#L104-L104) [src/agents/embedded-agent-runner/run.ts27-28](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/run.ts#L27-L28) [src/auto-reply/reply/agent-runner-memory.ts151-161](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L151-L161)

## Hooks and Configuration

The compaction behavior is highly configurable and integrated into the global hook system.

- Global Hooks: getGlobalHookRunner provides access to runBeforeCompaction and runAfterCompaction which are called during the lifecycle src/agents/embedded-agent-runner/run.ts 17
- Manual Compaction: Users can trigger compaction via the /compact command, handled by handleCompactCommand src/auto-reply/reply/commands-compact.ts 199
- Safeguard Runtime: consumeCompactionSafeguardCancelReason manages the state of active compaction safeguards to prevent overlapping cycles src/agents/agent-hooks/compaction-safeguard-runtime.js 44
- CLI Runtime Compaction: For runtimes like claude-cli , OpenClaw clears the cliSessionBindings in the session store when a compaction occurs to force a fresh session start on the next turn src/agents/command/cli-compaction.ts 185-187
- Context Engine Maintenance: runContextEngineMaintenance is triggered after compaction to perform garbage collection on vector stores or file indexes src/agents/embedded-agent-runner/run/attempt.ts 168

Sources:
[src/agents/embedded-agent-runner/run.ts17](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/run.ts#L17-L17) [src/auto-reply/reply/commands-compact.ts199](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/commands-compact.ts#L199-L199) [src/agents/agent-hooks/compaction-safeguard-runtime.js44](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/agent-hooks/compaction-safeguard-runtime.js#L44-L44) [src/agents/command/cli-compaction.ts185-187](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/command/cli-compaction.ts#L185-L187) [src/agents/embedded-agent-runner/run/attempt.ts168](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/run/attempt.ts#L168-L168)
