Compaction UI

Compaction UI v2.1.0

Memory compaction system for the OpenClaw Control UI — background execution with toast notifications, auto-trigger at configurable token thresholds, conversation summary paragraphs in compacted output, dedicated settings tab with model selector, and result history.

Status: ✅ Active

Features

1. Context Gauge Button (app-render.helpers.ts)

A circular SVG progress ring in the chat toolbar that doubles as the manual compact trigger.

• Placement: After session selector dropdown in renderChatControls()
• Data source: sessionsResult.sessions[].totalTokens and contextTokens from session rows
• Colors: Green (<60%), Yellow (60-85%), Red (≥85%)
• Disabled: When utilization <20% or during active compaction
• Tooltip: Shows "Context: XK / YK tokens (Z%)"

2. Background Compaction (Toast)

On click (or auto-trigger), compaction runs in the background using the standard bottom-right toast system — no blocking modal. The UI remains fully interactive.

• Running toast: Shows "Memory Compaction" with spinner
• Complete toast: Shows "Compacted: XK → YK" with checkmark (auto-dismisses after 5s)
• Error toast: Shows failure message (auto-dismisses after 5s)
• Uses backgroundJobToasts system consistent with all other background processes (cron, knowledge extraction, etc.)

3. Auto-Compaction

After every chat response (final event), the UI checks token usage against the configured threshold. If exceeded:

• Background compaction triggers automatically
• Toast shows "Auto-Compacting (X%)" with the current utilization
• 5-minute debounce prevents repeated triggers
• Chat refreshes automatically after successful compaction
• Silent toast removal if nothing was compacted

4. Conversation Summary Paragraph

Every compaction output now begins with a ## Conversation Summary section before the structured ## Goal section. This is a 3-6 sentence natural language paragraph that:

• Describes the overall topic(s) of the conversation
• Explains the flow of discussion and key transitions
• Summarizes how the conversation progressed
• Written in past tense as a narrative overview

Implementation: Custom instructions are injected into the upstream compaction LLM call via compact.ts. The instruction is prepended to any user-provided custom instructions (from /compact [instructions]), so both coexist.

Example output:

## Conversation Summary
The conversation began with the user requesting improvements to the compaction
system, specifically moving from a blocking modal to background toasts. Discussion
then shifted to adding a settings tab with auto-compaction controls. After
implementing and testing those features, the user noticed settings weren't
persisting across tab navigations, which led to a fix for the module-level
state cache. Finally, the user requested adding a narrative summary paragraph
to the compaction output for better context.

## Goal
...

5. Settings Tab (Plugin-Registered)

A dedicated Compaction tab under the Agent navigation group, registered via the Plugin UI architecture.

Registration: plugins-ui.ts → BUILTIN_UI_VIEWS with id: "compaction", group: "agent", position: 7, icon: "archive"

Cards:

Auto-Compaction Card

• Toggle: Enable/disable automatic compaction
• Threshold slider: 10% to 95% (default: 60%)
• Color-coded: Green (<60%), Yellow (60-85%), Red (≥85%)

Model Card

• Dropdown: Select a specific model for compaction or use session default
• Grouped by provider with context window sizes shown
• Warning callout when custom model selected (API key reminder)
• Fallback: If custom model fails, automatically falls back to session default

Result Storage Card

• Toggle: Opt-in to save the compacted summary text for review

Last Compaction Card

• Before/After: Large styled token counts in a 2-column grid
• Stats: Tokens saved, percent reduction, trigger type, timestamp, session key
• View Results: Expandable summary viewer (when storage is enabled)
• Clear: Reset stored result
• Hint: Shows "Enable Store Results" message when storage is off

State Management:

• Module-level state persists across re-renders within a session
• Settings reload from backend every time the tab is visited (2-second staleness threshold)
• resetCompactionSettingsState() exported for tests and tab switches

6. Auth Hierarchy

Compaction uses resolveApiKeyForProvider via getApiKeyForModel — the same auth chain as chat:

OAuth → API Key → Fallback

No separate configuration needed. If OAuth (Claude Max) is configured as the primary auth profile, compaction uses it automatically. Custom model selection uses this same auth chain independently.

7. Result Storage

When enabled, the most recent compaction result is persisted to {agentDir}/compaction-config.json:

{
  "settings": {
    "autoEnabled": true,
    "autoThresholdPercent": 60,
    "storeLastResult": true,
    "compactionModel": "anthropic/claude-sonnet-4-6"
  },
  "lastResult": {
    "timestamp": 1709283600000,
    "trigger": "manual",
    "tokensBefore": 50614,
    "tokensAfter": 4766,
    "tokensSaved": 45848,
    "percentReduction": 91,
    "sessionKey": "agent:main:main",
    "summary": "## Conversation Summary\nThe conversation focused on...\n\n## Goal\n..."
  }
}

When storage is disabled, metadata (timestamps, token counts) is still saved but the summary text is omitted.

8. Chat History Filters

• NO_REPLY/HEARTBEAT_OK filtering: Skips assistant messages with these exact texts
• Compaction divider: Renders labeled divider line for __openclaw.kind === "compaction" messages

Architecture