lossless-claw
Lossless Context Management plugin for OpenClaw, based on the LCM paper from 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
What it does
Two ways to learn: read the below, or check out this super cool animated visualization.
When a conversation grows beyond the model's context window, OpenClaw (just like all of the other agents) normally truncates older messages. LCM instead:
- Persists every message in a SQLite database, organized by conversation
- Summarizes chunks of older messages into summaries using your configured LLM
- Condenses summaries into higher-level nodes as they accumulate, forming a DAG (directed acyclic graph)
- Assembles context each turn by combining summaries + recent raw messages
- Provides tools (
lcm_grep, lcm_describe, lcm_expand) so agents can search and recall details from compacted history
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.
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.
Commands And Skill
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.
The shell CLI reads lcm.db without modifying conversation data. Its only write command sets one validated Lossless config value in openclaw.json:
lcm status
lcm conversations show --session-key 'agent:main:example'
lcm messages tail --conversation-id 42
lcm summaries list --conversation-id 42 --depth 0 --recency 7d
lcm config get freshTailCount
lcm config set freshTailCount 96
JSON is the default output. List commands use bounded keyset pagination. See Lossless Claw CLI for commands, filters, path precedence, output fields, config-write safety, and exit codes.
The native OpenClaw command surface provides in-session operations:
/lossless shows version, enablement/selection state, DB path and size, summary counts, and summary-health status/lossless backup creates a timestamped backup of the current LCM SQLite database/lossless doctor scans for broken or truncated summaries/lossless doctor maintenance reports active actionable compaction debt separately from inactive historical debt, grouped by reason, without writing/lossless doctor apply maintenance <conversation-id> confirm-inactive administratively closes one eligible inactive debt row after creating a SQLite backup/lossless doctor apply repairs broken summaries in the current conversation after the normal safety preflight/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/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/lossless status shows plugin, conversation, and maintenance state including deferred compaction debt/lcm is the shorter alias for /lossless
Supported native command examples:
/lossless/lossless backup/lossless doctor/lossless doctor maintenance/lossless doctor apply maintenance 42 confirm-inactive/lossless doctor apply 42 confirm-offline/lossless doctor clean/lcm
The package does not register these OpenClaw root subcommands:
openclaw losslessopenclaw lcmopenclaw /losslessopenclaw /lcm
The bundled skill focuses on configuration, diagnostics, architecture, and recall-tool usage. Its reference set lives under skills/lossless-claw/references/.
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.
Programmatic control
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:
status returns whether an LCM conversation is active and the current stored message count.doctor returns a bounded, sanitized warning list for summary-health issues.
Programmatic control never returns transcript text, local database paths, backup paths, credentials, provider debug, or shell output.
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.
Session Migration CLI
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.
Run it in dry-run mode first:
npx --package @martian-engineering/lossless-claw@latest lossless-claw-migrate-sessions --state-dir ~/.openclaw
Apply the import only after reviewing the dry-run output:
npx --package @martian-engineering/lossless-claw@latest lossless-claw-migrate-sessions --state-dir ~/.openclaw --apply
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.
Quick start
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.7.2-beta.2 or newer. That beta is the first published build with the branch-safe visible transcript projection used to bootstrap SQLite-backed sessions; stable 2026.7.1 does not provide it. If you cannot use a beta or upgrade OpenClaw, stay on a lossless-claw release compatible with your installed OpenClaw version.
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/[email protected] 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.
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.
Configuration
LCM is configured through a combination of plugin config and environment variables. Environment variables take precedence for backward compatibility.
Plugin config
Add a lossless-claw entry under plugins.entries in your OpenClaw config:
{
"plugins": {
"entries": {
"lossless-claw": {
"enabled": true,
"hooks": {
"allowConversationAccess": true
},
"llm": {
"allowModelOverride": true,
"allowedModels": ["openai/gpt-5.4-mini"]
},
"config": {
"freshTailCount": 64,
"leafChunkTokens": 80000,
"newSessionRetainDepth": 2,
"contextThreshold": 0.75,
"contextThresholdOverrides": [
{
"name": "large-context-models",
"match": { "modelContextWindowMin": 900000 },
"contextThreshold": 0.15
},
{
"name": "telegram-sessions",
"match": { "sessionPattern": "agent:*:telegram:**" },
"contextThreshold": 0.3
}
],
"incrementalMaxDepth": 1,
"cacheAwareCompaction": {
"enabled": true,
"cacheTTLSeconds": 300
},
"ignoreSessionPatterns": [
"agent:*:cron:**",
"agent:*:**:active-memory:**",
"agent:*:dreaming-narrative-**"
],
"proactiveThresholdCompactionMode": "deferred",
"summaryModel": "openai/gpt-5.4-mini",
"expansionModel": "openai/gpt-5.4-mini",
"delegationTimeoutMs": 300000,
"summaryTimeoutMs": 60000,
"summaryCallWindowMs": 600000,
"summaryMaxCallsPerWindow": 24,
"summarySpendBackoffMs": 1800000
}
}
}
}
}
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.
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 for the required subagent trust policy when using expansionModel.
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 |
64 |
Number of recent messages protected from compaction |
LCM_NEW_SESSION_RETAIN_DEPTH |
2 |
Context retained after /new (-1 keeps all context, 2 keeps d2+) |
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 |
1 |
How deep incremental compaction goes (0 = leaf only, 1 = one condensed pass, -1 = unlimited) |
LCM_LEAF_CHUNK_TOKENS |
20000 |
Max source tokens per leaf compaction chunk |
LCM_LEAF_TARGET_TOKENS |
2400 |
Target token count for leaf summaries |
LCM_CONDENSED_TARGET_TOKENS |
2000 |
Target token count for condensed summaries |
LCM_MAX_EXPAND_TOKENS |
4000 |
Token cap for sub-agent expansion queries |
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 |
"" |
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_SUMMARY_BASE_URL |
(from OpenClaw / provider default) |
Base URL override for summarization API calls |
LCM_EXPANSION_MODEL |
(from OpenClaw) |
Model override for lcm_expand_query sub-agent (e.g. openai/gpt-5.4-mini) |
LCM_EXPANSION_PROVIDER |
(from OpenClaw) |
Provider override for lcm_expand_query sub-agent |
LCM_DELEGATION_TIMEOUT_MS |
120000 |
Max time to wait for delegated lcm_expand_query sub-agent completion |
LCM_SUMMARY_TIMEOUT_MS |
60000 |
Max time to wait for a single model-backed LCM summarizer call |
LCM_SUMMARY_CALL_WINDOW_MS |
600000 |
Rolling window used by the per-session summarization spend guard |
LCM_SUMMARY_MAX_CALLS_PER_WINDOW |
24 |
Max model-backed summarization calls per session/window before spend backoff opens |
LCM_SUMMARY_SPEND_BACKOFF_MS |
1800000 |
Cooldown after the summarization spend guard opens |
LCM_PRUNE_HEARTBEAT_OK |
false |
Retroactively delete HEARTBEAT_OK turn cycles from LCM storage |
LCM_PROACTIVE_THRESHOLD_COMPACTION_MODE |
deferred |
Choose whether proactive threshold compaction is deferred into maintenance debt or kept inline for legacy behavior |
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 |
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.
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.
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.
Add a subagent policy under plugins.entries.lossless-claw and allowlist the canonical provider/model target you want the plugin to use:
{
"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.
openclaw doctor --fix can add the required subagent policy for a configured expansionModel. If a host still rejects a
Lossless Claw — это плагин для OpenClaw, который заменяет его сжатие контекста скользящим окном на систему суммаризации на основе DAG (направленного ациклического графа). Благодаря этому каждое сообщение сохраняется, а активный контекст остаётся в пределах лимита токенов модели.