@martian-engineering/lossless-claw 0.9.0 → 0.9.2

package/docs/architecture.md

@@ -125,7 +125,7 @@ The assembler runs before each model turn and builds the message array:
 2. Resolve each item — summaries become user messages with XML wrappers; messages are reconstructed from parts.
 3. Split into evictable prefix and protected fresh tail (last `freshTailCount` raw messages).
 4. Compute fresh tail token cost (always included, even if over budget).
-5. Fill remaining budget from the evictable set, keeping newest items and dropping oldest.
+5. Fill remaining budget from the evictable set. By default this keeps newest older items and drops the oldest; when `promptAwareEviction` is enabled and a searchable prompt is present, the evictable prefix is ranked by prompt relevance first and then restored to chronological order.
 6. Normalize assistant content to array blocks (Anthropic API compatibility).
 7. Sanitize tool-use/result pairing (ensures every tool_result has a matching tool_use).
 

package/docs/configuration.md

@@ -23,6 +23,7 @@ Most installations only need to override a handful of keys. If you want a comple
   "contextThreshold": 0.75,
   "freshTailCount": 64,
   "freshTailMaxTokens": 24000,
+  "promptAwareEviction": false,
   "newSessionRetainDepth": 2,
   "leafMinFanout": 8,
   "condensedMinFanout": 4,
@@ -123,6 +124,7 @@ openclaw plugins install --link /path/to/lossless-claw
 | `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. |
 | `freshTailMaxTokens` | `integer` | unset | `LCM_FRESH_TAIL_MAX_TOKENS` | Optional token cap for the protected fresh tail. The newest message is always preserved even if it exceeds the cap. |
+| `promptAwareEviction` | `boolean` | `false` | `LCM_PROMPT_AWARE_EVICTION_ENABLED` | When enabled, budget-constrained assembly keeps older evictable items by prompt relevance instead of pure chronology. This improves retrieval under tight budgets, but it can reduce prompt-cache hit rates because the preserved prefix changes as prompts change. |
 | `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. |
@@ -190,6 +192,21 @@ When cache-aware compaction is enabled:
 
 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.
 
+### Prompt-aware eviction
+
+When `promptAwareEviction` is enabled:
+
+- the protected fresh tail is still preserved exactly as usual
+- only the older evictable prefix is affected
+- if the evictable prefix does not fit and the current prompt has searchable terms, lossless-claw keeps the most relevant older items instead of just the newest older items
+
+Tradeoff:
+
+- this can improve retrieval quality when the prompt is asking about an older topic and the assembled context is tight
+- it also makes the assembled prefix less stable for providers with prefix-based prompt caching, because different prompts can keep different older items
+
+If Anthropic prompt-cache stability matters more than topical recall under pressure, set `promptAwareEviction: false`.
+
 ## Behavior notes
 
 ### Summary model resolution

package/docs/tui.md

@@ -237,6 +237,32 @@ The confirmation screen shows:
 
 Each interactive operation also has a standalone CLI equivalent for scripting and batch operations.
 
+### `lcm-tui doctor`
+
+Scans for genuinely truncated summaries and can rewrite them in place. This is narrower than `repair`: it looks for specific truncation marker shapes instead of the generic fallback-summary marker.
+
+```bash
+# Preview repairs for one conversation
+lcm-tui doctor 44 --show-diff
+
+# Apply repairs with an OpenAI-compatible backend
+lcm-tui doctor 44 --apply --provider openai --model gpt-5.3-codex --base-url https://proxy.example.com/openai
+
+# Scan only across every conversation
+lcm-tui doctor --all
+```
+
+| Flag | Description |
+|------|-------------|
+| `--apply` | Write repaired summaries to the database |
+| `--summary` | Scan only and show counts |
+| `--all` | Scan all conversations (discovery mode only) |
+| `--provider <id>` | API provider (default: anthropic) |
+| `--model <model>` | API model (default: `claude-haiku-4-5`) |
+| `--base-url <url>` | Custom API base URL (overrides config and env) |
+| `--show-diff` | Show unified diff for each fix |
+| `--timestamps` | Inject timestamps into rewrite source text |
+
 ### `lcm-tui repair`
 
 Finds and fixes corrupted summaries (those containing the `[LCM fallback summary]` marker from failed summarization attempts).
@@ -253,6 +279,9 @@ lcm-tui repair 44 --apply
 
 # Repair a specific summary
 lcm-tui repair 44 --summary-id sum_abc123 --apply
+
+# Repair through an OpenAI-compatible backend
+lcm-tui repair 44 --apply --provider openai --model gpt-5.3-codex --base-url https://proxy.example.com/openai
 ```
 
 The repair process:
@@ -260,7 +289,7 @@ The repair process:
 2. Orders them bottom-up: leaves first (in context ordinal order), then condensed nodes by ascending depth
 3. Reconstructs source material from linked messages (leaves) or child summaries (condensed)
 4. Resolves `previous_context` for each node (for deduplication in the prompt)
-5. Sends to Anthropic API with the appropriate depth prompt
+5. Sends to the resolved provider API with the appropriate depth prompt
 6. Updates the database in a single transaction
 
 | Flag | Description |
@@ -268,6 +297,9 @@ The repair process:
 | `--apply` | Write repairs to database (default: dry run) |
 | `--all` | Scan all conversations |
 | `--summary-id <id>` | Target a specific summary |
+| `--provider <id>` | API provider (inferred from `--model` when omitted) |
+| `--model <model>` | API model (default depends on provider) |
+| `--base-url <url>` | Custom API base URL (overrides config and env) |
 | `--verbose` | Show content hashes and previews |
 
 ### `lcm-tui rewrite`
@@ -484,14 +516,15 @@ Resolution order:
 
 If the provider auth profile mode is `oauth` (not `api_key`), set the provider API key environment variable explicitly.
 
-Interactive rewrite (`w`/`W`) can be configured with:
+Summary-producing operations (`doctor`, `repair`, `rewrite`, `backfill`, and interactive rewrite `w`/`W`) can be configured with:
 - `LCM_TUI_SUMMARY_PROVIDER`
 - `LCM_TUI_SUMMARY_MODEL`
 - `LCM_TUI_SUMMARY_BASE_URL`
-- `LCM_TUI_CONVERSATION_WINDOW_SIZE` (default `200`)
 
 It also honors `LCM_SUMMARY_PROVIDER` / `LCM_SUMMARY_MODEL` / `LCM_SUMMARY_BASE_URL` as fallback.
 
+Separately, the conversation browser window size uses `LCM_TUI_CONVERSATION_WINDOW_SIZE` (default `200`).
+
 ## Database
 
 The TUI operates directly on the SQLite database at `~/.openclaw/lcm.db`. All write operations (rewrite, dissolve, repair, transplant, backfill) use transactions. Changes take effect on the next conversation turn — the running OpenClaw instance picks up database changes automatically.

package/openclaw.plugin.json

@@ -25,6 +25,10 @@
       "label": "Fresh Tail Max Tokens",
       "help": "Optional token cap for the protected fresh tail; the newest message is always preserved"
     },
+    "promptAwareEviction": {
+      "label": "Prompt-Aware Eviction",
+      "help": "When enabled, budget-constrained assembly keeps older context by prompt relevance instead of pure chronology. This can improve recall under tight budgets, but it can also reduce provider prompt-cache hit rates because the preserved prefix changes as prompts change."
+    },
     "leafChunkTokens": {
       "label": "Leaf Chunk Tokens",
       "help": "Maximum source tokens per leaf compaction chunk before summarization"
@@ -226,6 +230,9 @@
         "type": "integer",
         "minimum": 0
       },
+      "promptAwareEviction": {
+        "type": "boolean"
+      },
       "leafChunkTokens": {
         "type": "integer",
         "minimum": 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martian-engineering/lossless-claw",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Lossless Context Management plugin for OpenClaw — DAG-based conversation summarization with incremental compaction",
   "type": "module",
   "main": "dist/index.js",
@@ -31,8 +31,9 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@mariozechner/pi-agent-core": "*",
-    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-agent-core": "0.66.1",
+    "@mariozechner/pi-ai": "0.66.1",
+    "@mariozechner/pi-coding-agent": "0.66.1",
     "@sinclair/typebox": "0.34.48"
   },
   "devDependencies": {

package/skills/lossless-claw/references/config.md

@@ -57,6 +57,21 @@ Good starting range:
 - Leave unset unless large tool outputs are forcing avoidable cost or overflow.
 - Start around `12000` to `32000` when you want a softer, size-aware fresh tail.
 
+### `promptAwareEviction`
+
+Controls whether budget-constrained assembly keeps older context by prompt relevance or pure chronology.
+
+Why it matters:
+
+- when enabled, lossless-claw can keep an older but on-topic summary instead of a newer irrelevant one
+- this can improve retrieval quality when the assembled context is tight
+- it also makes the preserved prompt prefix less stable, which can reduce prefix-based prompt-cache hit rates
+
+Good default:
+
+- `false`
+- enable it only when topical older-context recall under tight budgets matters more than prompt-cache stability
+
 ### `leafChunkTokens`
 
 Caps how much raw material gets summarized into one leaf summary.
@@ -232,6 +247,21 @@ See high-impact settings above.
 
 See high-impact settings above.
 
+### `promptAwareEviction`
+
+Boolean toggle for prompt-sensitive selection inside the evictable prefix during assembly.
+
+Why it matters:
+
+- only applies when the older evictable prefix does not fit the token budget
+- the protected fresh tail is unaffected
+- `true` keeps the most relevant older items for the current prompt
+- `false` falls back to pure chronological retention for the older prefix
+
+Env override:
+
+- `LCM_PROMPT_AWARE_EVICTION_ENABLED`
+
 ### `leafChunkTokens`
 
 See high-impact settings above.