Skip to main content

​
Database Persistence

PraisonAI Agents supports automatic conversation persistence with multiple database backends. Enable it with just 2 lines of code.

​
Quick Start

from praisonaiagents import Agent, db

# Create agent with database persistence
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    db=db(database_url="postgresql://localhost/mydb"),  # db(...) shortcut
    session_id="my-session"  # Optional: defaults to per-hour ID (YYYYMMDDHH)
)

# All chats are automatically persisted
agent.chat("Hello!")
New simplified import: Use from praisonaiagents import Agent, db for the cleanest API. The db module provides lazy-loaded database backends.

​
Installation

pip install "praisonai[tools]"

​
Supported Backends

CategoryBackends
ConversationPostgreSQL, MySQL, SQLite, SingleStore, Supabase, SurrealDB
Knowledge/VectorQdrant, ChromaDB, Pinecone, Weaviate, LanceDB, Milvus, PGVector, Redis
StateRedis, MongoDB, DynamoDB, Firestore, Upstash, Memory

​
Docker Setup (Local Development)

# PostgreSQL
docker run -d --name praison-postgres -p 5432:5432 \
    -e POSTGRES_PASSWORD=praison123 \
    -e POSTGRES_DB=praisonai \
    postgres:16

# Qdrant (vector search)
docker run -d --name praison-qdrant -p 6333:6333 qdrant/qdrant

# Redis (state/cache)
docker run -d --name praison-redis -p 6379:6379 redis:7

​
Usage Examples

​
PostgreSQL

from praisonaiagents import Agent
from praisonai.db import PostgresDB

db = PostgresDB(
    host="localhost",
    port=5432,
    database="praisonai",
    user="postgres",
    password="praison123"
)

agent = Agent(
    name="Assistant",
    db=db,
    session_id="user-123-session"
)

response = agent.chat("Remember my name is Alice")
# Later, with same session_id, agent remembers the conversation

​
SQLite (Zero Config)

from praisonaiagents import Agent
from praisonai.db import SQLiteDB

db = SQLiteDB(path="conversations.db")

agent = Agent(
    name="Assistant",
    db=db,
    session_id="local-session"
)

​
Auto-Detect Backend

from praisonai.db import PraisonDB

# PostgreSQL
db = PraisonDB(database_url="postgresql://user:pass@localhost/db")

# SQLite
db = PraisonDB(database_url="mydata.db")

# MySQL
db = PraisonDB(database_url="mysql://user:pass@localhost/db")

​
Session Resume

When you use the same session_id, the agent automatically loads previous conversation history: 
# First run
agent = Agent(name="Bot", db=db, session_id="session-001")
agent.chat("My favorite color is blue")

# Later run (same session_id)
agent = Agent(name="Bot", db=db, session_id="session-001")
agent.chat("What's my favorite color?")
# Agent remembers: "Your favorite color is blue"

​
Multiple Backends

Use different backends for conversation, state, and knowledge: 
from praisonai.db import PraisonDB

db = PraisonDB(
    database_url="postgresql://localhost/mydb",  # Conversations
    state_url="redis://localhost:6379",          # State/cache
    knowledge_url="http://localhost:6333"        # Vector search (Qdrant)
)

agent = Agent(name="Assistant", db=db, session_id="multi-backend")

​
API Reference

​
PraisonDB

PraisonDB(
    database_url: str = None,    # Conversation storage URL
    state_url: str = None,       # State storage URL  
    knowledge_url: str = None,   # Knowledge/vector storage URL
    **options                    # Backend-specific options
)

​
PostgresDB

PostgresDB(
    host: str = "localhost",
    port: int = 5432,
    database: str = "praisonai",
    user: str = "postgres",
    password: str = ""
)

​
SQLiteDB

SQLiteDB(path: str = "praisonai.db")

​
Best Practices

  1. Use consistent session_ids - Same session_id = same conversation thread
  2. Close connections - Call db.close() when done
  3. Use environment variables - Don’t hardcode credentials
import os
from praisonai.db import PraisonDB

db = PraisonDB(database_url=os.getenv("DATABASE_URL"))

​
Default Session ID

If you don’t provide a session_id, PraisonAI generates one automatically based on the current hour (UTC): 
Format: YYYYMMDDHH-{agent_hash}
Example: 2025122414-37812c
This means:
  • Conversations within the same hour automatically group together
  • Set session_id explicitly for persistent sessions across time
# Auto session_id (per-hour)
agent = Agent(name="Bot", db=db)  # session_id auto-generated

# Explicit session_id (recommended for continuity)
agent = Agent(name="Bot", db=db, session_id="user-123-thread-1")

​
CLI Commands

# Check database connectivity
praisonai persistence doctor

# Export session to file
praisonai persistence export --session-id my-session --output backup.jsonl

# Import session from file
praisonai persistence import --file backup.jsonl

# Check schema status
praisonai persistence status

# Apply migrations
praisonai persistence migrate

​
Environment Variables

export PRAISON_CONVERSATION_URL=postgresql://localhost:5432/praisonai
export PRAISON_STATE_URL=redis://localhost:6379
export PRAISON_KNOWLEDGE_URL=http://localhost:6333