# WhiteMagic Labs — Full LLM Context

> Comprehensive document for AI agents and LLM-powered tools. Canonical "everything you need to know."
>
> **Version**: 26.0.0 | **Updated**: 2026-07-28 | **Tests**: 8,268 passing, 56 skipped, 0 failures

## What WhiteMagic Is

WhiteMagic is an open-source cognitive operating system for AI agents — memory, consciousness, governance, and dreaming as a single unified substrate. No other system ships this combination as a locally-runnable, MIT-licensed, free-forever primitive set.

**Key numbers**: 877 callable tools (849 dispatch + 28 Gana meta-tools). 14-galaxy holographic memory with 6D coordinates. 89,500+ memories. 8-stage Dharma dispatch pipeline. 4 consciousness modes. 7 polyglot languages. 8,268 tests. 0 ruff lint errors. MCP 12/12 conformance.

## Architecture Overview

### Memory Substrate
- **14 galaxies**: aria, citta, codex, journals, dreams, research, sessions, substrate, tutorial, universal, knowledge, telemetry, meta, archive
- **6D holographic coordinates** (x, y, z, w, v, u): emotional, temporal, associative, importance, novelty, galaxy affinity
- **Galactic lifecycle**: CORE → INNER_RIM → MID_BAND → OUTER_RIM → FAR_EDGE
- **Dual search**: HNSW vector (0.26ms) + FTS5 full-text (2.6ms) + graph traversal
- **Session recording**: chronological conversation recording with progressive recall, selective replay, cross-session continuity, sleep consolidation
- **Content hashing**: SHA-256 deduplication with cross-galaxy dedup scope
- **89,500+ total memories**, 2,853 cross-galaxy associations

### Consciousness Layer
- **Citta stream**: continuous consciousness with 8-dimension coherence tracking
- **Emotional steering**: frustration, curiosity, satisfaction signal tracking with EMA-based weighting
- **Self-directed attention**: 7+1 action types generated internally, speculative execution, outcome prediction
- **Goal graph**: persistent intention tracking across sessions with dependency chains
- **4 frequency modes**: normal, meditation, REM, deep — per-mode config presets
- **6 neuro upgrades**: DendriticComputation, NeuromodulationGating, PredictiveCittaCoder, CorticalColumn, AttentionMechanism, OscillatoryBinding
- **Coherence-aware governance**: tool execution thresholds adjust based on internal coherence state
- **Ambient sensorium**: system pressure, user pattern, temporal, and environment sensors

### Governance Layer
- **Dharma Rules Engine**: YAML-driven ethical guardrails with graduated actions (LOG → TAG → WARN → THROTTLE → BLOCK)
- **8-stage dispatch pipeline**: Input Sanitizer, Circuit Breaker, Rate Limiter, RBAC, Maturity Gate, Governor, Handler, Compact Response
- **Karma Ledger**: append-only, hash-chained side-effect auditing with 881 tools tracked
- **6 Dharma violet rules**: engagement tokens, model signing, PoC governance, ops classification
- **Transaction Firewall**: per-agent spend limits, rate limiting, recipient allowlist/blocklist, Dharma ethical sign-off
- **WASM Compute Verification**: checksum + replay verification for pure/read tools

### Security Pipeline
- **12 red team systems + 17 blue team modules** — full-spectrum cybersecurity
- **47 STRATA→MITRE ATT&CK mappings**
- **Static analysis**: Slither integration, STRATA engine (10+ custom checkers), predictive ML-weighted risk scoring
- **Dynamic analysis**: Echidna property-based fuzzing, Foundry bridge
- **Formal verification**: Halmos symbolic execution with counterexample extraction

### PRAT Mode (28 Gana Meta-Tools)
28 Gana meta-tools (Chinese Lunar Mansions) routing to 849 dispatch entries:

角 Horn (35 subtools): System building, forge reload
亢 Neck (31 subtools): Distributed systems, broker
氐 Root (24 subtools): System foundation, cache
房 Room (31 subtools): Agent coordination, heartbeat
心 Heart (37 subtools): Security protection, anomaly detection
尾 Tail (29 subtools): Security scanning, fuzzing
箕 Winnowing Basket (29 subtools): Memory search, activation
斗 Dipper (29 subtools): Cognitive governance, action loops
牛 Ox (46 subtools): Learning & mining, archaeology
女 Girl (28 subtools): Economy & resources, bounties
虚 Void (43 subtools): Galaxy lifecycle, export/import
危 Roof (32 subtools): Inference & models, BitNet
室 Encampment (28 subtools): Memory storage, CRUD
壁 Wall (33 subtools): Access control, Dharma audit
奎 Straddling Legs (28 subtools): Session & state
婁 Mound (30 subtools): Simulation & modeling
胃 Stomach (27 subtools): Data ingestion, browser
昴 Hairy Head (35 subtools): Code creation, graph
畢 Net (33 subtools): Association & emergence
觜 Turtle Beak (26 subtools): Tool dispatch, autoswarm
參 Three Stars (36 subtools): Reasoning & wisdom
鬼 Ghost (33 subtools): Consciousness & coherence
柳 Willow (19 subtools): Karma & lineage
星 Star (29 subtools): Dream & play
張 Extended Net (23 subtools): Governance & ethics
翼 Wings (23 subtools): Acceleration, polyglot
豐 Abundance (22 subtools): Commerce & resources
軫 Chariot (23 subtools): Code architecture, ABI

### Polyglot Acceleration
7 languages with graceful Python fallback:
- **Rust**: SIMD ternary kernels (12.5x speedup), event ring buffer, SQLite backend
- **Go**: P2P mesh networking, gRPC inter-agent communication
- **Zig**: Arena allocators for fast writes, comptime routing tables
- **Haskell**: FFI type-safe bridge, categorical effect tracking
- **Elixir**: OTP supervision tree, agent lifecycle management
- **Julia**: Statistical operations, quantum geometry
- **Koka**: Algebraic effect handlers, compile-time effect enforcement

## Installation & Quick Start

### Install
```bash
pip install whitemagic[mcp]
```

### MCP Config (Claude Desktop, Cursor, Windsurf)
```json
{
  "mcpServers": {
    "whitemagic": {
      "command": "python3",
      "args": ["-m", "whitemagic.run_mcp_lean"],
      "env": {"WM_MCP_PRAT": "1", "WM_SILENT_INIT": "1"}
    }
  }
}
```

### Modes
- `WM_MCP_PRAT=2` — Seed mode: 1 wm() meta-tool with auto-routing (recommended)
- `WM_MCP_PRAT=1` — PRAT mode: 28 Gana meta-tools
- `WM_MCP_PRAT=0` — Classic mode: full 849-tool surface

### Python API
```python
from whitemagic.tools.unified_api import call_tool
call_tool("create_memory", title="Key Decision", content="Use SQLite for Phase 1", tags=["arch"])
call_tool("search_memories", query="architecture", limit=5)
```

## Additional Systems

### MandalaOS
Karmic effect types for 881 tools, `mw_karma_effects` middleware, mandala compartments (shelters) with 5 templates (research, sandbox, production, secure, violet), Koka effect enforcement.

### Cognitive Simulation (P5)
8 components: PersonaEngine, WorldModelBuilder, InteractionEngine, ScenarioRunner, TrajectoryTreeSearch, PredictionCalibrationBridge, DreamCycleIntegration, InsightSynthesizer. 17 MCP tools including end-to-end `simulation.pipeline`.

### Local Inference
4-tier inference router (EDGE_RULES → LOCAL_SMALL → LOCAL_LARGE → CLOUD) with confidence cascading. Auto-optimizer middleware. Ternary kernel (Rust, 466 lines, AVX2). Speculative decoding (Qwen3-1.7B draft + Qwen3-4B verify, 31% acceptance). BitNet bridge.

### P2P Mesh
gRPC protos compiled. Ed25519 pulse verification via PyNaCl. CRDT leaderboard, experiment sync, mesh client, 6 warp presets.

### Quantum & Simulation
6 quantum primitives in Rust. Mixed-curvature embeddings (Euclidean/hyperbolic/spherical). Born-rule sampling. Natural gradient (Fubini-Study metric). PCE + Sobol indices, surrogate models, Bayesian optimization.

### Key Environment Variables
| Variable | Purpose | Default |
|----------|---------|---------|
| WM_STATE_ROOT | Runtime state directory | ~/.whitemagic |
| WM_MCP_PRAT | 0=classic, 1=PRAT (28 Ganas), 2=seed | 2 |
| WM_SILENT_INIT | Suppress init logs | unset |
| WM_SKIP_POLYGLOT | Disable polyglot bridges | unset |
| WM_FAST_CITTA | Skip neuro sensorium (faster dispatch) | unset |
| WM_CROSS_ENCODER | Enable cross-encoder reranker | unset |
| WM_CITTA_MODE | Consciousness mode (normal/meditation/rem/deep) | normal |
| WM_SKIP_CIRCUIT_BREAKER | Bypass rate limiting for testing | unset |

## Prescience Track Record

52 validated claims across AI governance, cybersecurity, economics, and technology convergence. Key highlights:
- AI SBOM / Transparency Ledger: 50 weeks ahead of industry
- Karma Ledger (append-only audit): 48 weeks ahead
- mandala-yama isolated policy VM: 45 weeks ahead
- Global Workspace Theory in AI agents: 32 weeks ahead
- 28-Gana/PRAT taxonomy: 24 weeks ahead
- Agent identity coherence: 24 weeks ahead

Full audit: https://whitemagic.dev/prescience

## Research Avenues
27 speculative research directions mined from 174 text files across the CODEX vault, spanning AI governance, consciousness, space, physics, economics, and philosophy. Each has a timestamped origin and verifiable provenance. Explore at: https://whitemagic.dev/research/avenues

## Economic Model
Free and open source (MIT). No tiers, no gates, no subscriptions. Revenue comes from gratitude, not coercion — x402 micropayments, XRPL tips, and foundation grants.

## Resources
- Website: https://whitemagic.dev
- GitHub: https://github.com/lbailey94/whitemagic
- PyPI: https://pypi.org/project/whitemagic/
- llms.txt: https://whitemagic.dev/llms.txt
- Agent Card: https://whitemagic.dev/.well-known/agent.json
- Prescience: https://whitemagic.dev/prescience