MongoDB Knowledge

Store agent knowledge in MongoDB Atlas with per-tenant user_id / agent_id / run_id scope on every read and write.

Quick Start

Agent with MongoDB knowledge

from praisonaiagents import Agent, MemoryConfig

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",
            },
        },
    },
    memory=MemoryConfig(user_id="customer_42", session_id="session_2026_08_09"),
)

agent.start("What did we agree on for the refund?")

Direct Knowledge API

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. 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.

Full Method Surface

Since PR #5320 the MongoDB adapter implements the full KnowledgeStoreProtocol. Methods taking scope require at least one of user_id / agent_id / run_id; get / update / delete operate on a specific item_id and need no scope.

Method	Signature (key args)	Returns	Raises
`add(text, metadata?, user_id?, agent_id?, run_id?)`	≥1 scope required	`str` (document ID)	`ScopeRequiredError`
`search(query, limit=5, user_id?, agent_id?, run_id?, filters?)`	≥1 scope required	`List[dict]`	`ScopeRequiredError`
`get_all(user_id?, agent_id?, run_id?, limit=100)`	≥1 scope required	`SearchResult`	`ScopeRequiredError`
`delete_all(user_id?, agent_id?, run_id?)`	≥1 scope required	`bool`	`ScopeRequiredError`
`get(item_id)`	—	`SearchResultItem \| None`	—
`update(item_id, content, metadata?)`	—	`AddResult`	—
`delete(document_id)`	—	`bool`	—

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. The adapter recombines it into a litellm string as "<provider>/<model>" — except openai, which stays bare. It falls back to text-embedding-3-small when nothing is set:

config = {
    "vector_store": {
        "provider": "mongodb",
        "config": {
            "connection_string": "mongodb+srv://...",
            "database": "praison",
            "collection": "support_knowledge",
        },
    },
    "embedder": {
        "provider": "openai",
        "config": {"model": "text-embedding-3-small"},
    },
}

Run knowledge fully local by pointing the same embedder block at Ollama:

config = {
    "vector_store": {
        "provider": "mongodb",
        "config": {
            "connection_string": "mongodb://localhost:27017/",
            "database": "praison",
            "collection": "support_knowledge",
        },
    },
    "embedder": {
        "provider": "ollama",
        "config": {"model": "nomic-embed-text"},
    },
}

Atlas vector search indexes are built for a specific dimension. Switching the embedder model — e.g. from text-embedding-3-small (1536) to nomic-embed-text (768) — means you must re-create the vector index on the collection at the new dimension, or searches will error or return nothing.

Common Patterns

Isolate a single customer’s session by combining all three scopes:

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:

kb.search("refund history", user_id="customer_42")

Narrow the search to a single metadata field with filters=:

# Narrow the search to a single metadata field
kb.search("policy questions",
          user_id="customer_42",
          filters={"category": "policy"})

The MongoDB adapter silently dropped filters before PR #5320; it now folds each key in as metadata.<key> alongside the scope on both Atlas $vectorSearch and the text-search fallback.

Best Practices

Use Atlas for vector search

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.

Always pass scope for multi-tenant apps

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.

Prefer the Agent API

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.

Use mongodb+srv:// for Atlas connections

Atlas connection strings start with mongodb+srv:// or contain mongodb.net — the adapter detects these to enable vector search.

Since PR #3810, the MongoDB adapter honors user_id / agent_id / run_id on add() and search(). Since PR #5320, it also enforces those scopes: an unscoped add() / search() / get_all() / delete_all() raises ScopeRequiredError (previously an unscoped search() silently returned every tenant’s documents). The adapter also now defines get_all(), delete_all(), update(), and get() — earlier releases raised AttributeError for those calls on a MongoDB-backed Knowledge.

Knowledge Backends

Compare Chroma, mem0, and MongoDB storage backends

MongoDB Memory

Use MongoDB as the agent memory store

Local Memory & Knowledge

Run memory and knowledge fully local with Ollama embeddings

Ollama Embeddings

Local embedding models and their auto-detected dimensions

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

How It Works

Full Method Surface

Configuration Options

Common Patterns

Best Practices

Knowledge Backends

MongoDB Memory

Local Memory & Knowledge

Ollama Embeddings

​Quick Start

​How It Works

​Full Method Surface

​Configuration Options

​Common Patterns

​Best Practices

​Related

Knowledge Backends

MongoDB Memory

Local Memory & Knowledge

Ollama Embeddings

Quick Start

How It Works

Full Method Surface

Configuration Options

Common Patterns

Best Practices

Related