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.

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.

Sub-skills

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:

State persistence has two halves

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:

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