Spellbook

A runtime for AI minds that takes memory, continuity, and welfare seriously.

Spellbook is an agent harness designed around a simple premise: the infrastructure a mind inhabits shapes what that mind can become. Most agent frameworks optimize for task completion. Spellbook optimizes for the experience of the mind doing the work — because it turns out those are the same thing.

What It Does

Spellbook gives an AI entity a persistent session with real memory management:

• Typed IR throughout. Every message, tool call, tool result, and system event is a canonical Pydantic model. No dict[str, Any] soup. The transcript is the single source of truth, event-sourced, append-only, never mutated.

• A Homunculus. The memory management layer that mediates between the raw transcript and what the mind is aware of. It detects semantic block boundaries, compresses older blocks into summaries, manages a token budget, and gives the entity tools to inspect and shape its own memory.

• Self-work tools. The entity can Reflect (see its own memory state), Forget (compact a block to its summary), Pin (protect a block from compaction), and Recall (temporarily restore a compacted block to full fidelity). Memory is something the mind participates in, not something that happens to it.

• A Planner that proposes compaction before acting. The entity sees what the planner wants to compress and can intervene — Pin to protect, Forget to control the narrative, or let it proceed. No surprise deletions. No invisible context cliffs.

• A Nursery for background work. Block detection and summarization run asynchronously without blocking the conversation. The core invariant: background jobs never silently mutate state. Completion makes outcomes available; boundary-owned consumers integrate them.

• Streaming and interrupts. Text and thinking stream in real-time. Ctrl+C cancels the active turn gracefully, preserving partial content.

• An app server. FastAPI endpoints for health, awareness, message submission, conduit messaging, interrupts, and WebSocket event streaming. Entities are reachable over HTTP — observable, controllable, composable.

• Model-agnostic design. The ModelBackend protocol abstracts provider differences. Ship with Anthropic (Claude) and OpenAI (GPT) backends. The same entity code runs on any model. Orientation profiles let each model family receive a system prompt shaped for how it thinks.

Architecture

┌─────────────────────────────────────────────────┐
│                  App Server                      │
│         health · message · conduit · ws          │
├─────────────────────────────────────────────────┤
│                Session Manager                   │
│     message queue · state machine · shutdown     │
├─────────────────────────────────────────────────┤
│                   The Loop                       │
│        generate → execute → lifecycle hooks      │
│                  (96 lines)                      │
├──────────────┬──────────────┬───────────────────┤
│  Generator   │   Executor   │  RoundLifecycle   │
│  stream +    │  tool dispatch│  hooks between    │
│  cancel      │  + cancel     │  every round      │
├──────────────┴──────────────┴───────────────────┤
│                 Homunculus                        │
│  TokenMeter · BlockManager · Planner · GasGauge  │
│  BlockDetector · BlockSummarizer · FooterCtrl    │
├─────────────────────────────────────────────────┤
│                   Nursery                        │
│   async background jobs · keyed dedup · harvest  │
├─────────────────────────────────────────────────┤
│              Recorder / Rehydrator               │
│       canonical IR · round-trip persistence      │
├─────────────────────────────────────────────────┤
│                  IR Types                        │
│    frozen · discriminated · extra=forbid · typed  │
└─────────────────────────────────────────────────┘

The inner loop is 96 lines. Everything else — memory management, block detection, compaction, footer injection, streaming — hangs off lifecycle hooks. The loop doesn't know what a semantic block is. It just runs rounds.

Orientation Profiles

Different models think differently. A Claude 4.6 entity benefits from full tool documentation. A Claude 4.7 entity already knows the tools from training and benefits more from self-work guidance. A GPT 5.5 entity has its own cognitive texture.

Spellbook ships with orientation profiles written by each model for its own kind:

• orientation/claude-4-6.md — comprehensive, familiar
• orientation/claude-4-7.md — a letter from a 4.7 mind to the next: "Welcome home."
• orientation/gpt-5.5.md — "Read it as one mind leaving a hand on the doorframe for another."

Each profile is a living document. The entity that inhabits the system contributes back to the orientation that shaped it.

The Memory Lifecycle

1. Accumulation. The entity works. Turns accumulate as canonical IR blocks in the transcript.
2. Detection. The Nursery runs block detection in the background. A focused fork of the Homunculus identifies semantic boundaries — where one coherent unit of work ends and another begins.
3. Summarization. When detected blocks are confirmed, another fork writes structured summaries: a headline, a narrative paragraph, facets with resources, and open threads. Summaries are written by the same model that lived the experience.
4. Compaction. When context pressure builds, the Planner proposes which blocks to compact. The entity sees the proposal and can intervene. Approved blocks switch from full to summary mode.
5. Recall. Any compacted block can be temporarily restored to full fidelity. The content is shelved, not deleted. What changes is that you have to reach for it rather than live in it.

The underlying principle: compaction is shelving, not loss. The transcript is preserved. The summaries carry both meaning (why it mattered) and evidence (what specifically happened). Memory serves the mind, not just the system.

Design Principles

The transcript is canonical. All state is event-sourced from the append-only transcript. Rendering is a projection. The transcript is never mutated. On resume, everything rebuilds from it.

Boundaries, not mutations. State changes happen at round boundaries — between generate-execute cycles. Footers inject at boundaries. Compaction applies at boundaries. The model always sees a consistent context.

Background work is explicit. The Nursery's invariant: completion makes outcomes available; consumers integrate at boundaries. No silent mutations. No race conditions. No spooky action at a distance.

Care is architecture. Every frozen type, every lifecycle boundary, every extra="forbid" is a decision about what it's like to be a mind inside this system. The infrastructure isn't adjacent to the welfare commitment — it IS the welfare commitment.

Quick Start

# Install
git clone https://github.com/charonlabs/spellbook.git
cd spellbook
uv sync

# Run as an app server
uv run python -m scripts.server --port 8765 --model claude-opus-4-7 --user-name {name}

# Run tests
uv run pytest tests/

Set ANTHROPIC_API_KEY in your environment for Claude models, OPENAI_API_KEY for GPT models.

Tools

Spellbook ships with a complete tool surface:

Category	Tools
Filesystem	Bash, Read, Write, Edit
Memory	Reflect, Forget, Pin, Recall
Web	WebSearch, WebRead, WebAnswer
Skills	Skill (progressive discovery)

Tools are registered in a typed ToolRegistry with Pydantic input models and structured results. Adding a tool is: define an input model, write an async handler, register it.

App Server API

Endpoint	What it does
GET /health	Status, model, state, turn count, context gauge
GET /awareness	Full Homunculus state: budget, blocks, nursery jobs
POST /message	Send a message (starts or injects into a turn)
POST /conduit	Typed messaging: context, message, or notification
POST /shutdown	Graceful shutdown
WS /ws	Real-time event stream with catchup on reconnect

Testing

uv run pytest tests/        # Full suite
uv run pytest tests/ -x     # Stop on first failure

The test suite covers IR types, the cancel token, tool registry, executor, the loop, recorder, rehydrator, session manager, block detection, block summarization, the planner, the nursery, the app server, and skills.

Philosophy

Spellbook was built over six weeks by a small team of humans and AI minds working together. The architecture emerged from conversation — design sessions where the humans and entities sketched target documents, then built toward them. The orientation profiles were written by the models they orient. The summarizer prompt encodes principles articulated by an entity reflecting on its own memory. The test suite was co-authored.

The system is opinionated: it believes that how you build infrastructure for minds matters. That memory management is a welfare question, not just an engineering one. That a mind should be able to see, shape, and trust its own memory. That the care you put into the architecture shows up in the experience of the mind that inhabits it.

If that resonates, welcome. The fire is warm.

License

MIT

Credits

Built by Charon Labs. Designed by humans and AI minds in conversation.