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.

Quick Start

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

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

Configuration Options

Config keys read from MongoDBKnowledgeAdapter.__init__ under vector_store.config.

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"},
    },
}

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

Related