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, MemoryConfig
from praisonaiagents import db

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    memory=MemoryConfig(
        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, MemoryConfig
   from praisonaiagents import db
   
   agent = Agent(
       name="Assistant",
       memory=MemoryConfig(
           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, MemoryConfig
   from praisonaiagents import db
   
   agent = Agent(
       name="Assistant",
       memory=MemoryConfig(
           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

Storage Backend Options

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

Dedicated guides exist for the most common backends:

Selecting a backend

The store kind narrows which URL schemes resolve to a registered backend. database_url= reaches conversation stores, state_url= reaches state stores, and knowledge_url= reaches vector stores. Kind-specific schemes take priority over generic http(s):// sniffing, so state_url="mongodb://…" reaches the MongoDB state store rather than falling through to conversation detection.

URL schemes per store kind

Explicit backend override

Some registered backends need out-of-band config the URL cannot carry — GCS (bucket_name), Cosmos DB (connection_string + database + container), and any custom driver whose scheme is not listed above. Reach them by naming the backend explicitly:

from praisonaiagents import Agent, MemoryConfig
from praisonaiagents import db

agent = Agent(
    name="Assistant",
    memory=MemoryConfig(
        db=db(
            state_backend="gcs",            # scheme-less state backend
            state_options={"bucket_name": "my-state-bucket"},
            knowledge_backend="cosmosdb",   # scheme-less knowledge backend
            knowledge_options={
                "connection_string": "AccountEndpoint=…",
                "database": "praison",
                "container": "vectors",
            },
        ),
        session_id="session-1",
    ),
)
agent.start("State in GCS, vectors in Cosmos DB")

database_backend=, state_backend=, and knowledge_backend= are keyword-only and always win over URL scheme detection — use them to reach any registered backend whose scheme is not auto-inferable (e.g. a private or custom driver).

Unknown scheme

PraisonAIDB fails loudly on a scheme it cannot map, pointing at the override:

ValueError: Unable to infer DB backend from URL 'foo://bar';
supported schemes: postgres://, mysql://, sqlite://, redis://, libsql://, http(s)://;
or pass an explicit state_backend= to select a registered state backend

Backend Aliases

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

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

Configuration Options

See Selecting a backend for the scheme tables and override examples.

import os
from praisonaiagents import Agent, MemoryConfig
from praisonaiagents import 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")

Best Practices

Related