@cellstate/convex

Convex component for CELLSTATE — hierarchical memory for AI agents with trajectories, scopes, artifacts, notes, and multi-agent coordination.

What is CELLSTATE?

CELLSTATE is a hierarchical memory framework for AI agents that provides:

• Trajectories: Task containers that track agent work from start to completion
• Scopes: Context windows within trajectories for managing token budgets
• Turns: Ephemeral conversation messages within scopes
• Artifacts: Extracted values (code, decisions, plans) that persist beyond conversations
• Notes: Cross-trajectory knowledge that accumulates over time
• Agents: Multi-agent registration and coordination

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Your Convex App                           │
│                                                             │
│  ┌─────────────────┐  ┌──────────────────────────────────┐ │
│  │   Frontend       │  │  Convex Backend                  │ │
│  │   (React/etc)    │──│  Queries, Mutations, Actions     │ │
│  │                  │  │                                  │ │
│  │  Real-time subs  │  │  ┌────────────────────────────┐ │ │
│  │  via useQuery()  │  │  │  @cellstate/convex       │ │ │
│  └─────────────────┘  │  │  (CELLSTATE Component)       │ │ │
│                        │  │                            │ │ │
│                        │  │  Trajectories, Scopes,     │ │ │
│                        │  │  Turns, Artifacts, Notes,  │ │ │
│                        │  │  Agents, Tool Executions   │ │ │
│                        │  └────────────────────────────┘ │ │
│                        └──────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Data lives entirely inside Convex — no external API calls needed. You get real-time subscriptions, transactional consistency, and zero-latency reads for free.

Quick Start

1. Install

bun add @cellstate/convex

2. Register the Component

// convex/convex.config.ts
import { defineApp } from "convex/server";
import cellstate from "@cellstate/convex/convex.config";

const app = defineApp();
app.use(cellstate);
export default app;

3. Use in Your Code

// convex/myAgent.ts
import { CellstateMemory } from "@cellstate/convex";
import { components } from "./_generated/api";
import { internalAction } from "./_generated/server";
import { v } from "convex/values";

const memory = new CellstateMemory(components.cellstate);

export const runTask = internalAction({
  args: { prompt: v.string() },
  handler: async (ctx, { prompt }) => {
    // Start a task (creates trajectory + scope)
    const { trajectoryId, scopeId } = await memory.startTask(ctx, {
      name: "User query",
      description: prompt,
      tokenBudget: 8000,
    });

    // Record the user's message
    await memory.addTurn(ctx, {
      scopeId,
      trajectoryId,
      role: "user",
      content: prompt,
    });

    // Search existing knowledge
    const notes = await memory.searchNotes(ctx, {
      query: prompt,
      limit: 5,
    });

    // ... do LLM inference with notes as context ...

    // Extract valuable output as an artifact
    await memory.createArtifact(ctx, {
      trajectoryId,
      scopeId,
      name: "Analysis Result",
      content: "...",
      artifactType: "document",
      sourceTurn: 1,
    });

    // Save learned knowledge as a cross-trajectory note
    await memory.createNote(ctx, {
      noteType: "fact",
      title: "Discovered pattern",
      content: "...",
      sourceTrajectoryIds: [trajectoryId],
    });

    // Complete the task
    await memory.completeTask(ctx, {
      trajectoryId,
      scopeId,
      outcomeStatus: "success",
      outcomeSummary: "Analyzed user query successfully",
    });
  },
});

API Reference

Task Lifecycle

| Method | Description | |--------|-------------| | startTask({ name, description?, tokenBudget? }) | Create a trajectory + scope in one call | | completeTask({ trajectoryId, scopeId, outcomeStatus?, outcomeSummary? }) | Close scope and mark trajectory complete |

Trajectories

| Method | Description | |--------|-------------| | createTrajectory({ name, description?, agentId? }) | Create a task container | | updateTrajectoryStatus({ trajectoryId, status }) | Update status (active/completed/failed/suspended) | | getTrajectory(trajectoryId) | Get trajectory by ID | | listTrajectories(status?) | List trajectories, optionally filtered by status |

Scopes (Context Windows)

| Method | Description | |--------|-------------| | createScope({ trajectoryId, name, tokenBudget? }) | Create a new context window | | closeScope(scopeId) | Close a scope (triggers budget reclaim) | | getOpenScopes(trajectoryId) | Get all open scopes for a trajectory |

Turns (Conversation)

| Method | Description | |--------|-------------| | addTurn({ scopeId, trajectoryId, role, content }) | Add a message (auto-tracks token usage) | | getTurns(scopeId) | Get all turns in a scope, ordered by turn number |

Artifacts (Extracted Values)

| Method | Description | |--------|-------------| | createArtifact({ trajectoryId, scopeId, name, content, artifactType, sourceTurn }) | Save a persistent output | | listArtifacts(trajectoryId, artifactType?) | List artifacts, optionally filtered by type |

Artifact types: fact, code, document, data, config, log, summary, decision, plan

Notes (Cross-Trajectory Knowledge)

| Method | Description | |--------|-------------| | createNote({ noteType, title, content, sourceTrajectoryIds }) | Create long-term knowledge | | searchNotes({ query, noteType?, limit? }) | Full-text search across notes | | listNotes(noteType?, activeOnly?) | List notes by type | | deactivateNote(noteId) | Soft-delete a note |

Note types: convention, strategy, gotcha, fact, preference, relationship, procedure, meta

Agents (Multi-Agent Coordination)

| Method | Description | |--------|-------------| | registerAgent({ agentType, capabilities, canDelegateTo? }) | Register an agent | | updateAgentStatus(agentId, status) | Update status (active/idle/busy/offline) | | agentHeartbeat(agentId) | Heartbeat ping | | listAgents(status?) | List agents by status |

Tool Execution Audit

| Method | Description | |--------|-------------| | startToolExecution({ toolName, agentId?, trajectoryId? }) | Record tool invocation start | | completeToolExecution({ executionId, status, durationMs }) | Record tool completion |

Memory Hierarchy

Tenant (your Convex app)
├── Notes (cross-trajectory knowledge, persists forever)
├── Agents (registered agents with capabilities)
└── Trajectory (task container)
    ├── Scope (context window with token budget)
    │   └── Turns (individual messages)
    ├── Artifacts (extracted values from this task)
    └── Tool Executions (audit trail)

Best Practices

1. Start with a Trajectory: Every agent task should have a trajectory
2. Use Scopes for Token Management: Create new scopes when approaching token limits
3. Extract Artifacts: Save important outputs (code, decisions, plans) as artifacts
4. Create Notes for Patterns: When you notice recurring patterns, save them as notes
5. Register Agents: Use agent registration for multi-agent coordination and delegation

Schema

The component creates 7 tables isolated within the component boundary:

| Table | Purpose | Key Indexes | |-------|---------|-------------| | trajectories | Task containers | by_status, by_agent, by_parent | | scopes | Context windows | by_trajectory, by_open | | turns | Conversation messages | by_scope, by_trajectory | | artifacts | Persistent outputs | by_trajectory, by_type | | notes | Cross-trajectory knowledge | by_type, by_active, search_content (full-text) | | agents | Agent registry | by_type, by_status | | toolExecutions | Tool audit trail | by_trajectory, by_tool, by_agent |

License

Apache-2.0 — See the main CELLSTATE repository for details.