ai-persistence/stores

Implement the store interfaces you need (messages, runs, interrupts, metadata) against your database, then pass them to defineAIPersistence annotated with a named shape like ChatWithInterruptsPersistence. Validate the result with runPersistenceConformance from the testkit.

withPersistence rejects adapters typed as bare AIPersistence because stores.messages is possibly undefined. Annotate your factory with a named shape such as ChatTranscriptPersistence or ChatWithInterruptsPersistence so the messages store is known present.

saveThread is a full overwrite of the thread's message history, not an append. A one-message payload wipes prior history, so adapters must replace the stored thread rather than inserting rows incrementally.

Yes, listByThread and listReclaimable are optional and consumers feature-detect them, but findActiveRun is required. Any omitted optional method must be declared in skipMethods or the conformance suite fails.

createOrResume must return an existing run unchanged, preserving its stored usage, startedAt, and status. Overwriting existing runs breaks safe resume and double-submit handling, causing duplicate or reset agent runs.

No, the package ships contracts plus memoryPersistence for dev and tests. Durable storage requires writing your own adapter for your database, with recipes available for Drizzle, Prisma, Cloudflare, and custom stacks.