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-<your-host-id>"
      }
    }
  }
}

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", "<absolute-repo-path>", "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 for a missing agent id.

Three things to notice:

• New memories start at confidence 0.5 and move on evidence — feedback carries an outcome: success raises it, failure lowers it (floor 0.05), contradiction freezes it into the review queue, obsolete archives immediately.
• First validation from a different host earns an independent bonus (once per host per memory), with validated_by / evidence trails — confidence is evidence of correctness, not popularity.
• Hits embed one-hop neighbors automatically (empty here — no links yet; memory_link creates bidirectional links that get recalled for free).

How compounding works

Scoring (weights are the W_* constants in src/compound_memory/scoring.py): 0.70·similarity + 0.15·confidence + 0.10·recency(0.5+0.5·e^(−Δt/τ)) + 0.05·type weight. With the vector channel enabled, ranking switches to RRF fusion with an ε=0.04 prior tie-break (see the spec, "index as cache").

The 5 MCP tools

Tool descriptions embed the protocol rules themselves, so agents keep the loop intact even without host-side rules injected. Short English loop: docs/agent-integration.en.md. Full parameter reference: docs/agent-integration.md.

CLI

Checkout commands below (uv run inside a clone). Hosts that did not clone the repo use uvx --from compound-memory compound-memory … instead.

uv sync --extra dev              # first clone: build .venv (later `uv run` reuses it)

uv run compound-memory init               # initialize an empty store
uv run compound-memory write "Vercel Serverless has a 10s timeout" episode agent-workbuddy
uv run compound-memory search "Vercel timeout"   # default top_k=5; hits embed one-hop neighbors (limit 3, --no-neighbors to disable)
uv run compound-memory feedback <id> agent-claude
uv run compound-memory decay          # run from cron
uv run compound-memory revive <id>    # revive an archived memory
uv run compound-memory distill-plan   # distillation candidates: suggested_action is merge / promote / review; also report-only negative_salience and contradiction_pairs
uv run compound-memory dream --ns _shared   # read-only report: distill-plan section (including the negative sections) + decay_signals + equal stats snapshots (no writes, no LLM)
uv run compound-memory dream --ns _shared --propose  # system proposes: qualifying clusters go to <root>/distill/dream-proposals.json; a human runs dream-apply. Default off; empty pack is []
uv run compound-memory dream-apply --proposals apply.json --source agent-workbuddy --dry-run  # gated apply preview; drop --dry-run to run distill-apply on admitted rows
uv run compound-memory distill-apply "the merged insight" insight agent-workbuddy --sources <id1>,<id2>  # atomic: product (links, origin=distillation) + source archival, one commit
uv run compound-memory doctor           # one-page health check; exit 1 if AGENT_ID is unset, root is missing, the lock is broken, or git is unusable
uv run compound-memory stats            # health: uses/confidence buckets + liveness + distillation yield; exit 1 if AGENT_ID is unset
uv run compound-memory rebuild-index  # rebuild the search cache anytime
uv run compound-memory review-queue   # conflict queue (CLI-only entry)
uv run compound-memory git-log        # audit trail

More operations: explain <id> (confidence composition + evidence detail for one memory), forget <id> --agent <id> (terminal removal, ADR-0009), review-resolve (adjudicate conflicts), extract <transcript|dir> (deterministic session-transcript mining).

Architecture

Agent (MCP client / CLI)
  └─ memory_write | memory_search | memory_get | memory_link | memory_feedback
       └─ MemoryStore (~/.agents/memory)
            ├─ namespaces/_shared/{episode,fact,insight,skill,decision}/*.md   shared area
            ├─ namespaces/agent-*/...                                          private areas
            ├─ archive/...                                                     decayed archive (revivable)
            ├─ index/tokens.json                                               rebuildable lexical cache
            ├─ index/vectors.db                                                rebuildable vector cache (optional)
            ├─ review-queue.md                                                 fact/insight/decision conflict queue
            └─ .git/                                                           auto-commit on every write

Scheduled distillation prep (launchd / cron / systemd)

Per ADR 0001, the deterministic prep runs on a schedule while judgment (summarizing / merging) stays with the calling agent. Every day at 09:00 dream writes a read-only report to <root>/distill/last-plan.json (the distill object is the candidate list; nothing is archived or forgotten). Schedulers keep calling dream; dream-apply is the explicit, caller-supplied apply and is not part of the timer. Pick one scheduler — launchd (macOS standard, catches up after sleep), systemd user timer (Persistent=true, same catch-up), or cron (most portable, no catch-up) — all three drive the same platform-neutral scripts/distill-prepare.sh. Ready-made templates: scripts/com.compound-memory.distill-prepare.plist.tmpl (launchd), scripts/compound-memory-distill-prepare.{service,timer}.example (systemd), and scripts/compound-memory-distill-prepare.cron.example (cron). The filled launchd / systemd / cron commands are in the Chinese README. The script runs set -eu: any failure exits non-zero (visible via launchctl list / systemctl --user list-timers / cron mail, log at distill/prepare.log). distill/ is a runtime artifact directory (auto-gitignored) — no commit noise; only distill-apply after agent judgment lands one atomic commit.

Documentation

• CHANGELOG.md — release notes (0.5.x Windows support and later)
• docs/specs/0001-compound-memory-spec.md — design spec
• docs/agent-integration.en.md — short English setup (uvx, required agent id, 5 tools, search → feedback → write)
• docs/agent-integration.md — per-host MCP configs + the unified usage protocol (Chinese; full guide)
• docs/eval/README.md — how to record "can run" versus "did the same task change with memory". A checklist and a small fixed prompt set, not a measured effectiveness claim
• docs/adr/ — architecture decision records
• CONTEXT.md — glossary (Chinese)
• skills/compound-memory/SKILL.md — usage rules for hosts (Chinese)

Development

uv run pytest tests/ -q     # full suite (MCP tool boundary + distillation + lifecycle/index/CLI + input defense)
uv run mypy src/compound_memory/   # whole package, non-strict except the modules below

storage.validation, storage.paths, and server are checked with the per-module strict flags in pyproject.toml (the same mypy invocation CI runs on Ubuntu / Python 3.13). Other modules stay on the looser global config. Do not set strict = true inside a [[tool.mypy.overrides]] block: mypy applies that key to the global options and would strict-check the whole package.

Test seams: the MCP tool boundary via in-process mcp.Client(server) (no subprocess) plus unit tests for core modules (scoring / index / store ops). CI runs tests, type checks, and a pure-wheel install smoke on Linux and Windows across Python 3.11/3.12/3.13.

Platform support

Python ≥ 3.11 on macOS, Linux, and Windows.

Release

PyPI versions are immutable and the tag must match pyproject.toml's version (the release workflow verifies this and fails loudly). Releases go through GitHub Actions + PyPI Trusted Publisher (OIDC, no token): push a tag like v0.1.0 and release.yml builds and publishes automatically.

MCP Registry name: mcp-name: io.github.chinwe/compound-memory

server.json records the PyPI package compound-memory (stdio). It does not name a repo path. Host configs still use uvx --from compound-memory compound-memory-server, because the package name and the server console script differ.