Compound Memory

compound-memory

English | 简体中文

Local-first shared memory for multiple AI agents — plain Markdown files that compound in value as they are used. Memory lives on your disk as frontmatter-annotated Markdown, gets stronger with every confirmed use, decays into a revivable archive when neglected, and auto-commits to a local git history on every write.

Why

Every agent session starts from zero: preferences get re-asked, project conventions get re-discovered, the same pitfall gets hit twice. compound-memory gives all your agents one shared store:

• Local-first — nothing leaves your machine; memories are human-readable Markdown files, not rows in an opaque database.
• MCP-native — exactly 5 tools (memory_write / memory_search / memory_get / memory_link / memory_feedback) as the single read-write boundary; works with any MCP host (Claude Code, ZCode, WorkBuddy, …), plus a full CLI for operations.
• Compounding — confirmed usage raises confidence, related memories are recalled as neighbors, validation from a *different* host counts as independent evidence, and distillation merges many raw memories into fewer, denser ones.
• Multi-agent by design — a _shared namespace everyone reads, plus agent-* private namespaces each host owns; cross-host validation is tracked per host.
• Optional semantic recall — vector search via sqlite-vec + BGE embeddings, with automatic graceful fallback to pure lexical search when unavailable. Override the model with COMPOUND_MEMORY_EMBEDDING_MODEL (default Xenova/bge-small-zh-v1.5) and COMPOUND_MEMORY_EMBEDDING_DIM (default 512); changing either is an ops action and needs an explicit rebuild-index.

Quick Start

For AI agents

Paste this one-liner into your coding agent (Claude Code, Cursor, ZCode, …) and let it do the rest:

Set up compound-memory (https://github.com/chinwe/compound-memory) — a local-first multi-agent shared memory (MCP server + CLI) — on this machine. Do not clone the repo for a normal install. Initialize the store with `uvx --from compound-memory compound-memory init` (defaults to ~/.agents/memory). Register its stdio MCP server in this host's MCP config: command `uvx`, args `--from compound-memory compound-memory-server`, env `COMPOUND_MEMORY_ROOT=$HOME/.agents/memory` and `COMPOUND_MEMORY_AGENT_ID=agent-<your-host-id>`. Verify by calling `memory_search` and expecting a `{"hits": [...]}` response; if the host needs a restart to load MCP servers, tell me. Use `uv run --directory <repo>` only when developing against a local checkout. Short English setup and the search → feedback → write loop: docs/agent-integration.en.md. Full per-host configs: docs/agent-integration.md.

For humans

1. Install

Python ≥ 3.11. The default does not clone the repo:

# Default: PyPI. Hosts launch the MCP server with

uvx --from compound-memory compound-memory-server

Optional CLI on PATH:

uv tool install compound-memory # or: pip install compound-memory

Developer / local checkout only — not the default host launch

git clone https://github.com/chinwe/compound-memory.git cd compound-memory && uv sync --extra dev

2. Initialize your store

Defaults to ~/.agents/memory; override with the COMPOUND_MEMORY_ROOT env var. A leading ~ or $HOME is expanded; a blank override falls back to the default.

uvx --from compound-memory compound-memory init

after uv tool install: compound-memory init

3. Wire it into your MCP host (recommended)

This lets your everyday agents read/write the shared store automatically. No repo path:

{

"mcpServers": { "compound-memory": { "type": "stdio", "command": "uvx", "args": ["--from", "compound-memory", "compound-memory-server"], "env": { "COMPOUND_MEMORY_ROOT": "$HOME/.agents/memory", "COMPOUND_MEMORY_AGENT_ID": "agent- " } } } }

uvx takes the package name; the server console script is compound-memory-server, so --from is required. If uvx is not on PATH, set command to the absolute path ~/.local/bin/uvx. COMPOUND_MEMORY_AGENT_ID is required for any multi-agent store: the process identity wins over whatever the model claims, so a forged source cannot write another host's namespace or inflate cross-host validation. Unset or blank is a hard failure for shared _shared use: stats and doctor exit 1 (the diagnosis is still printed). MCP tools keep running, and the server logs the same warning at startup. Without the id, identity is self-reported and can be forged.

A local checkout is the developer path, not a second default: command uv, args ["run", "--directory", " ", "compound-memory-server"] after uv sync --extra dev.

Verify: ask your agent to call memory_search (any keyword) — a {"hits": [...]} response means you're connected. Or run uvx --from compound-memory compound-memory doctor (exit 0 when COMPOUND_MEMORY_AGENT_ID is set and the store is writable; exit 1 when it is unset or blank).

Claude Code plugin

Requires Claude Code and uv (uvx on PATH). This repository hosts a self-hosted marketplace. Submitting the plugin to Anthropic's official Directory is out of scope.

claude plugin marketplace add chinwe/compound-memory

claude plugin install compound-memory@compound-memory

That installs integrations/claude, which launches uvx --from compound-memory compound-memory-server with COMPOUND_MEMORY_AGENT_ID=agent-claude (override that env var in the host if you need a different id). A SessionStart hook adds a short reminder on new sessions; verify and disable steps are in the plugin README. Those marketplace and plugin files are not in the PyPI sdist or wheel: MANIFEST.in prunes them, and scripts/wheel_smoke.sh checks the built artifacts.

WorkBuddy / CodeBuddy plugin

Requires WorkBuddy or CodeBuddy and uv (uvx on PATH). This repository hosts a self-hosted marketplace at .codebuddy-plugin/marketplace.json.

/plugin marketplace add chinwe/compound-memory

/plugin install compound-memory@compound-memory

That installs integrations/workbuddy, which launches the same PyPI server with COMPOUND_MEMORY_AGENT_ID=agent-workbuddy. A SessionStart hook prints a short hard-rule reminder on new sessions and does not read the store. The Claude marketplace file is unchanged.

ZCode plugin

Requires the ZCode desktop app and uv (uvx on PATH). ZCode reads this repository's .claude-plugin/marketplace.json as its marketplace catalog, so no separate marketplace file is needed.

Clone the repository, then in ZCode: Plugin Marketplace → Add → Add Plugin Marketplace, paste the clone path (the directory containing .claude-plugin/), and install Compound Memory (ZCode) under Personal → compound-memory. That installs integrations/zcode, which launches the same PyPI server with COMPOUND_MEMORY_AGENT_ID=agent-zcode, plus a SessionStart hard-rule reminder and the short skill. The plugin's MCP server is named compound-memory; if ~/.zcode/cli/config.json already registers a server with that name (the hand-written path, §3 of docs/agent-integration.md), keep only one of the two.

4. Next step

Inject the usage protocol from skills/compound-memory/SKILL.md into your host (the search → feedback → write loop). The short English version is docs/agent-integration.en.md; the full protocol is docs/agent-integration.md §6.

Demo

One full loop: write → search → feedback (with cross-host first-validation bonus) → store health. Real output from v0.4.0, long payloads trimmed:

uv run compound-memory init

{ "ok": true, "root": "~/.agents/memory" }

Two different hosts each write one stable fact (new memories start at confidence 0.5, uses 0):

uv run compound-memory write \

"Deploy serverless functions on this platform times out at 10s — keep handlers under that budget" \ fact agent-claude --key vercel-timeout

{

"id": "20261007_86adf1", "ns": "_shared", "type": "fact", "source": "agent-claude", "content": "Deploy serverless functions on this platform times out at 10s — keep handlers under that budget", "confidence": 0.5, "uses": 0, "key": "vercel-timeout", "validated_by": [] ... }

uv run compound-memory write \

"User prefers concise replies with tables and code examples" \ fact agent-zcode --key user-style

Search ranks by score (--explain attaches per-hit ranking components for debugging):

uv run compound-memory search "serverless timeout"

[

{ "id": "20261007_86adf1", "score": 1.0292, "similarity": 1.0, "type": "fact", "source": "agent-claude", "content": "Deploy serverless functions on this platform times out at 10s — keep handlers under that budget", "neighbors": [] }, { "id": "20261007_6a0c0c", "score": 0.5211, "similarity": 0.4919, "type": "fact", "source": "agent-zcode", "content": "User prefers concise replies with tables and code examples", "neighbors": [] } ]

A different host used this memory and reported it back with the default success outcome — uses +1, conf +0.1; and since the reporter agent-workbuddy ≠ source agent-claude, the first cross-host validation adds another +0.15:

uv run compound-memory feedback 20261007_86adf1 agent-workbuddy

{

"id": "20261007_86adf1", "confidence": 0.75, "uses": 1, "last_used": "2026-10-07", "validated_by": ["agent-workbuddy"], "evidence": { "success_count": 1, "failure_count": 0, "contradiction_count": 0, "last_verified": "2026-10-07", "recent": [{ "date": "2026-10-07", "agent": "agent-workbuddy", "outcome": "success" }] } ... }

Store health at a glance (fixed-bucket histograms, liveness, distillation yield):

uv run compound-memory stats

{

"total": 2, "archived": 0, "active": 2, "avg_confidence": 0.625, "by_type": { "fact": 2 }, "by_ns": { "_shared": 2 }, "review_queue_entries": 0, "uses_histogram": { "0": 1, "1-2": 1, "3-5": 0, "6-9": 0, "10+": 0 }, "confidence_histogram": { "<0.3": 0, "0.3-0.6": 1, "0.6-0.8": 1, "0.8-1.0": 0 }, "recent_feedback_7d": 1, "cross_validated": 0, "distilled_total": 0, "distilled_recent_7d": 0 }

Current stats also includes retrieval (mode: vector or lexical, plus reason when the vector channel is off), attestation (attested, plus a warning when COMPOUND_MEMORY_AGENT_ID is unset), and expired_active (active-area memories whose valid_until has passed; 0 in this snapshot). cross_validated counts memories whose validated_by lists at least two distinct agents — the single cross-host validation above correctly leaves it at 0. memory_search carries the same retrieval object. CLI search stays a bare array. CLI stats exits 1 when COMPOUND_MEMORY_AGENT_ID is unset or blank; doctor is the one-page check (attestation, retrieval, write lock, git) and uses the same rule, plus root / lock / git failures. MCP tools do not stop f