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

# Knowledge Overview

> Give your agents access to documents and data

# Knowledge Overview

Knowledge allows your agents to answer questions using your own documents - PDFs, text files, web pages, and more.

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart LR
    D[Documents] --> I[Index]
    I --> V[(Vector Store)]
    Q[Question] --> A[Agent]
    V --> A
    A --> R[Answer + Citations]
    
    style D fill:#8B0000,color:#fff
    style V fill:#2E8B57,color:#fff
    style A fill:#4682B4,color:#fff
```

1. **Add documents** → Chunked and indexed
2. **Ask questions** → Agent retrieves relevant context
3. **Get answers** → With source citations

## Quick Start

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

agent = Agent(
    name="Research Assistant",
    knowledge=["research.pdf", "docs/"]
)

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

That's it! The agent can now answer questions using your documents.

## When to Use

| Approach | Best For | Link |
| - | - | - |
| `Agent(knowledge=[...])` | Most use cases | [Quick Start →](/docs/knowledge/quickstart) |
| `Knowledge()` class | Custom indexing | [Knowledge API →](/docs/sdk/praisonaiagents/knowledge/knowledge) |
| `RAG()` class | Custom pipelines | [RAG Module →](/docs/rag/module) |

## Knowledge vs Memory vs RAG

| Feature | Knowledge | Memory | RAG |
| - | - | - | - |
| **Purpose** | Answer from documents | Remember conversations | Retrieve + Generate |
| **Data Source** | Files, URLs | Conversations | Knowledge base |
| **Updates** | Manual (re-index) | Automatic | Uses Knowledge |
| **Best For** | Q\&A, research | Chat continuity | Citations, search |

## What `Knowledge.search()` returns

`Knowledge.search()` returns a typed `SearchResult` from `praisonaiagents.knowledge.models`.

| Field | Type | Description |
| - | - | - |
| `results` | `list[SearchResultItem]` | Ranked items |
| `metadata` | `dict` | Search-level metadata (always dict, never None) |
| `query` | `str` | Original query string |
| `total_count` | `int` | Total available (may exceed `len(results)` if paginated) |

<Warning>
  A `SearchResult` is a dataclass, so it is **always truthy** — even when empty. Check `.results` instead of the object.

  ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  # ❌ Wrong — SearchResult is a dataclass, always truthy
  if not results:
      print("No results")

  # ✅ Right — check .results (or .total_count)
  if not results.results:
      print("No results")
  ```
</Warning>

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

knowledge = Knowledge()
knowledge.store("Paris is the capital of France.")

results = knowledge.search("capital of France", user_id="alice")

for item in results.results:
    print(f"[{item.score:.2f}] {item.text}  ({item.source or '-'})")
```

<Note>
  Each `SearchResultItem` can be passed directly into RAG context utilities like `build_context` and `deduplicate_chunks`. See [Search Results](/docs/features/knowledge-search-results) for the full field reference.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/docs/knowledge/quickstart">
    Get started in 5 minutes
  </Card>

  <Card title="Storage Options" icon="database" href="/docs/knowledge/storage">
    Configure vector stores
  </Card>

  <Card title="Chat with PDFs" icon="file-pdf" href="/docs/knowledge/chat-with-pdf">
    Build a PDF chat agent
  </Card>

  <Card title="RAG" icon="magnifying-glass" href="/docs/rag/overview">
    Advanced retrieval
  </Card>
</CardGroup>


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