Live Memory

██╗     ██╗██╗   ██╗███████╗

██║ ██║██║ ██║██╔════╝ ██║ ██║██║ ██║█████╗ ██║ ██║╚██╗ ██╔╝██╔══╝ ███████╗██║ ╚████╔╝ ███████╗ ╚══════╝╚═╝ ╚═══╝ ╚══════╝ ███╗ ███╗███████╗███╗ ███╗ ██████╗ ██████╗ ██╗ ██╗ ████╗ ████║██╔════╝████╗ ████║██╔═══██╗██╔══██╗╚██╗ ██╔╝ ██╔████╔██║█████╗ ██╔████╔██║██║ ██║██████╔╝ ╚████╔╝ ██║╚██╔╝██║██╔══╝ ██║╚██╔╝██║██║ ██║██╔══██╗ ╚██╔╝ ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║╚██████╔╝██║ ██║ ██║ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ always-up-to-date codebase memory for Claude Code · ask, don't re-read

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 tee file content — passive learning (free)" .-> lm agent ==>|"ask_live_memory(question, cwd) 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

• accumulating context window

append-only · neutral compaction to a ledger"] lm --> snap[("Local JSON snapshot 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 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:

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](https://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):

/plugin marketplace add shofer-dev/claude-code-live-memory

/plugin install live-memory@shofer-live-memory

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

live-memory/

├── .claude-plugin/plugin.json # plugin manifest ├── .mcp.json # registers the server (type:http, explicit timeout) ├── hooks/ # PostToolUse(Read|Write|Edit|…) + FileChanged → TEE file content (passive learning) │ ├── hooks.json │ └── notify.py ├── skills/live-memory/SKILL.md # tells the agent when/why to call ask_live_memory ├── commands/ # USER-facing slash commands (not agent tools) │ ├── live-memory-stats.md # /live-memory-stats → GET /stats │ ├── live-memory-config.md # /live-memory-config → set model/provider, hot-reload │ ├── live-memory-empty.md # /live-memory-empty → wipe memory (this workspace or all) │ ├── live-memory-reset.md # /live-memory-reset → drop history + re-preload configured docs │ ├── stats.py · config.py · empty.py · reset.py ├── settings.json ├── deploy/ # systemd unit + env example + install-service.sh └── server/ # the long-running MCP server (Python, asyncio) ├── pyproject.toml # deps + mypy(strict) + pytest config ├── tests/ # pytest unit suite (mocked; no network) └── live_memory/ ├── main.py # entrypoint: python -m live_memory ├── server.py # MCP (HTTP) ask_live_memory + /health + /stats + /notify + /clear + /reset + /reload ├── workspace.py # per-cwd state registry (window + queue + store); fork/commit ├── manager.py # the agent loop (process one question); compaction ├── context_window.py # budget; file-context evict, Q&A summarize; fork/clone ├── summarizer.py # NEUTRAL, query-agnostic knowledge-ledger summarization ├── question_queue.py # per-workspace admission (serial/parallel) + per-entry timeout ├── async_jobs.py # opt-in fire-and-forget job registry (submit/poll) ├── keep_warm.py # background KV/prompt-cache keep-warm loop ├── conversation_store.py # versioned JSON snapshot (SHA-256 file validation) ├── llm_client.py # provider-pluggable: Anthropic Messages | OpenAI-compatible ├── oauth.py # subscription OAuth credential + auto-refresh (zero-config) ├── config.py # layered config (env > config.json > defaults) + provider knowledge ├── constants.py # ALL tunable magic numbers + defaults, centralized (config sources its defaults here) ├── models.py # core dataclasses (ChatMessage, FileContext, QuestionResult, …) ├── tool_executor.py # read-only tools (Read/Grep/Glob/find_paths/git/…), path-jailed ├── preload.py # configured preload globs → verbatim docs on workspace load ├── directory_tree.py # workspace scan, ~10% context cap ├── pricing.py # per-model USD cost (+ env overrides) ├── logging_setup.py # stderr→journald + optional rotating file └── prompts.py # system prompt + neutral-summary prompt

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.

Installation

Prerequisites: Python ≥ 3.10; ripgrep (rg) recomm