WhiteMagic

Local-first memory and session continuity for coding agents.

WhiteMagic gives an AI coding 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": ["serve", "--profile", "curated"]
    }
  }
}

Status

WhiteMagic v9. General release for AI coding agents.

• Supported platforms: Linux x86-64, macOS, Windows.

• The Linux x86-64 artifact is fully static — no glibc or distribution requirements.

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

Related MCP server: Memento

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;

• a complete backup, verification, and restore path;

• no telemetry 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:

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

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

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

Or use the install script (resolves the latest release and verifies the checksum automatically):

curl -fsSL https://raw.githubusercontent.com/lbailey94/whitemagic/main/scripts/install.sh | sh

Verify the installation:

wm --version   # wm 9.0.0
wm doctor      # environment health check

Connect an MCP client

Point any MCP client at:

wm serve --profile curated

The server communicates over stdio and exposes a single wm meta-tool. 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).

Privacy and data

• Your store lives locally at ~/.local/share/whitemagic. Nothing is sent to WhiteMagic-operated services; there is no telemetry.

• 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

Back up the whole store root (LMDB database, search indexes, and all session/state files — not just the lmdb/ subdirectory):

# Stop the server first, then:
wm backup                                  # writes ~/whitemagic-backups/<timestamp>/
wm backup --out /path/to/external/disk     # keep copies OFF the live machine

Each backup contains the full store plus a SHA256SUMS manifest. Restore after a failure (this replaces the target store):

wm restore --backup ~/whitemagic-backups/whitemagic-backup-<timestamp> --force
wm doctor                                  # confirm health after restore

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 (transaction.rollback) is an in-store, short-lived undo — not a substitute for backups.

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

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 a 237-tool archive 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.

Building from source

Requires Rust 1.85+:

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

Documentation

• docs/QUICKSTART.md — the two-process continuity demo

• docs/MCP_CONFIG_GUIDE.md — client configuration

• docs/MULTI_LAPTOP.md — moving between machines (backup/restore, session carry)

• CHANGELOG.md — release notes

• SECURITY.md — reporting vulnerabilities

Migrating from v26 (legacy Python)

If you ran the retired Python version:

wm migrate --v2-dir ~/.whitemagic/users/local/galaxies --dry-run   # preview
wm migrate --v2-dir ~/.whitemagic/users/local/galaxies              # migrate

License

MIT © Lucas Bailey and WhiteMagic Contributors

Support and security

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

• Security: email lbailey94@protonmail.com (please do not open public issues for security reports)