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 | | PreCompact | lcm session-snapshot --client codex | Force-ingest transcript deltas before manual or automatic Codex compaction | | 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           # start managed daemon in background
lcm daemon start --detach  # compatibility alias for managed background start
lcm daemon start --foreground  # start daemon in current terminal for debugging
# 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