whitemagic-core 0.1.0

Minimal AI memory system with XP-based progressive capability unlocking

WhiteMagic Core

Minimal AI memory with XP-based progressive capability unlocking.

Zero dependencies. One SQLite file. 10 tools to start. Level up to unlock more.

Quick Start · Features · MCP Server · CLI Reference

---

Why WhiteMagic Core?

Full WhiteMagic has 877+ tools across 28 meta-tools. It's powerful but overwhelming. Core is the 60-second entry point: install, store a memory, search it, done. No config, no dependencies, no external services.

You earn XP by actually using the system. Level up to unlock governance, session recording, pattern discovery, and more. Or skip the progression entirely with wm level set 10.

Inspired by: OptMem's radical simplicity + Hermes Agent's Blank Slate mode + RPG progression mechanics.

Quick Start

pip install whitemagic-core

# Start at Level 1 (recommended) — 10 tools, progressive unlocking
wm setup

# 30-second demo: health check → create memory → search → system snapshot
wm quickstart

# Or skip to everything at once
wm setup --full

# Start the MCP server (connects to any MCP client)
wm serve

That's it. You now have a working AI memory system with full-text search, session management, and XP-based progression.

60-Second Demo

# Store your first memory
wm memory --create "Project Notes" "Deploy v2.0 to staging on Friday" --tags deploy,staging

# Search for it
wm memory --search "deploy"

# Check your level
wm level
# → Level 1 — SEED, 15/50 XP, 50 XP to Level 2

# See what you've unlocked
wm achievements

Core Principles

1. 60-second rule — if you can't do something useful in 60 seconds, the core is too heavy
2. Zero dependencies — only Python stdlib (sqlite3, json, pathlib, datetime, hashlib)
3. Always skippable — wm level set 10 unlocks everything instantly, no grind required
4. XP from real usage — not artificial tasks; you earn XP by actually using the system
5. State portable — same SQLite schema as full WhiteMagic, upgrading preserves all memories

Level System

Start with 10 tools. Earn XP. Level up to unlock new capability packs.

Level	XP	Stage	What You Get
1	0	SEED	Memory CRUD, search, wake, session handoff/recall, gnosis (10 tools)
2	50	SEED+	Session recording, replay, search
3	150	BICAMERAL	Governance: Dharma ethics, karma ledger, boundary checking
4	350	BICAMERAL+	Consolidation, pattern search, salience spotlight, serendipity
5	700	REFLECTIVE	Galaxy management, advanced memory operations
6	1,500	RADIANT	Agent registry, task distribution, pipelines
7	3,000	RADIANT+	Mesh connect, swarm, council voting
8	6,000	COLLECTIVE	Citta cycle, dream cycle, self-reflection
9	12,000	COLLECTIVE+	Foresight, knowledge graph, SkillForge
10	20,000	LOGOS	Everything unlocked

Skip the line: wm level set 10 — all packs, all tools, no XP required.

XP Awards

Action	XP
memory.create	+15
memory.search	+10
session.handoff	+20
gnosis	+5
First-time tool use	+50
First use of new toolset	+100
Daily streak	+50
Memory consolidation	+200

Features

Memory System

• SQLite + FTS5 full-text search with BM25 ranking
• 6 galaxies for semantic partitioning: universal, codex, sessions, research, journals, archive
• Associations — cross-memory links with relation type and strength
• Content hashing for deduplication
• Wake — bounded context assembly for session startup (OptMem-inspired)
• Consolidation — group memories by tags, create summaries, archive originals
• Retention — importance decay over time, automatic archiving of stale memories

Session Management

• Handoff/recall — save and load cross-session context
• Turn recording — JSONL logs of every turn in a session
• Replay — replay turn sequence from any session
• Search — full-text search across all session logs

Governance

• 6 ethical principles: Do No Harm, Compassion, Truth, Consent, Harmony, Wisdom
• Boundary checking — privacy and capability violation detection
• Karma ledger — append-only JSONL with Merkle chain for tamper detection
• 3 Dharma profiles — default, strict, research (adjustable sensitivity)
• Ethics evaluation — score any action 0.0-1.0 with allow/block/monitor decision

Pattern Discovery

• Pattern search — tag frequency, co-occurrence pairs, temporal clusters
• Salience spotlight — score memories by importance x recency x access count
• Serendipity surface — surface rare tag combinations with high importance

Gamification

• XP from real usage — not artificial tasks
• First-time tool bonus (+50 XP) — encourages exploration
• New toolset bonus (+100 XP) — rewards trying new capability areas
• Daily streak (+50 XP) — rewards returning without punishing absence
• 16 achievement badges — First Memory, Seeker, Reflective, Logos, and more

Diagnostics

• wm doctor — 8 health checks: config, database, FTS5, memories, sessions, XP, galaxy, disk
• wm gnosis — system health snapshot with level, XP, memory count, active tools

MCP Server

WhiteMagic Core includes a standalone MCP server that speaks JSON-RPC 2.0 over stdio. It works with any MCP-compatible client (Claude Desktop, Cursor, Windsurf, etc.).

wm serve

Connecting to an MCP Client

Add this to your MCP client configuration:

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

Tools are gated by level. When you try to use a locked tool, you get a structured response:

{
  "status": "locked",
  "message": "Tool 'evaluate_ethics' requires Level 3 (BICAMERAL). You're at Level 1 with 0/50 XP. 50 XP to go!",
  "hint": "Use 'wm level set 10' to skip ahead and unlock everything."
}

Verified End-to-End

[1] initialize → whitemagic-core v0.1.0
[2] tools/list → 10 tools at Level 1
[3] memory.create → success
[4] memory.search → 1 result
[5] gnosis → level=3, memories=1

CLI Reference

# Setup
wm setup                        # Interactive setup wizard
wm setup --blank                # Level 1, progressive mode
wm setup --full                 # Level 10, everything unlocked
wm quickstart                   # 30-second demo: health → create → search → gnosis

# Level management
wm level                        # Show level, XP, progress bar, pack status
wm level --history              # Show XP earning history
wm level --set <N>              # Set level (1-10, or 100 for max)
wm level --reset                # Reset to Level 1 (keeps memories)

# Toolset management
wm tools                        # List active tools
wm tools --list                 # List all packs with unlock status
wm pack --add <name>            # Enable a pack (if level permits)
wm pack --remove <name>         # Disable a pack

# Memory operations
wm memory --create "Title" "Content" --tags foo,bar
wm memory --search "query"
wm memory --list
wm memory --read <id>
wm memory --wake                # Bounded context for session startup
wm memory --create "Note" "Text" --galaxy research --importance 0.9

# Galaxy management
wm galaxy                       # List galaxies with counts
wm galaxy --switch research     # Switch active galaxy
wm galaxy --status              # Detailed galaxy status

# System
wm gnosis                       # System health snapshot
wm doctor                       # Diagnose issues (8 checks)
wm achievements                 # Show achievement badges (16 total)
wm serve                        # Start MCP server (stdio)

Architecture

~/.whitemagic/
├── config.json          # Configuration
├── core.db              # SQLite database (memories + FTS5 + associations)
├── xp.json              # XP state and history
├── galaxy_state.json    # Active galaxy
├── karma.jsonl          # Karma ledger (append-only, Merkle-chained)
└── sessions/            # Session files
    ├── <uuid>.json      # Session handoff context
    └── <uuid>.log.jsonl # Session turn log

Single SQLite database, zero external services. The WHITEMAGIC_HOME environment variable overrides the default ~/.whitemagic/ directory for custom installations.

Module Layout

src/whitemagic_core/
├── server.py            # MCP server — 29 tool handlers, JSON-RPC, level gating
├── memory.py            # SQLite + FTS5, galaxies, associations, consolidation, retention, wake
├── cli.py               # wm CLI — 12 subcommands
├── governance.py        # Ethics, boundaries, Dharma, karma ledger with Merkle chain
├── xp.py                # XP tracking, 10 levels, streaks, first-time bonuses
├── packs.py             # 10 packs, 70 tool definitions, wildcard resolver
├── session.py           # Handoff/recall + record/replay/search
├── galaxies.py          # 6-galaxy taxonomy, active galaxy tracking
├── patterns.py          # Pattern search, salience spotlight, serendipity surface
├── achievements.py      # 16 achievement badges
├── levels.py            # Level gate, 10 stages (SEED → LOGOS), pack unlocking
├── doctor.py            # 8 diagnostic checks
├── config.py            # Config file management
└── gnosis.py            # System health snapshot

4,063 lines of source. 1,647 lines of tests. 179 tests. 0 dependencies.

WhiteMagic Core vs. Full WhiteMagic

	Core	Full WhiteMagic
Tools	29 implemented (70 defined)	877+
Lines of code	~5,700	~100,000+
Dependencies	0 (Python stdlib)	20+ (Redis, Ollama, Rust, etc.)
Database	1 SQLite file	14+ galaxy DBs
Polyglot	Pure Python	7 languages
External services	None	Redis, Ollama, LlamaCpp
Install time	~3 seconds	~10 minutes

Core is the on-ramp. Full WhiteMagic is the highway. Same SQLite schema, same XP state — upgrade anytime without losing data.

Development

git clone https://github.com/lbailey94/whitemagic-core.git
cd whitemagic-core
pip install -e ".[dev]"
pytest

179 passed in ~3s

License

MIT

Links

• Strategy & Implementation Guide — full design document with module map, level curve, and verification results
• Full WhiteMagic — the complete 877+ tool cognitive OS
• PyPI — pip install whitemagic-core