lbailey94/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).
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 10.4.0 line). 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 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 v10 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.