> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MongoDB Knowledge
> Use MongoDB Atlas as a scoped, vector-searchable knowledge backend
Store agent knowledge in MongoDB Atlas with per-tenant `user_id` / `agent_id` / `run_id` scope on every read and write.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "MongoDB Knowledge"
A[🤖 Agent] --> B[📥 add / 🔎 search]
B --> C[🍃 MongoDB Atlas]
C --> D[✅ Scoped results]
end
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef store fill:#6366F1,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class A agent
class B process
class C store
class D output
```
## Quick Start
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="SupportBot",
instructions="Answer using the customer's session history.",
knowledge={
"vector_store": {
"provider": "mongodb",
"config": {
"connection_string": "mongodb+srv://...",
"database": "praison",
"collection": "support_knowledge",
},
},
},
user_id="customer_42",
agent_id="support_bot_v1",
run_id="session_2026_08_09",
)
agent.start("What did we agree on for the refund?")
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Knowledge
kb = Knowledge(config={
"vector_store": {
"provider": "mongodb",
"config": {
"connection_string": "mongodb+srv://...",
"database": "praison",
"collection": "support_knowledge",
},
}
})
kb.add("Refund promised: $49 by Aug 12.",
user_id="customer_42", agent_id="support_bot_v1", run_id="session_2026_08_09")
kb.search("refund promise",
user_id="customer_42", agent_id="support_bot_v1", run_id="session_2026_08_09")
```
***
## How It Works
The adapter persists `user_id` / `agent_id` / `run_id` on each document and applies any provided scope as a pre-filter on search.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q[🔎 Query + scope] --> V{Atlas vector
search available?}
V -->|Yes| VS["$vectorSearch
filter: user_id / agent_id / run_id"]
V -->|No| TS["find #40;$text#41; + scope filter"]
VS --> R[✅ Scoped results]
TS --> R
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class Q input
class V decision
class VS,TS process
class R output
```
On Atlas `$vectorSearch`, the scope becomes the stage-level `filter`. Without Atlas vector search, the adapter falls back to MongoDB text search and merges the scope into the `find()` query. `None` values are dropped — omit an identifier to broaden the search on that dimension.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant Agent
participant Adapter as MongoDB adapter
participant Atlas as MongoDB Atlas
Agent->>Adapter: search(query, user_id=..., agent_id=...)
Adapter->>Atlas: $vectorSearch(filter=scope)
Atlas-->>Adapter: nearest documents in scope
Adapter-->>Agent: scoped results
```
***
## Configuration Options
Config keys read from `MongoDBKnowledgeAdapter.__init__` under `vector_store.config`.
| Option | Type | Default | Description |
| ------------------- | ------ | ------------------------------ | ------------------------------------------------------------------------ |
| `connection_string` | `str` | `"mongodb://localhost:27017/"` | MongoDB connection URI (use `mongodb+srv://...` for Atlas) |
| `database` | `str` | `"praisonai"` | Database name |
| `collection` | `str` | `"knowledge_base"` | Collection name |
| `use_vector_search` | `bool` | `True` | Enable Atlas `$vectorSearch`; falls back to text search when unavailable |
Embeddings are configured via the top-level `embedder` key:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
config = {
"vector_store": {
"provider": "mongodb",
"config": {
"connection_string": "mongodb+srv://...",
"database": "praison",
"collection": "support_knowledge",
},
},
"embedder": {
"provider": "openai",
"config": {"model": "text-embedding-3-small"},
},
}
```
***
## Common Patterns
Isolate a single customer's session by combining all three scopes:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
kb.search("refund promise",
user_id="customer_42", agent_id="support_bot_v1", run_id="session_2026_08_09")
```
Broaden across all sessions for one customer by omitting `run_id`:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
kb.search("refund history", user_id="customer_42")
```
***
## Best Practices
`use_vector_search=True` needs a MongoDB Atlas cluster with a vector index on the `embedding` path (similarity `cosine`). Without Atlas, the adapter transparently falls back to text search.
Provide `user_id` (and optionally `agent_id` / `run_id`) on both `add()` and `search()` to keep tenants isolated. Omitted scopes broaden the search on that dimension.
Passing `knowledge={...}` and `user_id=...` on the `Agent` handles scoping and context injection automatically. Use the direct `Knowledge` class only for custom indexing or search control.
Atlas connection strings start with `mongodb+srv://` or contain `mongodb.net` — the adapter detects these to enable vector search.
As of PR [#3810](https://github.com/MervinPraison/PraisonAI/pull/3810), the MongoDB adapter honors `user_id` / `agent_id` / `run_id` on both `add()` and `search()`. On earlier releases these kwargs were silently ignored, producing cross-tenant results. Upgrade to a release built after commit `6b6707c1`.
***
## Related
Compare Chroma, mem0, and MongoDB storage backends
Use MongoDB as the agent memory store