@martian-engineering/lossless-claw 0.2.8 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # lossless-claw
 
-Lossless Context Management plugin for [OpenClaw](https://github.com/openclaw/openclaw), based on the [LCM paper](https://papers.voltropy.com/LCM). Replaces OpenClaw's built-in sliding-window compaction with a DAG-based summarization system that preserves every message while keeping active context within model token limits.
+Lossless Context Management plugin for [OpenClaw](https://github.com/openclaw/openclaw), based on the [LCM paper](https://papers.voltropy.com/LCM) from [Voltropy](https://x.com/Voltropy). Replaces OpenClaw's built-in sliding-window compaction with a DAG-based summarization system that preserves every message while keeping active context within model token limits.
 
 ## Table of contents
 
@@ -94,7 +94,12 @@ Add a `lossless-claw` entry under `plugins.entries` in your OpenClaw config:
         "config": {
           "freshTailCount": 32,
           "contextThreshold": 0.75,
-          "incrementalMaxDepth": -1
+          "incrementalMaxDepth": -1,
+          "ignoreSessionPatterns": [
+            "agent:*:cron:**"
+          ],
+          "summaryProvider": "anthropic",
+          "summaryModel": "claude-3-5-haiku"
         }
       }
     }
@@ -102,12 +107,17 @@ Add a `lossless-claw` entry under `plugins.entries` in your OpenClaw config:
 }
 ```
 
+`summaryModel` and `summaryProvider` let you pin compaction summarization to a cheaper or faster model than your main OpenClaw session model. When unset, LCM uses OpenClaw's configured default model/provider.
+
 ### Environment variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `LCM_ENABLED` | `true` | Enable/disable the plugin |
 | `LCM_DATABASE_PATH` | `~/.openclaw/lcm.db` | Path to the SQLite database |
+| `LCM_IGNORE_SESSION_PATTERNS` | `""` | Comma-separated glob patterns for session keys to exclude from LCM storage |
+| `LCM_STATELESS_SESSION_PATTERNS` | `""` | Comma-separated glob patterns for session keys that may read from LCM but never write to it |
+| `LCM_SKIP_STATELESS_SESSIONS` | `true` | Enable stateless-session write skipping for matching session keys |
 | `LCM_CONTEXT_THRESHOLD` | `0.75` | Fraction of context window that triggers compaction (0.0–1.0) |
 | `LCM_FRESH_TAIL_COUNT` | `32` | Number of recent messages protected from compaction |
 | `LCM_LEAF_MIN_FANOUT` | `8` | Minimum raw messages per leaf summary |
@@ -121,11 +131,67 @@ Add a `lossless-claw` entry under `plugins.entries` in your OpenClaw config:
 | `LCM_LARGE_FILE_TOKEN_THRESHOLD` | `25000` | File blocks above this size are intercepted and stored separately |
 | `LCM_LARGE_FILE_SUMMARY_PROVIDER` | `""` | Provider override for large-file summarization |
 | `LCM_LARGE_FILE_SUMMARY_MODEL` | `""` | Model override for large-file summarization |
-| `LCM_SUMMARY_MODEL` | *(from OpenClaw)* | Model for summarization (e.g. `anthropic/claude-sonnet-4-20250514`) |
-| `LCM_SUMMARY_PROVIDER` | *(from OpenClaw)* | Provider override for summarization |
+| `LCM_SUMMARY_MODEL` | `""` | Model override for compaction summarization; falls back to OpenClaw's default model when unset |
+| `LCM_SUMMARY_PROVIDER` | `""` | Provider override for compaction summarization; falls back to `OPENCLAW_PROVIDER` or the provider embedded in the model ref |
+| `LCM_EXPANSION_MODEL` | *(from OpenClaw)* | Model override for `lcm_expand_query` sub-agent (e.g. `anthropic/claude-haiku-4-5`) |
+| `LCM_EXPANSION_PROVIDER` | *(from OpenClaw)* | Provider override for `lcm_expand_query` sub-agent |
 | `LCM_AUTOCOMPACT_DISABLED` | `false` | Disable automatic compaction after turns |
 | `LCM_PRUNE_HEARTBEAT_OK` | `false` | Retroactively delete `HEARTBEAT_OK` turn cycles from LCM storage |
 
+### Expansion model override requirements
+
+If you want `lcm_expand_query` to run on a dedicated model via `expansionModel` or `LCM_EXPANSION_MODEL`, OpenClaw must explicitly trust the plugin to request sub-agent model overrides.
+
+Add a `subagent` policy under `plugins.entries.lossless-claw` and allowlist the canonical `provider/model` target you want the plugin to use:
+
+```json
+{
+  "models": {
+    "openai/gpt-4.1-mini": {}
+  },
+  "plugins": {
+    "entries": {
+      "lossless-claw": {
+        "enabled": true,
+        "subagent": {
+          "allowModelOverride": true,
+          "allowedModels": ["openai/gpt-4.1-mini"]
+        },
+        "config": {
+          "expansionModel": "openai/gpt-4.1-mini"
+        }
+      }
+    }
+  }
+}
+```
+
+- `subagent.allowModelOverride` is required for OpenClaw to honor plugin-requested per-run `provider`/`model` overrides.
+- `subagent.allowedModels` is optional but recommended. Use `"*"` only if you intentionally want to trust any target model.
+- The chosen expansion target must also be available in OpenClaw's normal model catalog. If it is not already configured elsewhere, add it under the top-level `models` map as shown above.
+- If you prefer splitting provider and model, set `config.expansionProvider` and use a bare `config.expansionModel`.
+
+Plugin config equivalents:
+
+- `ignoreSessionPatterns`
+- `statelessSessionPatterns`
+- `skipStatelessSessions`
+- `summaryModel`
+- `summaryProvider`
+
+Environment variables still win over plugin config when both are set.
+
+### Summary model priority
+
+For compaction summarization, lossless-claw resolves the model in this order:
+
+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
+
+If `summaryModel` already includes a provider prefix such as `anthropic/claude-sonnet-4-20250514`, `summaryProvider` is ignored for that choice. Otherwise, the provider falls back to the matching override, then `OPENCLAW_PROVIDER`, then the provider inferred by the caller.
+
 ### Recommended starting configuration
 
 ```
@@ -138,6 +204,87 @@ LCM_CONTEXT_THRESHOLD=0.75
 - **incrementalMaxDepth=-1** enables unlimited automatic condensation after each compaction pass — the DAG cascades as deep as needed. Set to `0` (default) for leaf-only, or a positive integer for a specific depth cap.
 - **contextThreshold=0.75** triggers compaction when context reaches 75% of the model's window, leaving headroom for the model's response.
 
+### Session exclusion patterns
+
+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.
+
+Pattern rules:
+
+- `*` matches any characters except `:`
+- `**` matches anything, including `:`
+- Patterns match the full session key
+
+Examples:
+
+- `agent:*:cron:**` excludes cron sessions for any agent, including isolated run sessions like `agent:main:cron:daily-digest:run:run-123`
+- `agent:main:subagent:**` excludes all main-agent subagent sessions
+- `agent:ops:**` excludes every session under the `ops` agent id
+
+Environment variable example:
+
+```bash
+LCM_IGNORE_SESSION_PATTERNS=agent:*:cron:**,agent:main:subagent:**
+```
+
+Plugin config example:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "lossless-claw": {
+        "config": {
+          "ignoreSessionPatterns": [
+            "agent:*:cron:**",
+            "agent:main:subagent:**"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+### Stateless session patterns
+
+Use `statelessSessionPatterns` or `LCM_STATELESS_SESSION_PATTERNS` for sessions that should still be able to read from existing LCM context, but should never create or mutate LCM state themselves. This is useful for delegated or temporary sub-agent sessions that should benefit from retained context without polluting the database.
+
+When `skipStatelessSessions` or `LCM_SKIP_STATELESS_SESSIONS` is enabled, matching sessions:
+
+- skip bootstrap imports
+- skip message persistence during ingest and after-turn hooks
+- skip compaction writes and delegated expansion grant writes
+- can still assemble context from already-persisted conversations when a matching conversation exists
+
+Pattern rules are the same as `ignoreSessionPatterns`, and matching is done against the full session key.
+
+Environment variable example:
+
+```bash
+LCM_STATELESS_SESSION_PATTERNS=agent:*:subagent:**,agent:ops:subagent:**
+LCM_SKIP_STATELESS_SESSIONS=true
+```
+
+Plugin config example:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "lossless-claw": {
+        "config": {
+          "statelessSessionPatterns": [
+            "agent:*:subagent:**",
+            "agent:ops:subagent:**"
+          ],
+          "skipStatelessSessions": true
+        }
+      }
+    }
+  }
+}
+```
+
 ### OpenClaw session reset settings
 
 LCM preserves history through compaction, but it does **not** change OpenClaw's core session reset policy. If sessions are resetting sooner than you want, increase OpenClaw's `session.reset.idleMinutes` or use a channel/type-specific override.

package/docs/configuration.md

@@ -103,6 +103,75 @@ export LCM_SUMMARY_PROVIDER=anthropic
 
 Using a cheaper/faster model for summarization can reduce costs, but quality matters — poor summaries compound as they're condensed into higher-level nodes.
 
+When more than one source is present, compaction summarization resolves in this order:
+
+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
+
+If `summaryModel` already includes a provider prefix such as `anthropic/claude-sonnet-4-20250514`, `summaryProvider` is ignored for that choice.
+
+## Session controls
+
+### Excluding sessions entirely
+
+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.
+
+- Matching uses the full session key.
+- `*` matches any characters except `:`.
+- `**` matches anything, including `:`.
+
+Example:
+
+```bash
+export LCM_IGNORE_SESSION_PATTERNS=agent:*:cron:**,agent:main:subagent:**
+```
+
+### Stateless sessions
+
+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>`.
+
+Enable enforcement with `skipStatelessSessions` or `LCM_SKIP_STATELESS_SESSIONS=true`.
+
+When a session key matches a stateless pattern and enforcement is enabled, LCM will:
+
+- 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
+
+Example:
+
+```bash
+export LCM_STATELESS_SESSION_PATTERNS=agent:*:subagent:**,agent:ops:subagent:**
+export LCM_SKIP_STATELESS_SESSIONS=true
+```
+
+Plugin config example:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "lossless-claw": {
+        "config": {
+          "ignoreSessionPatterns": [
+            "agent:*:cron:**"
+          ],
+          "statelessSessionPatterns": [
+            "agent:*:subagent:**",
+            "agent:ops:subagent:**"
+          ],
+          "skipStatelessSessions": true
+        }
+      }
+    }
+  }
+}
+```
+
 ## TUI conversation window size
 
 `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`.