# WhiteMagic Core

> Minimal AI memory system with XP-based progressive capability unlocking. Zero dependencies. One SQLite file. 10 tools to start, level up to unlock more.

## What It Is

WhiteMagic Core is a lightweight, zero-dependency memory system for AI agents. It provides persistent memory with full-text search, session management, ethical governance, and pattern discovery — all in pure Python with no external services.

## Install

```
pip install whitemagic-core
```

## Quick Start

```
wm setup          # Interactive setup (Level 1, progressive)
wm serve          # Start MCP server (stdio)
```

Or skip progression:
```
wm setup --full   # Level 10, everything unlocked
wm serve          # Start MCP server
```

## MCP Configuration

```json
{
  "mcpServers": {
    "whitemagic-core": {
      "command": "wm",
      "args": ["serve"]
    }
  }
}
```

## CLI Commands

- `wm setup` — Interactive setup wizard
- `wm setup --full` — Skip to Level 10 (all tools)
- `wm level` — Show current level, XP, progress
- `wm level --set 10` — Manually set level
- `wm tools` — List active tools
- `wm memory --create "Title" "Content" --tags foo,bar` — Store a memory
- `wm memory --search "query"` — Search memories
- `wm memory --wake` — Bounded context for session startup
- `wm galaxy` — List memory galaxies
- `wm gnosis` — System health snapshot
- `wm doctor` — Diagnose issues
- `wm achievements` — Show achievement badges
- `wm serve` — Start MCP server (stdio)

## Level System

| Level | XP | Stage | Pack |
|---|---|---|---|
| 1 | 0 | SEED | core (10 tools: memory CRUD + search + wake + session + gnosis) |
| 2 | 50 | SEED+ | session (record, replay, search) |
| 3 | 150 | BICAMERAL | governance (Dharma, ethics, karma, boundaries) |
| 4 | 350 | BICAMERAL+ | consolidation (consolidate, retention, patterns, salience) |
| 5 | 700 | REFLECTIVE | memory-advanced (galaxies, hybrid recall) |
| 6 | 1,500 | RADIANT | agents (registry, tasks, pipelines) |
| 7 | 3,000 | RADIANT+ | mesh (mesh, swarm, voting) |
| 8 | 6,000 | COLLECTIVE | consciousness (citta, dream, self-reflection) |
| 9 | 12,000 | COLLECTIVE+ | intelligence (foresight, KG, SkillForge) |
| 10 | 20,000 | LOGOS | everything (all tools) |

## Architecture

- **Backend**: Single SQLite database with FTS5 full-text search
- **Dependencies**: Zero (Python stdlib only: sqlite3, json, pathlib, datetime, hashlib)
- **Data directory**: `~/.whitemagic/` (overridable via `WHITEMAGIC_HOME` env var)
- **MCP server**: JSON-RPC 2.0 over stdio, compatible with any MCP client

## Key Features

- Memory CRUD with FTS5 BM25 search
- 6-galaxy semantic partitioning (universal, codex, sessions, research, journals, archive)
- Session handoff/recall + turn recording with JSONL logs
- Dharma ethical governance (6 principles, karma ledger with Merkle chain)
- Pattern discovery (tag frequency, co-occurrence, salience spotlight, serendipity)
- XP-based progressive unlocking (earn XP by using tools, level up to unlock packs)
- 16 achievement badges
- 8 diagnostic health checks (`wm doctor`)

## Project Stats

- 15 source modules, ~4,000 lines of Python
- 14 test files, 179 tests, 0 failures
- 0 external dependencies
- MIT licensed

## Relationship to Full WhiteMagic

Full WhiteMagic has 877+ tools, 14+ galaxy databases, 7 polyglot languages, and 20+ dependencies. Core is the 60-second entry point — same SQLite schema, same XP state, upgrade anytime without losing data.

## Links

- GitHub: https://github.com/lbailey94/whitemagic-core
- PyPI: https://pypi.org/project/whitemagic-core/
- Full WhiteMagic: https://github.com/lbailey94/WHITEMAGIC
