@martian-engineering/lossless-claw 0.6.2 → 0.7.0

package/README.md

@@ -30,11 +30,23 @@ Nothing is lost. Raw messages stay in the database. Summaries link back to their
 
 ## Commands And Skill
 
-The plugin now ships a bundled `lossless-claw` skill plus a small native command surface:
+The plugin now ships a bundled `lossless-claw` skill plus a small plugin command surface for supported OpenClaw chat/native command providers:
 
 - `/lcm` shows version, enablement/selection state, DB path and size, summary counts, and summary-health status
 - `/lcm doctor` scans for broken or truncated summaries
-- `/lossless` is an alias for `/lcm` on native command surfaces
+- `/lossless` is an alias for `/lcm` on supported native command surfaces
+
+These are plugin slash/native commands, not root shell CLI subcommands. Supported examples:
+
+- `/lcm`
+- `/lcm doctor`
+- `/lossless`
+
+Not currently supported as root CLI commands:
+
+- `openclaw lcm`
+- `openclaw lossless`
+- `openclaw /lcm`
 
 The bundled skill focuses on configuration, diagnostics, architecture, and recall-tool usage. Its reference set lives under `skills/lossless-claw/references/`.
 
@@ -70,7 +82,7 @@ openclaw plugins install --link /path/to/lossless-claw
 
 The install command records the plugin, enables it, and applies compatible slot selection (including `contextEngine` when applicable).
 
-> **Note:** If your OpenClaw config uses `plugins.allow`, make sure both `lossless-claw` and any active plugins you rely on remain allowlisted. In some setups, narrowing the allowlist can prevent plugin-backed integrations from loading, even if `lossless-claw` itself is installed correctly. Restart the gateway after plugin config changes.
+> **Note:** If your OpenClaw config uses `plugins.allow`, allowlist the plugin id `lossless-claw` plus any other active plugins you rely on. Do not add command tokens or aliases like `lossless` or `/lcm` to `plugins.allow`; that setting only accepts plugin ids. In some setups, narrowing the allowlist can prevent plugin-backed integrations from loading, even if `lossless-claw` itself is installed correctly. Restart the gateway after plugin config changes.
 
 ### Configure OpenClaw
 
@@ -246,7 +258,7 @@ Lossless-claw distinguishes OpenClaw's two session-reset commands:
 - `2`: keep d2+ summaries; recommended default
 - `3+`: keep only deeper, more abstract summaries
 
-Lossless-claw currently applies these storage semantics through the `before_reset` hook only. User-facing confirmation text after `/new` or `/reset` must be emitted by OpenClaw's command handlers.
+Lossless-claw applies `/new` pruning through `before_reset` and uses `session_end` to catch transcript rollovers such as `/reset`, idle or daily session rotation, compaction session replacement, and deletions. User-facing confirmation text after `/new` or `/reset` must still be emitted by OpenClaw's command handlers.
 
 Use `ignoreSessionPatterns` or `LCM_IGNORE_SESSION_PATTERNS` to keep low-value sessions completely out of LCM. Matching sessions do not create conversations, do not store messages, and do not participate in compaction or delegated expansion grants.
 

package/docs/agent-tools.md

@@ -32,6 +32,8 @@ Summaries are lossy by design. The "Expand for details about:" footer at the end
 
 Search across messages and/or summaries using regex or full-text search.
 
+Use `mode: "full_text"` for keyword or topical recall. Wrap exact multi-word phrases in quotes to preserve phrase matching. Keep the default `sort: "recency"` for recent events, switch to `sort: "relevance"` when looking for the best older match on a topic, and use `sort: "hybrid"` when you want relevance without giving up recency entirely.
+
 **Parameters:**
 
 | Param | Type | Required | Default | Description |
@@ -44,6 +46,7 @@ Search across messages and/or summaries using regex or full-text search.
 | `since` | string | | — | ISO timestamp lower bound |
 | `before` | string | | — | ISO timestamp upper bound |
 | `limit` | number | | 50 | Max results (1–200) |
+| `sort` | string | | `"recency"` | `"recency"`, `"relevance"`, or `"hybrid"` for full-text ranking |
 
 **Returns:** Array of matches with:
 - `id` — Message or summary ID
@@ -59,6 +62,9 @@ Search across messages and/or summaries using regex or full-text search.
 # Full-text search across all conversations
 lcm_grep(pattern: "database migration", mode: "full_text", allConversations: true)
 
+# Older-topic recall ranked by FTS relevance
+lcm_grep(pattern: "\"error handling\" retries", mode: "full_text", sort: "relevance")
+
 # Regex search in summaries only
 lcm_grep(pattern: "config\\.threshold.*0\\.[0-9]+", scope: "summaries")
 
@@ -167,7 +173,7 @@ Add instructions to your agent's system prompt so it knows when to use LCM tools
 ## Memory & Context
 
 Use LCM tools for recall:
-1. `lcm_grep` — Search all conversations by keyword/regex
+1. `lcm_grep` — Search all conversations by keyword/regex. Prefer `mode: "full_text"` for topic recall, quote exact phrases, use `sort: "relevance"` for older-topic lookups, and `sort: "hybrid"` when recency should still matter.
 2. `lcm_describe` — Inspect a specific summary (cheap, no sub-agent)
 3. `lcm_expand_query` — Deep recall with sub-agent expansion
 

package/docs/configuration.md

@@ -1,272 +1,274 @@
-# Configuration guide
+# Configuration
 
-## Quick start
+Lossless-claw reads plugin configuration from `plugins.entries.lossless-claw.config`.
 
-Install the plugin with OpenClaw's plugin installer:
+Configuration precedence is:
 
-```bash
-openclaw plugins install @martian-engineering/lossless-claw
-```
+1. Environment variables
+2. `plugins.entries.lossless-claw.config`
+3. Built-in defaults from [`src/db/config.ts`](../src/db/config.ts)
 
-If you're running from a local OpenClaw checkout:
+Most installations only need to override a handful of keys. If you want a complete starting point, use the full example below and then delete entries you do not need.
 
-```bash
-pnpm openclaw plugins install @martian-engineering/lossless-claw
+## Complete `plugins.entries.lossless-claw.config` example
+
+```json
+{
+  "enabled": true,
+  "databasePath": "/Users/alice/.openclaw/lcm.db",
+  "ignoreSessionPatterns": [],
+  "statelessSessionPatterns": [],
+  "skipStatelessSessions": true,
+  "contextThreshold": 0.75,
+  "freshTailCount": 64,
+  "newSessionRetainDepth": 2,
+  "leafMinFanout": 8,
+  "condensedMinFanout": 4,
+  "condensedMinFanoutHard": 2,
+  "incrementalMaxDepth": 1,
+  "leafChunkTokens": 20000,
+  "bootstrapMaxTokens": 6000,
+  "leafTargetTokens": 2400,
+  "condensedTargetTokens": 2000,
+  "maxExpandTokens": 4000,
+  "largeFileThresholdTokens": 25000,
+  "summaryProvider": "",
+  "summaryModel": "",
+  "largeFileSummaryProvider": "",
+  "largeFileSummaryModel": "",
+  "expansionProvider": "",
+  "expansionModel": "",
+  "delegationTimeoutMs": 120000,
+  "summaryTimeoutMs": 60000,
+  "timezone": "America/Los_Angeles",
+  "pruneHeartbeatOk": false,
+  "maxAssemblyTokenBudget": 30000,
+  "summaryMaxOverageFactor": 3,
+  "customInstructions": "",
+  "circuitBreakerThreshold": 5,
+  "circuitBreakerCooldownMs": 1800000,
+  "fallbackProviders": [],
+  "cacheAwareCompaction": {
+    "enabled": true,
+    "maxColdCacheCatchupPasses": 2,
+    "hotCachePressureFactor": 4,
+    "hotCacheBudgetHeadroomRatio": 0.2
+  },
+  "dynamicLeafChunkTokens": {
+    "enabled": true,
+    "max": 40000
+  }
+}
 ```
 
-For local development of this plugin, link your working copy:
+Notes on the example:
 
-```bash
-openclaw plugins install --link /path/to/lossless-claw
-```
+- Values shown are the runtime defaults when a fixed default exists.
+- `databasePath` shows the expanded default path shape. Use an absolute path in config rather than `~`.
+- `timezone` has no fixed hardcoded default; at runtime it resolves from `TZ` first, then the system timezone. The example uses `America/Los_Angeles`.
+- `maxAssemblyTokenBudget` has no default. The example uses `30000` as a realistic cap for a 32k-class model.
+- `databasePath` is the preferred key. `dbPath` is an accepted alias.
+- `largeFileThresholdTokens` is the preferred key. `largeFileTokenThreshold` is an accepted alias.
 
-`openclaw plugins install` handles plugin registration/enabling and slot selection automatically.
+## Install and enable
 
-Set recommended environment variables:
+Install with OpenClaw's plugin installer:
 
 ```bash
-export LCM_FRESH_TAIL_COUNT=32
-export LCM_NEW_SESSION_RETAIN_DEPTH=2
-export LCM_INCREMENTAL_MAX_DEPTH=-1
+openclaw plugins install @martian-engineering/lossless-claw
 ```
 
-Restart OpenClaw.
-
-## Tuning guide
-
-### Context threshold
-
-`LCM_CONTEXT_THRESHOLD` (default `0.75`) controls when compaction triggers as a fraction of the model's context window.
-
-- **Lower values** (e.g., 0.5) trigger compaction earlier, keeping context smaller but doing more LLM calls for summarization.
-- **Higher values** (e.g., 0.85) let conversations grow longer before compacting, reducing summarization cost but risking overflow with large model responses.
-
-For most use cases, 0.75 is a good balance.
-
-### Fresh tail count
-
-`LCM_FRESH_TAIL_COUNT` (default `32`) is the number of most recent messages that are never compacted. These raw messages give the model immediate conversational continuity.
-
-- **Smaller values** (e.g., 8–16) save context space for summaries but may lose recent nuance.
-- **Larger values** (e.g., 32–64) give better continuity at the cost of a larger mandatory context floor.
-
-For coding conversations with tool calls (which generate many messages per logical turn), 32 is recommended.
-
-### /new retain depth
-
-`LCM_NEW_SESSION_RETAIN_DEPTH` (default `2`) controls what survives OpenClaw's `/new` command.
-
-- `-1` keeps all existing context items, making `/new` a transcript-only reset from lossless-claw's perspective.
-- `0` drops only fresh-tail message items and keeps all summaries.
-- `1` drops d0 summaries and keeps d1+.
-- `2` drops d0 and d1 summaries, keeping d2+ project-arc context. This is the recommended default.
-- `3+` keeps only deeper, more abstract summaries.
-
-`/new` never deletes the summaries themselves. It only prunes `context_items`, so the summary DAG remains available for later retrieval and expansion.
-
-### Leaf fanout
-
-`LCM_LEAF_MIN_FANOUT` (default `8`) is the minimum number of raw messages that must be available outside the fresh tail before a leaf pass runs.
-
-- Lower values create summaries more frequently (more, smaller summaries).
-- Higher values create larger, more comprehensive summaries less often.
-
-### Condensed fanout
-
-`LCM_CONDENSED_MIN_FANOUT` (default `4`) controls how many same-depth summaries accumulate before they're condensed into a higher-level summary.
-
-- Lower values create deeper DAGs with more levels of abstraction.
-- Higher values keep the DAG shallower but with more nodes at each level.
-
-### Incremental max depth
-
-`LCM_INCREMENTAL_MAX_DEPTH` (default `0`) controls whether condensation happens automatically after leaf passes.
-
-- **0** — Only leaf summaries are created incrementally. Condensation only happens during manual `/compact` or overflow.
-- **1** — After each leaf pass, attempt to condense d0 summaries into d1.
-- **2+** — Deeper automatic condensation up to the specified depth.
-- **-1** — Unlimited depth. Condensation cascades as deep as needed after each leaf pass. Recommended for long-running sessions.
-
-### Summary target tokens
-
-`LCM_LEAF_TARGET_TOKENS` (default `1200`) and `LCM_CONDENSED_TARGET_TOKENS` (default `2000`) control the target size of generated summaries.
-
-- Larger targets preserve more detail but consume more context space.
-- Smaller targets are more aggressive, losing detail faster.
-
-The actual summary size depends on the LLM's output; these values are guidelines passed in the prompt's token target instruction.
-
-### Leaf chunk tokens
-
-`LCM_LEAF_CHUNK_TOKENS` (default `20000`) caps the amount of source material per leaf compaction pass.
-
-- Larger chunks create more comprehensive summaries from more material.
-- Smaller chunks create summaries more frequently from less material.
-- This also affects the condensed minimum input threshold (10% of this value).
-
-### Maximum assembly token budget
-
-`LCM_MAX_ASSEMBLY_TOKEN_BUDGET` (default: none) caps the token budget used for context assembly and compaction threshold evaluation. When set, this takes precedence over both the 128k fallback and runtime-provided budgets.
-
-Set this if you're using a model with a smaller context window:
+If you are running from a local OpenClaw checkout:
 
-- **8k models:** `LCM_MAX_ASSEMBLY_TOKEN_BUDGET=7000`
-- **32k models:** `LCM_MAX_ASSEMBLY_TOKEN_BUDGET=30000`
-- **128k+ models:** No need to set (128k fallback is appropriate)
-
-### Summary size cap
-
-`LCM_SUMMARY_MAX_OVERAGE_FACTOR` (default: `3`) controls the hard ceiling on summary sizes relative to the target tokens (`leafTargetTokens` for leaf summaries, `condensedTargetTokens` for condensed summaries).
-
-If a summary exceeds `overage_factor * target_tokens`, it is deterministically truncated. A warning is logged when any summary exceeds `1.5 * target_tokens`.
-
-- **Lower values** (e.g., 2) enforce tighter summaries but may truncate more often with weaker summarizer models.
-- **Higher values** (e.g., 5) allow more LLM flexibility but risk storing oversized summaries.
-
-## Model selection
+```bash
+pnpm openclaw plugins install @martian-engineering/lossless-claw
+```
 
-LCM uses the same model as the parent OpenClaw session for summarization by default. You can override this:
+For local plugin development, link a working copy:
 
 ```bash
-# Use a specific model for summarization
-export LCM_SUMMARY_MODEL=anthropic/claude-sonnet-4-20250514
-export LCM_SUMMARY_PROVIDER=anthropic
-export LCM_SUMMARY_BASE_URL=https://api.anthropic.com
+openclaw plugins install --link /path/to/lossless-claw
 ```
 
-Using a cheaper/faster model for summarization can reduce costs, but quality matters — poor summaries compound as they're condensed into higher-level nodes.
+## Reference
+
+### Core storage and session behavior
+
+| Key | Type | Default | Env override | Purpose |
+| --- | --- | --- | --- | --- |
+| `enabled` | `boolean` | `true` | `LCM_ENABLED` | Enables or disables lossless-claw without uninstalling it. |
+| `databasePath` | `string` | `${HOME}/.openclaw/lcm.db` | `LCM_DATABASE_PATH` | Preferred path for the SQLite database. |
+| `dbPath` | `string` | alias of `databasePath` | `LCM_DATABASE_PATH` | Legacy alias for `databasePath`. Prefer `databasePath` in new config. |
+| `ignoreSessionPatterns` | `string[]` | `[]` | `LCM_IGNORE_SESSION_PATTERNS` | Session-key glob patterns that skip LCM entirely. |
+| `statelessSessionPatterns` | `string[]` | `[]` | `LCM_STATELESS_SESSION_PATTERNS` | Session-key glob patterns that may read from LCM but never write to it. |
+| `skipStatelessSessions` | `boolean` | `true` | `LCM_SKIP_STATELESS_SESSIONS` | Enforces `statelessSessionPatterns` when enabled. |
+| `newSessionRetainDepth` | `integer` | `2` | `LCM_NEW_SESSION_RETAIN_DEPTH` | Controls what survives `/new`. `-1` keeps all context, `0` keeps summaries only, higher values keep only deeper summaries. |
+| `timezone` | `string` | `TZ` or system timezone | `TZ` | IANA timezone used for timestamp rendering in summaries. |
+| `pruneHeartbeatOk` | `boolean` | `false` | `LCM_PRUNE_HEARTBEAT_OK` | Retroactively removes `HEARTBEAT_OK` turn cycles from persisted storage. |
 
-When more than one source is present, compaction summarization resolves in this order:
+### Compaction thresholds and summary sizing
 
-1. `LCM_SUMMARY_MODEL` / `LCM_SUMMARY_PROVIDER`
-2. Plugin config `summaryModel` / `summaryProvider`
-3. OpenClaw's default compaction model/provider
-4. Legacy per-call model/provider hints
+| Key | Type | Default | Env override | Purpose |
+| --- | --- | --- | --- | --- |
+| `contextThreshold` | `number` | `0.75` | `LCM_CONTEXT_THRESHOLD` | Fraction of the active model context window that triggers compaction. |
+| `freshTailCount` | `integer` | `64` | `LCM_FRESH_TAIL_COUNT` | Number of newest messages always kept raw. |
+| `leafMinFanout` | `integer` | `8` | `LCM_LEAF_MIN_FANOUT` | Minimum number of raw messages required before a leaf pass runs. |
+| `condensedMinFanout` | `integer` | `4` | `LCM_CONDENSED_MIN_FANOUT` | Number of same-depth summaries needed before condensation is attempted. |
+| `condensedMinFanoutHard` | `integer` | `2` | `LCM_CONDENSED_MIN_FANOUT_HARD` | Hard floor for condensation grouping during maintenance and repair flows. |
+| `incrementalMaxDepth` | `integer` | `1` | `LCM_INCREMENTAL_MAX_DEPTH` | Maximum automatic condensation depth after leaf compaction. Use `0` for leaf-only and `-1` for unlimited depth. |
+| `leafChunkTokens` | `integer` | `20000` | `LCM_LEAF_CHUNK_TOKENS` | Maximum source-token budget for a leaf compaction chunk. |
+| `bootstrapMaxTokens` | `integer` | `max(6000, floor(leafChunkTokens * 0.3))` | `LCM_BOOTSTRAP_MAX_TOKENS` | Maximum parent-history tokens imported when a new LCM conversation bootstraps. |
+| `leafTargetTokens` | `integer` | `2400` | `LCM_LEAF_TARGET_TOKENS` | Prompt target for leaf summary size. |
+| `condensedTargetTokens` | `integer` | `2000` | `LCM_CONDENSED_TARGET_TOKENS` | Prompt target for condensed summary size. |
+| `summaryMaxOverageFactor` | `number` | `3` | `LCM_SUMMARY_MAX_OVERAGE_FACTOR` | Hard ceiling multiplier before oversized summaries are deterministically truncated. |
+| `largeFileThresholdTokens` | `integer` | `25000` | `LCM_LARGE_FILE_TOKEN_THRESHOLD` | Preferred key for the token threshold that routes text attachments into large-file summarization. |
+| `largeFileTokenThreshold` | `integer` | alias of `largeFileThresholdTokens` | `LCM_LARGE_FILE_TOKEN_THRESHOLD` | Legacy alias accepted by the runtime. Prefer `largeFileThresholdTokens` in new config. |
+| `maxAssemblyTokenBudget` | `integer` | unset | `LCM_MAX_ASSEMBLY_TOKEN_BUDGET` | Optional hard cap for assembly and threshold evaluation, useful with smaller-context models. |
+| `maxExpandTokens` | `integer` | `4000` | `LCM_MAX_EXPAND_TOKENS` | Default token cap for `lcm_expand_query` responses. |
 
-If `summaryModel` already includes a provider prefix such as `anthropic/claude-sonnet-4-20250514`, `summaryProvider` is ignored for that choice.
+### Model selection, execution, and prompts
 
-For delegated `lcm_expand_query` runs, you can extend the sub-agent wait window with `delegationTimeoutMs` (plugin config) or `LCM_DELEGATION_TIMEOUT_MS` (environment variable). The default is `120000` milliseconds.
+| Key | Type | Default | Env override | Purpose |
+| --- | --- | --- | --- | --- |
+| `summaryModel` | `string` | `""` | `LCM_SUMMARY_MODEL` | Summarizer model override. Bare model names reuse the chosen provider; `provider/model` strings force a specific provider. |
+| `summaryProvider` | `string` | `""` | `LCM_SUMMARY_PROVIDER` | Provider hint used only when `summaryModel` is a bare model name. |
+| `largeFileSummaryModel` | `string` | `""` | `LCM_LARGE_FILE_SUMMARY_MODEL` | Large-file summarizer model override. |
+| `largeFileSummaryProvider` | `string` | `""` | `LCM_LARGE_FILE_SUMMARY_PROVIDER` | Large-file summarizer provider hint for bare model names. |
+| `expansionModel` | `string` | `""` | `LCM_EXPANSION_MODEL` | `lcm_expand_query` sub-agent model override. |
+| `expansionProvider` | `string` | `""` | `LCM_EXPANSION_PROVIDER` | `lcm_expand_query` sub-agent provider hint for bare model names. |
+| `delegationTimeoutMs` | `integer` | `120000` | `LCM_DELEGATION_TIMEOUT_MS` | Maximum time to wait for delegated expansion work. |
+| `summaryTimeoutMs` | `integer` | `60000` | `LCM_SUMMARY_TIMEOUT_MS` | Maximum time to wait for one model-backed summarizer call. |
+| `customInstructions` | `string` | `""` | `LCM_CUSTOM_INSTRUCTIONS` | Extra natural-language instructions injected into every summarization prompt. |
 
-## Session controls
+### Fallbacks, circuit breaking, and safety rails
 
-### Excluding sessions entirely
+| Key | Type | Default | Env override | Purpose |
+| --- | --- | --- | --- | --- |
+| `fallbackProviders` | `Array<{ provider: string; model: string }>` | `[]` | `LCM_FALLBACK_PROVIDERS` | Explicit provider/model fallback chain for compaction summarization. Format for env vars is `provider/model,provider/model`. |
+| `circuitBreakerThreshold` | `integer` | `5` | `LCM_CIRCUIT_BREAKER_THRESHOLD` | Consecutive auth failures before the summarization circuit breaker trips. |
+| `circuitBreakerCooldownMs` | `integer` | `1800000` | `LCM_CIRCUIT_BREAKER_COOLDOWN_MS` | Cooldown before the summarization circuit breaker resets automatically. |
 
-### `/new` vs `/reset`
+### Nested objects
 
-Lossless-claw treats the two OpenClaw reset commands differently:
+#### `cacheAwareCompaction`
 
-- `/new` keeps the active LCM conversation and prunes active context according to `newSessionRetainDepth`.
-- `/reset` archives the active conversation row and creates a fresh active row for the same stable `sessionKey`.
+| Key | Type | Default | Env override | Purpose |
+| --- | --- | --- | --- | --- |
+| `cacheAwareCompaction.enabled` | `boolean` | `true` | `LCM_CACHE_AWARE_COMPACTION_ENABLED` | Defers incremental leaf compaction more aggressively when prompt-cache telemetry indicates a hot cache. |
+| `cacheAwareCompaction.maxColdCacheCatchupPasses` | `integer` | `2` | `LCM_MAX_COLD_CACHE_CATCHUP_PASSES` | Maximum bounded catch-up passes allowed in one maintenance cycle when cache telemetry is cold. |
+| `cacheAwareCompaction.hotCachePressureFactor` | `number` | `4` | `LCM_HOT_CACHE_PRESSURE_FACTOR` | Multiplier applied to the hot-cache leaf trigger before raw-history pressure overrides cache preservation. |
+| `cacheAwareCompaction.hotCacheBudgetHeadroomRatio` | `number` | `0.2` | `LCM_HOT_CACHE_BUDGET_HEADROOM_RATIO` | Minimum fraction of the real token budget that must remain free before hot-cache incremental compaction is skipped entirely. |
 
-This preserves lossless history while still giving users a real clean-slate command.
-OpenClaw's command handlers still own the user-facing post-command disclosure text; lossless-claw applies only the underlying storage transition through `before_reset`.
+#### `dynamicLeafChunkTokens`
 
-Use `ignoreSessionPatterns` or `LCM_IGNORE_SESSION_PATTERNS` to keep low-value sessions completely out of LCM. Matching sessions do not create conversations, do not store messages, and do not participate in compaction or delegated expansion grants.
+| Key | Type | Default | Env override | Purpose |
+| --- | --- | --- | --- | --- |
+| `dynamicLeafChunkTokens.enabled` | `boolean` | `true` | `LCM_DYNAMIC_LEAF_CHUNK_TOKENS_ENABLED` | Enables dynamic working leaf chunk sizes for busier sessions. |
+| `dynamicLeafChunkTokens.max` | `integer` | `max(leafChunkTokens, floor(leafChunkTokens * 2))` | `LCM_DYNAMIC_LEAF_CHUNK_TOKENS_MAX` | Upper bound for the dynamic working chunk size. With the default `leafChunkTokens=20000`, this resolves to `40000`. |
 
-- Matching uses the full session key.
-- `*` matches any characters except `:`.
-- `**` matches anything, including `:`.
+### Cache-aware incremental compaction
 
-Example:
+When cache-aware compaction is enabled:
 
-```bash
-export LCM_IGNORE_SESSION_PATTERNS=agent:*:cron:**,agent:main:subagent:**
-```
+- hot cache stretches the incremental leaf trigger to `dynamicLeafChunkTokens.max`
+- hot cache skips incremental maintenance entirely when the assembled context is still comfortably below the real token budget
+- hot cache also gets a short hysteresis window so one ambiguous turn does not immediately discard a recently healthy cache signal
+- cold cache still allows bounded catch-up passes via `cacheAwareCompaction.maxColdCacheCatchupPasses`
 
-### Stateless sessions
+When incremental leaf compaction still runs on a hot cache, follow-on condensed passes are suppressed so the maintenance cycle only pays for the leaf pass that was explicitly justified.
 
-Use `statelessSessionPatterns` or `LCM_STATELESS_SESSION_PATTERNS` for sessions that should be able to read from LCM without writing to it. This is especially useful for sub-agent sessions, which use real OpenClaw keys like `agent:<agentId>:subagent:<uuid>`.
+## Behavior notes
 
-Enable enforcement with `skipStatelessSessions` or `LCM_SKIP_STATELESS_SESSIONS=true`.
+### Summary model resolution
 
-When a session key matches a stateless pattern and enforcement is enabled, LCM will:
+Compaction summarization resolves candidates in this order:
 
-- skip bootstrap imports
-- skip ingest and after-turn persistence
-- skip compaction writes
-- skip delegated expansion grant writes
-- still allow read-side assembly from existing persisted context
+1. `LCM_SUMMARY_MODEL` and `LCM_SUMMARY_PROVIDER`
+2. `plugins.entries.lossless-claw.config.summaryModel` and `summaryProvider`
+3. OpenClaw's default compaction model
+4. Legacy per-call provider and model hints
+5. `fallbackProviders`
 
-Example:
-
-```bash
-export LCM_STATELESS_SESSION_PATTERNS=agent:*:subagent:**,agent:ops:subagent:**
-export LCM_SKIP_STATELESS_SESSIONS=true
-```
+If `summaryModel` already contains a provider prefix such as `anthropic/claude-sonnet-4-20250514`, `summaryProvider` is ignored for that candidate.
+
+### Session pattern matching
+
+`ignoreSessionPatterns` and `statelessSessionPatterns` use full session keys.
+
+- `*` matches any characters except `:`
+- `**` matches anything, including `:`
 
-Plugin config example:
+Example:
 
 ```json
 {
-  "plugins": {
-    "entries": {
-      "lossless-claw": {
-        "config": {
-          "ignoreSessionPatterns": [
-            "agent:*:cron:**"
-          ],
-          "statelessSessionPatterns": [
-            "agent:*:subagent:**",
-            "agent:ops:subagent:**"
-          ],
-          "skipStatelessSessions": true
-        }
-      }
-    }
-  }
+  "ignoreSessionPatterns": [
+    "agent:*:cron:**"
+  ],
+  "statelessSessionPatterns": [
+    "agent:*:subagent:**",
+    "agent:ops:subagent:**"
+  ],
+  "skipStatelessSessions": true
 }
 ```
 
-## TUI conversation window size
+### `/new` and `/reset`
 
-`LCM_TUI_CONVERSATION_WINDOW_SIZE` (default `200`) controls how many messages `lcm-tui` loads per keyset-paged conversation window when a session has an LCM `conversation_id`.
+Lossless-claw treats OpenClaw reset commands differently:
 
-- Smaller values reduce render/query cost for very large conversations.
-- Larger values show more context per page but increase render time.
+- `/new` keeps the active LCM conversation and prunes active context according to `newSessionRetainDepth`
+- `/reset` archives the active conversation row and creates a fresh active row for the same stable `sessionKey`
 
-## Database management
+This keeps long-term history available while still giving users a real clean-slate reset.
 
-The SQLite database lives at `LCM_DATABASE_PATH` (default `~/.openclaw/lcm.db`). 
+## Environment-only knobs outside plugin config
 
-### Inspecting the database
+These settings are not part of `plugins.entries.lossless-claw.config`, but they still affect the system:
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `LCM_TUI_CONVERSATION_WINDOW_SIZE` | `200` | Number of messages `lcm-tui` loads per keyset-paged conversation window. |
+
+## Database operations
+
+The SQLite database lives at `databasePath` or `LCM_DATABASE_PATH`. The default path is `${HOME}/.openclaw/lcm.db`.
+
+Inspect it with:
 
 ```bash
 sqlite3 ~/.openclaw/lcm.db
 
-# Count conversations
 SELECT COUNT(*) FROM conversations;
-
-# See context items for a conversation
 SELECT * FROM context_items WHERE conversation_id = 1 ORDER BY ordinal;
-
-# Check summary depth distribution
 SELECT depth, COUNT(*) FROM summaries GROUP BY depth;
-
-# Find large summaries
 SELECT summary_id, depth, token_count FROM summaries ORDER BY token_count DESC LIMIT 10;
 ```
 
-### Backup
-
-The database is a single file. Back it up with:
+Back it up with:
 
 ```bash
 cp ~/.openclaw/lcm.db ~/.openclaw/lcm.db.backup
-```
-
-Or use SQLite's online backup:
-
-```bash
 sqlite3 ~/.openclaw/lcm.db ".backup ~/.openclaw/lcm.db.backup"
 ```
 
-## Per-agent configuration
+## Disabling lossless-claw
 
-In multi-agent OpenClaw setups, each agent uses the same LCM database but has its own conversations (keyed by session ID). The plugin config applies globally; per-agent overrides use environment variables set in the agent's config.
+To disable the plugin but keep it installed:
 
-## Disabling LCM
+```json
+{
+  "plugins": {
+    "entries": {
+      "lossless-claw": {
+        "enabled": false
+      }
+    }
+  }
+}
+```
 
-To fall back to OpenClaw's built-in compaction:
+To switch back to OpenClaw's legacy context engine instead:
 
 ```json
 {
@@ -277,5 +279,3 @@ To fall back to OpenClaw's built-in compaction:
   }
 }
 ```
-
-Or set `LCM_ENABLED=false` to disable the plugin while keeping it registered.