Persistence adapter for ChatClient

[DiegoGBrisa]

Problem

Right now there's no way to persist conversations on the client — if the page reloads or the user navigates away, the chat history is gone. You can wire it up manually through initialMessages and onFinish, but it's easy to miss edge cases (like clear(), tool results, or approval flows), and everyone ends up writing the same boilerplate.

This is especially relevant for SPAs, Electron apps, and offline-first setups where there's no server managing conversation state — the client is the source of truth.

Proposal

A simple, optional persistence option on ChatClient — same getItem/setItem/removeItem shape as ToolCacheStorage:

interface ChatPersistenceAdapter {
    getItem: (id: string) => Array<UIMessage> | undefined | Promise<Array<UIMessage> | undefined>
    setItem: (id: string, messages: Array<UIMessage>) => void | Promise<void>
    removeItem: (id: string) => void | Promise<void>
  }

When provided, ChatClient hydrates from getItem(id) on construction, saves on message changes, and clears on clear(). When omitted, everything works exactly as it does today — no breaking changes.

Where it lives

The interface and integration live in @tanstack/ai-client on ChatClient. Framework wrappers just pass it through as another option.

Usage

// Framework-agnostic
  const client = new ChatClient({
    id: 'conversation-123',
    connection: adapter,
    persistence: myPersistenceAdapter,
  })

// React — same option
  const chat = useChat({
    id: 'conversation-123',
    connection: adapter,
    persistence: myPersistenceAdapter,
  })

Custom adapter example

Users implement the three methods for whatever storage backend they need — IndexedDB, SQLite, a database, anything:

  const indexedDbPersistence: ChatPersistenceAdapter = {
    getItem: async (id) => {
      const record = await db.conversations.get(id)
      return record?.messages
    },
    setItem: async (id, messages) => {
      await db.conversations.put({ id, messages, updatedAt: Date.now() })
    },
    removeItem: async (id) => {
      await db.conversations.delete(id)
    },
  }

Happy to help with implementation if there's interest.