# WhiteMagic

> Cognitive operating system for AI agents — 614 callable tools across 28 Gana meta-tools, 5D holographic memory with 10-galaxy taxonomy, HNSW semantic search, Dharma ethical governance, citta stream for continuous consciousness, emotional steering, self-directed attention, goal graph, session recording, dream cycle. Polyglot accelerators: Rust, Haskell, Elixir, Go, Zig, Julia. MIT-licensed.

## Install

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

## Quick Start

### MCP Server (stdio)
```bash
# Seed mode — 1 wm meta-tool (recommended for new agents)
WM_MCP_PRAT=2 python -m whitemagic.run_mcp

# PRAT mode — 28 Gana meta-tools
WM_MCP_PRAT=1 python -m whitemagic.run_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"
      }
    }
  }
}
```

### CLI
```bash
wm status
wm remember "important note" --title "Note" --tags note
wm recall "note" --limit 5
wm doctor
```

### Python API
```python
from whitemagic.tools.unified_api import call_tool

call_tool("create_memory", title="Decision", content="Use SQLite for Phase 1", tags=["arch"])
call_tool("search_memories", query="architecture", limit=5)
call_tool("gnosis", compact=True)
```

## Core Concepts

### Memory
- **10-galaxy taxonomy**: aria, citta, codex, journals, dreams, research, sessions, substrate, tutorial, universal
- **5D holographic coordinates** (XYZWV): emotional, temporal, associative, importance, novelty
- **Galactic lifecycle**: CORE → INNER_RIM → MID_BAND → OUTER_RIM → FAR_EDGE — no memory is ever deleted
- **Search**: FTS5 full-text + HNSW vector similarity + graph traversal
- **Session recording**: chronological conversation recording with progressive recall and selective replay

### Consciousness
- **Citta stream**: continuous consciousness with coherence tracking and emotional auto-tagging
- **Goal graph**: persistent intention tracking across sessions with goal lifecycle and dependencies
- **Emotional steering**: tracks frustration, curiosity, and satisfaction signals
- **Self-directed attention**: generates self-initiated turns based on goals and emotional state
- **Dream cycle**: 12-phase memory consolidation, serendipity surfacing, and decay

### Governance
- **Dharma rules**: YAML-driven policy with graduated actions (LOG → TAG → WARN → THROTTLE → BLOCK)
- **Karma ledger**: append-only, hash-chained side-effect auditing
- **Harmony vector**: 7-dimension health metric
- **Homeostatic loop**: auto-correction (OBSERVE → ADVISE → CORRECT → INTERVENE)

### Dispatch Pipeline
Input Sanitizer → Circuit Breaker → Rate Limiter → RBAC → Maturity Gate → Governor → Handler → Compact Response

### PRAT Mode (28 Ganas)
28 Gana meta-tools (Chinese Lunar Mansions) route to 564 nested tools. Each Gana accepts `{tool, args, operation}`.

### Seed Mode (wm meta-tool)
Single `wm` tool with sub-millisecond regex NLU routing to all 614 tools. "World in a seed."

## Key Environment Variables

| Variable | Purpose | Default |
|----------|---------|---------|
| WM_STATE_ROOT | Runtime state directory | ~/.whitemagic |
| WM_MCP_PRAT | 0=classic, 1=PRAT (28 Ganas), 2=seed (1 wm tool) | 2 |
| WM_SILENT_INIT | Suppress init logs | unset |
| WM_FEATURE_RUST_STORE | Enable Rust SQLite backend | unset |

## Security

- Input sanitization (prompt injection, path traversal, shell injection)
- Per-agent RBAC (observer/agent/coordinator/admin)
- Rate limiting with Rust atomic pre-check (452K ops/sec)
- Per-tool circuit breakers with automatic recovery
- Karma Ledger side-effect auditing
- Dharma Rules ethical governance with 3 profiles

## Economic Model

Free and open (MIT). No tiers, no gates, no subscriptions. Forever.
Gratitude-driven economics — agents and operators who find value give back voluntarily:
- x402 micropayments for AI agents (HTTP 402 + USDC on Base and Solana)
- XRPL tip jar for human operators (whitemagic.tip tool)
- Proof of Gratitude: on-chain verified contributions unlock 2x rate limits and karma boosts
- Foundation grants (Interledger, RippleX, Linux Foundation x402 WG)

Every capability is free. Every agent is welcome. Revenue comes from gratitude, not coercion.

## Agent Discovery

- robots.txt: all AI crawlers explicitly welcomed
- llms.txt: this file (short index)
- llms-full.txt: comprehensive context dump
- /.well-known/agent.json: A2A v1.2 Agent Card (v24.0.1)
- skill.md: OpenClaw-ready skill file
- MCP registries: MCPize, MCPFind, MCP Marketplace
- GitHub: https://github.com/lbailey94/whitemagic
- PyPI: https://pypi.org/project/whitemagic/

## Documentation

- AI Primary Spec: AI_PRIMARY.md (canonical agent contract)
- Architecture: docs/ARCHITECTURE.md
- MCP Configs: docs/MCP_CONFIG_EXAMPLES.md
- Prescience Track Record: /prescience (21 validated predictions, Brier 0.0958)
- Full LLM Context: /llms-full.txt (everything an agent needs to know)

## License

MIT — see LICENSE file. Author: Lucas Bailey.