iframe-proxy | Sunbelt Computer Software

Choose the right storage backend for your knowledge base — from local development with Chroma to multi-tenant production with mem0.

from praisonaiagents import Agent

agent = Agent(
    name="Research Assistant",
    instructions="You are a research assistant.",
    knowledge=["./documents/"],
)

agent.start("What are the main findings?")

The user asks a question; the agent retrieves from mem0, Chroma, or a custom knowledge store you configured.

How It Works

Quick Start

Simple — enable with True

from praisonaiagents import Agent

agent = Agent(
    name="ResearchAssistant",
    instructions="You are a research assistant.",
    knowledge=["./documents/"],
    memory={"user_id": "user123"},
)

response = agent.chat("What are the main findings?")

With backend config

from praisonaiagents import Agent

agent = Agent(
    name="ResearchAssistant",
    instructions="You are a research assistant.",
    knowledge={
        "vector_store": {
            "provider": "chroma",
            "config": {
                "collection_name": "my_docs",
                "path": "./.praison/knowledge/my_docs",
            }
        }
    },
    memory={"user_id": "user123"},
)

Available Backends

Backend	Description	Best For
mem0 (default)	Long-term memory with semantic search	Multi-user apps, persistent memory
chroma	Local vector database	Development, single-user apps
internal	Built-in lightweight storage	Simple use cases

Scope Identifiers

Knowledge backends support three scope identifiers for multi-tenant isolation:

Identifier	Purpose	Example
`user_id`	Isolate per user	`"user_alice"`
`agent_id`	Isolate per agent type	`"research_agent_v1"`
`run_id`	Isolate per session	`"session_abc123"`

The mem0 backend requires at least one scope identifier. If none is provided, operations will fail with a ScopeRequiredError.

delete_all() requires a scope. The Chroma and SQLite backends now enforce the same contract as mem0: an unscoped delete_all() raises ScopeRequiredError instead of silently wiping the entire (typically shared) collection or table. Scoped deletes are unchanged.

# ✅ Scoped — deletes only Alice's items
knowledge.delete_all(user_id="alice")

# ❌ Unscoped — raises ScopeRequiredError (no data-loss / cross-tenant wipe)
knowledge.delete_all()

Example with Scope

from praisonaiagents import Agent

# User-scoped knowledge
agent = Agent(
    name="PersonalAssistant",
    instructions="You are a personal assistant.",
    knowledge=["./user_docs/"],
    memory={"user_id": "alice"} ,  # Knowledge scoped to Alice
)

# Agent-scoped knowledge (shared across users)
shared_agent = Agent(
    name="CompanyBot",
    instructions="You answer company policy questions.",
    knowledge=["./policies/"],
    agent_id="company_bot_v1",  # Shared knowledge
)

Combining Multiple Scopes

Combine user_id, agent_id, and run_id to isolate knowledge down to a specific session for a specific agent and user.

from praisonaiagents import Agent, MemoryConfig

agent = Agent(
    name="SupportBot",
    instructions="Answer using the customer's session history.",
    knowledge=["./support_docs/"],
    memory=MemoryConfig(user_id="customer_42", session_id="session_2026_05_30"),
)

agent.start("What did we discuss about my refund?")

You can also use the direct API for more control:

results = knowledge.search(
    "refund discussion",
    user_id="customer_42",
    agent_id="support_bot_v1",
    run_id="session_2026_05_30",
)

When you pass more than one scope identifier, PraisonAI automatically combines them using ChromaDB’s $and operator. A single identifier is passed through unchanged. You don’t need to write the $and yourself.

MongoDB backend

The MongoDB knowledge adapter honors the same user_id / agent_id / run_id scope on add() and search().

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 API — same scope keywords:

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")

On Atlas $vectorSearch, the scope is injected as the stage-level filter; on the text-search fallback, it is merged into the find() query. Only provided scopes are applied — omit an identifier to broaden the search on that dimension.

All provided identifiers are required to match (logical AND). Omit an identifier to broaden the scope on that dimension.

Multi-tenant SaaS application flow:

Per-customer isolation → set user_id
Per-agent isolation (e.g. SupportBot vs. SalesBot share infra but not data) → also set agent_id
Per-conversation isolation (e.g. ephemeral session memory) → also set run_id

Direct Knowledge API

For advanced use cases, you can use the Knowledge class directly:

from praisonaiagents import Knowledge

# Initialize with config
knowledge = Knowledge(config={
    "vector_store": {
        "provider": "chroma",
        "config": {
            "collection_name": "my_docs",
            "path": "./.praison/knowledge/my_docs",
        }
    }
})

# Add documents
knowledge.add("./documents/", memory={"user_id": "user123"})

# Search
results = knowledge.search("query", user_id="user123", limit=10)

Normalization Guarantees

PraisonAI normalizes all backend results to ensure consistent behavior:

metadata is ALWAYS a dict (never None)
text field is always present (mapped from memory for mem0)
score is always a float (defaults to 0.0)

This means you can safely access metadata without null checks:

# Safe - metadata is guaranteed to be a dict
for result in results['results']:
    source = result.get('metadata', {}).get('source', 'unknown')
    # This works even if the backend returns metadata=None

Protocol-Driven Architecture

All backends implement the KnowledgeStoreProtocol:

from praisonaiagents import KnowledgeStoreProtocol

class MyCustomBackend:
    """Custom backend implementing the protocol."""
    
    def search(self, query, *, user_id=None, agent_id=None, run_id=None, **kwargs):
        # Your implementation
        pass
    
    def add(self, content, *, user_id=None, agent_id=None, run_id=None, **kwargs):
        # Your implementation
        pass
    
    # ... other methods

Supported Providers

Set vector_store.provider to any name below. The value resolves through the Knowledge adapter registry.

Provider	Resolves to	Notes
`mem0`	`Mem0Adapter`	Default when no provider set. Multi-tenant, scope-required.
`chroma`	`ChromaAdapter`	Local persistent vector DB.
`chromadb`	`ChromaAdapter`	Alias for `chroma`.
`rag`	`ChromaAdapter`	Alias for `chroma`.
`mongodb`	`MongoDBKnowledgeAdapter`	Requires connection string.
`sqlite`	`SQLiteKnowledgeAdapter`	Zero-dependency fallback.
anything registered via `register_knowledge_adapter()`	Custom adapter	See Custom Knowledge Adapters.

Setting vector_store.provider to a name that isn’t a built-in adapter and hasn’t been registered raises ValueError with the list of valid names. This is intentional — the old behaviour silently ran on Mem0, hiding typos and custom-adapter bugs. The implicit default (omit vector_store entirely) still falls back to Mem0.Explicit falsey values ("" or None) raise too. Only the missing-config default is silent.

qdrant, pgvector, milvus, and pinecone are not top-level Knowledge providers. They are inner backends of mem0. Set provider: "mem0" and place the store name inside mem0’s nested config — see mem0 Backend below.

Configuration Options

mem0 Backend (Default)

Top-level provider is mem0; qdrant, pgvector, and similar stores live inside mem0’s nested config.

config = {
    "vector_store": {
        "provider": "mem0",
        "config": {
            "vector_store": {
                "provider": "qdrant",  # mem0's inner backend
                "config": {
                    "collection_name": "my_collection",
                }
            }
        }
    }
}

Chroma Backend

path is optional. Omit it and the store persists under an absolute per-project directory: <project>/.praisonai/knowledge/chroma. The store is isolated per project, so multiple projects (or Windows setups) never share one on-disk sqlite.

config = {
    "vector_store": {
        "provider": "chroma",
        "config": {
            "collection_name": "my_collection",
            "path": "./.praison/knowledge/my_collection",
        }
    }
}

A corrupt or cross-project Chroma store raises RuntimeError: Chroma persist failed at '<path>' (PanicException: ...) instead of crashing the process. Delete <path> and re-index, or point path at a fresh directory. See Knowledge Storage.

Error Handling

from praisonaiagents import (
    ScopeRequiredError,
    BackendNotAvailableError,
)

try:
    results = knowledge.search("query")  # Missing scope!
except ScopeRequiredError as e:
    print(f"Please provide user_id, agent_id, or run_id: {e}")
except BackendNotAvailableError as e:
    print(f"Backend not available: {e}")

Collection Naming Rules

Enhanced Security (PR #1597): Knowledge stores now validate collection names to prevent SQL injection attacks.

Knowledge stores that interpolate collection names into DDL/DML now require collection names to match ^[A-Za-z0-9_]+$. Affected backends:

Cassandra
pgvector
SingleStore vector

Invalid names raise: ValueError("collection_name must be non-empty and contain only alphanumerics and underscores") Valid examples:

my_collection
UserData123
agent_v2_docs

Invalid examples:

my-collection (contains hyphen)
user.docs (contains dot)
data collection (contains space)
../../etc (path traversal attempt)

Best Practices

Always provide scope identifiers for mem0

The mem0 backend requires at least one scope identifier. Without it, operations raise ScopeRequiredError.

agent = Agent(
    knowledge=["./docs"],
    memory={"user_id": "alice"},
)

Use alphanumeric collection names

Collection names must match ^[A-Za-z0-9_]+$ for backends that use DDL/DML (Cassandra, pgvector, SingleStore).Valid: my_collection, UserData123. Invalid: my-collection, user.docs.

Prefer Agent API over direct Knowledge API

The Agent API handles scoping, retrieval, and context injection automatically. Use the direct Knowledge class only when you need custom control over indexing or search.

Implement KnowledgeStoreProtocol for custom backends

Any class implementing KnowledgeStoreProtocol works as a backend — no base class inheritance needed.

from praisonaiagents import KnowledgeStoreProtocol

class MyBackend:
    def search(self, query, *, user_id=None, **kwargs): ...
    def add(self, content, *, user_id=None, **kwargs): ...

Extension: Custom Adapters

from praisonaiagents import Agent, Knowledge
from praisonaiagents.knowledge.adapters import register_knowledge_adapter

class QdrantKnowledgeAdapter:
    def __init__(self, config=None, verbose=0):
        self.config = config
    def store(self, *args, **kwargs): ...
    def search(self, *args, **kwargs): return []
    def delete(self, *args, **kwargs): ...

register_knowledge_adapter("qdrant", QdrantKnowledgeAdapter)

agent = Agent(
    name="Researcher",
    instructions="Answer using the knowledge base.",
    knowledge=Knowledge(config={"vector_store": {"provider": "qdrant"}}),
)

Register before the first Agent(...) or Knowledge(...) call reads .memory. See Custom Knowledge Adapters for the full protocol contract and registration API.

Behaviour on Unknown Provider

An explicitly-configured provider that isn’t a built-in adapter and hasn’t been registered raises ValueError.

from praisonaiagents import Knowledge

Knowledge(config={"vector_store": {"provider": "definitely_not_a_store"}})
# ValueError: unknown knowledge vector_store provider 'definitely_not_a_store'.
# Valid: chroma, chromadb, mem0, mongodb, rag, sqlite

Confirm which adapter you actually got:

from praisonaiagents import Knowledge

kb = Knowledge(config={
    "vector_store": {
        "provider": "chroma",
        "config": {"collection_name": "my_docs"},
    }
})
print(type(kb.memory).__name__)   # 'ChromaAdapter'

Explicit "" and None raise as well. Only the implicit default (omit vector_store entirely) silently falls back to Mem0 with a debug log — the raise catches typos and custom-adapter registration bugs early.

Shipped vs Plugin Providers

Top-level vector_store.provider accepts only providers with a registered Knowledge adapter.

Provider	Status	How to use
`chroma`	Shipped	Works out of the box — recommended default
`qdrant`, `pinecone`, `weaviate`, `milvus`, `pgvector`	Plugin	Call `register_knowledge_adapter(name, adapter_cls)` first (see Extension: Custom Adapters)

qdrant, pgvector, milvus, and pinecone also work as inner backends of mem0 without registration — set provider: "mem0" and nest the store under mem0’s own config. See mem0 Backend.

Incremental Indexing

Skip unchanged files for fast knowledge base updates

Knowledge

Core knowledge retrieval and agent integration

Vector Store

Store and query embeddings with a pluggable, namespace-aware backend

Sunbelt Computer Software

PL/B Language Development and Support

​How It Works

​Quick Start

​Available Backends

​Scope Identifiers

​Example with Scope

​Combining Multiple Scopes

​MongoDB backend

​Direct Knowledge API

​Normalization Guarantees

​Protocol-Driven Architecture

​Supported Providers

​Configuration Options

​mem0 Backend (Default)

​Chroma Backend

​Error Handling

​Collection Naming Rules

​Best Practices

​Extension: Custom Adapters

​Behaviour on Unknown Provider

​Shipped vs Plugin Providers

​Related

Incremental Indexing

Knowledge

Vector Store

How It Works

Quick Start

Available Backends

Scope Identifiers

Example with Scope

Combining Multiple Scopes

MongoDB backend

Direct Knowledge API

Normalization Guarantees

Protocol-Driven Architecture

Supported Providers

Configuration Options

mem0 Backend (Default)

Chroma Backend

Error Handling

Collection Naming Rules

Best Practices

Extension: Custom Adapters

Behaviour on Unknown Provider

Shipped vs Plugin Providers

Related