@martian-engineering/lossless-claw 0.2.0 → 0.2.2

package/README.md

@@ -1,11 +1,11 @@
 # lossless-claw
 
-> ⚠️ **Current requirement:** This plugin currently requires a custom OpenClaw build with [PR #22201](https://github.com/openclaw/openclaw/pull/22201) applied until that PR is merged upstream.
-
-Lossless Context Management plugin for [OpenClaw](https://github.com/openclaw/openclaw), based on the [LCM paper](https://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). 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.
 
 ## What it does
 
+Two ways to learn: read the below, or [check out this super cool animated visualization](https://losslesscontext.ai).
+
 When a conversation grows beyond the model's context window, OpenClaw (just like all of the other agents) normally truncates older messages. LCM instead:
 
 1. **Persists every message** in a SQLite database, organized by conversation
@@ -74,17 +74,19 @@ LCM is configured through a combination of plugin config and environment variabl
 
 ### Plugin config
 
-Add an `lossless-claw` block under `plugins.config` in your OpenClaw config:
+Add a `lossless-claw` entry under `plugins.entries` in your OpenClaw config:
 
 ```json
 {
   "plugins": {
-    "config": {
+    "entries": {
       "lossless-claw": {
         "enabled": true,
-        "freshTailCount": 32,
-        "contextThreshold": 0.75,
-        "incrementalMaxDepth": 1
+        "config": {
+          "freshTailCount": 32,
+          "contextThreshold": 0.75,
+          "incrementalMaxDepth": -1
+        }
       }
     }
   }
@@ -102,7 +104,7 @@ Add an `lossless-claw` block under `plugins.config` in your OpenClaw config:
 | `LCM_LEAF_MIN_FANOUT` | `8` | Minimum raw messages per leaf summary |
 | `LCM_CONDENSED_MIN_FANOUT` | `4` | Minimum summaries per condensed node |
 | `LCM_CONDENSED_MIN_FANOUT_HARD` | `2` | Relaxed fanout for forced compaction sweeps |
-| `LCM_INCREMENTAL_MAX_DEPTH` | `0` | How deep incremental compaction goes (0 = leaf only) |
+| `LCM_INCREMENTAL_MAX_DEPTH` | `0` | How deep incremental compaction goes (0 = leaf only, -1 = unlimited) |
 | `LCM_LEAF_CHUNK_TOKENS` | `20000` | Max source tokens per leaf compaction chunk |
 | `LCM_LEAF_TARGET_TOKENS` | `1200` | Target token count for leaf summaries |
 | `LCM_CONDENSED_TARGET_TOKENS` | `2000` | Target token count for condensed summaries |
@@ -110,18 +112,18 @@ Add an `lossless-claw` block under `plugins.config` in your OpenClaw config:
 | `LCM_LARGE_FILE_TOKEN_THRESHOLD` | `25000` | File blocks above this size are intercepted and stored separately |
 | `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_INCREMENTAL_MAX_DEPTH` | `0` | Depth limit for incremental condensation after leaf passes |
+| `LCM_INCREMENTAL_MAX_DEPTH` | `0` | Depth limit for incremental condensation after leaf passes (-1 = unlimited) |
 
 ### Recommended starting configuration
 
 ```
 LCM_FRESH_TAIL_COUNT=32
-LCM_INCREMENTAL_MAX_DEPTH=1
+LCM_INCREMENTAL_MAX_DEPTH=-1
 LCM_CONTEXT_THRESHOLD=0.75
 ```
 
 - **freshTailCount=32** protects the last 32 messages from compaction, giving the model enough recent context for continuity.
-- **incrementalMaxDepth=1** enables automatic condensation of leaf summaries after each compaction pass (without this, only leaf summaries are created and condensation only happens during manual `/compact` or overflow).
+- **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.
 
 ## How it works
@@ -171,7 +173,7 @@ This gives the model enough information to know what was discussed, when, and ho
 
 Compaction runs in two modes:
 
-- **Proactive (after each turn):** If raw messages outside the fresh tail exceed `leafChunkTokens`, a leaf pass runs. If `incrementalMaxDepth > 0`, condensation follows.
+- **Proactive (after each turn):** If raw messages outside the fresh tail exceed `leafChunkTokens`, a leaf pass runs. If `incrementalMaxDepth != 0`, condensation follows (cascading to the configured depth, or unlimited with `-1`).
 - **Reactive (overflow/manual):** When total context exceeds `contextThreshold × tokenBudget`, a full sweep runs: all eligible leaf chunks are compacted, then condensation proceeds depth-by-depth until stable.
 
 ### Depth-aware prompts

package/docs/architecture.md

@@ -87,7 +87,7 @@ The **condensed pass** merges summaries at the same depth into a higher-level su
 **Incremental (after each turn):**
 - Checks if raw tokens outside the fresh tail exceed `leafChunkTokens`
 - If so, runs one leaf pass
-- If `incrementalMaxDepth > 0`, follows with condensation passes up to that depth
+- If `incrementalMaxDepth != 0`, follows with condensation passes up to that depth (`-1` for unlimited)
 - Best-effort: failures don't break the conversation
 
 **Full sweep (manual `/compact` or overflow):**

package/docs/configuration.md

@@ -26,7 +26,7 @@ Set recommended environment variables:
 
 ```bash
 export LCM_FRESH_TAIL_COUNT=32
-export LCM_INCREMENTAL_MAX_DEPTH=1
+export LCM_INCREMENTAL_MAX_DEPTH=-1
 ```
 
 Restart OpenClaw.
@@ -70,8 +70,9 @@ For coding conversations with tool calls (which generate many messages per logic
 `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. Good default for active conversations.
-- **2+** — Deeper automatic condensation. Rarely needed; the full sweep handles this during 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
 

package/index.ts

@@ -597,7 +597,7 @@ function readLatestAssistantReply(messages: unknown[]): string | undefined {
 function createLcmDependencies(api: OpenClawPluginApi): LcmDependencies {
   const envSnapshot = snapshotPluginEnv();
   const readEnv: ReadEnvFn = (key) => process.env[key];
-  const config = resolveLcmConfig();
+  const config = resolveLcmConfig(process.env, _parsedPluginConfig);
 
   return {
     config,
@@ -854,6 +854,9 @@ function createLcmDependencies(api: OpenClawPluginApi): LcmDependencies {
   };
 }
 
+/** Cached config from configSchema.parse — available by the time register() runs. */
+let _parsedPluginConfig: Record<string, unknown> | undefined;
+
 const lcmPlugin = {
   id: "lossless-claw",
   name: "Lossless Context Management",
@@ -862,17 +865,12 @@ const lcmPlugin = {
 
   configSchema: {
     parse(value: unknown) {
-      // Merge plugin config with env vars — env vars take precedence for backward compat
       const raw =
         value && typeof value === "object" && !Array.isArray(value)
           ? (value as Record<string, unknown>)
           : {};
-      const enabled = typeof raw.enabled === "boolean" ? raw.enabled : undefined;
-      const config = resolveLcmConfig();
-      if (enabled !== undefined) {
-        config.enabled = enabled;
-      }
-      return config;
+      _parsedPluginConfig = raw;
+      return resolveLcmConfig(process.env, raw);
     },
   },
 

package/openclaw.plugin.json

@@ -7,7 +7,7 @@
     },
     "incrementalMaxDepth": {
       "label": "Incremental Max Depth",
-      "help": "How deep incremental compaction goes (0 = leaf only)"
+      "help": "How deep incremental compaction goes (0 = leaf only, -1 = unlimited)"
     },
     "freshTailCount": {
       "label": "Fresh Tail Count",
@@ -32,7 +32,7 @@
       },
       "incrementalMaxDepth": {
         "type": "integer",
-        "minimum": 0
+        "minimum": -1
       },
       "freshTailCount": {
         "type": "integer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martian-engineering/lossless-claw",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Lossless Context Management plugin for OpenClaw — DAG-based conversation summarization with incremental compaction",
   "type": "module",
   "main": "index.ts",

package/src/compaction.ts

@@ -795,14 +795,13 @@ export class CompactionEngine {
   private resolveIncrementalMaxDepth(): number {
     if (
       typeof this.config.incrementalMaxDepth === "number" &&
-      Number.isFinite(this.config.incrementalMaxDepth) &&
-      this.config.incrementalMaxDepth > 0
+      Number.isFinite(this.config.incrementalMaxDepth)
     ) {
-      return Math.floor(this.config.incrementalMaxDepth);
+      if (this.config.incrementalMaxDepth < 0) return Infinity;
+      if (this.config.incrementalMaxDepth > 0) return Math.floor(this.config.incrementalMaxDepth);
     }
     return 0;
   }
-
   private resolveFanoutForDepth(targetDepth: number, hardTrigger: boolean): number {
     if (hardTrigger) {
       return this.resolveCondensedMinFanoutHard();

package/src/db/config.ts

@@ -26,25 +26,97 @@ export type LcmConfig = {
   pruneHeartbeatOk: boolean;
 };
 
-export function resolveLcmConfig(env: NodeJS.ProcessEnv = process.env): LcmConfig {
+/** Safely coerce an unknown value to a finite number, or return undefined. */
+function toNumber(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const n = Number(value);
+    if (Number.isFinite(n)) return n;
+  }
+  return undefined;
+}
+
+/** Safely coerce an unknown value to a boolean, or return undefined. */
+function toBool(value: unknown): boolean | undefined {
+  if (typeof value === "boolean") return value;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  return undefined;
+}
+
+/** Safely coerce an unknown value to a trimmed non-empty string, or return undefined. */
+function toStr(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve LCM configuration with three-tier precedence:
+ *   1. Environment variables (highest — backward compat)
+ *   2. Plugin config object (from plugins.entries.lossless-claw.config)
+ *   3. Hardcoded defaults (lowest)
+ */
+export function resolveLcmConfig(
+  env: NodeJS.ProcessEnv = process.env,
+  pluginConfig?: Record<string, unknown>,
+): LcmConfig {
+  const pc = pluginConfig ?? {};
+
   return {
-    enabled: env.LCM_ENABLED !== "false",
-    databasePath: env.LCM_DATABASE_PATH ?? join(homedir(), ".openclaw", "lcm.db"),
-    contextThreshold: parseFloat(env.LCM_CONTEXT_THRESHOLD ?? "0.75"),
-    freshTailCount: parseInt(env.LCM_FRESH_TAIL_COUNT ?? "32", 10),
-    leafMinFanout: parseInt(env.LCM_LEAF_MIN_FANOUT ?? "8", 10),
-    condensedMinFanout: parseInt(env.LCM_CONDENSED_MIN_FANOUT ?? "4", 10),
-    condensedMinFanoutHard: parseInt(env.LCM_CONDENSED_MIN_FANOUT_HARD ?? "2", 10),
-    incrementalMaxDepth: parseInt(env.LCM_INCREMENTAL_MAX_DEPTH ?? "0", 10),
-    leafChunkTokens: parseInt(env.LCM_LEAF_CHUNK_TOKENS ?? "20000", 10),
-    leafTargetTokens: parseInt(env.LCM_LEAF_TARGET_TOKENS ?? "1200", 10),
-    condensedTargetTokens: parseInt(env.LCM_CONDENSED_TARGET_TOKENS ?? "2000", 10),
-    maxExpandTokens: parseInt(env.LCM_MAX_EXPAND_TOKENS ?? "4000", 10),
-    largeFileTokenThreshold: parseInt(env.LCM_LARGE_FILE_TOKEN_THRESHOLD ?? "25000", 10),
-    largeFileSummaryProvider: env.LCM_LARGE_FILE_SUMMARY_PROVIDER?.trim() ?? "",
-    largeFileSummaryModel: env.LCM_LARGE_FILE_SUMMARY_MODEL?.trim() ?? "",
-    autocompactDisabled: env.LCM_AUTOCOMPACT_DISABLED === "true",
-    timezone: env.TZ ?? Intl.DateTimeFormat().resolvedOptions().timeZone,
-    pruneHeartbeatOk: env.LCM_PRUNE_HEARTBEAT_OK === "true",
+    enabled:
+      env.LCM_ENABLED !== undefined
+        ? env.LCM_ENABLED !== "false"
+        : toBool(pc.enabled) ?? true,
+    databasePath:
+      env.LCM_DATABASE_PATH ?? toStr(pc.databasePath) ?? join(homedir(), ".openclaw", "lcm.db"),
+    contextThreshold:
+      (env.LCM_CONTEXT_THRESHOLD !== undefined ? parseFloat(env.LCM_CONTEXT_THRESHOLD) : undefined)
+        ?? toNumber(pc.contextThreshold) ?? 0.75,
+    freshTailCount:
+      (env.LCM_FRESH_TAIL_COUNT !== undefined ? parseInt(env.LCM_FRESH_TAIL_COUNT, 10) : undefined)
+        ?? toNumber(pc.freshTailCount) ?? 32,
+    leafMinFanout:
+      (env.LCM_LEAF_MIN_FANOUT !== undefined ? parseInt(env.LCM_LEAF_MIN_FANOUT, 10) : undefined)
+        ?? toNumber(pc.leafMinFanout) ?? 8,
+    condensedMinFanout:
+      (env.LCM_CONDENSED_MIN_FANOUT !== undefined ? parseInt(env.LCM_CONDENSED_MIN_FANOUT, 10) : undefined)
+        ?? toNumber(pc.condensedMinFanout) ?? 4,
+    condensedMinFanoutHard:
+      (env.LCM_CONDENSED_MIN_FANOUT_HARD !== undefined ? parseInt(env.LCM_CONDENSED_MIN_FANOUT_HARD, 10) : undefined)
+        ?? toNumber(pc.condensedMinFanoutHard) ?? 2,
+    incrementalMaxDepth:
+      (env.LCM_INCREMENTAL_MAX_DEPTH !== undefined ? parseInt(env.LCM_INCREMENTAL_MAX_DEPTH, 10) : undefined)
+        ?? toNumber(pc.incrementalMaxDepth) ?? 0,
+    leafChunkTokens:
+      (env.LCM_LEAF_CHUNK_TOKENS !== undefined ? parseInt(env.LCM_LEAF_CHUNK_TOKENS, 10) : undefined)
+        ?? toNumber(pc.leafChunkTokens) ?? 20000,
+    leafTargetTokens:
+      (env.LCM_LEAF_TARGET_TOKENS !== undefined ? parseInt(env.LCM_LEAF_TARGET_TOKENS, 10) : undefined)
+        ?? toNumber(pc.leafTargetTokens) ?? 1200,
+    condensedTargetTokens:
+      (env.LCM_CONDENSED_TARGET_TOKENS !== undefined ? parseInt(env.LCM_CONDENSED_TARGET_TOKENS, 10) : undefined)
+        ?? toNumber(pc.condensedTargetTokens) ?? 2000,
+    maxExpandTokens:
+      (env.LCM_MAX_EXPAND_TOKENS !== undefined ? parseInt(env.LCM_MAX_EXPAND_TOKENS, 10) : undefined)
+        ?? toNumber(pc.maxExpandTokens) ?? 4000,
+    largeFileTokenThreshold:
+      (env.LCM_LARGE_FILE_TOKEN_THRESHOLD !== undefined ? parseInt(env.LCM_LARGE_FILE_TOKEN_THRESHOLD, 10) : undefined)
+        ?? toNumber(pc.largeFileTokenThreshold) ?? 25000,
+    largeFileSummaryProvider:
+      env.LCM_LARGE_FILE_SUMMARY_PROVIDER?.trim() ?? toStr(pc.largeFileSummaryProvider) ?? "",
+    largeFileSummaryModel:
+      env.LCM_LARGE_FILE_SUMMARY_MODEL?.trim() ?? toStr(pc.largeFileSummaryModel) ?? "",
+    autocompactDisabled:
+      env.LCM_AUTOCOMPACT_DISABLED !== undefined
+        ? env.LCM_AUTOCOMPACT_DISABLED === "true"
+        : toBool(pc.autocompactDisabled) ?? false,
+    timezone: env.TZ ?? toStr(pc.timezone) ?? Intl.DateTimeFormat().resolvedOptions().timeZone,
+    pruneHeartbeatOk:
+      env.LCM_PRUNE_HEARTBEAT_OK !== undefined
+        ? env.LCM_PRUNE_HEARTBEAT_OK === "true"
+        : toBool(pc.pruneHeartbeatOk) ?? false,
   };
 }

package/src/summarize.ts

@@ -1,4 +1,3 @@
-import { resolveLcmConfig } from "./db/config.js";
 import type { LcmDependencies } from "./types.js";
 
 export type LcmSummarizeOptions = {
@@ -675,11 +674,10 @@ export async function createLcmSummarizeFromLegacyParams(params: {
 
   const apiKey = params.deps.getApiKey(provider, model);
 
-  const runtimeLcmConfig = resolveLcmConfig();
   const condensedTargetTokens =
-    Number.isFinite(runtimeLcmConfig.condensedTargetTokens) &&
-    runtimeLcmConfig.condensedTargetTokens > 0
-      ? runtimeLcmConfig.condensedTargetTokens
+    Number.isFinite(params.deps.config.condensedTargetTokens) &&
+    params.deps.config.condensedTargetTokens > 0
+      ? params.deps.config.condensedTargetTokens
       : DEFAULT_CONDENSED_TARGET_TOKENS;
 
   return async (