cellstate 0.5.2

Python SDK for CELLSTATE -- the memory & orchestration layer for AI agents

cellstate

Python SDK for CELLSTATE -- the memory and orchestration layer for AI agents.

Installation

pip install cellstate

With framework adapters:

pip install cellstate[langgraph]    # LangGraph checkpointer
pip install cellstate[langmem]      # LangMem memory store
pip install cellstate[pydantic-ai]  # PydanticAI state
pip install cellstate[all]          # Everything

Quick Start

from cellstate import CellstateClient

client = CellstateClient(
    api_key="cst_...",
    tenant_id="your-tenant-id",
)

# Create a trajectory (task container)
trajectory = await client.trajectories.create(
    name="Build feature X",
    description="Implement the new feature",
)

# Create a scope (context window)
scope = await client.scopes.create(
    trajectory_id=trajectory["trajectory_id"],
    name="Implementation",
    token_budget=8000,
)

# Store an artifact
artifact = await client.artifacts.create(
    trajectory_id=trajectory["trajectory_id"],
    scope_id=scope["scope_id"],
    artifact_type="Code",
    name="feature.py",
    content="def feature(): ...",
    source_turn=1,
    extraction_method="Explicit",
    ttl="Persistent",
)

Framework Adapters

LangGraph

from cellstate.adapters.langgraph import CellstateCheckpointer

checkpointer = CellstateCheckpointer(
    api_key="cst_...",
    tenant_id="...",
)
graph = StateGraph(State)
graph.compile(checkpointer=checkpointer)

LangMem

from cellstate.adapters.langmem import CellstateMemoryStore

store = CellstateMemoryStore(api_key="cst_...", tenant_id="...")
await store.add_memory("User prefers dark mode")
results = await store.search_memories("UI preferences")

Adapter Conformance Guardrails

Adapter layering and surface-area drift are enforced by tests:

• tests/test_adapter_conformance.py checks module complexity budgets.
• Public adapter method surfaces are pinned to golden fixtures.
• Allowed self.client.<manager> usage is pinned per adapter module.

Golden fixture location:

• tests/fixtures/adapter_protocol_golden.json

When intentionally changing adapter APIs or architecture, update the fixture in the same PR so drift is explicit and reviewable.

License

Apache-2.0