Session State Persistence — Resume Brainstorm Sessions from Any Machine

2026-03-24

apisdk-tssdk-py

What We Built

Session state persistence — save and restore full brainstorm session state (plan, tasks, decisions, files modified) to the gateway. Start a session on your laptop, resume on your desktop. Or next week. Plans don't die when the session ends.

POST /v1/sessions/{id}/state upserts session state with tenant + project scoping. GET /v1/sessions/latest?project=name returns the most recent session with a summary and resume hint.

Why It Matters

Session continuity is critical for complex multi-step AI work. Without persistence, every new session starts from scratch. With it, the CLI can ask "where did I leave off?" and pick up exactly where you stopped.

How It Works

// Save session state
await client.sessions.save("sess_abc123", {
  plan: { title: "20-PR plan", total_items: 20, completed_items: 17 },
  tasks: [{ id: "1", subject: "Build eval", status: "completed" }],
  project: { path: "/Users/dev/Projects/brainstorm" },
});

// Resume later
const latest = await client.sessions.latest("brainstorm");
// { session_id: "sess_abc123", tasks_pending: 3, resume_hint: "Continue with ..." }

Lockstep Checklist

[x] API Routes: src/api/routes/sessions-state.ts — POST + GET
[x] TS SDK: packages/sdk-ts/src/resources/sessions.ts — save() + latest()
[x] Python SDK: packages/sdk-py/src/brainstormrouter/resources/sessions.py — sync + async
[x] MCP Schemas: N/A — session state is CLI-specific
[x] Tests: src/api/routes/sessions-state.test.ts — 9 test cases