Database Persistence

Persist agent conversations, state, and knowledge across SQL, key-value, vector, and cloud backends

Database persistence keeps conversation history and state across restarts — pick a backend for your scale.

from praisonaiagents import Agent, db

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    db=db(database_url="sqlite:///conversations.db"),
    session_id="my-session",
)
agent.start("Hello — saved automatically")

The user returns later; the configured backend restores conversation history and agent state.

Quick Start

1. Simple Usage

   from praisonaiagents import Agent, db
   
   agent = Agent(
       name="Assistant",
       db=db(database_url="sqlite:///conversations.db"),
       session_id="session-1",
   )
   agent.start("Hello!")
   
2. With Configuration

   Hybrid setup — SQL for conversations, Redis for state:

   import os
   from praisonaiagents import Agent, db
   
   agent = Agent(
       name="Assistant",
       db=db(
           database_url=os.getenv("PRAISON_CONVERSATION_URL", "sqlite:///conversations.db"),
           state_url=os.getenv("PRAISON_STATE_URL", "redis://localhost:6379"),
       ),
       session_id="hybrid-session",
   )
   agent.start("Conversations in SQL, state in Redis")
   

---

How It Works

Component	Purpose	Example backends
ConversationStore	Messages, sessions, metadata	SQLite, PostgreSQL, MySQL
StateStore	Application state, key-value data	Redis, MongoDB
DefaultSessionStore	File-based sessions	JSON files on disk

---

Storage Backend Options

The registry supports 12 conversation, 9 state, and 20 knowledge backends — configure each store by URL scheme.

Conversation

Backend	Aliases	Best for
sqlite	—	Local development, single instance
sync_sqlite	sqlite_sync	Synchronous file access
async_sqlite	aiosqlite, sqlite_async	Async file access
postgres	neon, cockroachdb, crdb, cockroach, xata	Production SQL
async_postgres	asyncpg, postgres_async	Async Postgres
mysql	—	Existing MySQL infrastructure
async_mysql	aiomysql, mysql_async	Async MySQL
turso	libsql	Serverless SQLite over the network
supabase	—	Managed Postgres platform
singlestore	—	Distributed SQL
surrealdb	—	Multi-model database
json	—	Zero-dependency file storage

State

Backend	Aliases	Best for
memory	—	In-process, non-persistent
redis	—	Sub-millisecond in-memory state
valkey	—	Redis-compatible OSS fork
upstash	—	Serverless cloud KV
dynamodb	—	AWS-managed KV
firestore	—	Google Cloud document store
mongodb	—	Document-based state
async_mongodb	motor, mongodb_async	Async MongoDB
gcs	—	Object storage (requires bucket_name)

Knowledge

Backend	Aliases	Best for
chroma	chromadb	Embedded vector store
qdrant	—	Managed vector search
pinecone	—	Serverless vector database
weaviate	—	Hybrid search
lancedb	—	Embedded columnar vectors
milvus	—	Scalable vector search
pgvector	—	Postgres vector extension
redis	—	Redis vector index
valkey	—	Valkey vector index
cassandra	—	Wide-column vectors
clickhouse	—	Analytics-backed vectors
mongodb_vector	mongodb_atlas, mongo_vector	MongoDB Atlas vectors
couchbase	—	Distributed document vectors
singlestore_vector	singlestore_v	Distributed SQL vectors
surrealdb_vector	surrealdb_v	Multi-model vectors
upstash_vector	upstash_v	Serverless vector KV
cosmosdb	cosmos, azure_cosmos, cosmosdb_vector	Azure Cosmos DB vectors
lightrag	—	Graph-augmented retrieval
langchain	langchain_adapter	LangChain vector adapter
llamaindex	llama_index, llamaindex_adapter	LlamaIndex adapter

Dedicated guides exist for the most common backends:

SQLite

Local file database for development and single-instance apps

PostgreSQL

Production SQL with JSONB and connection pooling

MySQL

Popular SQL database with broad tooling support

Redis

Fast in-memory state store

MongoDB

Flexible document store for complex state

ClickHouse

Analytics database for large-scale data

JSON Files

Simple file-based storage with cross-platform locking

The registry is the authoritative list, not the docs. Call list_available_backends() at runtime to discover the current set:

from praisonai.persistence.config import list_available_backends

print(list_available_backends())
# {"conversation": [...], "state": [...], "knowledge": [...]}

---

Backend Aliases

Configure with either name — the registry resolves aliases before instantiating the factory (PraisonAI PR #2669).

Alias	Resolves to	Store
neon, xata, cockroachdb, crdb, cockroach	postgres	Conversation
asyncpg, postgres_async	async_postgres	Conversation
aiomysql, mysql_async	async_mysql	Conversation
sqlite_sync	sync_sqlite	Conversation
aiosqlite, sqlite_async	async_sqlite	Conversation
libsql	turso	Conversation
motor, mongodb_async	async_mongodb	State
mongodb_atlas, mongo_vector	mongodb_vector	Knowledge
chromadb	chroma	Knowledge
cosmos, azure_cosmos, cosmosdb_vector	cosmosdb	Knowledge
llama_index, llamaindex_adapter	llamaindex	Knowledge
langchain_adapter	langchain	Knowledge

PersistenceConfig(state_store="motor").validate() now succeeds and resolves to AsyncMongoDBStateStore. Unknown names still fail loudly, listing the current registry backends.

---

Configuration Options

Parameter	Description
database_url	Conversation store URL
state_url	State / run history store
knowledge_url	Vector or knowledge store

import os
from praisonaiagents import Agent, MemoryConfig, db

agent = Agent(
    name="Researcher",
    memory=MemoryConfig(
        db=db(
            database_url=os.getenv("PRAISON_CONVERSATION_URL"),
            state_url=os.getenv("PRAISON_STATE_URL"),
        ),
        session_id="research-42",
    ),
)
agent.start("Continue our research thread")

Database backends require the praisonai wrapper (pip install praisonai). The core SDK defines DbAdapter; implementations live in praisonai.persistence.

---

Best Practices

Choose the right backend

SQLite for development; PostgreSQL or MySQL for multi-user production; Redis for fast state; JSON files for minimal dependencies.

Use meaningful session IDs

Set session_id="user-123" so conversations resume reliably across restarts.

Read credentials from the environment

Never hardcode database URLs — use os.getenv("PRAISON_CONVERSATION_URL").

Separate stores by concern

Conversation history, run traces, and vectors scale differently — configure each URL independently.

---

Related

Database Persistence (Advanced)

MemoryConfig, CLI commands, and Docker setup

Session Persistence

JSON file sessions without a database