@cellstate/sdk

TypeScript SDK for CELLSTATE — persistent agent memory and multi-agent coordination.

Installation

bun add @cellstate/sdk

Quick Start

import { CellstateClient } from '@cellstate/sdk';

const client = new CellstateClient({
  apiKey: process.env.CELLSTATE_API_KEY!,
  tenantId: 'your-tenant-id',
  // Optional: baseUrl defaults to https://cst.batterypack.dev
});

// Create a trajectory (task container)
const trajectory = await client.trajectories.create({
  name: 'Build feature X',
  description: 'Implement new user authentication',
});

// Create a scope (context window)
const scope = await client.scopes.create({
  trajectory_id: trajectory.trajectory_id,
  name: 'Implementation phase',
  token_budget: 8000,
});

// Store an artifact (extracted value)
await client.artifacts.create({
  trajectory_id: trajectory.trajectory_id,
  scope_id: scope.scope_id,
  artifact_type: 'Code',
  name: 'auth-handler.ts',
  content: 'export function authenticate() {...}',
  source_turn: 1,
  extraction_method: 'Explicit',
  ttl: 'Persistent',
});

// Create a note (cross-trajectory knowledge)
await client.notes.create({
  note_type: 'Convention',
  title: 'Always use async/await',
  content: 'Prefer async/await over .then() chains for readability.',
  source_trajectory_ids: [trajectory.trajectory_id],
  source_artifact_ids: [],
  ttl: 'Persistent',
});

Core Concepts

Hierarchy

TENANT (Isolation boundary)
  └── TRAJECTORY (Task/Goal)
        ├── SCOPE (Context window)
        │     └── TURN (Ephemeral message)
        ├── ARTIFACT (Persists - valuable outputs)
        └── NOTE (Cross-trajectory knowledge)

Memory Types

| Type | Lifespan | Example | |------|----------|---------| | Ephemeral | Scope only | Current messages (Turns) | | Episodic | Configurable | Saved outputs (Artifacts) | | Semantic | Long-term | Learned knowledge (Notes) |

What Survives?

When a Scope closes:

• ❌ Turns are deleted (ephemeral)
• ✅ Artifacts persist
• ✅ Notes persist

SimpleMemory (3-Method API)

For quick integrations, use the simplified API:

import { SimpleMemory } from '@cellstate/sdk';

const memory = new SimpleMemory({
  apiKey: process.env.CELLSTATE_API_KEY!,
  tenantId: process.env.CELLSTATE_TENANT_ID!,
});

// Store memories
await memory.add('User prefers dark mode');
await memory.add('function greet() {...}', { type: 'artifact', artifactType: 'Code' });

// Search memories
const results = await memory.search('preferences');

// Get context for LLM injection
const context = await memory.getContext('user preferences');
// Returns XML-formatted context ready for system prompt

AG-UI Headless Primitives

Framework-agnostic building blocks for CopilotKit and AG-UI compatible apps:

import { createAgUiAdapter } from '@cellstate/sdk';

// Create headless adapter - no framework, just TypeScript
const adapter = createAgUiAdapter({
  threadId: 'trajectory-123',
  runId: 'scope-456',
});

// Subscribe to AG-UI events
adapter.onEvent((event) => {
  switch (event.type) {
    case 'TEXT_MESSAGE_CONTENT':
      appendToUI(event.delta);
      break;
    case 'TOOL_CALL_START':
      showToolIndicator(event.toolCallName);
      break;
  }
});

// Feed CELLSTATE stream events through the adapter
websocket.onmessage = (e) => {
  adapter.processEvent(JSON.parse(e.data));
};

Wrap with your framework of choice - React, Vue, Svelte, or vanilla JS. See docs/recipes/copilotkit.md for full examples.

API Reference

Managers

| Manager | Resource | Description | |---------|----------|-------------| | client.trajectories | Trajectory | Task containers | | client.scopes | Scope | Context windows with token budgets | | client.artifacts | Artifact | Extracted valuable outputs | | client.notes | Note | Cross-trajectory knowledge | | client.turns | Turn | Ephemeral conversation messages | | client.agents | Agent | Agent registration and lifecycle | | client.locks | Lock | Distributed locking | | client.messages | Message | Inter-agent messaging | | client.delegations | Delegation | Task delegation | | client.handoffs | Handoff | Context handoffs | | client.search | - | Global search | | client.packConfig | - | pack validation/parsing | | client.batch | - | Bulk CRUD operations | | client.edges | Edge | Graph relationships | | client.summarizationPolicies | SummarizationPolicy | Summarization policies | | client.summarizationRequests | SummarizationRequest | Summarization requests | | client.workingSet | WorkingSetEntry | Agent working set |

Common Operations

// CRUD operations
const item = await client.trajectories.create({ name: 'Task' });
const item = await client.trajectories.get(id);
const items = await client.trajectories.list({ status: 'Active' });
const item = await client.trajectories.update(id, { name: 'Updated' });
await client.trajectories.delete(id);

// Search
const results = await client.search.search({
  query: 'authentication',
  entity_types: ['Artifact', 'Note'],
});

// Multi-agent coordination
await client.agents.register({ agent_type: 'coder', capabilities: ['write_code'] });
await client.delegations.create({ from_agent_id, to_agent_id, task_description: '...' });
await client.locks.acquire({ resource_type: 'trajectory', resource_id: id, mode: 'Exclusive' });

Error Handling

import { CellstateError, NotFoundError, ValidationError } from '@cellstate/sdk';

try {
  await client.trajectories.get('nonexistent');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Trajectory not found');
  } else if (error instanceof ValidationError) {
    console.log('Validation errors:', error.validationErrors);
  } else if (error instanceof CellstateError) {
    console.log('API error:', error.code, error.message);
  }
}

Configuration

const client = new CellstateClient({
  baseUrl: 'https://cst.batterypack.dev',  // API endpoint
  apiKey: 'your-api-key',               // Required
  tenantId: 'your-tenant-id',           // Required
  timeout: 30000,                        // Request timeout (ms)
  headers: { 'X-Custom': 'value' },     // Custom headers
});

License

Apache-2.0