Metadata-Version: 2.4
Name: whitemagic-core
Version: 0.1.0
Summary: Minimal AI memory system with XP-based progressive capability unlocking
Project-URL: Homepage, https://github.com/lbailey94/whitemagic-core
Project-URL: Repository, https://github.com/lbailey94/whitemagic-core
Project-URL: Documentation, https://github.com/lbailey94/whitemagic-core#readme
Project-URL: Bug-Tracker, https://github.com/lbailey94/whitemagic-core/issues
Project-URL: Changelog, https://github.com/lbailey94/whitemagic-core/blob/main/CHANGELOG.md
Author-email: Lucas Bailey <contact@whitemagic.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,levels,mcp,memory,progressive,xp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

<div align="center">

# 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](#quick-start) · [Features](#features) · [MCP Server](#mcp-server) · [CLI Reference](#cli-reference)

</div>

---

## 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

```bash
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

```bash
# 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.).

```bash
wm serve
```

### Connecting to an MCP Client

Add this to your MCP client configuration:

```json
{
  "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:

```json
{
  "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

```bash
# 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

```bash
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](STRATEGY.md) — full design document with module map, level curve, and verification results
- [Full WhiteMagic](https://github.com/lbailey94/WHITEMAGIC) — the complete 877+ tool cognitive OS
- [PyPI](https://pypi.org/project/whitemagic-core/) — `pip install whitemagic-core`
