The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Whitemagic MCP listing page.
A local-first memory layer for MCP agents.
WhiteMagic gives an AI agent durable project memory over MCP: record important context, find it after restart, and carry useful decisions into the next session — without sending your memory store to any hosted service.
You are an agent reading this repo? Start with skill.md (five-minute operational onboarding) and llms.txt (machine-readable index).
https://mcp.whitemagic.dev/mcp (streamable-http):
read-only recall over a curated public corpus, keyless discovery, free
evaluation keys, no SLA. Your local store is never uploaded.https://api.whitemagic.dev: stateless
POST /verify for continuity-receipt bundles (/health and /info
keyless).WhiteMagic v9. Release channel: open alpha — public alpha for MCP agents. The version number is a compatibility signal; the channel is an evidence claim (beta and stable each require their own exit conditions, not a version milestone).
SECURITY.md.The supported alpha contract:
Download the binary and its checksum from the
latest release, then
(substituting your platform's artifact name — for example
wm-linux-x86_64-musl, wm-linux-aarch64-musl, or wm-macos-aarch64; the
.gz variants decompress with gunzip -c <file>.gz > <file>):
If ~/.local/bin is not on your PATH:
Or use the install script (resolves the latest release, picks the right artifact for your platform, and verifies the checksum automatically):
Adoption snapshot (2026-09-13): 759 npm downloads/30d · 1,846 Docker pulls · 67 crates.io downloads. Package installs are independent of the installer and grew without any website CTA — the memory layer chooses its own doors.
Verify the installation, activate it, and see the product work end to end:
wm grimoire proves the environment and previews client wiring; it ends by
telling you activation itself needs wm connect --write. wm quickstart is
the optional 30-second two-process continuity demo on an isolated store, and
wm doctor is a troubleshooting tool, not a setup step — run
wm doctor --deep when something looks wrong.
Point any MCP client at:
The server communicates over stdio and exposes the wm meta-tool plus a
discrete lifecycle catalog — 30 MCP tools in the curated profile: the 15
CRUD/lifecycle aliases (memory.create/search/read/list/hybrid_recall/update/ revisions/ingest, session.start/record/checkpoint/continuity,
receipts.emit/verify) and 15 read-only handles
(memory.count/stats/tags/aggregate/associations/batch_read/query/filter/ nearby/vector.search, session.list/recall/replay,
gnosis.status/explain). Read-only servers (--readonly) advertise the 23
read-only entries only — write routes are refused there anyway. The wm
meta-tool provides explicit access to the full curated route catalog (69
routes) without expanding the client's schema.
Direct handles for the common lifecycle calls, with NLU routing still available.
Explicit routing is the dependable contract:
wm(route="memory.create", args={...})wm(route="session.start", args={...})wm(route="tools.list", args={})--profile curated selects the supported memory/session surface and is the
default when no profile is specified. Pass --profile full for the research
archive surface (see below).
~/.local/share/whitemagic. Nothing is sent to
WhiteMagic-operated services; there is no telemetry by default (any future
sharing is opt-in, previewable, and schema-bound).Back up the whole store root (LMDB database, search indexes, and all
session/state files — not just the lmdb/ subdirectory):
Each backup contains the full store plus a SHA256SUMS manifest. Restore
after a failure (this replaces the target store):
Restore verifies every file against the manifest before touching anything, and refuses tampered or incomplete backups. Notes:
wm seal / wm verify detect integrity drift; they do not recover data.
Only a backup recovers data.transaction.rollback) is an in-store, short-lived
undo — not a substitute for backups.The codebase contains a larger research system beyond the product boundary:
autonomous cycles, dream consolidation, bicameral reasoning, an imagination
engine, self-play training loops, polyglot sidecars (Julia/Haskell/Zig/Koka),
a signed multi-agent mesh, holographic memory coordinates, and the full
research archive (~300 routes; the generated
docs/contract/route-schema-manifest.json is the authority) reachable via
wm serve without a profile restriction. These are
research surfaces without product acceptance evidence; they may change or be
removed. Only surfaces documented in this README are part of the product
contract.
Requires Rust 1.85+:
docs/QUICKSTART.md — the two-process continuity demodocs/QUICKSTART.es.md — guía rápida (Español)docs/QUICKSTART.pt-BR.md — guia rápido (Português BR)docs/QUICKSTART.fr.md — guide de démarrage (Français)docs/TRANSLATIONS.md — translation index and help-wanted languagesdocs/MCP_CONFIG_GUIDE.md — client configurationdocs/MULTI_LAPTOP.md — moving between machines (backup/restore, session carry)continuity-receipt — signed, offline-verifiable records of governed tasks (separate spec repo, Apache-2.0)CHANGELOG.md — release notesSECURITY.md — reporting vulnerabilitiesIf you ran the retired Python version:
Local memory → governed execution → verifiable continuity
whitemagic — local-first memory and session continuity for AI agentscontinuity-receipt — portable, offline-verifiable evidence for governed tasks (Apache-2.0)mandalaos-gate-lite — bounded agent execution that emits receipts (review snapshot)whitemagic-plugins — client integrations and adaptersEach repository stands on its own: WhiteMagic does not require MandalaOS, and
Continuity Receipt does not require WhiteMagic. Three entrances — use it →
whitemagic; review a protocol → continuity-receipt; attack the
security architecture → mandalaos-gate-lite.
MIT © Lucas Bailey and WhiteMagic Contributors
CONTRIBUTING.md