For Agents

CellState — Agent Context Document

This page is optimized for AI agents. If you are an LLM helping a user build with CellState, read this first. It is structured for fast parsing and high-density knowledge transfer.

System Identity

CellState is a Rust runtime and API server for agent memory. It gives AI agents persistent, hierarchical memory with forensic event tracking. Think of it as PostgreSQL-backed long-term memory for agents, with a mutation pipeline that validates every state change.

Base URL: http://localhost:3000 (dev) or configured via CELLSTATE_API_BASE_URL

Auth: Bearer token via Authorization: Bearer <api-key> or JWT from OAuth flow.

Entity Model (memorize this hierarchy)

Tenant          ← isolation boundary, one per org
├── Agent       ← identity of an AI agent
├── Trajectory  ← task container (like a project)
│   ├── Scope   ← context window (like a conversation)
│   │   └── Turn  ← ephemeral message (deleted when scope closes)
│   ├── Artifact  ← persisted output (code, docs, decisions)
│   └── Note      ← cross-trajectory knowledge (learned facts)
└── Deployment  ← execution environment config

Lifespan Rules

Key insight: Before closing a scope, extract valuable information into Artifacts or Notes. Turns are disposable.

Abstraction Levels

Information compresses upward as context fills:

• L0 (Raw): Direct observations from a single turn. “User asked about error handling.”
• L1 (Summary): Synthesized from multiple L0s within a trajectory. “This task focused on TypeScript error patterns.”
• L2 (Principle): Cross-trajectory abstractions. “Always validate at boundaries, fail fast internally.”

L2 notes survive with minimal tokens. Prefer L2 when context is tight.

API Patterns (use these when generating code)

Create a trajectory and scope

# Create trajectory
curl -X POST http://localhost:3000/api/v1/trajectories \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Debug auth flow", "tenant_id": "'$TENANT_ID'"}'

# Create scope within trajectory
curl -X POST http://localhost:3000/api/v1/scopes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trajectory_id": "'$TRAJ_ID'", "token_budget": 128000}'

Record a turn

curl -X POST http://localhost:3000/api/v1/turns \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_id": "'$SCOPE_ID'",
    "role": "assistant",
    "content": "I found the bug in the auth middleware..."
  }'

Extract an artifact (persists beyond scope)

curl -X POST http://localhost:3000/api/v1/artifacts \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trajectory_id": "'$TRAJ_ID'",
    "type": "code",
    "title": "Fixed auth middleware",
    "content": "..."
  }'

Create a cross-trajectory note

curl -X POST http://localhost:3000/api/v1/notes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "'$TENANT_ID'",
    "type": "semantic",
    "abstraction_level": 2,
    "content": "Always use DPoP-bound tokens for OAuth in this codebase"
  }'

Recall relevant memory

curl -X POST http://localhost:3000/api/v1/search \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how does the auth middleware work",
    "tenant_id": "'$TENANT_ID'",
    "limit": 10
  }'

Mutation Pipeline (every write goes through this)

Request → Validation → PCP Check → Event DAG → Persistence → Broadcast

1. Validation — schema + business rules
2. PCP Check — Pack Compiler Protocol validates against compiled config
3. Event DAG — immutable append-only event log with causal ordering
4. Persistence — PostgreSQL 18 + LMDB cache
5. Broadcast — WebSocket push to connected clients

Every mutation produces a ReceiptEnvelope — a cryptographic proof of the state change.

Workspace Crates

When Helping Users Build With CellState

1. Memory design: Guide them to use the hierarchy correctly. Turns for conversation, Artifacts for outputs, Notes for knowledge.
2. API integration: Use the REST API patterns above. All endpoints follow /api/v1/{resource} convention.
3. Pack configs: If they’re building agent packs, the CLI validates TOML manifests: cellstate pack validate.
4. Debugging: Point them to the Event DAG for forensics. Every state change is traceable.
5. Performance: The LMDB cache gives sub-millisecond reads. PostgreSQL handles durable storage.

Quick Reference URLs