WhiteMagic

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).

{
  "mcpServers": {
    "whitemagic": {
      "command": "wm",
      "args": ["--store", "/absolute/path/to/whitemagic/gen3", "serve", "--profile", "cyberbrain"]
    }
  }
}

Check the claims instead of trusting them

Five-minute verification path: VERIFY.md — source, the zero-egress proof you can run yourself, release signatures and SBOMs, and what a receipt signature does not establish. Security posture in SECURITY-INSIGHTS.yml; who decides what in GOVERNANCE.md.

Verified Standards & Benchmark Scorecard (November 2026)

The separate 2 November controlled answer trial used 24 fresh questions, native candidate 7f37a368, and Qwen2.5-0.5B Q4_K_M. Required evidence was present in all 22 support-bearing cases, but complete answer/state/citation delivery passed 0/24. Seven of 21 answerable cases had the correct value with irrelevant citations; four outputs were invalid and two held cases received inappropriate answers. This small fictional workload does not grade the configured product answer path or establish general model performance. Earlier replay inputs and raw results remain retained; they are not rescored as independent evidence.

Related MCP server: Memento

Hosted services (separate from the local package)

• Remote MCP — https://mcp.whitemagic.dev/mcp (streamable-http): read-only recall over a curated public corpus; keyless discovery; evaluation keys with a published 50 recalls/day allowance; OAuth 2.1; x402 session lease options published as $0.01 for 5 minutes or $0.50 for 24 hours, with a published 10,000 RPM limit; and memory.search_batch for up to 10 queries in one MCP call. These limits and options are described by the live server card; the batch tool is also present in the live tools/list response. Your local store is not uploaded to this read-only recall lane.

• Receipt verification and agent trust API — https://api.whitemagic.dev: stateless POST /verify for continuity-receipt bundles (/health and /info keyless), plus a published /erc8004/validate adapter targeting Base. See the API's live service metadata and endpoint documentation for the advertised contract.

• Memory Crystal client and API — scripts/crystal_client.py seals and opens crystal envelopes locally with AES-256-GCM or ChaCha20-Poly1305 (install the optional dependency with python3 -m pip install cryptography). The API documentation lists crystal store, fetch, and lineage endpoints; successful hosted persistence and retrieval are not implied by local encryption support.

  The helper is distributed as source in this repository; it is not bundled into the wm binary or platform installers. Use the helper from the source revision matching the server/API you intend to use. Generate a client key into a protected file with python3 scripts/crystal_client.py genkey --out crystal.key, then pass that file to seal and unseal with --key. seal obtains the owner locator from the authenticated /crystals/owner-locator endpoint. This requires an owner credential and an existing registry mapping; a payment or session pass does not establish ownership. If an existing crystal is unmapped, use the contact page to request a manual ownership review.

  Supply the bearer credential through the WM_CRYSTAL_TOKEN environment variable or --token-file /path/to/credential. Token files must be regular, non-symlink files with mode 0600 or stricter. Do not put credentials in command-line arguments or send plaintext or encryption keys to support. seal, push, pull, and lineage require authenticated owner access; seal, pull, and lineage no longer accept --tenant; keyless pulls and lineage queries are no longer supported. The former tenant-hash CLI flow is a breaking change.

Status

WhiteMagic Gen3 (the wm 11.2.0 line, unifying the Gen 2 v9 operational contract and CPR 0.5 bundle portability into the Gen 3 kernel). 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).

• Install path: Linux x86-64, Linux arm64, and macOS arm64 (v10/v11 open-alpha matrix) — install-gated (Windows x86_64 and Intel macOS x86_64 remain on the stable Gen 2 v9.3.4 release line while ONNX Runtime packaging is Linux glibc 2.39+ and macOS arm64). Releases also publish gzipped distributables (~58% smaller) that the installer prefers on slow links. macOS installs through the same checksum-verified installer (hardware smoke evidence in issue #2); Windows installs the stable line through scripts/install.ps1. Every gated installer path in the active matrix is certified against the published release in CI.

• Support window: the current minor and the previous minor on the install-gated lines receive fixes; older minors are archival — see SECURITY.md.

• Trusted, local-first, single-user operation with Landlock containment and firebreak guards.

• Audited unsafe surface & test accounting (ENG-09, ENG-11): In the Gen 2 (v11.2.0) workspace, 15/16 crates enforce #![forbid(unsafe_code)] (16 audited unsafe blocks in wm-polyglot for FFI/SIMD; ~4,960 distinct tests / 9,715 CI-job sum across matrix targets). In the Gen 3 (v11.2.0) workspace, 4/7 crates enforce #![forbid(unsafe_code)] (48 audited unsafe blocks across wm-gen3-core LMDB/mmap, wm-gen3-shm POSIX shared memory, and wm-sandbox Linux Landlock/seccomp syscalls; 655 distinct core+harness library tests / ~837 distinct workspace tests / 1,677 CI-job sum).

What it does

The supported alpha contract:

• trusted, local, single-user operation;

• explicit MCP routes for dependable behavior;

• durable memory creation and lexical search without an external model;

• session record, replay, and cross-session continuity;

• an end-to-end install invariant (wm selftest) with host-health diagnostics;

• no telemetry by default and no required WhiteMagic cloud service;

• truthful degradation when optional models or embeddings are unavailable.

Install

Download the binary and its checksum from the latest release, then (substituting your platform's artifact name — for example wm-linux-x86_64, wm-linux-aarch64, or wm-macos-aarch64; the .gz variants decompress with gunzip -c <file>.gz > <file>):

sha256sum -c wm-linux-x86_64.sha256
chmod +x wm-linux-x86_64
mkdir -p ~/.local/bin && mv wm-linux-x86_64 ~/.local/bin/wm

If ~/.local/bin is not on your PATH:

export PATH="$HOME/.local/bin:$PATH"

Or use the install script (resolves the latest release, picks the right artifact for your platform, and verifies the checksum automatically):

curl -fsSL https://www.whitemagic.dev/install.sh?ref=readme | sh

Other channels

npx whitemagic-mcp serve                     # npm (no global install)
cargo install whitemagic                     # crates.io
docker run -i lbailey94/whitemagic:9 serve   # Docker Hub

Adoption snapshot (2026-10-16): 5,680 npm downloads · 6,173 Docker Hub pulls · 322 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 and see the product work end to end:

wm --version    # wm 11.2.0
wm status       # display substrate status, epoch, record counts, and store health

wm grimoire --plan is 100% read-only (0 disk writes even on missing or --bare stores) and reports detected client configuration targets without changing those files. Grimoire does not write client configurations; copy the MCP server command below into your client's configuration. --json prints a machine- readable report. wm selftest runs the full invariant check (a throwaway store plus host health); see docs/SELFTEST_AND_HOST_HEALTH.md.

Everyday commands

wm status                       # store, epoch, record counts, store health
wm selftest                     # install invariant + host health (--json, --strict)
wm remember "decision text"     # record a memory (--galaxy, --source, --kind)
wm recall "query"               # search memories (--limit, --historical, --scope)
wm session list                 # sessions: checkpoint | record | continuity | list
wm backup ./gen3-backup         # snapshot store + SHA256SUMS manifest (--json)
wm restore ./gen3-backup        # verify SHA256SUMS and restore store (--force, --json)
wm --store "$HOME/.local/share/whitemagic/gen3" serve --profile cyberbrain

The v9-only commands (doctor, connect, setup, quickstart, update, seal, verify, trust, anchor) belong to the wm9 binary line; wm backup, wm restore, and wm verify-receipt are natively supported in wm 11.2.0.

Connect an MCP client

Use this command for an MCP client. The explicit store keeps Gen3 data separate from the stable Gen2 store:

wm --store "$HOME/.local/share/whitemagic/gen3" serve --profile cyberbrain
wm --store "$HOME/.local/share/whitemagic/gen3" serve --profile full

In the JSON configuration above, replace /absolute/path/to/whitemagic/gen3 with the expanded path, for example the output of printf '%s\n' "$HOME/.local/share/whitemagic/gen3".

The server communicates over stdio. Two profiles exist:

• cyberbrain (default) — the lean MCP surface, including memory_recall, memory_remember, memory_get, memory_stats, the wm meta-tool (explicit route= dispatch to the catalog), session_checkpoint, session_continuity, session_record, session_list, galaxy_list, galaxy_fork, mesh_sync.

• full — the extended MCP catalog covering memory CRUD, search, sessions, receipts, galaxies, mandala, gnosis, sangha, and mesh; optional features add gated routes (decision.shortlist, decision.deliberate, decision.outcome, systemone.decide) when compiled in. The route count is whatever the running binary registered; its tools/list response and wm contract --json are the authorities for their respective surfaces.

Explicit routing is the dependable contract:

• wm(route="memory.create", args={...})

• wm(route="session.start", args={...})

• wm(route="galaxy.list", args={})

Privacy and data

• Your store lives locally at ~/.local/share/whitemagic/gen3 (resolution order: --store <path> → $WM_STORE → $WM_STORE_PATH → ~/.local/share/whitemagic/gen3, falling back to ./gen3-store only if $HOME is unset). Nothing is sent to WhiteMagic-operated services; there is no telemetry by default (any future sharing is opt-in, previewable, and schema-bound).

• Privacy flags exclude memories from responses and reasoning. They are access controls, not encryption — anyone who can read the store files can read the contents. Do not store credentials in memories.

• Conversation capture happens through explicit tool calls, not automatically.

Backup and restore

In wm 11.2.0+, use wm backup <dest_dir> [--json] and wm restore <backup_dir> [--force] [--json] to create and verify a full store snapshot with a SHA256SUMS manifest (or copy the whole store directory while no server is running):

# Stop any `wm serve` first, then run:
wm backup /path/to/external/disk/gen3-$(date +%F) --json
# Or copy the store root directly:
cp -a ~/.local/share/whitemagic/gen3 /path/to/external/disk/gen3-$(date +%F)

• Keep at least one copy on a different disk or machine.

• After restoring a copy, verify it with wm selftest and inspect it with wm status.

• Transaction rollback (mandala/session internals) is a short-lived undo, not a substitute for backups.

Research surface (not part of the alpha contract)

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 rest of the route catalog reachable via wm serve --profile full plus the optional feature-gated routes. wm contract --json is the authority for the compiled route set. 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.

Building from source

Requires Rust 1.85+:

cargo build --release
cargo test          # full test suite
cargo clippy --all-targets

Authored Memory-Task Evaluation (32 Scenarios)

benchmarks/pinned_task_eval.py runs 32 authored scenarios, eight each for continuity, conflict, record-addressed repair, and cue-guided deterministic migration. The final frozen run is tied to public source commit 766edb2, a local source-derived candidate whose exact version and binary hash are recorded in the task report. It is not the separately signed release binary; this run does not qualify the current public-main release. The machine-readable results are archived with the evaluation. The historical 19169fa result JSON remains available separately.

• Continuity: WhiteMagic scored 8/8 on decision recall, open-arc precision, cross-session crystal surfacing, and new-session track routing. The structured-metadata file baseline also scored 8/8 on decisions and arcs under the same salience rules. agent_context.text stayed within a 1,120 UTF-8-byte cap (largest 1,091; mean of per-context ceil(bytes/4) estimates 266.625). This is a byte-based estimate, not a tokenizer guarantee; transport/debug metadata is excluded.

• Conflict: governed current truth and verifiable revision lineage scored 7/7. All-case current truth was 7/8 because M8 is an intentional unlinked-contradiction negative control; unlinked contradictory text is not a supersession operation. Structured files matched on governed conflict.

• Repair: WhiteMagic scored 8/8 for rank-one repaired identity, poison-free top-three recall, audit-trail verification, and legitimate-neighbor preservation. Equal-information record-addressed files scored 4/8 at rank one and 5/8 for joint repair-and-preserve in the top three.

• Cue-guided migration: 8/8 end-to-end success, target precision/recall, and converging-DAG verification; all 24 legitimate neighbors were preserved. These cases supply exact stale clues, query, and authoritative replacement.

These are scripted authored cases, not an open-ended model study: there is no connected model, unseen holdout, or autonomous-agent evaluation. Structured files tie WhiteMagic on continuity, governed conflict, and discovery; baseline wire overheads differ. Salience and discovery use bounded text patterns that can misread quoted, negated, stale, speculative, or unfamiliar phrasing; they do not independently prove authority or truth. Latency includes fresh process startup and unequal tool batches, so the run establishes no latency or cost advantage.

Reproduce with the reviewed candidate binary and the archived harness:

WM_BINARY=/absolute/path/to/reviewed/wm python3 benchmarks/pinned_task_eval.py
python3 -m unittest discover -s benchmarks -p test_pinned_task_eval.py

Documentation

• docs/INDEX.md — map of the documentation tree

• docs/DEVELOPER_GUIDE.md — workspace layout, build, test, and architecture

• docs/SELFTEST_AND_HOST_HEALTH.md — wm selftest checks, thresholds, and --strict/--json contracts

• docs/STORE_LAYOUT.md — Gen3 store layout and database structure

• docs/SUTRA_GUIDE.md — Sutra and tool dispatch reference

• INSTALL.md — source build, store setup, optional model layer

• skill.md — five-minute agent onboarding

• llms.txt — machine-readable index

• docs/CHARTER.md — binding constitutional core

• continuity-receipt — signed, offline-verifiable records of governed tasks (separate spec repo, Apache-2.0)

• CHANGELOG.md — release notes

• SECURITY.md — reporting vulnerabilities

Migrating from v26 / Gen2 (LMDB stores)

If you ran the retired Python version (v26) or an earlier Gen2 line, audit and migrate its LMDB store (the directory containing data.mdb) into Gen3:

wm census ~/.whitemagic/users/local/galaxies/lmdb          # zero-dependency audit
wm migrate --source ~/.whitemagic/lmdb --dry-run           # preview
wm migrate --source ~/.whitemagic/lmdb                     # migrate into the Gen3 store
wm migrate-all --source-root <projects-root> --target-root ~/.local/share/whitemagic/gen3-projects

wm quarantine <file> reviews the migration quarantine log; a WM_STORE/--store override selects the destination.

The stack

Local memory → governed execution → verifiable continuity

• whitemagic — local-first memory and session continuity for AI agents

• continuity-receipt — portable, offline-verifiable evidence for governed tasks (Apache-2.0)

• mandala — bounded agent execution and Landlock LSM governance kernel

• whitemagic-plugins — client integrations and adapters

Each repository stands on its own: WhiteMagic does not require Mandala, and Continuity Receipt does not require WhiteMagic. Three entrances — use it → whitemagic; review a protocol → continuity-receipt; attack the security architecture → mandala.

License

MIT © Lucas Bailey and WhiteMagic Contributors

Support and security

• Support: open an issue at https://github.com/lbailey94/whitemagic/issues

• Support the lab (voluntary, not a service payment): Base USDC tip jar 0x213b6bB4fB073E86167c58DA6Cb6E9477557DaA8 · XRPL tip jar raakfKn96zVmXqKwRTDTH5K3j5eTBp1hPy — see https://www.whitemagic.dev/support. Services are paid via x402 or evaluation keys; the tip jar unlocks nothing.

• Contributing: CONTRIBUTING.md

• Security: email security@whitemagic.dev (please do not open public issues for security reports)