Architecture

How Phantasm is designed and implemented

Phantasm is a project-scoped memory runtime for AI agents, task-independent by design. At a high level, it is a local system that bootstraps into a repository, stores durable memory in a single authoritative runtime, and answers explicit operations like ingest, search, and compile through a deterministic request contract.

Design idea

Treat memory as project runtime, not just retrieval infrastructure

Many competing systems optimize for cross-session recall, graph retrieval, or generic agent state. Phantasm's design is narrower and more opinionated: memory belongs to the repository, should be bootstrapped locally, and should expose explicit operational semantics instead of behaving like a hidden background layer.

01

Bootstrap layer

The runtime is installed into each repository with phantasm bootstrap. That creates the local .phantasm/ layout, tracked config files, and the state directory that holds the live runtime.

02

Request layer

Phantasm exposes one explicit JSON request/response contract through handle-request. Operations are versioned, auditable, and separated into mutations, reads, snapshots, and maintenance flows. The read-only describe operation returns the complete machine-readable API schema, operation params, safety rules, and runnable examples for agents.

03

Persistence layer

The source of truth is one authoritative SQLite store per project under .phantasm/state/store.sqlite. Runtime caches may exist, but durable memory truth lives in local state, not in prompt text or transient agent memory. Current runtimes automatically repair older v1 stores that are missing quality_json metadata columns.

04

Memory domain layer

The runtime stores authoritative records, suggestions, review items, raw evidence, operations, idempotency receipts, trust decisions, and backup metadata. The system is designed to preserve lifecycle and auditability, not just similarity search hits.

Runtime layout

What gets created inside a project

.phantasm/
├── phantasm.toml
├── clients.toml
└── state/
    ├── store.sqlite
    ├── backups/
    ├── indexes/
    ├── logs/
    ├── raw/
    └── tmp/

The important split is declarative config versus mutable local state. Config drives behavior; the SQLite-backed runtime holds the memory truth.

For the exact supported config keys today, use the configuration reference.

Operational flow

How a request moves through the system

1

The client sends a versioned request envelope with operation, client profile, and parameters.

2

The runtime validates the request, trust profile, confirmations, and idempotency requirements.

3

The operation reads or mutates the project-scoped store against a stable snapshot or serialized write boundary.

4

The response returns machine-readable data, warnings, review items, remediation, and provenance summary.

Compile model

What makes Phantasm different from plain memory retrieval

The project README frames Phantasm as a context compiler rather than a simple memory lookup layer. Conceptually, the runtime ingests structured project truth, resolves contradictions and lineage, determines what is live, profiles importance, allocates what fits within a token budget, and assembles the final context payload in model-aware order.

Even where the current codebase is still maturing toward that broader design, the implementation is already shaped around explicit operations, deterministic behavior, and durable project-local state rather than "store embeddings and hope retrieval works."

High-level comparison

How the architecture differs from common competitors

System
Primary abstraction
Typical shape
How Phantasm differs
Mem0 / OpenMemory
Memory layer service
Platform or MCP memory shared across apps and tools
Phantasm is narrower: the repository owns the memory runtime and its lifecycle.
Zep / Graphiti
Context engineering plus temporal graph memory
Knowledge-graph-heavy retrieval and temporal reasoning
Phantasm favors simpler project-local operational semantics over graph-first architecture.
Letta
Stateful agent memory blocks
Agent-centric persistent state and attached memory
Phantasm is repository-centric rather than agent-centric.
LangGraph memory
Framework persistence primitives
Short-term checkpointing plus long-term stores inside a graph framework
Phantasm is a product opinion and runtime contract, not just persistence building blocks.

Implementation principles

What the codebase optimizes for

  • Project-scoped state instead of account-scoped or thread-scoped memory.
  • Single authoritative durable store per repository.
  • Explicit operations with auditability and idempotency.
  • Deterministic search and compile behavior for the same store state and request.
  • Operator-friendly backups, imports, maintenance, and recovery flows.

Why this matters

Why users may prefer this architecture

  • You can reason about the system as part of the repository, not as a hidden cloud memory product.
  • Memory behavior is easier to inspect, validate, and operate in engineering workflows.
  • The architecture fits teams who want local control, explicit contracts, and git-adjacent project boundaries.