Mental Model

Mental Model

How to think in CellState. Read this first if you’re new to the codebase.

For system internals, see ARCHITECTURE.md.

Core Philosophy

CellState is a hierarchical memory framework for AI agents. It models memory the way humans remember: some things are fleeting (what you had for breakfast), others persist (how to ride a bike).

The key insight: Turns are cheap and disposable. Artifacts and Notes are valuable and persist.

The Hierarchy

TENANT (isolation boundary — one per organization)
  └── TRAJECTORY (task/goal — like a project folder)
        ├── SCOPE (context window — like a conversation)
        │     ├── TURN (ephemeral — dies when scope closes)
        │     └── TURN
        ├── ARTIFACT (persists — important outputs)
        └── NOTE (cross-trajectory knowledge)

Entity Lifespans

Memory Types

What Survives When a Scope Closes?

• Turns are deleted (ephemeral conversation)
• Artifacts survive (extracted value)
• Notes survive (learned knowledge)

Before closing a scope, extract valuable information into Artifacts or Notes.

Abstraction Levels (L0 → L1 → L2)

Information compresses upward as context fills:

L0 (Raw):      "User asked about error handling in turn 3, wanted try/catch"
L1 (Summary):  "This trajectory focused on error handling patterns in TypeScript"
L2 (Principle): "Always validate at system boundaries, fail fast internally"

L2 principles survive with minimal tokens. “Always validate inputs” is cheaper than storing 50 examples of input validation.

Token Budget Flow

Each Scope tracks token usage against a budget:

Scope(token_budget=8000)
  ├─ Turn(500 tokens) → used: 500
  ├─ Turn(400 tokens) → used: 900
  ├─ Turn(600 tokens) → used: 1500
  ├─ ...
  └─ When 80% full → trigger summarization

Summarization triggers: token threshold exceeded, scope closing, turn count threshold, artifact count threshold, or manual API trigger.

TTL (Time-to-Live)

Persistent    — never expires
Session       — expires when session ends
Scope         — expires when scope closes
Ephemeral     — alias for Scope
ShortTerm     — ~1 hour
MediumTerm    — ~24 hours
LongTerm      — ~7 days
Permanent     — alias for Persistent
Duration(ms)  — custom milliseconds

Multi-Agent Coordination

Delegation (Sub-task)

Agent A needs specialist help → creates Delegation to Agent B → Agent B works in a child trajectory → returns artifacts and result to Agent A.

Handoff (Transfer Control)

Agent A transfers full context to Agent B → Agent B takes over the trajectory → Agent A steps back. Use for escalation.

Message (Async Communication)

Agent A sends a notification/query to Agent B → Agent B processes when ready. Non-blocking.

Lock (Exclusive Access)

Agent A acquires an exclusive or shared lock on a resource → other agents wait → release when done. Prevents conflicts.

Graph Relationships (Edges)

Entities can be linked with typed relationships:

Mutation Pipeline

All writes flow through a 4-stage pipeline (see ARCHITECTURE.md for details):

1. Assemble — fetch context and policy config (I/O)
2. Gates — run pure policy checks (no I/O)
3. Commit — atomic database transaction
4. Receipt — return proof, broadcast event

Gates are pure functions. They receive a frozen ValidationContext and return Pass or Reject. No async, no database calls. This makes policy enforcement deterministic and testable.

Common Patterns

Task Execution

1. Create Trajectory (name="Fix bug #123")
2. Create Scope (token_budget=8000)
3. Add Turns (conversation with user/tools)
4. Extract Artifacts (code changes, decisions)
5. Close Scope (turns deleted, artifacts persist)
6. Complete Trajectory (outcome recorded)

Knowledge Extraction

1. During work, identify reusable knowledge
2. Create Note with type:
   - Convention: "Always use async/await, not .then()"
   - Strategy: "Start with tests for complex features"
   - Gotcha: "The API returns 500 for auth failures, not 401"
3. Link to source artifacts/trajectories
4. Note persists across all future trajectories

Context Management

1. Check scope.tokens_used vs scope.token_budget
2. If approaching limit (>80%):
   a. Summarize old turns → create Summary artifact
   b. Create Note with L1/L2 abstractions
   c. Close scope, open new one
3. New scope starts fresh but artifacts/notes persist

Quick Reference

When to Create What

What Persists?

API Endpoints

Interactive API docs: build with --features openapi,swagger-ui and visit /docs.