@donadiosolutions/lcm

Lossless Context Manager
Shared memory infrastructure for coding agents

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

Runtime Model • Installation • MCP Tools • Development

Lossless Context Manager 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 and Codex have native hook integrations, while VS Code uses 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.

Runtime Model

flowchart LR
  subgraph Clients["Clients"]
    CC["Claude Code<br/>hooks + MCP"]
    CX["Codex<br/>hooks + MCP"]
  end

  CC --> D["lcm daemon"]
  CX --> D

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

Capabilities by integration path

Path	Restore	Prompt hints	Turn writeback	Automatic compaction	Notes
Claude Code	Yes	Yes	Yes, via transcript/hooks	Yes	Primary hook-based integration
GitHub Copilot (VS Code)	No	Yes, via rules	No	No	Repo-local skill can teach Copilot to call lcm, but there is no automatic restore or turn capture yet
Codex	Yes	Yes	Yes, via native hooks	Yes, thresholded	lcm connectors install codex writes native Codex hooks, the Codex skill, and user-level rules for restore, prompt hints, passive learning, rolling transcript snapshots, and thresholded compaction

LCM Model

Phase	What happens
Persist	Raw messages are stored in SQLite per conversation
Summarize	Older messages are grouped into leaf summaries
Condense	Summaries roll up into higher-level DAG nodes
Promote	Durable insights are copied into cross-session memory
Restore	New sessions recover context from summaries and promoted memory
Recall	Agents query, expand, and inspect memory on demand

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+
• For hook based automation, one of:
  • Claude Code (native hooks)
  • Codex CLI/VSCode integration/app (native hooks)
  • VS Code with GitHub Copilot extension (connector-based)

Claude Code

Install the lcm binary first:

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

claude plugin add github:donadiosolutions/lcm
lcm install

lcm install writes config, registers hooks, installs slash commands, registers MCP, and verifies the daemon.

VS Code (GitHub Copilot)

Install the lcm binary first:

npm install -g @donadiosolutions/lcm

Then install the repo-local Copilot connector:

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

This creates a workspace skill under .github/skills/lcm-memory/SKILL.md so Copilot can search and store memory through the lcm CLI.

Codex

Install the lcm binary first:

npm install -g @donadiosolutions/lcm

Then install the Codex connector:

lcm connectors install codex
lcm connectors doctor codex

This installs the default Codex connector set:

• Native hooks in ~/.codex/hooks.json and Codex's current hooks feature in ~/.codex/config.toml
• The LCM skill in ~/.codex/skills/lcm-memory/SKILL.md
• User-level rules in ~/.codex/AGENTS.md

The native hooks use:

Codex event	LCM command	Purpose
SessionStart	lcm restore --client codex	Restore project memory at startup, resume, or clear
UserPromptSubmit	lcm user-prompt --client codex	Inject relevant memory before each prompt
PostToolUse	lcm post-tool --client codex	Capture passive learning signals from tool use
Stop	lcm session-snapshot --client codex	Ingest Codex transcript deltas and compact when the configured token threshold is reached

Import older Codex sessions when needed:

lcm import --codex
lcm import --provider all

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 for the current VS Code/Codex setup path and remaining limitations.

Hooks

Claude Code uses plugin-managed hooks. All Claude Code hooks auto-heal: each validates that all required entries remain registered and repairs missing entries before continuing. Codex uses native hooks from ~/.codex/hooks.json.

Hook	Command	Purpose
PreCompact	lcm compact --hook	Intercepts compaction and writes DAG summaries
SessionStart	lcm restore	Restores project context, recent summaries, and promoted memory
SessionEnd	lcm session-end	Ingests the completed Claude transcript
UserPromptSubmit	lcm user-prompt	Searches memory and injects prompt-time hints

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

MCP Tools

Tool	Purpose
lcm_search	Hybrid search across episodic memory (SQLite) and semantic memory
lcm_grep	Regex or full-text search across raw messages and summaries
lcm_expand	Decompress a summary node into its source content by traversing the DAG
lcm_describe	Inspect metadata and lineage of a memory node (depth, token count, parent/child links)
lcm_store	Persist durable memory manually with optional tags
lcm_stats	Show token savings, compression ratios, and usage statistics
lcm_doctor	Diagnose daemon, hooks, MCP registration, and summarizer setup

CLI

# Setup & diagnostics
lcm install                # setup wizard
lcm uninstall              # remove hooks, MCP, and config
lcm doctor                 # diagnostics: daemon, hooks, MCP, summarizer
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 <nodeId>      # inspect metadata for a memory node
lcm expand <nodeId>        # 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 --pool           # connection pool statistics

# Project path aliases
lcm map list               # list canonical project paths and aliases
lcm map list --json        # output the project path map as JSON
lcm map show               # show the current project's canonical path and aliases
lcm map show [path-or-hash] # show a specific path or project hash
lcm map add <alias>        # add an alias to the current project
lcm map add <alias> --canonical <path> # add an alias to a specific canonical project
lcm map add <alias> --hash <hash>      # add an alias to a specific project hash
lcm map remove <alias>     # remove an alias from its unambiguous project

# Compaction & promotion
lcm compact                # compact the current project
lcm compact --all          # compact all tracked projects
lcm promote                # promote durable insights to long-term memory
lcm promote --all          # promote across all tracked projects

# Import / export
lcm import                 # import Claude Code sessions for the current project
lcm import --all           # import all projects
lcm import --codex         # import Codex CLI sessions
lcm import --provider all  # import Claude Code and Codex CLI sessions
lcm export                 # export promoted knowledge to JSON
lcm import-knowledge <f>   # import a knowledge JSON file

# Connectors (wire lcm into other AI agents)
lcm connectors list        # list available agents and installed connectors
lcm connectors install <a> # install a connector for an agent
lcm connectors remove <a>  # remove a connector for an agent
lcm connectors doctor      # check connector health

# Sensitive data
lcm sensitive add <pat>    # 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 <str>   # 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
# If doctor reports a stale daemon version, stop the stale daemon process and rerun this command.

# Hook handlers (internal — called by Claude Code hooks)
lcm compact --hook         # PreCompact hook
lcm restore                # SessionStart hook
lcm session-end            # SessionEnd hook
lcm user-prompt            # UserPromptSubmit hook
lcm post-tool              # PostToolUse hook (passive learning)

# MCP server
lcm mcp                    # start MCP server

See Project path aliases for lcm map ambiguity rules, manual ~/.lcm/map.json edits, backups, and daemon reload behavior.

Configuration

All environment variables are optional. The default summarizer mode is auto.

Variable	Default	Description
LCM_SUMMARY_PROVIDER	auto	auto, claude-process, codex-process, anthropic, openai, or disabled
LCM_SUMMARY_MODEL	unset	Optional model override for the selected summarizer provider
LCM_CONTEXT_THRESHOLD	0.75	Context fill ratio that triggers compaction
LCM_FRESH_TAIL_COUNT	32	Most recent raw messages protected from compaction
LCM_LEAF_MIN_FANOUT	8	Minimum raw messages per leaf summary
LCM_CONDENSED_MIN_FANOUT	4	Minimum summaries per condensed node
LCM_INCREMENTAL_MAX_DEPTH	0	Automatic condensation depth
LCM_LEAF_CHUNK_TOKENS	20000	Maximum source tokens per leaf compaction pass
LCM_LEAF_TARGET_TOKENS	1200	Target size for leaf summaries
LCM_CONDENSED_TARGET_TOKENS	2000	Target size for condensed summaries
LCM_MAX_EXPAND_TOKENS	4000	Token cap for DAG expansion via lcm_expand
LCM_LARGE_FILE_TOKEN_THRESHOLD	25000	File size (tokens) above which content is extracted to disk
LCM_AUTOCOMPACT_DISABLED	false	Set to true to disable automatic compaction after each turn
LCM_ENABLED	true	Set to false to disable the plugin while keeping it registered

auto resolves per caller:

• lcm -> claude-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

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/
  ...                         Vitest suites

Privacy

All conversation data is stored locally in ~/.lcm/. On first startup after upgrading from older releases, lcm automatically migrates an existing legacy runtime directory to ~/.lcm/ when the new directory is absent or does not already contain LCM data. Nothing is sent to any LCM 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. Long Context Manager (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

This project is a maintained fork in the original LCM lineage, which itself stands on the shoulders of lossless-claw, the original implementation by Martian Engineering. This fork keeps the DAG-based compaction architecture, the LCM memory model, and the foundational design decisions.

The underlying theory comes from the LCM paper by Voltropy.

License

MIT