Agent LCM

Agent LCM gives coding agents one shared, local memory. It captures sessions from Codex, Cursor, VS Code, GitHub Copilot, and Kiro, then makes that history searchable from any of those harnesses through MCP.

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.
• 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 finds matching sessions across harnesses.
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. Every copy uses the same ~/.agent-lcm store; you never need to find or reference a harness cache path.

Install in each harness

Agent Plugins 1.0 defines the package, not one shared installer. Use the native flow for each harness:

Harness	Install
Codex	codex plugin marketplace add Team-Volt/agent-lcm, then codex plugin add agent-lcm@agent-lcm
GitHub Copilot CLI	copilot plugin install Team-Volt/agent-lcm
VS Code	Run Chat: Install Plugin From Source and enter https://github.com/Team-Volt/agent-lcm; VS Code also discovers the Copilot CLI install
Cursor	Use /add-plugin after Agent LCM is listed in the Cursor Marketplace, or ask an admin to add the repository to your Team Marketplace
Kiro IDE	Open Powers, choose the GitHub import option, and enter https://github.com/Team-Volt/agent-lcm

These flows follow the current Codex plugin, Copilot CLI plugin, VS Code agent plugin, Cursor marketplace, and Kiro Powers documentation.

Compatible clients discover the same portable components:

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

Codex and Cursor compatibility manifests are included for their native plugin layouts. 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. Restart the harness after installation.

Enable automatic capture

agent-lcm setup all detects the harnesses installed under your home directory and installs or repairs hooks only for those harnesses. 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

Run only the commands for the harnesses you use. VS Code and GitHub Copilot share ~/.copilot/hooks/agent-lcm.json; either setup command installs the same auto-detecting hooks. Setup preserves unrelated hook entries, is safe to run again, and writes private files containing the absolute Agent LCM command. If a target file already exists and needs changes, setup first saves a timestamped -pre-agent-lcm- backup beside it.

The user hook locations are:

Harness	Hook file
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

Check the result, then restart each harness:

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

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

agent-lcm daemon start
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 stop
agent-lcm daemon start

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, and Kiro:

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

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

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.