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