Skip to content
Back to search

lossless-claw

Lossless Claw — LCM (Lossless Context Management) plugin for OpenClaw

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/martian-engineering/lossless-claw with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/martian-engineering/lossless-claw'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/martian-engineering--lossless-claw/badge.svg)](/listings/martian-engineering--lossless-claw)

HTML

<a href="/listings/martian-engineering--lossless-claw"><img src="/api/listings/martian-engineering--lossless-claw/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- OpenClaw with plugin context engine support - Node.js 22+ - An LLM provider configured in OpenClaw (used for summarization)

> **Compatibility:** `lossless-claw` requires OpenClaw `2026.9.2` or newer, the first stable release with native plugin session panels. The Context explorer requires **Settings → Labs → Custom plugin UI**. If you cannot upgrade, keep your earlier compatible Lossless release and use `lcm-tui` to inspect context. See [Context explorer](docs/context-explorer.md).

On OpenClaw hosts that advertise the durable context-engine turn contract, LosslessClaw declares current-turn transcript fencing and commits each accepted turn through an atomic idempotency ledger. Older supported hosts continue to use the existing `afterTurn` compatibility path.

> **Upgrade compatibility:** Lossless Claw 1.x accepts `transcriptGcEnabled` and `autoRotateSessionFiles` so 0.15 configs continue to load. It ignores both settings and warns at startup. Remove them after upgrading; OpenClaw owns active transcript storage and session-file rotation.

Install the plugin

Lossless Claw 1.0 stable releases use npm's `latest` channel. The `beta` channel remains available for prerelease testing.

Use OpenClaw's plugin installer (recommended):

openclaw plugins install @martian-engineering/lossless-claw@latest

If you're running from a local OpenClaw checkout, use:

pnpm openclaw plugins install @martian-engineering/lossless-claw@latest

Use exact versions only for rollback or reproducible canary testing. OpenClaw records an exact install spec such as `@martian-engineering/lossless-claw@0.12.0` as a pinned update track, so OpenClaw plugin update sync will keep that version until you move back to the stable track:

openclaw plugins update @martian-engineering/lossless-claw@latest

For local plugin development, build your working copy first, then link it instead of copying files:

cd /path/to/lossless-claw
pnpm build

openclaw plugins install --link /path/to/lossless-claw
# or from a local OpenClaw checkout:
# pnpm openclaw plugins install --link /path/to/lossless-claw

Re-run `pnpm build` after local source changes so the linked plugin's `dist/` output stays current.

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`, 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

Ensure the context engine slot points at lossless-claw and explicitly allow its conversation prompt hook:

{
  "plugins": {
    "slots": {
      "contextEngine": "lossless-claw"
    },
    "entries": {
      "lossless-claw": {
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  }
}

OpenClaw builds that protect `before_prompt_build` as a conversation-access hook require this grant. Without it, the context engine still loads, but OpenClaw blocks Lossless's static recall-policy prompt hook and logs the missing setting. The grant belongs beside `config`, not inside it.

Restart OpenClaw after configuration changes.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 649 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # lossless-claw
  2. 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.
  3. Built and maintained by **[Martian Engineering](https://martian.engineering/?utm_source=github&utm_medium=readme&utm_campaign=lossless-claw)**. Need help with agents, memory, or AI in your own stack? [Get in touch](#about-martian-engineering).
  4. ## Table of contents
  5. - [What it does](#what-it-does)
  6. - [Quick start](#quick-start)
  7. - [Configuration](#configuration)
  8. - [Commands And Skill](#commands-and-skill)
  9. - [Session Migration CLI](#session-migration-cli)
  10. - [Documentation](#documentation)
  11. - [Development](#development)
  12. - [Line endings](#line-endings)
  13. - [Security](#security)
  14. - [License](#license)
  15. - [About Martian Engineering](#about-martian-engineering)
  16. ## What it does
  17. Two ways to learn: read the below, or [check out this super cool animated visualization](https://losslesscontext.ai).
  18. When a conversation grows beyond the model's context window, OpenClaw (just like all of the other agents) normally truncates older messages. LCM instead:
  19. 1. **Persists every message** in a SQLite database, organized by conversation
  20. 2. **Summarizes chunks** of older messages into summaries using your configured LLM
  21. 3. **Condenses summaries** into higher-level nodes as they accumulate, forming a DAG (directed acyclic graph)
  22. 4. **Assembles context** each turn by combining summaries + recent raw messages
  23. 5. **Provides tools** (`lcm_grep`, `lcm_describe`, `lcm_expand`) so agents can search and recall details from compacted history
  24. Nothing is lost. Raw messages stay in the database. Summaries link back to their source messages. Agents can drill into any summary to recover the original detail.
  25. **It feels like talking to an agent that never forgets. Because it doesn't. In normal operation, you'll never need to think about compaction again.**
  26. ## Commands And Skill
  27. The package installs an agent-oriented `lcm` shell CLI and includes a bundled `lossless-claw` skill plus plugin commands for supported OpenClaw chat/native command providers.
  28. The shell CLI reads `lcm.db` without modifying conversation data. Its only write command sets one validated Lossless config value in `openclaw.json`:
  29. ```bash
  30. lcm status
  31. lcm conversations show --session-key 'agent:main:example'
  32. lcm messages tail --conversation-id 42
  33. lcm summaries list --conversation-id 42 --depth 0 --recency 7d
  34. lcm config get freshTailCount
  35. lcm config set freshTailCount 96
  36. ```
  37. JSON is the default output. List commands use bounded keyset pagination. See [Lossless Claw CLI](docs/cli.md) for commands, filters, path precedence, output fields, config-write safety, and exit codes.
  38. The native OpenClaw command surface provides in-session operations:
  39. - `/lossless` shows version, enablement/selection state, DB path and size, summary counts, and summary-health status
  40. - `/lossless backup` creates a timestamped backup of the current LCM SQLite database
  41. - `/lossless doctor` scans for broken or truncated summaries
  42. - `/lossless doctor maintenance` reports active actionable compaction debt separately from inactive historical debt, grouped by reason, without writing
  43. - `/lossless doctor apply maintenance <conversation-id> confirm-inactive` administratively closes one eligible inactive debt row after creating a SQLite backup
  44. - `/lossless doctor apply` repairs broken summaries in the current conversation after the normal safety preflight
  45. - `/lossless doctor apply <conversation-id> confirm-offline` repairs a specific conversation after its active channel path has been paused or moved away; targeted repair is restricted to authorized OpenClaw command senders and always requires the explicit offline confirmation
  46. - `/lossless doctor clean` shows read-only high-confidence junk diagnostics for archived subagents and cron sessions under every configured OpenClaw agent id, plus NULL-key orphaned subagent runs
  47. - `/lossless status` shows plugin, conversation, and maintenance state including deferred compaction debt
  48. - `/lcm` is the shorter alias for `/lossless`
  49. Supported native command examples:
  50. - `/lossless`
  51. - `/lossless backup`
  52. - `/lossless doctor`
  53. - `/lossless doctor maintenance`
  54. - `/lossless doctor apply maintenance 42 confirm-inactive`
  55. - `/lossless doctor apply 42 confirm-offline`
  56. - `/lossless doctor clean`
  57. - `/lcm`
  58. The package does not register these OpenClaw root subcommands:
  59. - `openclaw lossless`
  60. - `openclaw lcm`
  61. - `openclaw /lossless`
  62. - `openclaw /lcm`
  63. The bundled skill focuses on configuration, diagnostics, architecture, and recall-tool usage. Its reference set lives under `skills/lossless-claw/references/`.
  64. Deferred compaction debt on an active conversation is actionable maintenance pressure. Debt on an archived or otherwise inactive conversation is historical: normal stable-session maintenance cannot select that conversation, so `/lossless doctor maintenance` reports it separately and shows a bounded set of recent examples. Closing historical debt requires the exact `confirm-inactive` token and a successful file-backed SQLite backup. The close records an `operator-ignored` resolution on the maintenance row only; it does not run compaction and does not delete or rewrite conversations, messages, summaries, or context items. If that conversation later receives a genuine new debt request, the prior administrative resolution is cleared and the row becomes pending again.
  65. ### Programmatic control
  66. Lossless-claw also exposes an optional host-facing context-engine control contract for OpenClaw gateways that support context-engine capabilities and control dispatch. The contract is intentionally smaller than the native slash command surface:
  67. - `status` returns whether an LCM conversation is active and the current stored message count.
  68. - `doctor` returns a bounded, sanitized warning list for summary-health issues.
  69. Programmatic control never returns transcript text, local database paths, backup paths, credentials, provider debug, or shell output.
  70. This surface is capability-gated by the OpenClaw host. At the time of this change there is not yet a stable OpenClaw release with the required context-engine control endpoints; downstream users should treat it as unavailable unless their host advertises the matching capability, for example through the pending `openclaw/openclaw#98060` contract or an equivalent downstream gateway.
  71. ## Session Migration CLI
  72. `lossless-claw-migrate-sessions` is a one-time shell CLI for backfilling OpenClaw JSONL session files into `lcm.db` after lossless-claw was disabled, missing, or installed after sessions already existed. It is not a background replay loop and it does not run summarization.
  73. Run it in dry-run mode first:
  74. ```bash
  75. npx --package @martian-engineering/lossless-claw@latest lossless-claw-migrate-sessions --state-dir ~/.openclaw
  76. ```
  77. Apply the import only after reviewing the dry-run output:
  78. ```bash
  79. npx --package @martian-engineering/lossless-claw@latest lossless-claw-migrate-sessions --state-dir ~/.openclaw --apply
  80. ```
  81. The command defaults to `${OPENCLAW_STATE_DIR:-~/.openclaw}` and `${OPENCLAW_STATE_DIR:-~/.openclaw}/lcm.db`. `--apply` creates a timestamped SQLite backup before writing when the database already exists. Use `--file <path>` or repeatable `--sessions-dir <path>` for targeted imports, `--since <iso-date>` or `--limit <n>` to narrow a batch, and `--json` for machine-readable output.
  82. ## Quick start
  83. ### Prerequisites
  84. - OpenClaw with plugin context engine support
  85. - Node.js 22+
  86. - An LLM provider configured in OpenClaw (used for summarization)
  87. > **Compatibility:** `lossless-claw` requires OpenClaw `2026.9.2` or newer, the first stable release with native plugin session panels. Transcript ingestion also relies on OpenClaw's visible-transcript delta reader and current-turn read fence, which every release from `2026.8.1` ships. The Context explorer requires **Settings → Labs → Custom plugin UI**. If you cannot upgrade, keep your earlier compatible Lossless release and use `lcm-tui` to inspect context. See [Context explorer](docs/context-explorer.md).
  88. On OpenClaw hosts that advertise the durable context-engine turn contract,
  89. LosslessClaw declares current-turn transcript fencing and commits each accepted
  90. turn through an atomic idempotency ledger. Older supported hosts continue to use
  91. the existing `afterTurn` compatibility path.
  92. > **Upgrade compatibility:** Lossless Claw 1.x accepts `transcriptGcEnabled` and `autoRotateSessionFiles` so 0.15 configs continue to load. It ignores both settings and warns at startup. Remove them after upgrading; OpenClaw owns active transcript storage and session-file rotation.
  93. ### Install the plugin
  94. Lossless Claw 1.0 stable releases use npm's `latest` channel. The `beta`
  95. channel remains available for prerelease testing.
  96. Use OpenClaw's plugin installer (recommended):
  97. ```bash
  98. openclaw plugins install @martian-engineering/lossless-claw@latest
  99. ```
  100. If you're running from a local OpenClaw checkout, use:
  101. ```bash
  102. pnpm openclaw plugins install @martian-engineering/lossless-claw@latest
  103. ```
  104. Use exact versions only for rollback or reproducible canary testing. OpenClaw records an exact install spec such as `@martian-engineering/lossless-claw@0.12.0` as a pinned update track, so OpenClaw plugin update sync will keep that version until you move back to the stable track:
  105. ```bash
  106. openclaw plugins update @martian-engineering/lossless-claw@latest
  107. ```
  108. For local plugin development, build your working copy first, then link it instead of copying files:
  109. ```bash
  110. cd /path/to/lossless-claw
  111. pnpm build
  112. openclaw plugins install --link /path/to/lossless-claw
  113. # or from a local OpenClaw checkout:
  114. # pnpm openclaw plugins install --link /path/to/lossless-claw
  115. ```
  116. Re-run `pnpm build` after local source changes so the linked plugin's `dist/` output stays current.
  117. The install command records the plugin, enables it, and applies compatible slot selection (including `contextEngine` when applicable).
  118. > **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.
  119. ### Configure OpenClaw
  120. Ensure the context engine slot points at lossless-claw and explicitly allow its
  121. conversation prompt hook:
  122. ```json
  123. {
  124. "plugins": {
  125. "slots": {
  126. "contextEngine": "lossless-claw"
  127. },
  128. "entries": {
  129. "lossless-claw": {
  130. "hooks": {
  131. "allowConversationAccess": true
  132. }
  133. }
  134. }
  135. }
  136. }
  137. ```
  138. OpenClaw builds that protect `before_prompt_build` as a conversation-access hook
  139. require this grant. Without it, the context engine still loads, but OpenClaw
  140. blocks Lossless's static recall-policy prompt hook and logs the missing setting.
  141. The grant belongs beside `config`, not inside it.
  142. Restart OpenClaw after configuration changes.
  143. ## Configuration
  144. LCM is configured through a combination of plugin config and environment variables. Environment variables take precedence for backward compatibility.
  145. ### Plugin config
  146. Add a `lossless-claw` entry under `plugins.entries` in your OpenClaw config:
  147. ```json
  148. {
  149. "plugins": {
  150. "entries": {
  151. "lossless-claw": {
  152. "enabled": true,
  153. "hooks": {
  154. "allowConversationAccess": true
  155. },
  156. "llm": {
  157. "allowModelOverride": true,
  158. "allowedModels": ["openai/gpt-5.4-mini"]
  159. },
  160. "config": {
  161. "freshTailCount": 64,
  162. "leafChunkTokens": 80000,
  163. "newSessionRetainDepth": 2,
  164. "contextThreshold": 0.75,
  165. "contextThresholdOverrides": [
  166. {
  167. "name": "large-context-models",
  168. "match": { "modelContextWindowMin": 900000 },
  169. "contextThreshold": 0.15
  170. },
  171. {
  172. "name": "telegram-sessions",
  173. "match": { "sessionPattern": "agent:*:telegram:**" },
  174. "contextThreshold": 0.3
  175. }
  176. ],
  177. "incrementalMaxDepth": 1,
  178. "cacheAwareCompaction": {
  179. "enabled": true,
  180. "cacheTTLSeconds": 300
  181. },
  182. "ignoreSessionPatterns": [
  183. "agent:*:cron:**",
  184. "agent:*:**:active-memory:**",
  185. "agent:*:dreaming-narrative-**"
  186. ],
  187. "proactiveThresholdCompactionMode": "deferred",
  188. "summaryModel": "openai/gpt-5.4-mini",
  189. "expansionModel": "openai/gpt-5.4-mini",
  190. "delegationTimeoutMs": 300000,
  191. "summaryTimeoutMs": 60000,
  192. "summaryCallWindowMs": 600000,
  193. "summaryMaxCallsPerWindow": 24,
  194. "summarySpendBackoffMs": 1800000
  195. }
  196. }
  197. }
  198. }
  199. }
  200. ```
  201. The `ignoreSessionPatterns` entries in this example are storage exclusions. Matching cron, active-memory, and OpenClaw memory-core dreaming narrative sessions do not create LCM conversation rows or store messages in LCM.
  202. `leafChunkTokens` controls how many source tokens can accumulate in a leaf compaction chunk before summarization is triggered. The default is `20000`, but quota-limited summary providers may benefit from a larger value to reduce compaction frequency. `summaryModel` and `summaryProvider` let you request a cheaper or faster compaction model through OpenClaw's `api.runtime.llm.complete` capability; OpenClaw still owns provider dispatch and auth. Explicit summary model requests require `llm.allowModelOverride` and matching `llm.allowedModels` policy entries for `lossless-claw`. `expansionModel` does the same for `lcm_expand_query` sub-agent calls (drilling into summaries to recover detail). `delegationTimeoutMs` controls how long `lcm_expand_query` waits for that delegated sub-agent to finish before returning a timeout error; it defaults to `120000` (120s). `summaryTimeoutMs` controls the per-call timeout for model-backed LCM summarization; it defaults to `60000` (60s). `summaryMaxCallsPerWindow`, `summaryCallWindowMs`, and `summarySpendBackoffMs` bound repeated non-auth summarization spend per session. When unset, the model settings still fall back to OpenClaw's configured default model/provider. See [Expansion model override requirements](#expansion-model-override-requirements) for the required `subagent` trust policy when using `expansionModel`.
  203. ### Environment variables
  204. | Variable | Default | Description |
  205. |----------|---------|-------------|
  206. | `LCM_ENABLED` | `true` | Enable/disable the plugin |
  207. | `LCM_DATABASE_PATH` | `~/.openclaw/lcm.db` | Path to the SQLite database |
  208. | `LCM_IGNORE_SESSION_PATTERNS` | `""` | Comma-separated glob patterns for session keys to exclude from LCM storage |
  209. | `LCM_STATELESS_SESSION_PATTERNS` | `""` | Comma-separated glob patterns for session keys that may read from LCM but never write to it |
  210. | `LCM_SKIP_STATELESS_SESSIONS` | `true` | Enable stateless-session write skipping for matching session keys |
  211. | `LCM_CONTEXT_THRESHOLD` | `0.75` | Fraction of context window that triggers compaction (0.0–1.0) |
  212. | `LCM_FRESH_TAIL_COUNT` | `64` | Number of recent messages protected from compaction |
  213. | `LCM_NEW_SESSION_RETAIN_DEPTH` | `2` | Context retained after `/new` (`-1` keeps all context, `2` keeps d2+) |
  214. | `LCM_LEAF_MIN_FANOUT` | `8` | Minimum raw messages per leaf summary |
  215. | `LCM_CONDENSED_MIN_FANOUT` | `4` | Minimum summaries per condensed node |
  216. | `LCM_CONDENSED_MIN_FANOUT_HARD` | `2` | Relaxed fanout for forced compaction sweeps |
  217. | `LCM_INCREMENTAL_MAX_DEPTH` | `1` | How deep incremental compaction goes (0 = leaf only, 1 = one condensed pass, -1 = unlimited) |
  218. | `LCM_LEAF_CHUNK_TOKENS` | `20000` | Max source tokens per leaf compaction chunk |
  219. | `LCM_LEAF_TARGET_TOKENS` | `2400` | Target token count for leaf summaries |
  220. | `LCM_CONDENSED_TARGET_TOKENS` | `2000` | Target token count for condensed summaries |
  221. | `LCM_MAX_EXPAND_TOKENS` | `4000` | Token cap for sub-agent expansion queries |
  222. | `LCM_LARGE_FILE_TOKEN_THRESHOLD` | `25000` | File blocks above this size are intercepted and stored separately |
  223. | `LCM_LARGE_FILE_SUMMARY_PROVIDER` | `""` | Provider override for large-file summarization |
  224. | `LCM_LARGE_FILE_SUMMARY_MODEL` | `""` | Model override for large-file summarization |
  225. | `LCM_SUMMARY_MODEL` | `""` | Model override for compaction summarization; falls back to OpenClaw's default model when unset |
  226. | `LCM_SUMMARY_PROVIDER` | `""` | Provider override for compaction summarization; falls back to `OPENCLAW_PROVIDER` or the provider embedded in the model ref |
  227. | `LCM_SUMMARY_BASE_URL` | *(from OpenClaw / provider default)* | Base URL override for summarization API calls |
  228. | `LCM_EXPANSION_MODEL` | *(from OpenClaw)* | Model override for `lcm_expand_query` sub-agent (e.g. `openai/gpt-5.4-mini`) |
  229. | `LCM_EXPANSION_PROVIDER` | *(from OpenClaw)* | Provider override for `lcm_expand_query` sub-agent |
  230. | `LCM_DELEGATION_TIMEOUT_MS` | `120000` | Max time to wait for delegated `lcm_expand_query` sub-agent completion |
  231. | `LCM_SUMMARY_TIMEOUT_MS` | `60000` | Max time to wait for a single model-backed LCM summarizer call |
  232. | `LCM_SUMMARY_CALL_WINDOW_MS` | `600000` | Rolling window used by the per-session summarization spend guard |
  233. | `LCM_SUMMARY_MAX_CALLS_PER_WINDOW` | `24` | Max model-backed summarization calls per session/window before spend backoff opens |
  234. | `LCM_SUMMARY_SPEND_BACKOFF_MS` | `1800000` | Cooldown after the summarization spend guard opens |
  235. | `LCM_PRUNE_HEARTBEAT_OK` | `false` | Retroactively delete `HEARTBEAT_OK` turn cycles from LCM storage |
  236. | `LCM_PROACTIVE_THRESHOLD_COMPACTION_MODE` | `deferred` | Choose whether proactive threshold compaction is deferred into maintenance debt or kept inline for legacy behavior |
  237. | `LCM_CACHE_TTL_SECONDS` | `300` | Cache TTL used by cache-aware deferred compaction when provider/runtime telemetry does not supply a more specific retention window |
  238. Deferred proactive compaction is also the default. Set `proactiveThresholdCompactionMode` or `LCM_PROACTIVE_THRESHOLD_COMPACTION_MODE` to `inline` only if you need legacy foreground compaction behavior. In deferred mode, lossless-claw records one coalesced prompt-mutating debt item after the turn, leaves background `maintain()` to process only non-prompt-mutating work while Anthropic cache is still hot, and then consumes that debt pre-assembly once the cache is cold or the prompt is approaching overflow.
  239. ### Expansion model override requirements
  240. 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.
  241. For most setups, `openai/gpt-5.4-mini` is a better starting point than Anthropic Haiku because it is cheap, fast, and does not depend on Anthropic quota remaining.
  242. Add a `subagent` policy under `plugins.entries.lossless-claw` and allowlist the canonical `provider/model` target you want the plugin to use:
  243. ```json
  244. {
  245. "models": {
  246. "openai/gpt-4.1-mini": {}
  247. },
  248. "plugins": {
  249. "entries": {
  250. "lossless-claw": {
  251. "enabled": true,
  252. "subagent": {
  253. "allowModelOverride": true,
  254. "allowedModels": ["openai/gpt-4.1-mini"]
  255. },
  256. "config": {
  257. "expansionModel": "openai/gpt-4.1-mini"
  258. }
  259. }
  260. }
  261. }
  262. }
  263. ```
  264. - `subagent.allowModelOverride` is required for OpenClaw to honor plugin-requested per-run `provider`/`model` overrides.
  265. - `subagent.allowedModels` is optional but recommended. Use `"*"` only if you intentionally want to trust any target model.
  266. - 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.
  267. - If you prefer splitting provider and model, set `config.expansionProvider` and use a bare `config.expansionModel`.
  268. - `openclaw doctor --fix` can add the required `subagent` policy for a configured `expansionModel`. If a host still rejects a stale or unavailable override, `lcm_expand_query` retries once without the override so recall does not fail hard.
  269. Plugin config equivalents:
  270. - `ignoreSessionPatterns`
  271. - `statelessSessionPatterns`
  272. - `skipStatelessSessions`
  273. - `newSessionRetainDepth`
  274. - `summaryModel`
  275. - `summaryProvider`
  276. - `delegationTimeoutMs`
  277. - `summaryTimeoutMs`
  278. Environment variables still win over plugin config when both are set.
  279. ### Summary model priority
  280. For compaction summarization, lossless-claw resolves the model in this order:
  281. 1. `LCM_SUMMARY_MODEL` / `LCM_SUMMARY_PROVIDER`
  282. 2. Plugin config `summaryModel` / `summaryProvider`
  283. 3. OpenClaw's default compaction model/provider
  284. 4. Runtime/session model/provider hints from OpenClaw
  285. If `summaryModel` already includes a provider prefix such as `anthropic/claude-sonnet-4-6`, `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.
  286. Summary calls are dispatched through OpenClaw's runtime LLM layer, so auth profiles, OAuth refresh, API keys, base URLs, and provider-specific request preparation remain host-owned. Run `openclaw doctor --fix` after adding explicit summary model overrides if you want OpenClaw to add the matching `plugins.entries.lossless-claw.llm` policy.
  287. ### Recommended starting configuration
  288. ```
  289. LCM_FRESH_TAIL_COUNT=64
  290. LCM_LEAF_CHUNK_TOKENS=20000
  291. LCM_INCREMENTAL_MAX_DEPTH=1
  292. LCM_CONTEXT_THRESHOLD=0.75
  293. LCM_SUMMARY_MODEL=openai/gpt-5.4-mini
  294. LCM_EXPANSION_MODEL=openai/gpt-5.4-mini
  295. ```
  296. - **freshTailCount=64** protects the last 64 messages from compaction, expanding through the newest user when needed so its assistant/tool suffix cannot be separated from the active instruction.
  297. - **leafChunkTokens=20000** limits how large each leaf compaction chunk can grow before LCM summarizes it. Increase this when your summary provider is quota-limited and frequent leaf compactions are exhausting that quota.
  298. - **incrementalMaxDepth=1** runs one condensed pass after each leaf compaction by default. Set to `0` for leaf-only behavior, a larger positive integer for a deeper cap, or `-1` for unlimited cascading.
  299. - **contextThreshold=0.75** triggers compaction when context reaches 75% of the model's window, leaving headroom for the model's response.
  300. - **contextThresholdOverrides** optionally picks a different threshold for matching model ids, model context-window ranges, or session patterns. If no rule matches, LCM falls back to `contextThreshold`.
  301. ### Session exclusion patterns
  302. ### Session reset semantics
  303. Lossless-claw distinguishes OpenClaw's two session-reset commands:
  304. - `/new` keeps the active conversation row and all stored summaries, but prunes `context_items` so the next turn rebuilds context from retained summaries instead of the fresh tail.
  305. - `/reset` archives the active conversation row and creates a new active row for the same stable `sessionKey`, giving the next turn a clean LCM conversation while preserving prior history.
  306. Lossless-claw no longer rewrites active OpenClaw transcripts for GC or session rotation. SQLite-backed OpenClaw owns active transcript storage; Lossless keeps durable conversation, summary, and recall data in its own SQLite database. If you want an LCM database snapshot before maintenance, run `/lossless backup`.
  307. `newSessionRetainDepth` (or `LCM_NEW_SESSION_RETAIN_DEPTH`) controls how much summary structure survives `/new`:
  308. - `-1`: keep all existing context items
  309. - `0`: keep all summaries, drop only fresh-tail messages
  310. - `1`: keep d1+ summaries
  311. - `2`: keep d2+ summaries; recommended default
  312. - `3+`: keep only deeper, more abstract summaries
  313. 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.
  314. 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.
  315. Cron scheduler keys (`agent:<agent>:cron:<job>...`) are isolated automatically when OpenClaw reuses the same `sessionKey` for a new runtime `sessionId`: lossless-claw archives the prior active run and creates a fresh LCM conversation for the new run. Leave cron sessions out of `ignoreSessionPatterns` when they need in-run LCM compaction.
  316. Pattern rules:
  317. - `*` matches any characters except `:`
  318. - `**` matches anything, including `:`
  319. - Patterns match the full session key
  320. Examples:
  321. - `agent:*:cron:**` excludes cron sessions for any agent when you want to bypass LCM entirely
  322. - `agent:*:**:active-memory:**` excludes active-memory sessions under nested session-key prefixes; the `**` segment is intentionally broad because it spans colon-separated session-key segments
  323. - `agent:*:dreaming-narrative-**` excludes OpenClaw memory-core dreaming narrative sessions; OpenClaw builds those keys with the `dreaming-narrative-` prefix ([source](https://github.com/openclaw/openclaw/blob/b81666ca6af25c86cc099983a4358cdc5ea9ced8/extensions/memory-core/src/dreaming-narrative.ts))
  324. - `agent:main:subagent:**` excludes all main-agent subagent sessions
  325. - `agent:ops:**` excludes every session under the `ops` agent id
  326. Treat these examples as storage exclusions. Matching sessions do not create LCM conversation rows or store messages in LCM, so use them only for lanes whose history can stay outside LCM.
  327. Environment variable example:
  328. ```bash
  329. LCM_IGNORE_SESSION_PATTERNS=agent:*:cron:**,agent:main:subagent:**
  330. ```
  331. Plugin config example:
  332. ```json
  333. {
  334. "plugins": {
  335. "entries": {
  336. "lossless-claw": {
  337. "config": {
  338. "ignoreSessionPatterns": [
  339. "agent:*:cron:**",
  340. "agent:main:subagent:**"
  341. ]
  342. }
  343. }
  344. }
  345. }
  346. }
  347. ```
  348. ### Stateless session patterns
  349. 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.
  350. When `skipStatelessSessions` or `LCM_SKIP_STATELESS_SESSIONS` is enabled, matching sessions:
  351. - skip bootstrap imports
  352. - skip message persistence during ingest and after-turn hooks
  353. - skip compaction writes and delegated expansion grant writes
  354. - can still assemble context from already-persisted conversations when a matching conversation exists
  355. Pattern rules are the same as `ignoreSessionPatterns`, and matching is done against the full session key.
  356. Environment variable example:
  357. ```bash
  358. LCM_STATELESS_SESSION_PATTERNS=agent:*:subagent:**,agent:ops:subagent:**
  359. LCM_SKIP_STATELESS_SESSIONS=true
  360. ```
  361. Plugin config example:
  362. ```json
  363. {
  364. "plugins": {
  365. "entries": {
  366. "lossless-claw": {
  367. "config": {
  368. "statelessSessionPatterns": [
  369. "agent:*:subagent:**",
  370. "agent:ops:subagent:**"
  371. ],
  372. "skipStatelessSessions": true
  373. }
  374. }
  375. }
  376. }
  377. }
  378. ```
  379. ### OpenClaw session reset settings
  380. 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.
  381. ```json
  382. {
  383. "session": {
  384. "reset": {
  385. "mode": "idle",
  386. "idleMinutes": 10080
  387. }
  388. }
  389. }
  390. ```
  391. - `session.reset.mode: "idle"` keeps a session alive until the idle window expires.
  392. - `session.reset.idleMinutes` is the actual reset interval in minutes.
  393. - OpenClaw does **not** currently enforce a maximum `idleMinutes`; in source it is validated only as a positive integer.
  394. - If you also use daily reset mode, `idleMinutes` acts as a secondary guard and the session resets when **either** the daily boundary or the idle window is reached first.
  395. - Legacy `session.idleMinutes` still works, but OpenClaw prefers `session.reset.idleMinutes`.
  396. Useful values:
  397. - `1440` = 1 day
  398. - `10080` = 7 days
  399. - `43200` = 30 days
  400. - `525600` = 365 days
  401. For most long-lived LCM setups, a good starting point is:
  402. ```json
  403. {
  404. "session": {
  405. "reset": {
  406. "mode": "idle",
  407. "idleMinutes": 10080
  408. }
  409. }
  410. }
  411. ```
  412. ## Documentation
  413. - [Configuration guide](docs/configuration.md)
  414. - [Architecture](docs/architecture.md)
  415. - [Agent tools](docs/agent-tools.md)
  416. - [TUI Reference](docs/tui.md)
  417. - [lcm-tui](tui/README.md)
  418. - [Optional: enable FTS5 for fast full-text search](docs/fts5.md)
  419. ## Development
  420. ```bash
  421. # Build (bundles TypeScript to dist/index.js)
  422. pnpm build
  423. # Run tests
  424. npx vitest
  425. # Type check
  426. npx tsc --noEmit
  427. # Run a specific test file
  428. npx vitest test/engine.test.ts
  429. ```
  430. ### Project structure
  431. ```
  432. index.ts # Plugin entry point and registration
  433. src/
  434. engine.ts # LcmContextEngine — implements ContextEngine interface
  435. assembler.ts # Context assembly (summaries + messages → model context)
  436. compaction.ts # CompactionEngine — leaf passes, condensation, sweeps
  437. summarize.ts # Depth-aware prompt generation and LLM summarization
  438. retrieval.ts # RetrievalEngine — grep, describe, expand operations
  439. expansion.ts # DAG expansion logic for lcm_expand_query
  440. expansion-auth.ts # Delegation grants for sub-agent expansion
  441. expansion-policy.ts # Depth/token policy for expansion
  442. large-files.ts # File interception, storage, and exploration summaries
  443. transcript-repair.ts # Tool-use/result pairing sanitization
  444. types.ts # Core type definitions (dependency injection contracts)
  445. openclaw-bridge.ts # Bridge utilities
  446. db/
  447. config.ts # LcmConfig resolution from env vars
  448. connection.ts # SQLite connection management
  449. migration.ts # Schema migrations
  450. store/
  451. conversation-store.ts # Message persistence and retrieval
  452. summary-store.ts # Summary DAG persistence and context item management
  453. fts5-sanitize.ts # FTS5 query sanitization
  454. tools/
  455. lcm-grep-tool.ts # lcm_grep tool implementation
  456. lcm-describe-tool.ts # lcm_describe tool implementation
  457. lcm-expand-tool.ts # lcm_expand tool (sub-agent only)
  458. lcm-expand-query-tool.ts # lcm_expand_query tool (main agent wrapper)
  459. lcm-conversation-scope.ts # Conversation scoping utilities
  460. common.ts # Shared tool utilities
  461. test/ # Vitest test suite
  462. specs/ # Design specifications
  463. openclaw.plugin.json # Plugin manifest with config schema and UI hints
  464. tui/ # Interactive terminal UI (Go)
  465. main.go # Entry point and bubbletea app
  466. data.go # Data loading and SQLite queries
  467. dissolve.go # Summary dissolution
  468. repair.go # Corrupted summary repair
  469. rewrite.go # Summary re-summarization
  470. transplant.go # Cross-conversation DAG copy
  471. prompts/ # Depth-aware prompt templates
  472. .goreleaser.yml # GoReleaser config for TUI binary releases
  473. ```
  474. ### Line endings
  475. This repository codifies LF line endings through `.gitattributes` so diffs stay
  476. stable across macOS, Linux, and Windows development environments.
  477. - Git should store text files with LF endings in the repository.
  478. - The root `* text=auto eol=lf` rule normalizes newly added text files.
  479. - Common source, documentation, lockfile, template, and config extensions are
  480. listed explicitly so contributors and tooling see the expected policy.
  481. - Binary assets and SQLite/database files are marked `binary` to avoid unsafe
  482. newline conversion.
  483. - If your editor or operating system prefers CRLF locally, keep the repository
  484. rules authoritative and avoid committing CRLF-only rewrites.
  485. - After changing line-ending rules, prefer a focused normalization commit so
  486. future functional changes remain easy to review.
  487. ## Security
  488. Please report suspected vulnerabilities privately. See [SECURITY.md](SECURITY.md)
  489. for the supported disclosure process and response expectations.
  490. ## License
  491. MIT
  492. ## About Martian Engineering
  493. lossless-claw is built, maintained, and funded by
  494. [Martian Engineering](https://martian.engineering/?utm_source=github&utm_medium=readme&utm_campaign=lossless-claw).
  495. We're a small team of senior engineers who build products, integrations, data
  496. systems, and agents inside our clients' stacks, and run hands-on AI training for
  497. engineering teams in their own codebases.
  498. If you're running lossless-claw in production, building on OpenClaw, or want
  499. help bringing agents into your own systems, we'd like to hear from you:
  500. - Email: [clients@martian.engineering](mailto:clients@martian.engineering)
  501. - Book a call: [30-minute intro](https://calendly.com/drew-tada-martian/30min?utm_source=github&utm_medium=readme&utm_campaign=lossless-claw)
  502. - More of our open source: [github.com/Martian-Engineering](https://github.com/Martian-Engineering)
  503. Bug reports and feature requests belong in
  504. [GitHub Issues](https://github.com/Martian-Engineering/lossless-claw/issues).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.