Luna/Documentation/References/OpenClaw/Compaction Strategy.md

Compaction Strategy

OpenClaw employs a multi-layered conversation compaction system to manage long-running sessions within finite model context windows. Unlike basic truncation, this system uses LLM-driven summarization, token-budget gating, and quality safeguards to preserve critical state, identifiers, and recent context.

---

Trigger & Token Gating

Compaction is primarily triggered by "preflight" checks before processing a new turn, ensuring the model has sufficient headroom for its next response. This process is managed in auto-reply/reply/agent-runner-memory.ts and memory-flush.ts.

Gating Logic

The decision to compact is based on a projected token count compared against a computed threshold:

• Threshold Formula: contextWindowTokens - reserveTokensFloor - softThresholdTokens
• Reserve Floor: Defaults to 20,000 tokens (reserveTokensFloor), providing a safety buffer for tool outputs and reasoning.
• Soft Threshold: An additional 4,000 token buffer (softThresholdTokens) to prevent compaction oscillations at the exact limit.
• Token Estimation: Performed by estimateMessagesTokens(), which strips toolResult.details for security and applies a SAFETY_MARGIN of 1.2 to account for estimation inaccuracies.

Execution Hooks

• shouldRunPreflightCompaction: Runs before a turn to ensure the input fits the budget.
• shouldRunMemoryFlush: Evaluates if the session should be "flushed" to long-term memory based on token pressure.
• Deduplication: hasAlreadyFlushedForCurrentCompaction prevents redundant flushes within a single compaction cycle.
• Manual Trigger: The /compact command allows users to manually force a compaction cycle.

---

Summarization Core

The core summarization engine in agents/compaction.ts orchestrates the transformation of raw history into structured summaries.

Resource Allocation

• SUMMARIZATION_OVERHEAD_TOKENS: 4,096 tokens are reserved for the summarization prompt, system instructions, and previous summaries.
• Adaptive Chunking: computeAdaptiveChunkRatio shrinks chunk sizes as the average message size increases. If a single message exceeds 50% of the context window, it is flagged as isOversizedForSummary and handled via fallback mechanisms.

Orchestration Pipeline

1. summarizeChunks: Splits the history into chunks based on maxChunkTokens.
2. summarizeWithFallback: Attempts a full summary. On failure, it separates "small" messages from "oversized" ones, summarizing the small messages and annotating the oversized ones (e.g., [Large message (~15K tokens) omitted from summary]).
3. summarizeInStages: For very large histories, it generates partial summaries and then merges them using MERGE_SUMMARIES_INSTRUCTIONS.

Preservation Priorities

The system uses MERGE_SUMMARIES_INSTRUCTIONS to ensure the model retains:

• Active tasks and current status (in-progress, blocked, pending).
• Commitments, decisions, and their rationale.
• Unresolved user asks and key factual identifiers.
• Recent context over older history.

---

Safeguard Extension

The compaction-safeguard.ts hook acts as a safety layer, registering on session_before_compact to manage context sharing and content preservation.

Context Preservation

• Recent Turns: Preserves DEFAULT_RECENT_TURNS_PRESERVE = 3 turns verbatim to maintain immediate conversational flow.
• History Pruning: pruneHistoryForContextShare drops older chunks if the new content consumes too much of the history budget. Dropped messages are summarized and prepended as a previousSummary.
• Suffix Protection: Critical metadata is appended to a protected suffix that survives truncation:
  • Tool failures (capped at 8 failures).
  • File operations (read/modified lists).
  • Workspace rules (extracted from AGENTS.md).

Length Constraints

• MAX_COMPACTION_SUMMARY_CHARS: 16,000 characters cap for the total summary.
• MAX_FILE_OPS_SECTION_CHARS: 2,000 characters for file operation logs.
• MAX_FILE_OPS_LIST_CHARS: 900 characters for the list of files.

---

Quality Guard

The Quality Guard (compaction-safeguard-quality.ts) ensures the LLM-generated summary meets strict structural and content requirements.

Required Sections

Every summary must contain these exact Markdown headings:

• ## Decisions
• ## Open TODOs
• ## Constraints/Rules
• ## Pending user asks
• ## Exact identifiers

Identifier Preservation

The system extracts opaque identifiers (URLs, file paths, hex IDs, ports) using regex and enforces their preservation.

• Strict Policy: If identifierPolicy is set to strict, the guard validates that all extracted identifiers appear in the final summary.
• Audit Loop: auditSummaryQuality checks for section presence and identifier integrity. If checks fail, the system triggers a regeneration with qualityFeedbackInstruction.

---

Default Instructions

Default behavior is governed by compaction-instructions.ts, which merges user-defined, runtime, and system-level instructions.

export const DEFAULT_COMPACTION_INSTRUCTIONS =
  "Write the summary body in the primary language used in the conversation.\n" +
  "Focus on factual content: what was discussed, decisions made, and current state.\n" +
  "Keep the required summary structure and section headers unchanged.\n" +
  "Do not translate or alter code, file paths, identifiers, or error messages.";

Instructions are capped at MAX_INSTRUCTION_LENGTH = 800 characters to prevent prompt bloat.

---

Runtime Execution & Truncation

The compact.ts runner provides the entry point for both automated and manual compaction.

Execution Flow

1. Preparation: Opens the session, sanitizes history, and runs before_compaction hooks.
2. Safety Timeout: Wraps the LLM call in compactWithSafetyTimeout to prevent hanging processes.
3. Post-Processing: Runs after_compaction hooks and estimates the resulting token count.

Session Truncation

If enabled via config.agents.defaults.compaction.truncateAfterCompaction, the system physically rewrites the session JSONL file using session-truncation.ts.

• Removal: Deletes message entries that were summarized.
• Re-parenting: Re-parents orphaned entries to the nearest kept ancestor to maintain the integrity of the session tree.
• Archiving: Optionally creates an archive of the original session file before truncation.

---

Configuration Knobs

Compaction behavior can be tuned via OpenClawConfig:

• config.agents.defaults.compaction.model: Override the model used for summarization.
• config.agents.defaults.compaction.reserveTokensFloor: Minimum buffer (default ~20,000).
• config.agents.defaults.compaction.timeoutSeconds: Max time allowed for a summarization call.
• config.agents.defaults.compaction.truncateAfterCompaction: Boolean to enable physical file cleanup.
• memoryFlush: Configuration for soft thresholds and forced flush triggers.

---

Relevance to Luna

Luna currently uses a basic LibrarianAgent for compaction with no token-budget gating, no quality guards, and no structured instruction sets. To achieve OpenClaw-level reliability, Luna should adopt:

• Token-Budget Gating: Triggering compaction based on projected context usage rather than arbitrary turn counts.
• Structured Sections: Enforcing a specific Markdown schema in summaries to ensure critical state is never lost.
• Identifier Preservation: Using regex extraction and quality audits to protect file paths and IDs.
• Quality Audit Loop: Implementing a verification step that can re-trigger summarization if requirements are missed.
• Session Truncation: Physically cleaning up on-disk history files to prevent unbounded growth.

Patterns like the compaction-safeguard provide a more resilient approach for long-term project management in Luna by ensuring the project state, goals, and critical constraints are always prioritized in the model's working memory.

See also: Core, Configuration, Session Management