Live Memory README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Live Memory listing page.
Live Memory — Claude Code plugin
A cheap, always-on model that learns your repo — so your agent stops re-reading it.
Live Memory runs a separate, cheap large-context model as a long-lived MCP server that accumulates
knowledge of your codebase across sessions. Instead of re-reading the same files every session, your
agent asks one read-only tool, ask_live_memory, the broad-understanding questions — "where is X,
how does Y work, what calls Z" — and Live Memory answers in a way that bootstraps the primary agent to
start doing productive work (e.g., edits). It learns passively from your agent's own reads and edits
(teed via hooks — no extra reading) and stays current as the repo changes (modifications and deletions).
Read-only and path-jailed (it can never edit, create, or run anything); zero-config on a Claude
subscription (Haiku, no API key); the memory model is pluggable — point it at a local model or any
OpenAI-compatible endpoint.
How it works
Your agent reads or edits files as usual; hooks quietly tee that content to the server so it learns
for free. When the agent needs to understand something, it asks ask_live_memory instead of
re-reading — the server answers from its accumulated, per-workspace memory (or reads the code itself,
read-only, if it hasn't seen it yet). One server serves every session and persists across sessions.
Benchmarks
A/B on a real repo, cost per task, run to completion. Cost is shown three ways: the premium (building) model's bill — what your expensive model spends, since the companion runs on a cheap or local model — and all-in, also counting the companion's own cost on DeepSeek-v4-flash or Haiku:
| per task | premium-model bill | all-in · DeepSeek-flash† | all-in · Haiku | faster |
|---|---|---|---|---|
| Understanding-heavy (trace / comprehend) | −61% | −57% | −25% | ~22% |
| Hybrid (understand-then-edit: bug fixes + features) | −28% | −26% | −11% | ~11% |
| Pure edit / execution | ~break-even | ~break-even | ~break-even | ~0 |
Understanding-heavy work also offloads ~93% of the premium model's codebase-reading tokens (with lower
cost variance), and correctness never regressed on the hybrid tasks (12/12 passed with and without
it). DeepSeek-v4-flash matched Haiku's answer accuracy (98% vs 91% over 3 reps) at ~8× lower token
price; a local companion is ≈ free, so all-in ≈ the premium-model bill. Fully reproducible + audited
(human + Fable). Full numbers + methodology: benchmark/results/RESULTS.md.
† companion re-priced at DeepSeek-v4-flash rates (~8× cheaper than Haiku); exact for the understanding case, derived from the measured cost ratio for the hybrid case.
Lineage: Live Memory began as a feature of shofer.dev (Arkware's
parallel multi-agent coding platform), where sessions share an in-sync codebase memory. This is that
idea as a standalone Claude Code plugin — a fresh implementation, self-contained, with no
dependency on shofer. Part of the shofer Claude Code plugin family (with
slang-workflows).
Design: DESIGN.md · How it compares to Copilot/Cursor: COMPARISON.md · Testing: TESTING.md · Privacy: PRIVACY.md.
Quickstart
live-memory is an HTTP MCP server you run once (a singleton that serves every Claude Code session)
plus a plugin that registers ask_live_memory, the hooks, and the slash commands. Start the server
first — Claude Code only connects to it (it never spawns it), so if it isn't running you'll get a
connection error.
1 — Start the server (zero-config on a Claude subscription → Haiku; no API key needed):
2 — Install the plugin (inside a Claude Code session):
Ask your agent a whole-repo question — it'll call ask_live_memory instead of reading files.
/live-memory-stats shows accumulated knowledge + cost · /live-memory-config switches
model/provider · /live-memory-empty wipes memory · /live-memory-reset starts a workspace
over with its configured preload docs re-loaded. Providers, systemd, workspaces, and concurrency
are detailed below.
Shape
Architecture (see DESIGN.md for the full rationale)
- One externally-supervised, idempotent HTTP MCP server (singleton) serves all
Claude Code sessions; state is keyed per workspace (
cwd). - Model = independent + provider-pluggable: the server runs its own cheap
model (not the session's). Two adapters cover ~everything — Anthropic Messages
(with
cache_control) and OpenAI-compatible (DeepSeek/OpenAI/gateways). Zero-config: with no key but a Claude subscription, it uses the subscription OAuth token (auto-refreshed) on Haiku. - Passive (organic) learning: PostToolUse/FileChanged hooks tee the content
of the files your agent reads/edits into the memory, so it warms up for free from
real work;
ask_live_memoryis the active fallback for anything unseen. - Preload globs (opt-in):
preload_globs(e.g.docs/*.md) names reference docs loaded verbatim into the system prompt whenever a workspace is (re)loaded — the memory starts out knowing them. They behave like observations: compaction later distills them into the knowledge ledger under pressure./live-memory-resetdrops a workspace's history trail and re-preloads them fresh. - Append-only window between compactions; compaction = batched neutral summarization with a high/low-watermark (rare, batched) — observed files + Q&A distilled into a query-agnostic knowledge ledger — never front-truncation.
- Frozen volatile block + observation deltas (KV-cache preservation): the volatile system block (ledger + preloaded/observed content + manifest) is frozen between compactions and re-sent byte-identical; changes that arrive in between (a teed file, a staleness notice) are appended to the history as delta messages instead of mutating the block — so the provider's prefix cache keeps matching instead of truncating at the first changed byte.
- Two-tier timeout:
ask_live_memory(question, cwd, max_answer_tokens?)blocks up to the server-configured soft budget (default_timeout_s, default 60s — no longer a tool argument) and returns a best-effort answer before the hard.mcp.jsonMCP timeout. - Disclosed answer-length budget: the answer is hard-capped (default
LIVE_MEMORY_MAX_ANSWER_TOKENS) and the model is told the cap, so it self-regulates instead of being truncated mid-sentence; the optionalmax_answer_tokensarg overrides it per question. - Human status via the
/live-memory-statsslash command (→/stats), kept off the agent's tool surface.
Installation
Prerequisites: Python ≥ 3.10; ripgrep (rg) recommended (powers
Grep); git optional (powers git_search / get_changed_files).
1. Install the server:
2. Install the plugin into Claude Code so it reads .mcp.json, the hooks, the
skill, and the slash commands. The repo root doubles as a single-plugin
marketplace (.claude-plugin/marketplace.json); /plugin install only
installs from a marketplace, never a bare directory — so add the marketplace
first, then install from it. Inside a Claude Code session:
shofer is the marketplace name; live-memory is the plugin name. To install
from a local clone instead, point add at the checkout directory:
After editing plugin files later, run /plugin marketplace update shofer then
/reload-plugins (installed plugins are cached under ~/.claude/plugins/, so
source edits aren't picked up live).
For local development, skip the marketplace entirely and launch Claude Code
with the plugin loaded directly — this does pick up edits via /reload-plugins:
(The server in step 3 must be running before Claude Code connects — .mcp.json
points at a type:http endpoint Claude Code only connects to, never spawns; if
the server is down you'll see a connection error in /plugin's Errors tab.)
3. Run the server (next section). 4. Dev checks: mypy live_memory/ && pytest.
Running the server
The HTTP transport requires the server to be already running before Claude
Code connects (Claude Code does not start type:http servers) — run it under an
external supervisor (systemd/container/etc.).
Zero-config (no API key): if you're logged into a Claude subscription, it just works — the server reuses that credential (auto-refreshed) on Haiku.
The subscription path draws on your subscription's rate-limit budget (not $-metered) — a documented ToS gray area. For an always-on service prefer a key.
Pick any model/provider — env vars or the /live-memory-config slash
command (writes config.json, hot-reloads, no restart):
Supported providers: anthropic (Messages API + Bedrock/Vertex/gateways, API key
or subscription OAuth) and openai (any OpenAI-compatible endpoint: OpenAI,
DeepSeek, local models, gateways). Then enable the plugin so Claude Code reads
.mcp.json and connects.
Run as a systemd service
deploy/ has the boilerplate. One command registers and starts it:
It creates a venv + installs the server, writes a config at
~/.config/live-memory/live-memory.env (from live-memory.env.example — edit it
for provider/model/key), installs live-memory.service, enables lingering, and
starts it. Config is supplied to the process by systemd via EnvironmentFile=.
- Persistence survives restarts automatically: per-workspace snapshots live
in
LIVE_MEMORY_DATA_DIR(default~/.claude/plugins/data/live-memory), so a restart reloads each workspace's memory on its next query. - Subscription (zero-config) auth needs a user service (the default): it
runs as you, so it can read
~/.claude/.credentials.jsonand reuse your Claude login (auto-refreshed). A--systemservice can also do this, but the unit must setUser=+Environment=HOME=…(the installer does this for you).
Logs
By default the server logs to stderr, which systemd captures into the journal — the idiomatic place, with rotation and unit/PID metadata:
Two caveats and the escape hatch:
- A user service's journal only persists across reboots if journald has
persistent storage (
/var/log/journalexists). If yours is volatile, those logs vanish on reboot. - For a durable, greppable plain-text log regardless, set
LIVE_MEMORY_LOG_FILE(e.g./var/log/live-memory/live-memory.logfor a system service, or an absolute path under~/.local/state/live-memory/for a user one). It's a rotating handler (LIVE_MEMORY_LOG_MAX_BYTES×LIVE_MEMORY_LOG_BACKUPS) and writes in addition to journald.LIVE_MEMORY_LOG_LEVEL(defaultINFO) tunes verbosity.
Workspaces & cwd
Memory is keyed per workspace, from the cwd passed to ask_live_memory.
cwd must be an absolute path (a relative path is rejected — the shared
server can't resolve it against your session). By default the server snaps each
cwd to its enclosing git repo root, so a subdirectory and the repo root
share one memory:
| Env var | Default | Effect |
|---|---|---|
LIVE_MEMORY_CANONICALIZE_WORKSPACE | true | Snap cwd to its git repo root. Set false for a distinct memory per exact directory. |
LIVE_MEMORY_REPO_ROOT_MODE | nearest | Inside a submodule/worktree: nearest = the submodule's own root (git's default); outermost = the superproject root (fold submodule questions into the parent's memory). |
Preload globs — start out knowing your docs
preload_globs names glob patterns (relative to each workspace root) whose
matching files are read from disk and loaded verbatim into the system prompt
every time a workspace is (re)loaded — reference material the memory knows
before its first question. Preloaded content is treated like an observation:
rendered inline under its own heading until compaction distills it into the
knowledge ledger and sheds the raw bytes under budget pressure.
| Env var | Default | Effect |
|---|---|---|
LIVE_MEMORY_PRELOAD_GLOBS | (empty) | Comma-separated globs (relative to the workspace root, ** supported) preloaded verbatim on workspace load. Absolute patterns and matches escaping the workspace (symlinks) are skipped, as are binary files. |
LIVE_MEMORY_PRELOAD_MAX_TOTAL_BYTES | 2097152 | Total cap across all preloaded files per workspace (per-file cap is LIVE_MEMORY_PASSIVE_MAX_FILE_BYTES). The effective cap is additionally clamped to the window budget (compaction_floor × LIVE_MEMORY_MAX_CONTEXT_TOKENS) — preloading past the floor would just make the first question distill + shed the docs immediately. To preload a corpus bigger than ~300 KB, raise LIVE_MEMORY_MAX_CONTEXT_TOKENS too. |
Notes:
- Preload runs when a workspace is loaded — its first query after a server
start,
/live-memory-empty, or a config change. A glob change via/live-memory-configapplies to already-loaded workspaces on their next reset/restart, not retroactively. /live-memory-resetstarts a workspace over in one step: it drops the current history trail (Q&A history, knowledge ledger, file manifest — memory and on-disk snapshot) and immediately re-preloads the configured globs fresh from disk. Use it when the accumulated trail has gone stale but you want the verbose reference docs back. (/live-memory-emptyis the same wipe without the eager re-preload — the docs still load lazily on the next question.)
Monitoring scope (file_globs) and the question timeout
| Env var / config key | Default | Effect |
|---|---|---|
LIVE_MEMORY_FILE_GLOBS / file_globs | (empty — monitor everything) | Comma-separated fnmatch patterns (workspace-relative; * also crosses /). When set, the file-change feed — passive ingestion, stale/deleted tracking, modified hints — applies only to matching paths; everything else is dropped at the workspace boundary. Pair it with preload_globs for a docs-only memory: /live-memory-config set preload_globs=docs/*.md file_globs=docs/*.md. |
LIVE_MEMORY_DEFAULT_TIMEOUT_S / default_timeout_s | 60 | The soft per-question time budget. ask_live_memory no longer takes a timeout argument — callers get this configured budget; the model is told it and returns a best-effort answer at the deadline. Keep it below the hard .mcp.json MCP timeout. |
Scoping matters for cache stability too: an unscoped feed tees every file your agents touch, and each new observation is a delta the next question must carry. A docs-only scope keeps the memory focused and its prompt small.
Concurrency
Questions to the same workspace are admitted by one of two models:
| Env var | Default | Effect |
|---|---|---|
LIVE_MEMORY_CONCURRENCY | parallel | parallel (default) = no queue delay — each question forks the window, up to MAX_PARALLEL_QUERIES run at once, and the fork that explored the most codebase commits back (others still return their answer but don't update shared memory). serial = one question at a time per workspace (shared window grows in place; strongest cache locality, concurrent callers wait). |
LIVE_MEMORY_MAX_PARALLEL_QUERIES | 4 | Max concurrent questions per workspace in parallel mode. |
(Questions to different workspaces always run concurrently, regardless of this setting.)
Async (fire-and-forget) tools — opt-in
MCP tool calls block the caller's turn until they return. If you want the agent
to submit a slow query, keep working, and collect the answer later, set
LIVE_MEMORY_ASYNC_TOOLS=true to additionally expose:
ask_live_memory_submit(question, cwd)→ returns ajob_idimmediately.ask_live_memory_result(job_id)→ the answer when ready, or[running]to poll again.
The agent drives the polling (Claude Code can't push completion into a running
turn). Off by default; ask_live_memory (synchronous) is always available.
Cache keep-warm
Off by default — opt in with LIVE_MEMORY_KEEP_WARM=true, or via the slash
command: /live-memory-config set keep_warm=true. A background loop pings each
recently-active workspace's prefix (max_tokens=1, output discarded) so the
provider's KV/prompt cache doesn't go cold between questions — keeping the next
real query on cache-hit pricing instead of a full cold re-read. The heartbeat
interval is provider knowledge: 4 minutes (240s) for Anthropic/OpenAI (just
under their minute-scale cache TTLs), and auto-set very long for DeepSeek
(its disk cache lasts hours/days, so even enabled it self-disables there).
Override with LIVE_MEMORY_KEEP_WARM_INTERVAL_S /
/live-memory-config set keep_warm_interval_s=…, or stop warming idle
workspaces sooner with LIVE_MEMORY_KEEP_WARM_MAX_IDLE_S.
/live-memory-stats shows when the cache was last refreshed.