Crate cellstate 

CELLSTATE Rust SDK

The cellstate crate provides a typed Rust interface to the CELLSTATE agent memory platform. It includes:

• Core types: Entity IDs, enums, and domain structures from cellstate-core
• PCP types: Memory commit, recall service, and PCP runtime from cellstate-pcp
• HTTP client: CellstateClient for all REST API operations
• Wire types: Request/response structs matching the API’s snake_case JSON

Quick Start

use cellstate::CellstateClient;
use cellstate::types::CreateTrajectoryRequest;

// Create a client from env vars (CELLSTATE_API_URL, CELLSTATE_API_KEY)
let client = CellstateClient::from_env()?;

// Create a trajectory
let traj = client.create_trajectory(&CreateTrajectoryRequest {
    name: "Research task".to_string(),
    description: Some("Investigating memory models".to_string()),
    parent_trajectory_id: None,
    agent_id: None,
    metadata: None,
}).await?;

println!("Created: {}", traj.trajectory_id);

Re-exported Types

All types from cellstate-core and cellstate-pcp are re-exported at the crate root for convenience:

use cellstate::{TrajectoryId, ScopeId, AgentId, EntityIdType};
use cellstate::{Trajectory, Scope, Artifact, Note, Turn};
use cellstate::{TrajectoryStatus, AgentStatus, ArtifactType, NoteType, TurnRole};
use cellstate::{ContextPackage, ContextWindow, TokenBudget};
use cellstate::{EventKind, EventHeader, DagPosition};

Re-exports

pub use client::CellstateClient;

pub use client::ResponseFormat;

Modules

client

HTTP client for the CELLSTATE REST API.

error

Error types for the CELLSTATE Rust SDK.

types

Request and response wire types for the CELLSTATE REST API.

Structs

Agent

An agent in the multi-agent system.

AgentId

Type-safe ID for agent entities.

Artifact

Artifact - typed output preserved across scopes. Artifacts survive scope closure and can be referenced later.

ArtifactId

Type-safe ID for artifact entities.

ContentHash

SHA-256 content hash for deduplication and integrity verification.

ContextAssembler

Context assembler that builds context windows from packages. Adds sections by priority until budget is exhausted.

ContextPackage

Context package - all inputs for assembly. Similar to ContextPackage in the TypeScript CRM pattern.

ContextWindow

Assembled context window with token budget management.

DagPosition

Position of an event in the DAG.

EventHeader

Event header with all metadata needed for processing.

EventKind

Event kind encoded as a 16-bit value.

MemoryCommit

Memory commit - versioned record of an interaction. Enables: “Last time we decided X because Y” Every interaction creates a versioned commit for recall, rollback, audit, and rehydration.

Note

Note - long-term cross-trajectory knowledge. Notes persist beyond individual trajectories.

NoteId

Type-safe ID for note entities.

PCPConfig

Master PCP configuration.

PCPRuntime

PCP Runtime - the main validation and checkpoint engine.

RecallService

Service for recalling past interactions and decisions. Provides query methods for memory commits.

Scope

Scope - partitioned context window within a trajectory. Scopes provide isolation and checkpointing boundaries.

ScopeId

Type-safe ID for scope entities.

ScoringComponent

ScoringDebug

Debug output for scoring transparency

ScoringWeights

Weights for deterministic scoring formula.

SourceQuality

Source quality tracking (P2)

TenantId

Type-safe ID for tenant entities.

TokenBudget

Segment-based token budget allocation.

Trajectory

Trajectory - top-level task container. A trajectory represents a complete task or goal being pursued.

TrajectoryId

Type-safe ID for trajectory entities.

Turn

Turn - ephemeral conversation buffer entry. Turns die with their scope.

TurnId

Type-safe ID for turn entities.

Enums

AbstractionLevel

Semantic abstraction level for notes (L0 → L1 → L2 hierarchy).

AgentStatus

Status of an agent in the system.

ArtifactType

Type of artifact produced during a trajectory.

Effect

An effect represents the outcome of an operation.

EntityType

Entity type discriminator for polymorphic references.

ErrorEffect

An error effect that can be persisted and replayed.

ExtractionMethod

Method used to extract an artifact or evidence.

NoteType

Type of note (cross-trajectory knowledge).

TTL

Time-to-live and retention configuration for memory entries. Supports both time-based expiration and count-based limits.

TrajectoryStatus

Status of a trajectory (task container).

TurnRole

Role of a turn in conversation.

Traits

EntityIdType

Trait for type-safe entity IDs.

Type Aliases

RawContent

Raw binary content for BYTEA storage.

Timestamp

Timestamp type using UTC timezone.