ai-persistence/stores

Persistence Stores

Builds on ai-persistence and ai-persistence/server.

@tanstack/ai-persistence ships contracts, not a backend for your database. An adapter is an object with a stores map; implement the stores you need against whatever you already run and hand the result to withPersistence. The core never inspects your tables, so the schema is yours.

Use memoryPersistence() for dev and tests. Everything durable is an adapter you write. This skill is the contract reference; the per-stack recipes that write a chat-persistence.ts into an app are ai-persistence/build-{drizzle,prisma,cloudflare,custom}-adapter, and a complete node:sqlite implementation lives in examples/ts-react-chat/src/lib/sqlite-persistence.ts.

Choose a shape

import { defineAIPersistence } from '@tanstack/ai-persistence'
import type { ChatWithInterruptsPersistence } from '@tanstack/ai-persistence'

// Sparse is fine — only implement what you need.
export const persistence: ChatWithInterruptsPersistence = defineAIPersistence({
  stores: {
    messages, // required for withPersistence / reconstructChat
    runs, // required if you have interrupts
    interrupts,
    // metadata optional
  },
})

Shape	Contents
ChatTranscriptPersistence	messages (+ optional runs/interrupts/metadata)
ChatWithInterruptsPersistence	messages + runs + interrupts
ChatPersistence	all four chat stores

defineAIPersistence preserves exact keys and rejects unknown keys at runtime.

Annotate your factory with a named shape. Bare AIPersistence is the all-optional sparse bag, so withPersistence and reconstructChat reject it (stores.messages is possibly undefined). This is the single most common mistake when writing an adapter.