compound-memory
English | 简体中文
Power your agent
पब्लिशर की अपनी कमांड। PlugMCP एंडपॉइंट नहीं।
Host a copy with our keys and logs.
uvx compound-memory==0.5.12Claude Code में लोकल कमांड के लिए इंस्टॉल लिंक नहीं है। नीचे दी गई कमांड कॉपी करें और टर्मिनल में चलाएँ।
COMPOUND_MEMORY_ROOT=<value> COMPOUND_MEMORY_AGENT_ID=<value> claude mcp add io.github.chinwe-compound-memory -- uvx compound-memory==0.5.12टर्मिनल में चलाएँ।
{ "mcpServers": { "io.github.chinwe-compound-memory": { "command": "uvx", "args": [ "compound-memory==0.5.12" ], "env": { "COMPOUND_MEMORY_ROOT": "<value>", "COMPOUND_MEMORY_AGENT_ID": "<value>" } } }}claude_desktop_config.json
रिमोट URL या आपकी मशीन पर कमांड? दोनों इंस्टॉल में क्या अंतर है
PlugMCP पर चलाएँ
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
लॉन्चपब्लिशर से
English | 简体中文
Local-first shared memory for multiple AI agents that compounds with use; Markdown + git, MCP + CLI.
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.
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:
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._shared namespace everyone reads, plus agent-* private namespaces each host owns; cross-host validation is tracked per host.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.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.
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
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
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).
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.
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.
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.
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.
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:
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. Same-host success base bumps are recorded in evidence.host_bumps and cap at 0.3 for that host (a single host tops out at 0.8; ADR-0012).validated_by / evidence trails — confidence is evidence of correctness, not popularity.memory_link creates bidirectional links that get recalled for free).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").
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.
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 maintain # one ops pass: read-only dream → optional decay → health-snapshot. Decay is off unless --with-decay or RUN_DECAY=1 (DECAY=1). No --propose, no dream-apply
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).
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
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.
compound-memory maintain is the single daily job: read-only dream (writes <root>/distill/last-plan.json, same report as dream, never --propose) → optional decay → health-snapshot. The snapshot runs after decay, so it records the post-decay store when decay ran. Default is dream + health-snapshot. Decay stays off unless you pass --with-decay or set RUN_DECAY=1 (DECAY=1 is an alias). Any failing step exits non-zero and names that step on stderr; later steps do not run.
scripts/distill-prepare.sh stays the dream-only prep path. Do not point a timer at dream --propose, dream-apply, or distill-apply (ADR-0001 / #72 / #97): proposals and merges stay an explicit human/agent step. scripts/daily-maintain.sh is a thin launchd/cron wrapper (resolves uv on PATH, then execs compound-memory maintain). It does not orchestrate the steps.
From a checkout, one cron line is enough (decay off):
0 9 * * * COMPOUND_MEMORY_ROOT=$HOME/.agents/memory $HOME/.local/bin/uv run --project <repo> compound-memory maintain >> $HOME/.agents/memory/distill/daily-maintain.log 2>&1
Same job with decay: prefix RUN_DECAY=1. A launchd ProgramArguments array can be the same uv, run, --project, <repo>, compound-memory, maintain (set COMPOUND_MEMORY_ROOT and, only if you want decay, RUN_DECAY under EnvironmentVariables). The thin wrapper is the PATH-proof alternative: /bin/sh <repo>/scripts/daily-maintain.sh with UV_BIN set. Keep using distill-prepare.sh when the timer should only refresh the dream report.
CHANGELOG.md — release notes (0.5.x Windows support and later)docs/specs/0001-compound-memory-spec.md — design specdocs/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 claimdocs/adr/ — architecture decision recordsCONTEXT.md — glossary (Chinese)skills/compound-memory/SKILL.md — usage rules for hosts (Chinese)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.
Python ≥ 3.11 on macOS, Linux, and Windows.
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.
Local-first shared memory for multiple AI agents that compounds with use; Markdown + git, MCP + CLI.
{ "mcpServers": { "io.github.chinwe-compound-memory": { "command": "uvx", "args": [ "compound-memory==0.5.12" ], "env": { "COMPOUND_MEMORY_ROOT": "<value>", "COMPOUND_MEMORY_AGENT_ID": "<value>" } } }}टूल
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
पब्लिशर ने ये एनवायरनमेंट वेरिएबल बताए हैं: COMPOUND_MEMORY_ROOT, COMPOUND_MEMORY_AGENT_ID।
Compound Memory stdio पर लोकल चलता है।
पिछली जाँच 2026-11-09 को हुई। Local-first shared memory for multiple AI agents that compounds with use; Markdown + git, MCP + CLI.