Compaction Mechanics

+15 Mana ✨
OpenClaw Compaction Reference(DOCUMENTATION)OpenClaw Session Management(DOCUMENTATION)

Introduction

When the context window fills up, OpenClaw does not simply crash or truncate the conversation. Instead, it employs a compaction process that intelligently reduces context usage while preserving the most important information. Understanding how compaction works helps you anticipate its effects and structure conversations to minimize information loss.

Key Concepts

  • Automatic Compaction: OpenClaw's process for reducing context usage when the window approaches capacity
  • Tool Result Trimming: The first phase of compaction that removes or summarizes old tool outputs
  • Pre-Compaction Memory Flush: A silent agentic turn where the agent writes important context to MEMORY.md before compaction occurs
  • JSONL History Preservation: Session transcripts stored in JSONL format on disk, preserving the full conversation even after in-context compaction
  • Compaction Threshold: The context usage percentage that triggers automatic compaction (typically 85-90%)

Real World Context

A developer has been working with their agent for 45 minutes on a complex refactoring task. The context is 90% full with tool results from reading files, running tests, and reviewing diffs. Without compaction, the next exchange would exceed the context limit. OpenClaw's compaction kicks in: it first writes important decisions to MEMORY.md, then trims old tool results, and then summarizes earlier conversation segments. The developer can continue working without losing critical context.

Deep Dive

Compaction occurs in three phases when the context usage crosses the threshold:

Phase 1: Pre-Compaction Memory Flush

Before any content is removed, OpenClaw runs a silent agentic turn. The agent reviews the conversation and writes important information to MEMORY.md:

markdown
Pre-compaction memory flush:
1. Agent silently reviews the current conversation
2. Identifies important decisions, findings, and context
3. Writes these to MEMORY.md with timestamps
4. This turn is invisible to the user
5. Ensures critical context survives compaction

This silent turn is crucial. It captures decisions and context that might be lost when older messages are trimmed. The user does not see this turn — it happens automatically in the background.

The memory flush is triggered when context usage exceeds approximately 85% of the window:

markdown
Trigger conditions:
- Context usage > 85% of window capacity
- At least 10 messages in the conversation
- At least 5 minutes since last compaction

These conditions prevent premature or excessive compaction. Short conversations never trigger it, and the cooldown period prevents compaction loops.

Phase 2: Tool Result Trimming

After the memory flush, old tool results are trimmed:

markdown
Tool result trimming:
1. Tool results older than 5 messages are candidates for trimming
2. Large tool results (>2,000 tokens) are summarized to ~200 tokens
3. Very old tool results (>15 messages) are removed entirely
4. The most recent 3 tool results are always preserved in full

This is where the biggest token savings occur. A file read that consumed 10,000 tokens is replaced with a 200-token summary like: "Read server.ts (450 lines): Express server with 12 route handlers, middleware chain for auth/logging/cors, PostgreSQL connection pool setup."

Phase 3: Conversation Summarization

If trimming tool results is insufficient, older conversation segments are summarized:

markdown
Conversation summarization:
1. Messages older than 20 turns are grouped into segments
2. Each segment is summarized to ~10% of its original size
3. The summary preserves: decisions made, files modified, errors encountered
4. Recent messages (last 10 turns) are never summarized

The full, uncompacted conversation is always preserved on disk in JSONL format:

markdown
JSONL history:
- Location: ~/.openclaw/sessions/<session-id>/transcript.jsonl
- Format: One JSON object per line (message, tool call, or tool result)
- Retention: Kept indefinitely until manual cleanup or session pruning
- Purpose: Full audit trail, debugging, and session recovery

This means no information is truly lost — it is just removed from the active context to make room for new interactions.

Common Pitfalls

  • Relying on compacted context for critical details: After compaction, specific code snippets and exact error messages from early in the conversation may be gone. Reference MEMORY.md or re-read files instead.
  • Not understanding the silent memory flush: The pre-compaction turn consumes tokens and time. If your agent seems to pause briefly before responding, it may be performing a memory flush.
  • Assuming JSONL transcripts are the active context: JSONL files are for offline reference only. The agent cannot access them during the conversation.

Best Practices

  • Summarize important findings as you go: Do not wait for compaction. Periodically ask the agent to write key findings to MEMORY.md during long sessions.
  • Reference MEMORY.md after compaction: If the agent seems to have lost context, remind it to check MEMORY.md for previously stored information.
  • Use JSONL transcripts for post-session review: After a complex session, review the JSONL transcript to capture any details the agent may have missed during the memory flush.

Summary

  • Compaction occurs in three phases: pre-compaction memory flush, tool result trimming, and conversation summarization
  • The pre-compaction memory flush is a silent agentic turn that writes important context to MEMORY.md before any content is removed
  • Tool result trimming provides the largest token savings by summarizing or removing old tool outputs
  • Full conversation transcripts are preserved in JSONL format on disk regardless of in-context compaction
  • Proactively write important findings to MEMORY.md during long sessions rather than relying solely on automatic compaction
✓ Completed