Knowledge Base

Add document and URL knowledge to agents for grounded, accurate answers

The knowledge system lets agents retrieve relevant information from PDFs, documents, and URLs before answering, grounding responses in your own sources.

from praisonaiagents import Agent

agent = Agent(
    name="Research Assistant",
    instructions="Answer questions using the knowledge base.",
    knowledge=["research_paper.pdf", "data.txt"],
)

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

The user asks about their documents; the agent embeds, searches, and answers from your PDFs and URLs.

Key Features

Process PDFs, documents, spreadsheets, images, and web content

Multiple strategies for optimal text segmentation

Vector-based search with optional reranking

User, agent, and run-specific knowledge scoping

Optional relationship extraction and storage

Automatic quality assessment for stored knowledge

Quick Start

1. Level 1 — List of sources (simplest)

   Pass a list of files or URLs and the agent answers from them.

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Research Assistant",
       instructions="Answer questions using the knowledge base.",
       knowledge=["research_paper.pdf", "data.txt"],
   )
   
   agent.start("What are the key findings?")
   
2. Level 2 — Dict (inline config)

   Use a dict to pick a vector store while still passing sources inline.

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Research Assistant",
       instructions="Answer questions using the knowledge base.",
       knowledge={
           "sources": ["research_paper.pdf", "data.txt"],
           "vector_store": {
               "provider": "chroma",
               "config": {"collection_name": "research_docs", "path": ".praison"},
           },
       },
   )
   
   agent.start("What are the key findings?")
   
3. Level 3 — Config class (full control)

   Use KnowledgeConfig for typed control over chunking, retrieval, and reranking.

   from praisonaiagents import Agent, KnowledgeConfig
   
   agent = Agent(
       name="Research Assistant",
       instructions="Answer questions using the knowledge base.",
       knowledge=KnowledgeConfig(
           sources=["research_paper.pdf", "data.txt"],
           chunking_strategy="semantic",
           retrieval_k=5,
           rerank=True,
       ),
   )
   
   agent.start("What are the key findings?")
   

How It Works

Phase	What happens
1. Add	Documents are chunked, embedded, and stored in the vector store via knowledge.add()
2. Search	knowledge.search(query) embeds the query and returns top-k similar chunks
3. Retrieve	Agent injects the chunks as context before calling the LLM
4. Generate	LLM answers using the retrieved knowledge; responses are grounded in your data

---

Configuration Options

KnowledgeConfig SDK Reference

Full parameter reference for KnowledgeConfig

The most common options at a glance:

Option	Type	Default	Description
sources	list[str]	[]	Files, directories, or URLs to index
embedder	str	"openai"	Embedder to use for vector encoding
chunking_strategy	str	"semantic"	"fixed" / "semantic" / "sentence" / "paragraph"
retrieval_k	int	5	Number of chunks to retrieve per query
rerank	bool	False	Apply reranking to improve result order

Basic Configuration

Set vector_store.provider explicitly and a fallback (e.g. to SQLite) is logged at WARNING level with Retrieval quality may be reduced so you notice it. Rely on the default (no explicit provider) and a fallback stays at DEBUG, because that path is expected (PR #2982).

knowledge_config = {
    "vector_store": {
        "provider": "chroma",
        "config": {
            "collection_name": "knowledge_base",
            "path": ".praison",
            "distance_metric": "cosine"
        }
    },
    "embedder": {
        "provider": "openai",
        "config": {
            # Overridden by OPENAI_EMBEDDING_MODEL if set; see /docs/cli/knowledge-cli#environment-variables
            "model": "text-embedding-3-small"
        }
    }
}

If your configured backend seems ignored

Configure a mem0 or mongodb vector store on a release before 2026-07-14 and find that searches feel like keyword matching? Your Knowledge instance may have been silently falling back to SQLite. This was a bug (fixed in PR #2982) where the adapter constructors rejected an internal verbose keyword and the resulting TypeError was swallowed.

Check which adapter you actually got:

from praisonaiagents import Knowledge

kb = Knowledge(config={
    "vector_store": {
        "provider": "mem0",
        "config": {"collection_name": "my_docs"},
    }
})
print(type(kb.memory).__name__)   # 'Mem0Adapter' on the fix; 'SQLiteKnowledgeAdapter' means you're on a buggy release.

Upgrade to a release built from main after commit 69d7ecf to fix it. An explicitly-configured backend that fails to initialise now emits a WARNING log — no more silent degradation:

WARNING praisonaiagents.knowledge.knowledge: Knowledge provider 'mem0' failed to initialize (<reason>); falling back to a different backend. Retrieval quality may be reduced.

The configured backend is honoured on releases built after commit 69d7ecf; before that, the same code silently ran on SQLite.

from praisonaiagents import Agent, Knowledge

kb = Knowledge(config={
    "vector_store": {
        "provider": "mem0",
        "config": {"collection_name": "research_docs"},
    }
})

agent = Agent(
    name="Researcher",
    instructions="Answer research questions using the knowledge base.",
    knowledge=kb,
)

agent.start("What did we learn about solar output in 2024?")

Advanced Configuration with Graph Store

knowledge_config = {
    "vector_store": {
        "provider": "chroma",
        "config": {
            "collection_name": "knowledge_base",
            "path": ".praison"
        }
    },
    "graph_store": {
        "provider": "neo4j",
        "config": {
            "url": "bolt://localhost:7687",
            "username": "neo4j",
            "password": "password"
        }
    },
    "llm": {
        "provider": "openai",
        "config": {
            "model": "gpt-4o-mini",
            "temperature": 0
        }
    },
    "reranker": {
        "enabled": True,
        "default_rerank": False
    }
}

Choosing Sources and Chunking

Pick a source type, then a chunking strategy that matches your content.

Chunking Strategies

Token-based Chunking

kb = Knowledge({
    "chunker": {
        "name": "token",
        "chunk_size": 500,
        "chunk_overlap": 50
    }
})

Best for: Consistent chunk sizes, token-limited models

kb = Knowledge({
    "chunker": {
        "name": "sentence",
        "chunk_size": 10,  # sentences per chunk
        "min_chunk_size": 3
    }
})

Best for: Natural text boundaries, Q&A systems

kb = Knowledge({
    "chunker": {
        "name": "semantic",
        "threshold": 0.7,
        "min_chunk_size": 100
    }
})

Best for: Topic-based segmentation, research papers

kb = Knowledge({
    "chunker": {
        "name": "sdpm",
        "max_chunk_size": 1000
    }
})

Best for: Document structure preservation

Document Processing

Supported File Types

• PDF (.pdf)
• Word (.doc, .docx)
• Text (.txt)
• Markdown (.md)
• RTF (.rtf)

• Excel (.xls, .xlsx)
• CSV (.csv)
• JSON (.json)
• XML (.xml)

• Images (OCR)
• HTML pages
• Web URLs
• YouTube videos

Processing Options

# Add with metadata
kb.add(
    "research.pdf",
    user_id="user123",
    metadata={
        "category": "AI Research",
        "year": 2024,
        "author": "Dr. Smith"
    }
)

# Batch processing
documents = ["doc1.pdf", "doc2.txt", "doc3.md"]
for doc in documents:
    kb.add(doc, user_id="user123")

# URL processing
kb.add("https://arxiv.org/pdf/2301.00000.pdf", user_id="user123")

Handling indexing failures

Indexing errors are surfaced, not swallowed. When the embedding call fails, the CLI exits non-zero and the Python API raises.

Knowledge.add(source) from Python raises RuntimeError on the first source whose embedding fails. Wrap batch calls in try / except to keep going.

from praisonaiagents import Knowledge

kb = Knowledge()
try:
    kb.add("research_paper.pdf")
except RuntimeError as e:
    # message includes the embedding model and the underlying error, e.g.
    # "Failed to generate embedding (model=text-embedding-3-small): 403 model_not_found"
    print(f"Indexing failed: {e}")

The lower-level ChromaKnowledgeAdapter.add() returns an AddResult instead of raising:

result = adapter.add("Paris is the capital of France.")
if not result.success:
    print(result.message)   # "Failed to generate embedding (model=…): …"

Search degrades gracefully — a failed embedding is logged at WARNING and the call returns an empty SearchResult rather than raising, so an embedding outage cannot bring down the calling agent.

Search Features

Basic Search

# Simple search
results = kb.search("artificial intelligence", limit=5)

# User-scoped search
results = kb.search(
    query="machine learning",
    user_id="user123",
    limit=10
)

Advanced Search Options

With Reranking

# Enable Mem0 reranking for better relevance
results = kb.search(
    query="neural networks",
    user_id="user123",
    rerank=True,
    top_k=20  # Retrieve more before reranking
)

# Combine keyword and semantic search
results = kb.search(
    query="transformer architecture",
    user_id="user123",
    keyword_search=True,  # Better recall
    filter_memories=True  # Better precision
)

# Filter by metadata
results = kb.search(
    query="implementation details",
    user_id="user123",
    filters={
        "category": "technical",
        "year": {"$gte": 2023}
    }
)

Memory Integration

When used with agents, knowledge automatically integrates with memory:

agent = Agent(
    name="Research Assistant",
    knowledge={
        "sources": ["papers/"],
        "vector_store": {
            "provider": "chroma",
            "config": {"collection_name": "research_docs"}
        }
    },
    memory=True  # Enable memory integration
)

# Knowledge is automatically searched during conversations
response = agent.start("What does the research say about transformers?")

Graph Store Features

Graph stores add relationship extraction and connection queries on top of semantic search.

Configuration

knowledge_config = {
    "graph_store": {
        "provider": "neo4j",  # or "memgraph"
        "config": {
            "url": "bolt://localhost:7687",
            "username": "neo4j",
            "password": "password"
        }
    },
    "extract_relationships": True
}

Relationship Queries

# Find related concepts
results = kb.search_graph(
    "What concepts are related to transformers?",
    user_id="user123"
)

# Explore connections
results = kb.search_graph(
    "How is attention mechanism connected to BERT?",
    user_id="user123"
)

Best Practices

Match chunk size to your query complexity

Use smaller chunks (100-200 tokens) for precise fact retrieval. Use larger chunks (500-1000 tokens) when answers need more context. Semantic chunking works best for research papers and long-form documents.

Separate collections by domain

Use a different collection_name per knowledge domain (e.g., product_docs, legal_contracts). This prevents cross-contamination and allows targeted filtering by domain.

Use metadata for filtering

Add metadata when indexing documents to enable filters= in searches. Filter by category, year, or author to narrow results without changing query text.

Enable reranking for higher precision

Set rerank=True in kb.search() when you need top-quality results. Reranking retrieves more candidates then scores them for relevance — best for Q&A and research assistants.

Example: Research Assistant

Complete Example

from praisonaiagents import Agent
from praisonaiagents import Knowledge

# Configure knowledge base
knowledge_config = {
    "vector_store": {
        "provider": "chroma",
        "config": {
            "collection_name": "research_papers",
            "path": "./knowledge_db"
        }
    },
    "chunker": {
        "name": "semantic",
        "threshold": 0.7
    },
    "embedder": {
        "provider": "openai",
        "config": {
            "model": "text-embedding-3-small"
        }
    },
    "reranker": {
        "enabled": True
    }
}

# Create research assistant
research_agent = Agent(
    name="Research Assistant",
    instructions="""You are an expert research assistant.
    Use the knowledge base to provide accurate, well-sourced answers.
    Always cite the specific documents you reference.""",
    knowledge={
        "sources": ["research_papers"],
        **knowledge_config
    }
)

# Use the assistant
response = research_agent.start(
    "What are the main approaches to AI alignment?"
)

# Direct knowledge queries
kb = research_agent.knowledge
papers = kb.search("alignment techniques", limit=5)
for paper in papers:
    print(f"- {paper['text'][:100]}...")
    print(f"  Source: {paper.get('metadata', {}).get('source')}")

Troubleshooting

Symptom	Likely cause	Fix
praisonai knowledge index exits 1 with no chunks stored	Directory contained no supported file types, or every file failed to extract.	Check the file extensions and re-run with --verbose to see per-file diagnostics.
AddResult.message: Failed to generate embedding (model=…): 401	Missing or invalid OPENAI_API_KEY.	Export a valid key: export OPENAI_API_KEY=sk-….
AddResult.message: Failed to generate embedding (model=…): 404 model_not_found	OPENAI_EMBEDDING_MODEL is set to a name the provider doesn’t recognise.	Unset it (default is text-embedding-3-small) or set it to a supported model like text-embedding-3-large.
search() returns empty results for content you just indexed	Embedding failure at index time was masked by an older build.	Upgrade to the latest release (PR #2823); indexing now exits non-zero if nothing was stored.
Search is slower or more expensive than expected	OPENAI_EMBEDDING_MODEL=text-embedding-3-large is set.	Switch back to text-embedding-3-small for latency-sensitive apps, or budget for the ~6.5× cost.

Related

RAG

Build retrieval-augmented generation pipelines

Vector Store

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