Conversation store backends

All server-side backends require VITE_FEATURE_CONVERSATION_DB=true set at build time (before bun run build; this is a VITE_* build-time variable). Set CONVERSATION_STORE_BACKEND at runtime to force a specific backend, or leave it unset to auto-select.

Platform recommendation

Platform	Recommended store	Why
Cloudflare Workers	d1	Managed SQL, easy to inspect/migrate/export
Docker / self-hosted	postgres	Reuse existing infrastructure
Kubernetes	postgres	Standard managed database pattern
Any platform	agentstate	Cloud-hosted, no infrastructure to manage
Local development	memory	No setup; data is ephemeral

Auto-selection order

When CONVERSATION_STORE_BACKEND is not set, the server picks the first available backend:

1. AgentState — when AGENTSTATE_API_KEY is set and CONVERSATION_STORE_BACKEND is not explicitly d1, postgres, or memory.
2. Cloudflare D1 — when the CONVERSATIONS_D1 binding is present (Cloudflare Workers only).
3. Postgres — when DATABASE_URL is set.
4. Memory — fallback in development/CI.

AgentState

Cloud-hosted conversation store. Works on all platforms. Requires an as_live_ prefixed key.

AGENTSTATE_API_KEY=as_live_xxx
## AGENTSTATE_BASE_URL=https://agentstate.app/api   # optional override
## AGENTSTATE_AI_ENRICH=true                        # optional AI title enrichment
## CONVERSATION_STORE_BACKEND=agentstate             # optional — auto-selected when key is present

Cloudflare D1

Cloudflare-only. Requires a provisioned D1 database and a Worker binding.

CONVERSATION_STORE_BACKEND=d1
CONVERSATIONS_D1_DATABASE_ID=<uuid>

Provision and migrate:

bun run cf:setup-conversations
bun run cf:migrate-conversations

The setup script creates the D1 database, stores the UUID in wrangler.toml, and adds the CONVERSATIONS_D1 binding. The migration script applies the schema. During CI deploys, set CONVERSATIONS_D1_DATABASE_ID as a secret so wrangler deploy includes the binding. Without it, the binding is excluded from the deploy.

Also accepts AGENT_CONVERSATIONS_D1_DATABASE_ID as an alias for CONVERSATIONS_D1_DATABASE_ID.

When to use: standard Cloudflare deployments that want queryable, exportable conversation history.

Postgres

Any PostgreSQL-compatible database.

CONVERSATION_STORE_BACKEND=postgres
DATABASE_URL=postgresql://user:password@host:5432/db

Also accepts POSTGRES_URL or POSTGRES_PRISMA_URL instead of DATABASE_URL. The runtime creates the conversations table and indexes if they do not exist. The database user needs CREATE TABLE, CREATE INDEX, SELECT, INSERT, UPDATE, and DELETE on the target schema.

When to use: Kubernetes, Docker, or any deployment with an existing Postgres instance.

Memory

Ephemeral in-process store. Lost on process restart.

CONVERSATION_STORE_BACKEND=memory

Use only in development or tests.

Browser (default)

Default when VITE_FEATURE_CONVERSATION_DB is not true or when the user is unauthenticated. No server config needed. History is stored in browser localStorage. Clearing browser data loses history.

Deprecated alias

NEXT_PUBLIC_FEATURE_CONVERSATION_DB=true is equivalent to VITE_FEATURE_CONVERSATION_DB=true but is deprecated. Do not use it for new deployments.