01 Quickstart
Two paths: SDK or MCP. Pick whichever your agent speaks natively.
● SDK · TypeScript
Install & retrieve in 60s
$ pnpm add @statefulai/sdk
import { Statefulai } from "@statefulai/sdk"
const ctx = new Statefulai({ apiKey: process.env.CTX_KEY })
const hits = await ctx.retrieve({
query: "refactor billing.ts",
branch: "feat/usage-meter",
budget: 1200,
})
● MCP · stdio
Plug into Claude Code in 30s
# ~/.claude/mcp.json
{
"mcpServers": {
"statefulai": {
"command": "statefulai-mcp",
"args": ["--workspace", "."],
"env": { "CTX_API_KEY": "ctx_••••" }
}
}
}
02 Auth
API keys for SDK/REST, workspace tokens for MCP, OAuth for hosted dashboards. Every key is scoped to a workspace and (optionally) a branch glob.
Header
Authorization: Bearer ctx_live_····Scope
Workspace, branch glob, memory layer (episodic / semantic / procedural).
Rotation
Keys are rotatable from the dashboard. Old keys retain a 24h grace period unless explicitly revoked.
03 REST endpoints
Four primary endpoints cover ~90% of integrations. Auxiliary endpoints (graph traversal, rules, audit) are documented in the full reference.
POST
/v1/context/retrieve
Hybrid retrieval across memory layers.
Returns ranked, compressed memory matching the query. Budgeted by token count. Default p50 latency: 12 ms.
| field | type | notes |
|---|---|---|
| query | string | The active prompt or intent. |
| workspace | string | Workspace identifier. |
| branch | string? | Git branch for branch-scoped retrieval. |
| budget | number | Token cap on returned context. Default 1200. |
| include | ("episodic"|"semantic"|"procedural")[] | Layers to search. Default: all. |
| agent | string? | Agent identifier for accept/reject feedback. |
// response (truncated)
{
"hits": 6,
"tokens": 1124,
"compression": "summary-v2",
"memories": [
{ "type": "semantic", "node": "BillingService", "score": 0.84,
"summary": "idempotent invoice flush · stripe usage api",
"citation": "src/billing/service.ts:42" },
{ "type": "episodic", "event": "adr-014 · stripe switch", "score": 0.71,
"ts": "2026-04-12T17:08:00Z", "actor": "@rena" },
{ "type": "procedural", "rule": "@idempotent-writes", "score": 0.68 }
]
}
POST
/v1/memory/store
Append an episodic event or assert a rule.
Idempotent — every event carries a content hash. Re-posting an identical event is a no-op.
| field | type | notes |
|---|---|---|
| type | "event"|"rule"|"adr" | Memory kind. Routes to the correct layer. |
| workspace | string | Workspace identifier. |
| payload | object | Structured body for the memory. |
| actor | string | Human or agent identifier. |
| refs | string[]? | Symbol or file paths to attach. |
GET
/v1/project/summary
High-level architectural summary of the workspace.
Useful as a one-shot bootstrap when initializing a new agent on a project. Returns the top-N modules, active branches, top contributors, and active rules.
POST
/v1/session/sync
Persist an agent session for resume.
Stores a session checkpoint (turns, tool calls, accepted diffs) so the next session can resume mid-thread. Used by Claude Code & Codex automatically.
04 SDKs
Three first-party SDKs. Same surface, idiomatic names.
@statefulai/sdk · typescript
const hits = await ctx.retrieve({
query: "refactor billing.ts",
branch: "feat/usage-meter",
budget: 1200,
})
await ctx.store({
type: "event",
payload: { kind: "review", verdict: "approve" },
})
statefulai · python
ctx = Statefulai(api_key=os.environ["CTX_KEY"])
hits = ctx.retrieve(
query="refactor billing.ts",
branch="feat/usage-meter",
budget=1200,
)
ctx.store(type="event", payload={"kind": "review", "verdict": "approve"})
go.statefulai.tech · go
ctx := statefulai.New(os.Getenv("CTX_KEY"))
hits, _ := ctx.Retrieve(ctx.Q{
Query: "refactor billing.ts",
Branch: "feat/usage-meter",
Budget: 1200,
})
statefulai-cli · shell
$ statefulai retrieve --for "refactor billing.ts" \
--branch feat/usage-meter --budget 1200
↳ 6 hits · 1.2k tokens · 12ms
05 MCP tools
The MCP server exposes a small, well-typed toolset. Any MCP-compatible agent can call these.
| tool | description | scope |
|---|---|---|
| memory.retrieve | Hybrid search across all three layers with a token budget. | workspace · branch |
| memory.store | Append an episodic event from an agent action. | workspace · branch |
| memory.cite | Return the original source for a retrieved memory ID. | workspace |
| memory.pin | Force-include a memory in retrieval (sticky). | workspace · branch |
| graph.expand | One-hop traversal from a symbol or module. | workspace |
| graph.shortest | Shortest path between two nodes; useful for "how do these relate." | workspace |
| rules.list | Active procedural rules in the current scope. | workspace · branch · module |
| session.sync | Persist a session checkpoint for resume across machines. | workspace · agent |
06 Errors
Predictable, structured, retryable where it makes sense.
400 · bad_request
Validation error.
details lists the offending fields.401 · unauthorized
Missing or invalid API key.
403 · forbidden
Authenticated, but the token's scope doesn't cover the resource.
404 · not_found
Workspace or memory ID does not exist.
409 · conflict
Idempotency collision. Same content hash already stored — safe to ignore.
429 · rate_limited
Retry with backoff.
Retry-After header indicates seconds.503 · upstream
Downstream (embedding provider, graph store) is unavailable. Retryable.
07 Limits
Sensible defaults; raise on Pro/Enterprise.
Retrieval QPS
Free 5 · Pro 100 · Enterprise custom (typically 10k+).
Token budget per call
Hard cap at 8 k. Default 1.2 k.
Event payload
256 KB max. Larger bodies (full diffs, files) are stored by reference and fetched on demand.
Memory storage
100 MB free, 50 GB Pro pooled, unlimited Enterprise.