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"]

Loading

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"]

Loading

Installation

Prerequisites

• Node.js 22.12.0 or newer
• 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 LCM from npm, then configure the native Claude Code integration:

npm install -g @donadiosolutions/lcm@latest
lcm install
lcm doctor

lcm install writes the native Claude Code hooks and MCP configuration, installs slash commands and skills, and verifies the daemon. If it finds a recognized LCM Marketplace installation from the current or legacy upstream repository, it removes that installation first to prevent duplicate hooks. LCM no longer supports direct installation from the Claude Marketplace.

Update LCM through npm and rerun the idempotent installer:

npm install -g @donadiosolutions/lcm@latest
lcm install
lcm doctor

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

Codex import defaults to the current canonical project. Add --all to consider all locally verified projects. LCM conservatively reconciles deleted ~/.codex/worktrees/ sessions from exact thread ownership or a unique local repository match and reports unresolved or ambiguous sessions without guessing. On a repository's first LCM command, import registers the current verified Git identity before indexing Codex history, so sessions started in subdirectories are included immediately. lcm export --all reconciles every metadata-backed candidate and exports each final canonical project only once.

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 npm-managed native hooks in ~/.claude/settings.json. 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
UserPromptSubmit	lcm user-prompt	Searches memory and injects prompt-time hints
PostToolUse	lcm post-tool	Captures passive-learning signals from tool use
Stop	lcm session-snapshot	Ingests transcript deltas during the session
SessionEnd	lcm session-end	Ingests the completed Claude transcript

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"]

Loading

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

See Command-line behavior for custom and nested help behavior and unknown-command handling.

# 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

# Machine and project identity
lcm machine register --name workstation # register this machine for PostgreSQL
lcm machine show --json                  # show the local machine UUID
lcm machine recover <machine-uuid>       # recover after a reimage
lcm project create [path] --name lcm     # create and bind a PostgreSQL project
lcm project link <project-uuid> [path]   # pair a path to a remote project
lcm project link <local-hash> <alias>    # add a same-machine path alias
lcm project unlink [path]                # remove an alias or remote binding
lcm project list --json                  # list local and remote identities
lcm project show [path|local-hash|project-uuid] # inspect one uniquely mapped project

# Compaction & promotion
lcm compact                # compact the current project
lcm compact --all          # compact all tracked projects
lcm compact --reasoning-effort high  # one-run OpenAI Responses reasoning override
lcm compact --timeout-ms 120000 --retry-max-attempts 4  # one-run request-policy overrides
lcm promote                # promote durable insights to long-term memory
lcm promote --all          # promote across all tracked projects

# Configuration
lcm config get llm.provider             # show the normalized stored value
lcm config get llm.model --effective    # include defaults and environment overrides
lcm config set llm.model gpt-5-mini        # store a string value
lcm config set hooks.disableAutoCompact true --json  # store a typed JSON value

# 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 restart         # validate config, restart daemon, and apply changes
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 Machine registration and project identity for linked-worktree consolidation, historical Codex reconciliation, PostgreSQL pairing, reimage recovery, local aliases, permissions, unlink/relink behavior, migration binding, and ambiguity diagnosis. Remote UUID show targets resolve through that local project map: exactly one local entry must bind the UUID. Unknown or multiply mapped UUIDs are rejected; use lcm project list --json and select a local path or hash to diagnose them.

Configuration

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

Variable	Default	Description
LCM_SUMMARY_PROVIDER	auto	auto, claude-process (claude/claude-cli aliases), codex-process (codex alias), anthropic, openai (custom/openai-compatible aliases), 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 LCM while keeping its native integration installed

auto resolves per caller:

• lcm -> claude-process
• explicit config or LCM_SUMMARY_PROVIDER override always takes precedence

LCM_SUMMARY_MODEL overrides llm.model after JSON and runtime configuration are merged. An explicitly empty environment value is still an override and fails validation when the selected remote provider requires a model.

OpenAI defaults to Chat Completions. llm.baseUrl is the canonical endpoint key; legacy llm.baseURL remains readable for migration, but conflicting values are rejected. OpenAI requests default to a 600000 ms timeout and three total attempts with bounded exponential backoff. To opt into the Responses API and reasoning, set llm.apiMode to responses and llm.reasoningEffort to none, minimal, low, medium, high, or xhigh in ~/.lcm/config.json. A --reasoning-effort CLI value overrides JSON for one lcm compact invocation without rewriting the file. Process summarizers accept their provider-native reasoning levels: Claude accepts low, medium, high, xhigh, and max; Codex accepts minimal, low, medium, high, and xhigh. Set llm.fastMode (default false), or use --fast-mode/--no-fast-mode for one compaction, to control process-provider priority processing. LCM passes these controls to the provider CLI, whose installed version and selected model remain authoritative, and reports failures without exposing prompts, provider bodies, credential-bearing URLs, or credentials.

See docs/configuration.md for the complete JSON example, provider requirements, and deeper operational guidance.

Storage backend

SQLite remains the zero-configuration storage backend. LCM also validates the configuration and verified-TLS prerequisites for an explicit remote-primary PostgreSQL selection and includes an internal PostgreSQL 18 pool, migration runner, schema baseline, and isolated conformance harness. Machine/project identity is enabled, and the PostgreSQL conversation adapter is available to conformance tests. The native-transcript repository from #86 is available for explicit backfill and adapter conformance. The promoted-memory, recall, redaction-administration, and coordination repositories from #88 are likewise available for direct adapter use and shared conformance. Issue #90 extends the staged coordination repository with transaction locks, fenced leases, passive-inbox claims, cleanup, and diagnostics, but normal daemon/CLI activation stays staged until #92/#224. Issue #87 adds independently usable summary-DAG, context-item, and large-file repositories with transactional graph integrity, deterministic recursive expansion, and optional final-write fence validation under the same conversation lock namespace. Issue #91 adds durable versioned local hook envelopes, idempotent passive-inbox delivery, and a bounded crash-recoverable replication worker. Its status, validation, quarantine, and exact-event replay commands are operator-invoked and staged; hooks remain offline-only and no PostgreSQL worker starts automatically. Selecting postgresql therefore starts the daemon with an explicitly unavailable storage factory instead of falling back to SQLite. The health endpoint reports 503 and unavailable storage; status and statistics routes return fixed 503 responses, and SQLite background scans remain disabled. Project routes first validate machine registration and the explicit project binding, then fail safely at the unavailable repository boundary. Connection credentials stay out of JSON and effective configuration output. Provision the schema as its migration owner with lcm postgres migrate, then apply the reviewed identity and conversation runtime grants, plus the separate native-transcript grants when that repository is used, and the memory and administration grants for the #88 adapters. Direct distributed-coordination callers also apply the separate coordination grants. The same grant script supplies only the additional column-scoped inbox writes, applied-row deletion, and identity-sequence usage required by staged #91 delivery; it does not grant table-wide writes or sequence inspection. The staged summary, context, and large-file adapters use their dedicated summary/context grants. See storage backend configuration for operators, the PostgreSQL schema reference for the 23-table data and namespace-aware extension contract, and the storage repository architecture for repository ownership, lifetimes, transactions, and the local-outbox boundary. The native-transcript guide defines sanitized “raw” records, provenance, checkpoints, quarantine, and rollback. The PostgreSQL memory and administration guide defines metadata, tag, recall, counter, coordination, and scoped-purge semantics. The PostgreSQL cross-machine coordination guide defines transaction-lock, fenced-lease, final-write fence, queue-claim, delivery, acknowledgement, replay, quarantine, cleanup, diagnostic, and crash-recovery semantics. The PostgreSQL summary, context, and large-file guide defines graph, coverage, context-range, ordering, lock/fence, grant, query-plan, diagnostic, and recovery semantics.

Development

npm install
npm run build
npx vitest
npx tsc --noEmit
npm run test:postgresql

The PostgreSQL command owns an exact PostgreSQL 18 container and all temporary TLS, network, volume, credential, and database resources. See PostgreSQL development before changing its image digest, migrations, runtime, or cleanup guards.

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
  storage/                    backend selection and repository architecture
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.

Acknowledgments

See ACKNOWLEDGMENTS.md for project lineage and prior work.

License

MIT