lossless-claude/lcm

lcm Shared memory infrastructure for coding agents

DAG-based summarization, SQLite-backed message persistence, promoted long-term memory, MCP retrieval tools

Website • Runtime Model • Installation • MCP Tools • Development

---

lcm replaces sliding-window forgetfulness with a persistent memory runtime for both humans and agents.

• Every message is stored in a project SQLite database.
• Older context is compacted into a DAG of summaries instead of being dropped.
• Durable decisions and findings are promoted into cross-session memory.
• Claude Code already has end-to-end hook integration, while VS Code, Codex, and Oh My Pi use connector-based workflows on the same backend today.

Humans and agents use the same backend. The integration surface differs by client, but the memory model is shared.

This repo started as a fork of lossless-claw by Martian Engineering, adapted for Claude Code. The LCM model and DAG architecture originate from the Voltropy paper.

Runtime Model

flowchart LR
  subgraph Clients["Clients"]
    CC["Claude Codehooks + MCP"]
  end

  CC --> D["lcm daemon"]

  D --> DB[("project SQLite DAG")]
  D --> PM[("promoted memory FTS5")]
  D --> TOOLS["MCP toolssearch / grep / expand / describe / store / stats / doctor"]

Capabilities by integration path

LCM Model

Nothing is dropped. Raw messages remain in the database. Summaries point back to their sources. Promoted memory remains searchable across sessions.

flowchart TD
  A["conversation / tool output"] --> B["persist raw messages"]
  B --> C["compact into leaf summaries"]
  C --> D["condense into deeper DAG nodes"]
  C --> E["promote durable insights"]
  D --> F["restore future context"]
  E --> F
  F --> G["search / grep / describe / expand / store"]

Installation

Prerequisites

• Node.js 22+
• Claude Code if you want hook-based automation
• GitHub Copilot in VS Code if you want VS Code integration
• Codex CLI if you want Codex connector installation, summarization, or transcript import
• Oh My Pi if you want Oh My Pi connector installation or transcript import

Claude Code

Install the lcm binary first:

npm install -g @lossless-claude/lcm  # provides the `lcm` command

claude plugin marketplace add lossless-claude/lcm
claude plugin install lcm@lossless-claude
lcm install

lcm install writes config, registers MCP, installs the /memory skill and lcm.md, and sets up the Claude Code, Codex, and Oh My Pi integrations. It reports one outcome per harness and exits non-zero on any failure; --dry-run writes nothing. Run from the Claude Code plugin (/memory install) it skips the connector installs and leaves the MCP entry to the plugin manifest; use the npm CLI for all harnesses.

VS Code (GitHub Copilot)

Install the lcm binary first:

npm install -g @lossless-claude/lcm

Then install the repo-local Copilot connector:

lcm connectors install github-copilot
lcm connectors doctor github-copilot

This creates a workspace skill under .agents/skills/lcm-memory/SKILL.md. Both Codex and Copilot read that directory, so one installed file serves either host.

Codex

Install the lcm binary first:

npm install -g @lossless-claude/lcm

Then install the Codex connector:

lcm connectors install codex
lcm connectors doctor codex

The default connector installs native hooks for automatic restore, prompt recall, incremental turn capture, and compaction continuity. Review and trust them in Codex /hooks; connector diagnostics distinguish configuration from activation. See Codex setup. Paginated rollout rewrites resume capture only for a proven subagent tail match; other paginated recovery mismatches remain blocked and are reported by lcm doctor. Stored history is preserved.

Import older Codex or Oh My Pi sessions, or replay all supported history:

lcm import --codex
lcm import --omp
lcm import --replay

If you also want MCP inside Codex, run lcm connectors install codex --type mcp. Today that prints the TOML block you must add manually to .codex/config.toml.

See docs/vscode-codex.md and docs/omp.md for the current connector setup paths and known shortcomings.

Hooks

The plugin registers seven hooks. Every hook fails open (exit 0) and, before running, removes stale copies of itself left in settings.json by older installers so nothing fires twice.

flowchart LR
  SS["SessionStart"] --> CONV["Conversation"]
  CONV --> UP["UserPromptSubmit(each prompt)"]
  UP --> CONV
  CONV --> PC["PreCompact(if context fills)"]
  PC --> CONV
  CONV --> SE["SessionEnd"]

MCP Tools

CLI

# Setup & diagnostics
lcm install                # setup wizard
lcm uninstall              # remove hooks, MCP, and config
lcm doctor                 # diagnostics, bounded store lists (stale, record-less) and orphan-summary ids
lcm doctor --verbose       # complete store lists, orphan ids and event details
lcm doctor --repair-manual-attribution # preview manual memory session attribution; explicit --apply requires an offline hold and backs up each changed store
lcm diagnose               # scan recent sessions for hook failures
lcm status                 # daemon + summarizer mode
lcm -V                     # version

# Memory inspection
lcm search "query"        # search episodic and promoted memory
lcm grep "pattern"        # search messages and summaries
lcm describe       # inspect session or summary metadata and commit references
lcm expand         # expand a summary node into source detail
lcm store "content"       # persist a durable memory entry
lcm stats                  # memory and compression overview
lcm stats -v               # per-conversation breakdown
lcm stats --warning-backtest # offline environment-warning backtest for the current project; warnings stay off
lcm stats --pool           # connection pool statistics
lcm stats --pool --json    # connection pool statistics as JSON

# Compaction & promotion
lcm compact                # compact the current project
lcm compact --all          # compact all tracked projects
lcm compact --verbose      # per-session token detail
lcm compact --replay       # compact sequentially with threaded context (resumable)
lcm compact --replay --restart  # discard recorded progress and start from scratch
lcm promote                # promote durable insights to long-term memory
lcm promote --all          # promote across all tracked projects

# Import / export
lcm import                 # import Claude Code, Codex and OMP sessions for the current project
lcm import --all           # import all projects
lcm import --replay        # import and compact with threaded context (resumable)
lcm import --replay --restart # discard recorded progress and start from scratch
lcm import --provider codex   # import Codex sessions (--codex is the short form)
lcm import --provider omp     # import Oh My Pi sessions (--omp is the short form)
lcm export                 # export promoted knowledge to JSON on stdout
lcm export --all --output  # every project, written to files; --tags, --since filter
lcm import-knowledge    # import a knowledge JSON file

# Connectors (wire lcm into other AI agents)
lcm connectors list        # list available agents and installed connectors
lcm connectors install  # install a connector for an agent (--type rules|mcp|skill|hooks)
lcm connectors remove   # remove a connector for an agent
lcm connectors doctor      # check connector health
lcm connectors install  --global  # in the agent's user-level config, not this repo

# Sensitive data
lcm sensitive add     # add a redaction pattern (project-scoped)
lcm sensitive add --global # add a global redaction pattern
lcm sensitive list         # list all active patterns
lcm sensitive test    # test what gets redacted
lcm sensitive purge --yes  # remove all stored data for the current project

# Daemon
lcm daemon start --detach  # start daemon in background
lcm daemon restart         # pick up changed LCM_* values
lcm daemon stop --hold     # keep it down so hooks cannot respawn it (--minutes , --reason )

# Hook handlers (internal — called by Claude Code and Codex hooks)
lcm compact --hook         # PreCompact hook (Claude Code)
lcm restore                # SessionStart hook (Claude Code)
lcm session-end            # SessionEnd hook (Claude Code)
lcm user-prompt            # UserPromptSubmit hook (Claude Code)
lcm post-tool              # PostToolUse + PostToolUseFailure hooks (Claude Code, passive learning)
lcm session-snapshot       # Stop hook (Claude Code, rolling ingest)
lcm codex-hook             # native Codex lifecycle hook — see docs/vscode-codex.md

# MCP server
lcm mcp                    # start MCP server

lcm help [command] prints this same reference from the CLI. lcm bench is a development tool: it benchmarks search against a local corpus, which the npm package does not include; see docs/search.md.

Configuration

All environment variables are optional. The default summarizer mode is auto. The daemon reads the tuning values when it starts: after changing one, run lcm daemon restart.

auto resolves per caller:

• Claude caller -> claude-process
• Codex caller -> codex-process
• Copilot caller -> copilot-process
• OMP caller -> omp-process
• explicit config or LCM_SUMMARY_PROVIDER override always takes precedence

See docs/configuration.md for tuning notes and deeper operational guidance.

Development

npm install
npm run build
npx vitest
npx tsc --noEmit

Build before testing: the suite asserts dist/ was built from the current sources, and fails with the rebuild command instead of silently testing a stale binary. LCM_SKIP_CACHE_SYNC=1 npm run build skips the plugin-cache sync when only dist/ matters.

To score a candidate summarizer model against the real compaction engine, see docs/summarizer-bench.md. The bench is opt-in — it is skipped unless LCM_EVAL_MODEL and LCM_EVAL_CORPUS_DIR are set, so npx vitest never calls a paid API.

Repository layout

bin/
  lcm.ts                      CLI entry point (binary: lcm)
src/
  compaction.ts               DAG compaction engine
  connectors/                 client integration adapters
  daemon/                     HTTP daemon, lifecycle, config, routes
  db/                         SQLite schema + promoted memory
  hooks/                      Claude hook handlers + auto-heal
  llm/                        summarizer backends
  mcp/                        MCP server + tool definitions
  store/                      conversation and summary persistence
installer/
  install.ts                  setup wizard
  uninstall.ts                cleanup
test/
  bench/                      summarizer eval bench (opt-in, see docs/summarizer-bench.md)
  ...                         Vitest suites

Privacy

All conversation data is stored locally in ~/.lossless-claude/. Nothing is sent to any lossless-claude server.

If you configure an external summarizer (claude-process, anthropic, openai, etc.), messages are sent to that provider for summarization — after built-in secret redaction. lcm scrubs common secret patterns (API keys, tokens, passwords) from message content before writing to SQLite and before sending to the summarizer.

Add project-specific patterns with lcm sensitive add "MY_PATTERN". See docs/privacy.md for full details.

Technical Notes

• Claude Code integration is hook-first.
• The daemon is shared; the memory backend is client-agnostic.
• The repo carries the original lossless-claw lineage; the current runtime is Claude Code oriented.

Acknowledgments

lcm stands on the shoulders of lossless-claw, the original implementation by Martian Engineering. The DAG-based compaction architecture, the LCM memory model, and the foundational design decisions all originate there.

The underlying theory comes from the LCM paper by Voltropy.

License

MIT