Agent LCM

Agent LCM gives coding agents one shared, local memory. It captures sessions from Codex, Cursor, VS Code, GitHub Copilot, Kiro, Claude Code, and OpenCode, then makes that history searchable from those harnesses through MCP when MCP is configured for the harness.

LCM stands for lossless context memory. The sanitized event archive is the source of truth. Search indexes, summaries, and graphs are derived from it and can be rebuilt.

Why use it

Coding agents lose useful context when a session ends, compacts, or moves to a different harness. Agent LCM keeps that work available without sending it to a hosted memory service.

• Resume earlier work with source-backed evidence instead of recollection.
• Search Codex work from Cursor, Copilot work from Kiro, or any other supported combination. Cross-harness search is the default.
• Keep one private store per user and machine instead of one database per harness or repository.
• Import sessions that existed before Agent LCM was installed when that harness has a supported importer.
• Capture Claude Code sessions through live hooks and import sessions already stored under ~/.claude/projects.
• Rebuild the SQLite index from the raw archive if the derived data is damaged.
• Run without embeddings, external APIs, or cloud storage.

How it works

Capture hooks sanitize each event and publish it to a private on-disk inbox. One authenticated local daemon drains that inbox, appends the event to the raw archive, and updates SQLite. MCP and storage CLI requests use the same daemon, so harnesses do not compete as independent database writers.

Retrieval is global unless a caller passes a harnesses filter. The usual MCP flow is:

1. lcm_grep searches the current cwd or repository first, then retries globally when the scoped search is empty.
2. lcm_describe inspects a session or summary node.
3. lcm_expand follows its source lineage, or lcm_pack_context returns a bounded context block ready for the agent.

Agent LCM targets Agent Plugins 1.0. The portable package surface is plugin.json, skills/, and mcp.json. Agent Plugins 1.0 does not standardize lifecycle hooks, so this repository also ships harness-specific hook manifests and an idempotent setup command. See the compatible client matrix for the component types each client currently loads.

Requirements

• Node.js 22.18 or newer

Install the CLI

npm install --global @team-volt/agent-lcm
agent-lcm setup all

You can also install the current source directly from GitHub:

npm install --global github:Team-Volt/agent-lcm
agent-lcm setup all

The npm package provides the stable agent-lcm command used by capture hooks, imports, diagnostics, and daemon administration. Native plugins provide MCP and skills from their managed caches where supported. OpenCode setup automatically configures its local MCP server in valid opencode.json or opencode.jsonc. Every copy uses the same ~/.agent-lcm store; you never need to find or reference a harness cache path.

Install in each harness

Each harness selects its own native package format. Run the setup command for each harness you use, then follow its guide for native installation, trust, and removal:

Harness	Setup command	Guide
Codex	agent-lcm setup codex	Codex guide
Cursor	agent-lcm setup cursor	Cursor guide
VS Code	agent-lcm setup vscode	VS Code guide
GitHub Copilot CLI	agent-lcm setup copilot	Copilot guide
Kiro IDE	agent-lcm setup kiro	Kiro guide
Claude Code	agent-lcm setup claude	Claude Code guide
OpenCode	agent-lcm setup opencode	OpenCode guide

The guides follow the current Codex plugin, Copilot CLI plugin, VS Code agent plugin, Cursor Marketplace, Kiro Powers, Claude Code plugins, and OpenCode plugins documentation. If setup cannot run a supported native command, it reports the guide and uses the manual hook path when that harness needs one.

The repository root remains an Agent Plugins package for Kiro and other skills/MCP-only clients:

• skills/lcm-recall/SKILL.md
• the agent-lcm stdio server in mcp.json

The published npm package omits that root manifest so Codex, Cursor, and Claude Code select their native compatibility manifests, which include hooks. Copilot and VS Code use the native package generated by setup. If a client cannot install the plugin, add this stdio MCP server:

{
  "command": "agent-lcm",
  "args": ["mcp"]
}

The harness must inherit a PATH that contains the npm global binary. Native plugin installation is more reliable for GUI apps because it uses the bundled command. Use the relevant guide's trust or refresh note after installation; a restart is not a general requirement documented by every harness.

Enable automatic capture

agent-lcm setup all detects the harnesses installed under your home directory and completes native setup where supported, with manual hook wiring only where that harness needs it. It does not create configuration directories for clients you do not use. To configure a harness that setup cannot detect, run its command directly:

agent-lcm setup codex
agent-lcm setup cursor
agent-lcm setup vscode
agent-lcm setup copilot
agent-lcm setup kiro
agent-lcm setup claude
agent-lcm setup opencode

Run only the commands for the harnesses you use. A legacy VS Code and GitHub Copilot fallback may share ~/.copilot/hooks/agent-lcm.json; native plugin hooks are loaded from the plugin store instead of being duplicated there. Setup preserves unrelated hook entries, is safe to run again, and writes private files containing the absolute Agent LCM command when manual wiring is needed. If a target file already exists and needs changes, setup first saves a timestamped -pre-agent-lcm- backup beside it.

Legacy or setup-managed user integration paths are:

Harness	Legacy or setup path
Codex	~/.codex/hooks.json
Cursor	~/.cursor/hooks.json
VS Code	~/.copilot/hooks/agent-lcm.json
GitHub Copilot	~/.copilot/hooks/agent-lcm.json
Kiro	~/.kiro/hooks/agent-lcm.json
Claude Code	No managed hook file; status path is ~/.claude/settings.json
OpenCode	~/.config/opencode/plugins/agent-lcm.ts, .agent-lcm-opencode-plugin.state, and opencode.json

Codex, Cursor, Copilot, VS Code, and Claude Code native plugins carry their own hooks. OpenCode uses the generated global plugin for live capture and its managed MCP entry. Removal disables capture through a durable state marker and removes only the exact owned MCP entry; it does not delete the generated plugin path. Setup does not add a second user-level copy after native installation. The Codex path above exists only for older fallback entries, which setup removes after native installation succeeds.

Check setup-managed and legacy hook files, then run the broader doctor checks:

agent-lcm setup status
agent-lcm doctor --json

Setup and removal print one report per harness. Exit status 0 means the requested native work and hook work completed. Exit status 2 means a manual native step remains (manual-required) or a shared Copilot resource was deliberately retained (shared-retained). Exit status 1 means the command failed; inspect stderr before retrying. If stderr says the native action completed but the hook file could not be updated safely, repair that file and rerun the same command. A reported concurrent change is left untouched; for other file errors, inspect the file because publication may have completed. Add --json when a script needs the report fields.

Native lifecycle support is limited to the commands that each client documents:

• Codex probes with codex plugin list, adds the installed npm package as a local marketplace, then runs codex plugin add agent-lcm@agent-lcm. The npm artifact omits the portable root manifest so Codex loads the native manifest, including hooks. Removal runs codex plugin remove agent-lcm@agent-lcm.
• GitHub Copilot CLI and VS Code share the Copilot plugin store. Setup probes with copilot plugin list, builds a private native package with absolute Agent LCM hook and MCP commands, and installs it with copilot plugin install. agent-lcm remove copilot and agent-lcm remove vscode return shared-retained without uninstalling that shared plugin; use the documented Copilot uninstall command only after reviewing both clients.
• Cursor and Kiro are probed with cursor-agent --version and kiro-cli --version. Neither CLI documents a noninteractive plugin install or removal command. Cursor must load the native npm package, not the repository-root Agent Plugin, to get hooks. Kiro uses the repository-root Power and the separate Kiro hook file.
• Claude Code probes claude plugin marketplace list --json and claude plugin list --json. Setup adds the installed package root with claude plugin marketplace add <package-root> --scope user when needed, then runs either claude plugin install agent-lcm@agent-lcm --scope user or claude plugin update agent-lcm@agent-lcm --scope user. Removal uninstalls only that user plugin and retains the marketplace. Pass --home PATH to use a Claude config directory through CLAUDE_CONFIG_DIR.
• OpenCode writes the generated global plugin to ~/.config/opencode/plugins/agent-lcm.ts. Pass --home PATH to use an alternate OpenCode config directory; the plugin is written to <PATH>/plugins/agent-lcm.ts. It captures stable session, prompt, and tool events. Setup also adds its owned local agent-lcm MCP server to opencode.json or opencode.jsonc while preserving unrelated settings and JSONC comments. agent-lcm remove opencode disables the generated plugin and removes only its owned MCP server. This integration targets stable OpenCode plugins, not OpenCode 2 beta, and does not provide historical import.

Setup validates an existing hook file before invoking a native CLI, preserves unrelated entries, and changes only exact Agent LCM-owned registrations. It backs up a changed file as *-pre-agent-lcm-*.json and holds an atomic lock directory at <target>.lock for at most ten seconds. A helper process anchors its working directory to the checked target directory before it reads, backs up, or publishes through a unique wx temporary file, fsync, and rename. Symlinked directory components, lock paths, targets, and non-regular files are refused. Hook commands must be absolute paths without shell metacharacters. These rules make repeated setup and removal safe while avoiding a second user-level hook copy after native installation. A native client and a hook file cannot share one transaction. If another process changes the hook file during native work, Agent LCM reports whether the native action completed or setup stopped, then leaves the changed bytes untouched.

Hooks start the daemon on demand. You can also manage it directly:

agent-lcm daemon start
agent-lcm daemon restart
agent-lcm daemon status
agent-lcm daemon stop

After upgrading the npm package, restart the daemon once so the new runtime becomes the owner. Native plugin copies with the same daemon protocol will reuse it instead of replacing it:

npm install --global @team-volt/agent-lcm@latest
agent-lcm daemon restart

Import existing sessions

Start with a dry run. Import never changes the source files, and rerunning it skips event IDs already in the shared store.

agent-lcm import --harness codex --dry-run
agent-lcm import --harness codex

Known default locations are available for Codex, GitHub Copilot, Kiro, and Claude Code:

agent-lcm import --harness copilot
agent-lcm import --harness kiro
agent-lcm import --harness claude

OpenCode live capture does not include a historical session importer.

Cursor and VS Code need an exported file because their local session formats are not stable public import surfaces. Pass a Cursor chat Markdown export or a VS Code JSON/OTLP export:

agent-lcm import --harness cursor /path/to/chat.md --dry-run
agent-lcm import --harness vscode /path/to/export.json --dry-run

To scan the known locations for every directly readable harness under a home directory:

agent-lcm import --all --dry-run
agent-lcm import --all

The report lists scanned and imported sessions, imported and duplicate events, rejected records, failures, and harnesses that still need an export. The legacy Codex-only command remains available during initial migration work:

agent-lcm import-codex-sessions --dry-run --json

The Claude importer reads the primary project session JSONL files. It imports visible user and assistant text plus completed tool calls. It skips Claude metadata, private thinking blocks, sidechain records, and subagents transcripts.

Local storage

The default store is ~/.agent-lcm. Set AGENT_LCM_HOME to use another one.

~/.agent-lcm/
  events.jsonl                 active raw append target
  segments/
    manifest.json              archive manifest and migration state
    *.jsonl.gz                 verified compressed raw segments
  index.sqlite                 derived FTS, summaries, and graph metadata
  overflow/                    sanitized large-value spill files
  inbox/                       durable capture queue
  quarantine/                  malformed queue records
  runtime/                     daemon socket, token, and ownership files

The active log rotates at 64 MiB. The daemon verifies and compresses closed segments with gzip level 1, stores byte locators in SQLite, and removes the duplicate full JSON from archived index rows. The index does not keep a second full copy of archived event payloads.

Raw history is unlimited by default. To expire closed raw segments after a fixed number of days, set a positive integer in the process environment or in ~/.agent-lcm/.env:

AGENT_LCM_RETENTION_DAYS=90

Finite retention removes exact old event sources but keeps session and summary records. Check config_error and migration fields with:

agent-lcm health --json
agent-lcm maintain --once --json

Privacy and safety

Agent LCM stores session content on the local machine. It redacts common secret fields and token formats before publication, strips credential URI passwords, and bounds large strings and payloads. Oversized sanitized values use local overflow files with hashes and byte counts.

Redaction lowers risk but cannot prove that arbitrary tool output contains no sensitive data. Protect ~/.agent-lcm as you would protect local source code and shell history. Agent LCM creates its store directories with mode 0700 and private files with mode 0600 on platforms that support POSIX permissions.

Useful commands

agent-lcm --help
agent-lcm doctor --json
agent-lcm health --json
agent-lcm stats --json
agent-lcm sessions --include-summaries --json
agent-lcm usage --json
agent-lcm cleanup --json

cleanup compacts the derived search index; it does not delete retained raw events. Use cleanup --apply only after reviewing the preview.

Development

git clone git@github.com:Team-Volt/agent-lcm.git
cd agent-lcm
npm ci
npm run typecheck
npm test
npm run smoke
npm pack --dry-run

The smoke test uses a temporary AGENT_LCM_HOME, captures events through the real CLI, starts the daemon and MCP server, searches the shared store, and cleans up its processes.

See Architecture and Troubleshooting for implementation and recovery details.

License

Agent LCM uses the MIT License. See LICENSE.