ai-persistence/build-custom-adapter

Create a single chat-persistence.ts that implements the four stores (messages, runs, interrupts, metadata) against your existing database client, then assemble them with defineAIPersistence. Follow the seven idempotency invariants and verify with runPersistenceConformance from the testkit.

Use a custom adapter only when your database has no dedicated recipe, such as raw pg, Kysely, node:sqlite, MongoDB, or Redis. If the app already runs Drizzle, Prisma, or Cloudflare D1, route to those skills since they contain driver-specific code.

Redis works well for metadata and locks but is awkward for interrupts because listings need ordered secondary indexes you maintain by hand. A common split is Postgres for messages, runs, and interrupts with Redis for locks, combined via composePersistence.

The usual cause is checking patch.field !== undefined instead of 'field' in patch in runs.update, which cannot distinguish an omitted field from an explicit clear. An explicit undefined for detachedSince must write NULL, or reattached runs look permanently detached to the reaper.

Run runPersistenceConformance from @tanstack/ai-persistence/testkit against a throwaway database, declaring intentional omissions with skip and unimplemented optional methods with skipMethods. The suite checks all stores and the idempotency invariants.

Use a compound _id subdocument or a unique index on { namespace, key }, never a delimiter-joined string. Joined keys collide because ('a:b','c') and ('a','b:c') must remain distinct records, which the conformance suite checks.