Persistent, read-only codebase memory for Claude Code; ask it instead of re-reading files.
2026-11-10
Sterne
—
Tools
—
Uptime
—
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
flowchart LR
repo[("Your repo")]
subgraph sessions["Claude Code sessions — premium model (many, over time)"]
agent["Agent"]
end
agent -->|"reads / edits files"| repo
agent -. "PostToolUse / FileChanged hooks<br/>tee file content — passive learning (free)" .-> lm
agent ==>|"ask_live_memory(question, cwd)<br/>one read-only MCP tool"| lm
lm ==>|"grounded answer — no file re-reading"| agent
subgraph server["Live Memory — one MCP server per workspace (singleton)"]
lm["Cheap / local large-context model<br/>+ accumulating context window<br/>append-only · neutral compaction to a ledger"]
lm --> snap[("Local JSON snapshot<br/>persists across sessions")]
end
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 asksask_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:
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):
git clone https://github.com/shofer-dev/claude-code-live-memory
cd claude-code-live-memory/deploy && ./install-service.sh # venv + user systemd service, auto-starts on boot
# …or just run it in a terminal:
# cd claude-code-live-memory/server && pip install -e . && python -m live_memory
2 — Install the plugin (inside a Claude Code session):
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_memory is 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-reset drops 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.json MCP 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 optional
max_answer_tokens arg overrides it per question.
Human status via the /live-memory-stats slash command (→ /stats), kept
off the agent's tool surface.
cd server
pip install -e . # runtime deps (mcp, anthropic, starlette, uvicorn, watchdog, httpx)
# for development/tests: pip install -e ".[dev]" # adds mypy, pytest, pytest-asyncio
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:
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:
claude --plugin-dir /ABSOLUTE/PATH/TO/claude-code-live-memory
(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.
cd server && pip install -e .
python -m live_memory
# serves MCP at http://127.0.0.1:7711/mcp (+ /health, /stats, /notify, /reload)
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):
# DeepSeek (cheap, recommended), via env:
LIVE_MEMORY_PROVIDER=openai LIVE_MEMORY_BASE_URL=https://api.deepseek.com \
LIVE_MEMORY_API_KEY=sk-... LIVE_MEMORY_MODEL=deepseek-chat python -m live_memory
# …or at runtime, from inside Claude Code:
/live-memory-config set provider=openai base_url=https://api.deepseek.com model=deepseek-chat api_key=sk-...
/live-memory-config show
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:
cd deploy
./install-service.sh # user service (recommended — see below)
./install-service.sh --system # system-wide (best for API-key setups)
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.json and reuse your Claude
login (auto-refreshed). A --system service can also do this, but the unit
must set User= + Environment=HOME=… (the installer does this for you).
systemctl --user status live-memory
journalctl --user -u live-memory -f
systemctl --user restart live-memory # after editing the env file
Logs
By default the server logs to stderr, which systemd captures into the
journal — the idiomatic place, with rotation and unit/PID metadata:
journalctl --user -u live-memory -f # user service
sudo journalctl -u live-memory -f # system service
Two caveats and the escape hatch:
A user service's journal only persists across reboots if journald has
persistent storage (/var/log/journal exists). 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.log for 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 (default INFO) 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.
/live-memory-config set preload_globs=docs/*.md,README.md # or:
LIVE_MEMORY_PRELOAD_GLOBS="docs/*.md,README.md"
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-config applies to already-loaded workspaces on their next
reset/restart, not retroactively.
/live-memory-reset starts 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-empty is 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_memoryno 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 a job_id immediately.
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.
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich Live Memory?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt Live Memory einen API-Schlüssel?
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Welchen Transport verwendet Live Memory?
Live Memory läuft lokal über stdio.
Wann wurde Live Memory zuletzt geprüft?
Zuletzt geprüft: 2026-11-10. Persistent, read-only codebase memory for Claude Code; ask it instead of re-reading files.
