MongoDB State Store

Flexible document storage for agent state with TTL and rich metadata

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

1. 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!")
   
2. 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.

---

Related

Redis State Store

In-memory state for sub-millisecond access

Database Persistence

Overview of conversation and state backends