compaction-ui

name	compaction-ui
version	2.3.0
description	Background memory compaction with auto-trigger, chat summary paragraph, configurable threshold, model selector, settings tab, and result storage for OpenClaw Control 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

Component	Status
Context Gauge Button	✅ Working
Background Compaction (toast)	✅ Working
Auto-Compaction Trigger	✅ Working
Conversation Summary Paragraph	✅ Working
Settings Tab (plugin-registered)	✅ Working
Model Selector	✅ Working
Last Result Storage + Viewer	✅ Working
Settings Persistence & Reload	✅ Working
Auth Hierarchy (OAuth > API > Fallback)	✅ Working
Chat History Filters	✅ Working
Full Background Isolation (no chat interference)	✅ Working

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

Backend RPCs

Method	Description
sessions.compact	Execute compaction (records result after completion)
compaction.getSettings	Read settings from config file
compaction.saveSettings	Update settings (threshold auto-clamped 10-95%)
compaction.getLastResult	Get stored last compaction result
compaction.clearLastResult	Clear stored result

Files Modified

File	Purpose
src/gateway/server-methods/compaction.ts	Settings RPCs, config I/O, result recording
src/gateway/server-methods/sessions.ts	sessions.compact RPC (records result after compaction)
src/gateway/server-methods/plugins-ui.ts	Plugin view registration
src/gateway/server-methods.ts	Handler wiring
src/gateway/server-methods-list.ts	Method registration
src/gateway/method-scopes.ts	Scope registration
src/agents/pi-embedded-runner/compact.ts	Chat summary instruction injection
ui/src/ui/app-render.helpers.ts	Context gauge + background toast trigger
ui/src/ui/app-gateway.ts	Auto-compaction check after final event
ui/src/ui/views/compaction-settings.ts	Settings tab view
ui/src/ui/app-render.ts	View wiring + import
ui/src/ui/views/chat.ts	Chat history filters

Config File

{agentDir}/compaction-config.json — per-agent, created on first settings save.

Plugin Registration

The compaction tab is registered as a builtin plugin view in plugins-ui.ts:

{
  id: "compaction",
  label: "Compaction",
  subtitle: "Memory Management",
  icon: "archive",
  group: "agent",
  position: 7,
  pluginId: "compaction-ui",
}

Known Gotchas

• Settings not persisting across tab visits: Fixed in v2.1.0. The module-level _state.loaded flag was preventing reloads. Now reloads every 2 seconds when re-entering the tab.
• Model selector requires API keys: If you select a custom model, make sure the provider's API key is configured. The UI shows a warning callout.
• Compaction model format: Must be "provider/model" format (e.g. "anthropic/claude-sonnet-4-6"). Invalid formats are silently ignored and fall back to session default.
• parentId skip-set propagation must be message-only: When filtering memory flush messages from readSessionMessages, the skip set must ONLY propagate through entries with a message field. Non-message protocol entries (type:"custom") bridge between logical turns — if their IDs enter the skip set, the entire remaining conversation gets hidden. The fix: only check parsed?.message entries against the skip set, and only add their IDs to it.
• No blocking modal — ever: The gauge button in app-render.helpers.ts must NEVER render a full-screen overlay modal. Compaction is a background process; all status is communicated via the bottom-right toast system. Remove any position:fixed; inset:0 overlay conditioned on compactState.phase. The button may show a spinner icon while running, but must not block the UI.

Changelog

v2.1.0

• Conversation summary paragraph: Compaction output now starts with a ## Conversation Summary narrative paragraph before structured sections
• Model selector: Choose a specific model for compaction or use session default, with provider-grouped dropdown
• Settings reload fix: Tab now reloads settings from backend every 2s instead of caching forever
• Reference files updated: Synced references/ with current source

v2.0.0

• Background compaction: Replaced blocking full-screen modal with background job toast
• Auto-compaction: Triggers after chat response when token usage exceeds threshold (configurable, default 60%, 5-minute debounce)
• Settings tab: Plugin-registered Compaction tab under Agent nav group
• Result recording: sessions.compact records before/after token counts and optional summary
• Auth hierarchy: Same OAuth → API → Fallback chain as chat
• Settings RPCs: compaction.getSettings, compaction.saveSettings, compaction.getLastResult, compaction.clearLastResult

v1.0.0

• Initial release: Context gauge button, blocking modal with animated phases, sessions.compact RPC with LLM summarization, chat history NO_REPLY/HEARTBEAT_OK filtering, compaction divider lines