For Vibe Coders

CellState for Vibe Coders

You’re building with an AI copilot and you need to understand CellState fast. This page teaches the system visually. Share it with your LLM — it’s written for both of you.

The Battery Metaphor 🔋

CellState uses a battery metaphor. Here’s the mapping:

┌─────────────────────────────────────────────────────┐
│                    THE BATTERY                       │
│                                                      │
│  CELL    = State Container    (holds agent memory)   │
│  PACK    = Module Bundle      (config + prompts)     │
│  CIRCUIT = Execution Flow     (mutation pipeline)    │
│  RECEIPT = Mutation Proof     (cryptographic audit)  │
│                                                      │
│  A Cell holds state.                                 │
│  A Pack defines behavior.                            │
│  A Circuit processes changes.                        │
│  A Receipt proves what happened.                     │
└─────────────────────────────────────────────────────┘

How Memory Works (The Funnel)

Think of CellState memory as a funnel. Raw conversation flows in at the top, and only the valuable stuff persists at the bottom.

            ┌───────────────────────────────┐
            │         TURNS (ephemeral)      │  ← Messages in a conversation
            │    "The user asked about X"    │     DELETED when scope closes
            │    "I suggested trying Y"      │
            └──────────────┬────────────────┘
                           │ extract value
            ┌──────────────▼────────────────┐
            │      ARTIFACTS (persisted)     │  ← Saved outputs
            │   "Fixed auth middleware"      │     SURVIVE scope close
            │   "Database migration v3"      │     Live in trajectory
            └──────────────┬────────────────┘
                           │ distill knowledge
            ┌──────────────▼────────────────┐
            │     NOTES (cross-trajectory)   │  ← Learned facts
            │  "Always validate at edges"    │     SURVIVE everything
            │  "Use DPoP tokens for OAuth"   │     Shared across tasks
            └───────────────────────────────┘

The rule: Before closing a scope, ask yourself: “What did I learn that’s worth keeping?”

The Hierarchy (Your Mental Map)

YOUR ORG (Tenant)
│
├── 🤖 Agent: "code-reviewer"
├── 🤖 Agent: "docs-writer"
│
├── 📁 Trajectory: "Fix auth bug"
│   ├── 💬 Scope: "Debug session 1"
│   │   ├── Turn: "User: auth is broken"
│   │   ├── Turn: "AI: I see the issue..."
│   │   └── Turn: "AI: Fixed! Here's the patch"
│   ├── 📎 Artifact: "auth-middleware-fix.rs"
│   └── 📝 Note: "OAuth tokens need DPoP binding"
│
├── 📁 Trajectory: "Build search feature"
│   ├── 💬 Scope: "Design session"
│   ├── 💬 Scope: "Implementation session"
│   ├── 📎 Artifact: "search-index-schema.sql"
│   └── 📝 Note: "pgvector cosine similarity > 0.8 works well"
│
└── 📝 Note: "Always run migrations before tests"
    (this note is cross-trajectory — visible everywhere)

What Happens When You Make a Change

Every write in CellState goes through the Mutation Pipeline. Think of it as airport security for your data.

  You send a request
       │
       ▼
  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌──────────┐
  │ Validate │───▶│  PCP    │───▶│ Event   │───▶│  Save   │───▶│Broadcast │
  │  Input   │    │  Check  │    │  DAG    │    │  to DB  │    │  to WS   │
  └─────────┘    └─────────┘    └─────────┘    └─────────┘    └──────────┘
   "Is this      "Does config   "Log it in    "PostgreSQL    "Tell clients
    valid?"       allow this?"   the ledger"   + LMDB cache"  in real-time"

Nothing bypasses this pipeline. Every state change is validated, logged, persisted, and broadcast.

Abstraction Levels (How Memory Compresses)

As your context window fills up, CellState compresses information upward:

  ┌─────────────────────────────────────────────────────────┐
  │ L0 — RAW                                                │
  │ "In turn 3, user asked about try/catch in TypeScript"   │
  │ "In turn 7, user wanted async error handling"           │
  │ "In turn 12, user asked about Result types"             │
  │                                         many tokens ████│
  └────────────────────────┬────────────────────────────────┘
                           │ summarize
  ┌────────────────────────▼────────────────────────────────┐
  │ L1 — SUMMARY                                            │
  │ "This trajectory focused on error handling patterns      │
  │  in TypeScript, comparing try/catch vs Result types"     │
  │                                      fewer tokens ███   │
  └────────────────────────┬────────────────────────────────┘
                           │ distill
  ┌────────────────────────▼────────────────────────────────┐
  │ L2 — PRINCIPLE                                          │
  │ "Always validate at system boundaries.                   │
  │  Fail fast internally, recover at edges."                │
  │                                      minimal tokens █   │
  └─────────────────────────────────────────────────────────┘

L2 principles are the most valuable — they encode deep knowledge in minimal tokens.

The Crate Map (What’s Where in the Code)

cellstate (workspace root)
│
├── cellstate-core     ← Domain types. Start here.
│                        Entity definitions, Event DAG, IDs.
│
├── cellstate-pcp      ← Pack Compiler Protocol.
│                        Validates mutations against config.
│
├── cellstate-pipeline ← The mutation pipeline.
│                        Orchestrates validate → check → log → save.
│
├── cellstate-storage  ← LMDB cache + storage traits.
│                        Sub-millisecond hot reads.
│
├── cellstate-pg       ← PostgreSQL 18 extension (pgrx).
│                        Custom types and functions in the DB.
│
├── cellstate-api      ← The API server. 51 route modules.
│                        REST + WebSocket + MCP + WebMCP.
│
├── cellstate-cli      ← CLI tool.
│                        `cellstate init`, `pack`, `start`, `inspect`.
│
└── cellstate          ← SDK crate.
                         Re-exports core + pcp for consumers.

Common Vibe Coding Patterns

”I want to add memory to my agent”

Tell your AI copilot:

“Use the CellState REST API. Create a trajectory for this task, a scope for our conversation, and extract artifacts when we produce something valuable."

"I want to search past knowledge”

Tell your AI copilot:

“Hit the /api/v1/search endpoint with our query. CellState uses pgvector for semantic search. Results come back scored and ranked."

"I want to understand what happened”

Tell your AI copilot:

“Query the Event DAG. Every state change is an immutable event with causal ordering. We can trace any mutation back to its origin."

"I want to build an agent pack”

Tell your AI copilot:

“Create a pack.toml manifest with our prompts and config. Use cellstate pack validate to check it. Then cellstate pack emit to compile it.”

Quick Start for You + Your AI

# 1. Get the system running
git clone https://github.com/TheFreeBatteryFactory/CellState.git
cd cellstate && make setup && make db-setup && make dev-api

# 2. Create your first trajectory
curl -X POST http://localhost:3000/api/v1/trajectories \
  -H "Authorization: Bearer dev-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "My first vibe coding session"}'

# 3. Start building with your AI copilot
# Point your LLM at /docs/for-agents for the machine-readable reference

Further Reading