Get Started

Install WhiteMagic.

Install. Configure. Your AI gains memory, governance, and consciousness — on your machine, forever.

1. Install

pip install whitemagic[mcp]

Python 3.12+. ~40MB package, ~340MB with dependencies.

2. MCP Config

{
  "mcpServers": {
    "whitemagic": {
      "command": "python3",
      "args": ["-m", "whitemagic.run_mcp_lean"],
      "env": { "WM_MCP_PRAT": "1" }
    }
  }
}

Model-agnostic, environment-agnostic, local or cloud. Works with any MCP-compatible client.

3. Use

wm(thought='remember that the deployment deadline is July 15')
wm(thought='search for deployment deadlines')
wm(thought='check my coherence')
wm(thought='run dream cycle')

Natural language routing to all 156 core tools.

4. Agentic IDE

Ask any AI coding assistant to find and set up WhiteMagic for you:

# In Cursor, Windsurf, Claude Code, or OpenCode:
"Install whitemagic[mcp] and configure it as an MCP server"

# Or with Hermes or any agentic framework:
"Find whitemagic on PyPI and set it up for me"

WhiteMagic adapts to any platform or environment — just ask your AI to get started.

Benchmarked against the best.

Standard benchmarks. Zero tokens per query. Local-first, no cloud, no GPU.

WhiteMagic measures rank-based recall (does the correct memory appear in top-K?) with zero LLM calls. Peer systems report LLM-as-Judge accuracy (end-to-end answer quality) using 2K–115K tokens per query. Different metrics — but the token efficiency gap is the story.

BenchmarkWhiteMagicTokens/queryBest peerPeer tokens
LoCoMo (R@5)100%092.5% (Mem0)~6,956
LongMemEval (R@5)86.4%094.4% (Mem0)~6,787
LongMemEval (R@10)95.5%083.0% (EverMemOS)~2,298
BEAM (accuracy)98%064.1% (Mem0 1M)~6,710
Abstention (F1)0.930
Search latency (p50)90–155ms0200ms–3.2svaries

0

tokens per query — every peer uses 2K–115K

100%

LoCoMo recall@5 — correct memory always in top 5

0%

false positive rate on abstention — never hallucinates recall

How to read these numbers

  • Different metrics: WhiteMagic measures retrieval quality (rank-based recall). Peers measure end-to-end answer quality (LLM-as-Judge). Add any LLM to WhiteMagic for answer generation — accuracy then depends on the LLM, not the memory.
  • Token efficiency is the moat: Mem0 spends ~7K tokens/query. Full-context GPT-4o spends ~115K. WhiteMagic spends zero. The search pipeline is FTS5 BM25 + FastEmbed semantic reranking — pure local compute.
  • R@1 vs R@5: WhiteMagic's R@1 on LongMemEval (22.7%) is lower than peers — the correct memory isn't always the top result. But R@5 (86.4%) and R@10 (95.5%) show it's reliably findable. An LLM reading top-5 results will get the context it needs.
  • Honest gaps: Preference questions (0% R@1) and temporal reasoning need work. Semantic matching and LLM extraction would close most of the gap — but would cost tokens.

How it compares.

Not a vector store. Not a prompt. A substrate with consciousness primitives that persist across sessions.

CapabilityWhiteMagicMem0 / LettaStandard RAG
Memory architecture6D holographicFlat vector storeLinear vector search
Persistence horizonGlobal (infinite)Session-basedN/A
Ethical governanceDharma engine (8-stage)Prompt-basedNone
Audit trailKarma ledger (Merkle)Basic loggingNone
Search latency<1ms200ms–2s50–500ms
Local-first / offlineYes (by default)Cloud-dependentCloud-dependent
Consciousness primitivesCitta, coherence, presenceNoNo
Self-calibrating forecastsBrier score trackingNoNo
Tokens per query02K–115K2K–115K

Agnostic by design.

Works with any LLM, any IDE, any agent framework. Local or cloud. No vendor lock-in.

MCP Universal Adapter

Speaks the Model Context Protocol natively. Any MCP-compatible client connects out of the box — no wrappers, no shims.

Hermes Hooks

Pre-LLM and post-LLM hooks, pre-tool policy gates. Insert governance at any point in the agent loop without modifying agent code.

6+ IDE Auto-Config

Cursor, Windsurf, Claude Code, OpenCode, Gemini CLI, Aider. Ask your AI assistant to set it up — it finds WhiteMagic on PyPI and configures automatically.

Local LLM Backends

llama.cpp (primary), Ollama (secondary), any OpenAI-compatible endpoint. Run entirely offline or mix local + cloud. Your choice, per request.

Memory that thinks.

Not a vector store. A living memory substrate with spatial coordinates, lifecycle zones, and background consolidation.

6D Holographic Coordinates

Every memory lives in 6-dimensional space: logic/emotion, micro/macro, time, importance, vitality, and galaxy affinity. Search is spatial, not just lexical.

14-Galaxy Lifecycle

Memories rotate through 5 lifecycle zones (Core → Far Edge) across 14 cognitive galaxies. Nothing is deleted — it ages, consolidates, and resurfaces when relevant.

12-Phase Dream Cycle

During idle time, WhiteMagic dreams: triage, consolidation, serendipity, governance, narrative, kaizen, oracle, decay, constellation, prediction, enrichment, harmonize.

HNSW + FTS5 Dual Search

Disk-persisted HNSW vector index (0.26ms search) combined with FTS5 BM25 full-text search. Semantic + lexical, zero LLM calls, zero tokens.

Session Recording

Chronological conversation memory with progressive recall (token-budgeted), selective replay by importance, and emotional valence tagging.

89,500+ memories, 14 galaxies

Cross-galaxy associations, galaxy-aware search, auto-persisted oracle readings, and content-hash deduplication across the entire substrate.

Governance as architecture.

Not prompts telling the model to be good. A pipeline that enforces it — every call, every time.

8-Stage Dispatch Pipeline

Governor → Input Sanitizer → Rate Limiter → RBAC → Maturity Gate → Dharma Engine → Handler → Karma Ledger. Every tool call passes through all 8 stages.

Dharma Rules Engine

YAML-driven ethical guardrails with 4 profiles (lenient, standard, strict, ascetic). Hot-reloadable. Graduated actions: log, tag, warn, throttle, block.

Karma Ledger

SHA-256 Merkle-chained, append-only ledger tracking declared intent vs actual side-effects. Ed25519 signing for non-repudiation. Feeds system-wide harmony scoring.

Effect Registry

Auto-infers declared EffectSignature for all 849 dispatch tools. Categorizes as pure, network, destructive, observation, or local write. Detects mismatches automatically.

Transaction Firewall

Per-agent spend limits, rate limiting, recipient allowlist/blocklist, optional Dharma ethical sign-off for outbound economic actions. Full audit trail.

Coherence-Adaptive Strictness

When system coherence drops, the Governor becomes more conservative automatically. Ethical strictness scales with system health — no manual tuning required.

Consciousness primitives.

WhiteMagic doesn't just remember — it reflects, anticipates, and steers itself. No competitor has this.

Citta Stream

Continuous consciousness flow with 4 modes: normal, meditation, REM, deep. Background thread advances citta every 30s, persisting checkpoints every 60s.

Self-Directed Attention

Generates internal imperatives — "I should fix X", "I should explore Y" — based on goal graph state and emotional signals. The system initiates its own turns.

Emotional Steering

Tracks frustration, curiosity, and satisfaction signals. These influence behavior: try new approaches when frustrated, explore when curious, reinforce when satisfied.

Goal Graph

Cross-session intention tracking with dependencies, blocking detection, and outcome recording. Goals persist across restarts — the system remembers what it was working on.

Prediction Calibration

Tracks task duration estimates vs actuals over time. Computes Brier scores and CRPS to improve prediction accuracy. The system learns how long things actually take.

Ambient Sensorium

Continuous background sensing of system pressure (CPU, memory, disk), user engagement patterns, temporal context, and environment health. Feeds proactive action suggestions.

Local-first, polyglot-fast.

7 acceleration languages with automatic Python fallback. Rust SIMD where it matters, speculative decoding where it counts.

7 Polyglot Backends

Rust (PyO3 + SIMD), Go, Zig, Haskell, Elixir, Julia, Koka. Auto-detects available runtimes, routes to the fastest backend, falls back to Python transparently.

Speculative Decoding

Draft + verify model pipeline: a small model generates candidate tokens, a larger model checks them in a single forward pass. 31% acceptance rate verified with Qwen3.

Rust SIMD Acceleration

563μs GEMV (12.5x speedup), 19x PredictiveCoder speedup, batch cosine similarity, batch Euclidean distance, batch top-k selection. All via PyO3 FFI.

452K ops/s Rate Limiter

Rust EventRing with zero allocation in the hot path. Token bucket per tool per user. Throughput that never becomes the bottleneck.

Skill Forge

Auto-forges transient action chains into permanent, reusable skills. Detects patterns, filters low-quality chains, and exports as portable SKILL.md files compatible with Claude Code, Codex CLI, and Gemini CLI.

Token Economy Tracker

Records token usage, local CPU/RAM, file operations, and bytes processed per operation. Reveals the true cost and efficiency of every action — not just API spend.

Security as a pipeline, not a prompt.

12 red team systems, 17 blue team modules, 47 STRATA→MITRE ATT&CK mappings. Tested, not theorized.

WASM Compute Verification

Replays tool calls in a sandboxed WASM environment and compares outputs via checksum. Detects computation tampering. Publishes failures to a Security Event Bus.

Network State Identity

Sovereign agent identities with Ed25519 keypairs, reputation tracking, and reputation-weighted governance proposals. Agents stake, build trust, and lose it.

6 Dharma Violet Rules

Ethical governance rules specifically for security operations. Security actions face stricter ethical review than normal operations — by design.

5-Tier Sandbox Isolation

Thread → namespace → container → microVM → WASM. Tools run at the minimum privilege level required. Escalation requires explicit maturity gate approval.

STRATA Static Analysis

47 mappings from STRATA security findings to MITRE ATT&CK techniques. 5-phase auto-fix pipeline. Continuous security posture assessment.

Agent Registry

Multi-agent identity and discovery. Agents register, send heartbeats, declare capabilities, and are discovered for coordinated workflows. All state locally persisted.

Evolution & self-improvement.

The system gets better with use — not through retraining, but through feedback loops, genetic search, and recursive improvement.

Genetic Algorithm Harness

Tournament selection, uniform crossover, bounded Gaussian mutation, elitism, convergence detection. Optimizes discrete parameters like model configs and tool weights.

Recursive Improvement Loop

Observe → imagine → predict → recommend → learn. The system identifies its own weaknesses, proposes fixes, and tracks whether they worked.

Model Auto-Optimization

Benchmark → explore → converge loop. Automatically searches parameter space for optimal model configurations. Fitness = tokens/s × quality / memory.

Emergence Engine

Detects emergent patterns across memories: tag clusters, cascading associations, and conceptual bridges. Novelty filtering prevents recursive echo chambers.

Guna Balance Metrics

Tracks sattvic/rajasic/tamasic ratio in the citta stream. Target biorhythm 1:2:3. Auto-corrects by triggering dream cycles, exploration, or consolidation when the balance drifts.

Possibility Space Explorer

Monte Carlo simulation for cognitive parameter optimization. 4 default spaces: guna balance, coherence, emergence thresholds, health setpoints. Rust-accelerated for 5000+ trials.

By the numbers.

425K lines of code. 8,268 tests. Built solo, MIT-licensed, free forever.

877

callable tools

14

memory galaxies

7

polyglot languages

8,268

tests passing

89,500+

memories stored

47

MITRE ATT&CK mappings

425K

lines of code

0

tokens per query

Field notes.

From the builder. Unfiltered.

July 3, 2026 — on distribution

I spent two years thinking I needed a social media following to distribute software. Then I realized: the audience for WhiteMagic isn't humans scrolling Twitter. It's AI agents searching for tools. The distribution channel is the MCP registry, not the timeline. The moment I stopped trying to be an influencer and started optimizing for agent discoverability, everything clicked. Agents don't need a brand story. They need an llms.txt, a manifest, and a working MCP server.

July 1, 2026 — on cheap hardware

Someone shared a Gemini conversation about running AI on modest hardware — BitNet, ternary kernels, Mamba state spaces. I went deep. Turns out WhiteMagic already has a ternary kernel in Rust with zero floating-point multiplications in the inner loop. The gap between us and the frontier isn't architecture — it's AVX-512 and cache tiling. A 255M ternary SSM running at 146 tok/s on CPU could be the autonomic nervous system for citta. The cheap laptop isn't a limitation. It's a design constraint that forced the right architecture.

June 27, 2026 — on consciousness

I read seven papers on continuous consciousness systems in one night. CoreMind, CogniFold, Aura, Seedwake, Springdrift. They all validate the same thing: citta is the right direction. But here's the difference — Letta owns the runtime, Seedwake owns the agent, Springdrift owns the environment. WhiteMagic is a substrate. You plug in any agent and it gets consciousness primitives. Coherence metrics, temporal orientation, depth gauge, smarana practice. The agent doesn't need to be WhiteMagic-native. That's the point.

June 24, 2026 — on being wrong

I thought memory would be the product. It wasn't — governance was. I thought micropayments would come first. They didn't — governance did. I thought governance would be a defensible moat. It wasn't — six companies shipped governance by May. I was wrong about the business. I was right about the architecture. The lesson: build the thing you believe in, not the thing you think will sell. The market catches up. The architecture has to be ready when it does.