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

# Large Context Knowledge Handling

> Complete guide to handling large knowledge bases efficiently

PraisonAI Agents provides a comprehensive system for handling large knowledge bases efficiently, with automatic strategy selection, token budgeting, and intelligent compression.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="KnowledgeAgent",
    instructions="Answer from a large document corpus",
    knowledge={"sources": ["./docs"]},
)
agent.start("What changed in the API this quarter?")
```

The user queries a huge knowledge base; retrieval, budgeting, and compression keep answers within context limits.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    User[👤 User question] --> Agent[🤖 Agent]
    Agent --> Budget[📊 Token budget]
    Budget --> Retrieve[🔍 Smart retrieval]
    Retrieve --> Answer[✅ Grounded answer]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
    class Agent agent
    class Budget,Retrieve tool
    class User,Answer ok
```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Large Context Knowledge Handling

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result    Agent-->>User: Response
```

# Large Context Knowledge Handling

## Overview

The large context handling system includes:

| Feature | Description |
| - | - |
| [Token Budgeting](https://praison.ai/docs/features/token-budgeting.md) | Dynamic budget management for context windows |
| [Incremental Indexing](https://praison.ai/docs/features/incremental-indexing.md) | Efficient file tracking and updates |
| [Retrieval Strategies](https://praison.ai/docs/features/retrieval-strategies.md) | Automatic strategy selection by corpus size |
| [Smart Retrieval](https://praison.ai/docs/features/smart-retrieval.md) | Hybrid search with reranking |
| [Context Compression](https://praison.ai/docs/features/context-compression.md) | Intelligent compression to fit budgets |
| [Hierarchical Summaries](https://praison.ai/docs/features/hierarchical-summaries.md) | Multi-level summaries for large corpora |

## Quick Start

**1. Create an agent with knowledge**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="KnowledgeAgent",
    instructions="Answer questions using the knowledge base.",
    knowledge={"sources": ["./docs"]},
    memory={"user_id": "my_user"},
)
response = agent.chat("What are the main features?")
```

**2. Index and search via CLI**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai knowledge index ./docs --user-id myuser
praisonai knowledge search "query" --strategy hybrid --compress
```

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Agent Query                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  Strategy Selection                          │
│  (DIRECT → BASIC → HYBRID → RERANKED → COMPRESSED → HIER)   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Smart Retrieval                            │
│         (Keyword + Semantic + Reranking)                     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                 Context Compression                          │
│      (Deduplication + Extraction + Truncation)               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Token Budgeting                            │
│           (Enforce limits, reserve response)                 │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      LLM Response                            │
└─────────────────────────────────────────────────────────────┘
```

## CLI Commands

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Index documents
praisonai knowledge index ./docs --user-id myuser

# Get corpus statistics
praisonai knowledge stats ./docs

# Search with options
praisonai knowledge search "query" --strategy hybrid --rerank --compress

# Build hierarchical summaries
praisonai knowledge summarize ./docs --levels 3

# Clear knowledge store
praisonai knowledge clear --yes
```

## Configuration

### RetrievalConfig

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.rag import RetrievalConfig, RetrievalStrategy

config = RetrievalConfig(
    # Strategy selection
    strategy=RetrievalStrategy.AUTO,
    
    # Retrieval settings
    top_k=10,
    min_score=0.5,
    
    # Token budget
    max_context_tokens=4000,
    reserved_response_tokens=1000,
    
    # Features
    use_hybrid=True,
    use_reranking=True,
    use_compression=True,
    compression_ratio=0.5,
)

agent = Agent(
    name="ConfiguredAgent",
    knowledge={
        "sources": ["./docs"],
        "retrieval_k": 10,
        "retrieval_threshold": 0.5,
        "rerank": True,
    }
)
```

> [!NOTE]
>
> The same `RetrievalConfig` instance can now be passed straight to `Agent(retrieval_config=config)` — it replaces the config derived from `knowledge=` wholesale. Previously that raised `TypeError`. See [RAG → Pass retrieval tuning directly to `Agent`](https://praison.ai/docs/features/rag#pass-retrieval-tuning-directly-to-agent).

## Examples

### Context-Required Q\&A

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Example with unique codes that require retrieval
from praisonaiagents import Agent

agent = Agent(
    name="PolicyExpert",
    instructions="Answer based ONLY on provided knowledge.",
    knowledge={"sources": ["./policies"]},
    memory={"user_id": "demo_user"},
)

# This question requires retrieval - answer cannot be guessed
response = agent.chat("What is the manager approval code?")
# Agent retrieves: "ZEBRA-71" from policy document
```

### Large Corpus Handling

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.rag import RetrievalConfig, RetrievalStrategy

# For large corpora, use hierarchical strategy
agent = Agent(
    name="LargeCorpusAgent",
    knowledge={
        "sources": ["./large_docs"],  # 100k+ files
        "retrieval_k": 10,
    }
)
```

### Scope Isolation

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Different users have isolated knowledge
agent_user1 = Agent(
    name="Agent",
    knowledge={"sources": ["./docs"]},
    memory={"user_id": "user1"},
)

agent_user2 = Agent(
    name="Agent",
    knowledge={"sources": ["./docs"]},
    memory={"user_id": "user2"},
)

# Each user's indexed content is isolated
```

## Performance

The system is designed for zero performance impact when not in use:

* **Lazy imports** - Heavy dependencies loaded only when needed
* **Incremental indexing** - Only changed files re-indexed
* **Automatic strategy** - Simpler strategies for smaller corpora
* **Token budgeting** - Prevents context overflow

## Best Practices

> [accordion] Use incremental indexing
>
> Re-index only changed files in large, frequently updated corpora to save time and cost.

> [accordion] Set token budgets per model
>
> Match budgets to your model window so retrieval and history share space safely.

> [accordion] Enable reranking for relevance
>
> Hybrid search plus reranking improves answer quality on noisy document sets.

> [accordion] Use hierarchical summaries at scale
>
> For corpora above \~100k tokens, summarise in layers instead of stuffing raw chunks into context.

## Related

> [card] [Token Budgeting](https://praison.ai/docs/features/token-budgeting.md)
>
> Dynamic budget management

> [card] [Smart Retrieval](https://praison.ai/docs/features/smart-retrieval.md)
>
> Hybrid search with reranking

> [card] [Context Compression](https://praison.ai/docs/features/context-compression.md)
>
> Compress retrieved context to fit budgets

> [card] [Hierarchical Summaries](https://praison.ai/docs/features/hierarchical-summaries.md)
>
> Multi-level summaries for large corpora


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.