sessions

The durable conversation record for AI SDK agents. Full design: docs/sessions.md (repo root).

import { createSessionStore, MemoryStorage } from "sessions";

const store = createSessionStore({ storage: new MemoryStorage() });
const s = await store.open("thread-42");

await s.say("hello");
const row = await s.turn((t) => generateText({ model, messages: t.messages }));
// row.content derived from a persisted raw turn record, citing row.sourceRef
await store.verifyRow("thread-42", row.seq); // { ok: true } — the mini-terra

• Two-phase append: raw turn record persisted first; the display row is derived FROM it and cites it (sourceRef). verifyRow re-derives and compares — ghost-class drift (a displayed reply not derivable from its source) is mechanically detectable.
• Ghost-guard extraction: reply text comes from the turn's NEW messages only; a text-less final message (finishReason=length, reasoning-only) yields an honest (no text reply) placeholder with finishReason surfaced — never a walk into history.
• Fencing: epoch/nextTurn CAS; concurrent turns lose loudly.
• Fail-loud reads: waitReply returns placeholder rows (caller sees placeholder: true), throws on failed sessions, never silently filters.
• Two provenance drivers, one surface: ownTurnRecord() (plain tool-loop agents — the package persists the truth) and workflowJournal() (workflow agents — cite the journal step, store nothing twice).
• Storage SPI: MemoryStorage shipped; PostgresStorage takes any injected sql.unsafe-capable driver (Bun.SQL, postgres.js) — no driver dependency.

Proofs: bun test (11 contract tests, incident shapes pinned); bun smoke/live-glm.ts (real model through plain-loop mode); SESSIONS_PG_URL=… bun smoke/pg-smoke.ts (real Postgres).

Lineage: ria's chat store (fencing, the ghost-reply incident and fix), skill-ai-backend's transcript lessons (empty-assistant prune as a PROMPT projection — placeholder rows never enter the derived prompt but never leave the record; "the session is the only source of truth"). Deliberately out of scope: client-executable operations, UI chat state (wrap the SDK's own Chat/useChat), memory consolidation (the memory standard's job).