MongoDB State Store

MongoDB stores agent state as flexible documents — ideal for nested metadata and schema-less data.

from praisonaiagents import Agent, db

agent = Agent(
    name="DocumentBot",
    instructions="You are a helpful assistant.",
    db=db(state_url="mongodb://localhost:27017/praisonai"),
    session_id="mongo-session",
)
agent.start("Store my preferences in MongoDB state")

The user sets preferences; MongoDB stores flexible agent state as documents.

Quick Start

Simple Usage

pip install pymongo praisonai

from praisonaiagents import Agent, db

agent = Agent(
    name="DocumentBot",
    db=db(state_url="mongodb://localhost:27017/praisonai"),
    session_id="session-1",
)
agent.start("Hello!")

With Configuration

Use MongoDBStateStore directly for collection and database control:

from praisonai.persistence import create_state_store

store = create_state_store(
    "mongodb",
    url="mongodb://localhost:27017",
    database="praisonai",
    collection="agent_state",
)
store.set("user:123:prefs", {"theme": "dark"}, ttl=3600)

How It Works

MongoDB is a state store — it holds key-value agent state, not full conversation history. Pair it with a SQL conversation backend when you need both.

Feature	Description
Document storage	Nested objects and arrays without a fixed schema
TTL index	Automatic expiry via `expires_at` field
Hash operations	`hget`, `hset`, `hgetall` for structured state

Configuration Options

Option	Type	Default	Description
`url`	`str`	`"mongodb://localhost:27017"`	MongoDB connection URL
`database`	`str`	`"praisonai"`	Database name
`collection`	`str`	`"state"`	Collection for state documents

URL formats

db(state_url="mongodb://localhost:27017/praisonai")
db(state_url="mongodb://user:pass@host:27017/praisonai?replicaSet=rs0")

For async workloads, use create_state_store("async_mongodb", ...).

Best Practices

Pair with a conversation backend

Use database_url for chat history and state_url for fast agent state — MongoDB handles state only.

Set TTL for ephemeral data

Pass ttl on set() for session-scoped preferences that should expire automatically.

Use replica sets in production

Append replicaSet= to the URL for high availability.

Choose collection names per app

Set collection="prod_state" vs collection="staging_state" to isolate environments on one cluster.

Redis State Store

In-memory state for sub-millisecond access

Database Persistence

Overview of conversation and state backends

Redis State Store

ClickHouse Persistence

​Quick Start

​How It Works

​Configuration Options

​URL formats

​Best Practices

​Related

Redis State Store

Database Persistence

Quick Start

How It Works

Configuration Options

URL formats

Best Practices

Related