ai-persistence

name	ai-persistence
description	Durability and state persistence for TanStack AI chats with @tanstack/ai-persistence. Routes to server chat persistence (withPersistence), client persistence (localStorage/IndexedDB), the store contracts, and adapter recipes. Distinguishes delivery durability (resumable streams) from conversation state. Use when conversations must survive reloads, multi-device, approvals, or server restarts — NOT for stream reconnect alone.
type	core
library	tanstack-ai
library_version	0.0.0
sources	["TanStack/ai:docs/persistence/overview.md","TanStack/ai:docs/persistence/chat-persistence.md","TanStack/ai:docs/persistence/client-persistence.md","TanStack/ai:docs/persistence/controls.md","TanStack/ai:docs/persistence/build-your-own-adapter.md"]

TanStack AI Persistence

Builds on the ai-core skill in @tanstack/ai, and usually ai-core/chat-experience.

TanStack AI splits delivery durability from state persistence. They share no code and solve different problems.

Layer	Answers	Package / API
Delivery durability	Reconnect to a stream still running	memoryStream / @tanstack/ai-durable-stream on the response; see resumable streams docs
State persistence	What is the conversation, later?	Client persistence on useChat + server withPersistence from @tanstack/ai-persistence

A replayable stream is not a saved conversation. A saved conversation is not a live stream. Production apps often use both.

Persistence is a contract, not a database

@tanstack/ai-persistence ships the store interfaces, the middleware that drives them, an in-memory reference backend, and a conformance testkit. It does not ship a backend for your database, and you do not need one: implement the stores against whatever you already run — Postgres, SQLite, D1, Mongo — and hand the result to withPersistence. The core never inspects your tables.

Ships in the package	What it is
MessageStore / RunStore / InterruptStore / MetadataStore	The four chat state contracts
GenerationRunStore / ArtifactStore / BlobStore	The generation contracts (job lifecycle + bytes)
withPersistence / withGenerationPersistence	Chat + generation middleware
memoryPersistence()	In-process reference backend, all seven stores (dev, tests)
reconstructChat / reconstructGeneration	Server hydrate route helpers (chat / generation)
retrieveArtifact / retrieveBlob / resolveArtifactBlobKey	Serve persisted generation-media bytes back
LockStore / withLocks / InMemoryLockStore (from @tanstack/ai/locks)	Coordination, not this package — see ai-core/locks
@tanstack/ai-persistence/testkit	runPersistenceConformance gate (chat state stores)

Chat vs generation stores. Chat persistence keys on threadId and uses messages + optional runs / interrupts / metadata. Generation persistence keys on its own runId and uses generationRuns (required by withGenerationPersistence) plus an optional artifacts + blobs pair — provide both or neither — to store the generated media bytes at blob key artifacts/<runId>/<artifactId>. A generation run's identity is its own runId, but threadId is required on the record: it is the stable slot successive runs fill, and findLatestForThread — the only query that hydrates a run — keys on it. To build the R2/D1-backed byte stores for a Worker, see ai-persistence/build-cloudflare-artifact-store.

Where bytes land. Default blob key is artifacts/<runId>/<artifactId>. Pass storageKey to withGenerationPersistence for your own folder structure — it receives { artifactId, runId, threadId, role, activity, path, mimeType, name } and returns the key. Server-side only (a browser-supplied key is path traversal + cross-tenant writes). The resolved key is recorded on ArtifactRecord.blobKey because it is no longer derivable; read through resolveArtifactBlobKey(record), never by recomputing. Records predating blobKey fall back to the default convention — which is why that convention can never be changed retroactively. A non-unique key overwrites, so include artifactId unless that is intended.

Byte storage stores generated output, not prompt URLs. Provider result URLs expire, so they are downloaded and kept. Prompt media sent as base64 (source: { type: 'data' }) is stored too. Prompt media sent as a URL is NOT fetched — that URL is caller-supplied, so downloading it server-side is an SSRF vector, and the bytes are redundant. Apps that genuinely need a durable copy opt in with allowInputUrl, a predicate so the check can't be skipped: allowInputUrl: ({ url }) => url.hostname.endsWith('.cdn.example.com'). Never suggest () => true. All artifact fetches are http/https-only, timed out (artifactFetchTimeoutMs) and size-capped (maxArtifactBytes); input fetches also block loopback/private/link-local hosts and refuse redirects. artifactFetch injects the fetch, for routing through an egress-restricted proxy.

Two related route-level rules: a GET that serves artifact bytes by id MUST authorize the caller against ArtifactRecord.threadId before serving (404, not 403, so valid ids aren't confirmed), and reconstructGeneration MUST be given authorize on any multi-user route. Both take ids straight from the caller.

Portable sandbox snapshots use the same messages, artifacts, and blobs stores. Their artifact reader checks the checkpoint thread, but it does not authenticate a caller. Authorize the thread before any route reads a snapshot artifact. The snapshot checkpoint store also needs atomic append and fork operations. A SQLite adapter must write a checkpoint, its head, and blob reference counts in one transaction.

Sub-skills

Need to...	Read
Wire server-side chat history, runs, interrupts	ai-persistence/server/SKILL.md
Survive reloads in the browser	ai-core/client-persistence/SKILL.md in @tanstack/ai
Implement the store interfaces for your DB	ai-persistence/stores/SKILL.md
Multi-instance locks (separate from state)	ai-core/locks/SKILL.md in @tanstack/ai

Adding persistence to an app? Pick the recipe that matches what it already runs — each one writes a single chat-persistence.ts against the app's existing database client and schema:

The app runs...	Read
Drizzle ORM (SQLite / Postgres / MySQL)	ai-persistence/build-drizzle-adapter/SKILL.md
Prisma	ai-persistence/build-prisma-adapter/SKILL.md
Cloudflare Workers + D1 (± Durable Object locks)	ai-persistence/build-cloudflare-adapter/SKILL.md
Cloudflare Workers + R2/D1 for generated media bytes	ai-persistence/build-cloudflare-artifact-store/SKILL.md
Anything else — raw pg, Kysely, SQLite, Mongo	ai-persistence/build-custom-adapter/SKILL.md

State persistence has two halves

Half	Stores	Survives	Typical use
Client	transcript ± resume pointer in browser storage	reload / tab close (per browser)	SPA restore, offline-first
Server	messages, runs, interrupts, metadata in your DB	restart + multi-device	authoritative history, durable approvals

They are independent. Use either alone or both.

Identity: threadId and Scope

Server stores key on threadId (same as chat({ threadId }) / ChatMiddlewareContext.threadId / Scope.threadId from @tanstack/ai).

• Store methods take bare threadId strings for adapter simplicity.
• Multi-user isolation is your job: derive userId / tenantId from session server-side; authorize before load/save / reconstructChat.
• Never treat a client-supplied thread id alone as ownership — ids are guessable.

Authoritative-history contract

When both halves run, ownership per turn is decided by request messages:

Client sends	Meaning	On finish
Non-empty messages	Full transcript (source of truth)	Server overwrites stored thread
Empty messages	Continue from server copy	Server loads stored thread

Never post a delta as messages — that wipes history down to the delta.

Client-authoritative: always send full transcript; browser is truth, server mirrors.
Server-authoritative: send empty messages (or hydrate via server load); server is truth, multi-device works.

Recommended production stack

1. Client: persistence: true — server-authoritative, no client cache.
2. Server: withPersistence(backend) — messages + runs + interrupts.
3. Route: delivery durability if mid-stream reconnect matters.
4. Optional: withLocks(distributedLockStore) from @tanstack/ai/locks when other middleware needs multi-instance coordination (not part of the state bag).

Minimal end-to-end sketch

Server

import {
  chat,
  chatParamsFromRequest,
  toServerSentEventsResponse,
} from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
import { withPersistence } from '@tanstack/ai-persistence'
// Your adapter — see ai-persistence/stores.
import { persistence } from './persistence'

export async function POST(request: Request) {
  const params = await chatParamsFromRequest(request)
  const stream = chat({
    adapter: openaiText('gpt-5.5'),
    messages: params.messages,
    threadId: params.threadId,
    runId: params.runId,
    ...(params.resume ? { resume: params.resume } : {}),
    middleware: [withPersistence(persistence)],
  })
  return toServerSentEventsResponse(stream)
}

Client (server-authoritative)

import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'

function Chat({ threadId }: { threadId: string }) {
  const { messages, sendMessage } = useChat({
    threadId,
    connection: fetchServerSentEvents('/api/chat'),
    persistence: true,
  })
  // ...
}

With persistence: true, the client caches nothing and hydrates the transcript from the server on mount (thread id is the key). Pair with a server load path such as reconstructChat for the GET.

Critical rules

1. Not Vercel AI SDK. Persistence is @tanstack/ai-persistence + middleware, not Vercel useChat storage hacks.
2. saveThread is full overwrite, never append.
3. createOrResume is insert-if-absent for the same runId.
4. Interrupt create is insert-if-absent — never clobber resolved → pending.
5. Locks ≠ state. Import withLocks from @tanstack/ai/locks. Sandbox resume is a sandbox-package concern — not a stores key. stores accepts only messages, runs, interrupts, metadata.
6. You own the schema. No package invents migrations for you.
7. Run the conformance testkit against any adapter you write.
8. Authorize thread access at the route boundary.

Cross-references

• ai-core/chat-experience (@tanstack/ai) — useChat, SSE, client persistence option overview
• ai-core/middleware (@tanstack/ai) — middleware hooks; withPersistence is a ChatMiddleware
• Resumable streams docs — delivery durability only