# Knowledge Retrieval Settings

Tune how your AVCodex agent retrieves and uses knowledge from your documents.

---

When you add knowledge sources (manufacturer datasheets, programming guides, internal SOPs, AS-built drawings) to an AVCodex agent, the AI uses **Retrieval-Augmented Generation (RAG)** to find and use relevant information. Advanced RAG Settings let you tune that process.

## How your agent uses your documents

Before the dials, here is how the agent actually finds and uses information from uploaded documents.

### What is RAG

**RAG (Retrieval-Augmented Generation)** is how the agent "reads" your documents to answer questions. Instead of memorizing everything, the AI:

1. **Searches** your documents for relevant information when a user asks a question.
2. **Retrieves** the most relevant sections.
3. **Generates** a response using that information.

Think of it like a research-savvy junior engineer who pulls the exact spec page out of a Biamp manual before answering, rather than trying to recall the whole binder from memory.

### What is a "chunk"

When you upload a document, AVCodex automatically breaks it into smaller pieces called **chunks**. A chunk is typically a paragraph or a few paragraphs of text.

**Why chunks?**

- AI models cap how much text they can process at once.
- Smaller pieces let the AI find the exact relevant section, not the whole document.
- It is faster and more accurate than searching full documents.

**Example:** A 200-page Crestron programming guide might split into 600 chunks. When a programmer asks a question, the agent searches all 600 chunks and pulls only the 5 most relevant ones.

### How search works

When a user asks a question, AVCodex turns both the question and your document chunks into mathematical representations (called embeddings). It then finds chunks whose meaning is closest to the question.

This is **semantic search**. It understands meaning, not only keywords. So "How do I reset a DM-NVX endpoint?" can match a chunk titled "Restoring a DigitalMedia receiver to factory defaults" even when the wording differs.

### Standard search vs hybrid search

**Standard search (default)**

Looks at each chunk independently and finds the ones most similar to the user's question.

- Good for: FAQ-style content, focused topics, smaller knowledge bases.
- Best when: each chunk contains a self-contained answer.

**Hybrid search**

Combines two strategies:

1. **Chunk search**: Which individual chunks match the question best?
2. **Document search**: Which whole documents are most relevant overall?

It then boosts chunks that come from highly relevant documents, even when those chunks are not the top individual matches.

- Good for: multiple documents on similar topics, long documents, broad questions.
- Best when: context from the same document matters, or you have 10+ files (think a full library of QSC, Crestron, and Extron programming guides).

**Example:** A user asks about "warranty replacement procedure." Standard search might pull one good chunk from your service SOP and another from a random product page. Hybrid search recognizes that your "RMA and Warranty Process" document is highly relevant overall, so it favors chunks from that document.

## Accessing RAG settings

1. Open your agent in the AVCodex dashboard.
2. Go to the **Build** tab.
3. Scroll to **Knowledge Sources**.
4. Click **Advanced RAG Settings** to expand.

## Settings reference

### Relevance threshold

**Default: 0.15** | Range: 0.00 to 1.00

Controls how closely a document chunk must match the user's query to be included in the agent's context.

| Value | Behavior |
|---|---|
| **Lower (0.00 to 0.15)** | More results included, may pull loosely related content. |
| **Medium (0.15 to 0.30)** | Balanced (recommended starting point). |
| **Higher (0.30 to 1.00)** | Stricter matching, only highly relevant content. |

**When to adjust:**

- **Lower the threshold** if users say the agent is missing information that is in your documents.
- **Raise the threshold** if responses bring in too much off-topic material or the agent looks confused by conflicting sources.

### Max chunks

**Default: 5** | Range: 1 to 20

The maximum number of document chunks retrieved per user query. Each chunk is a section of your uploaded content.

| Value | Behavior |
|---|---|
| **Fewer chunks (1 to 3)** | Focused responses, lower token use, faster. |
| **Moderate (4 to 7)** | Balanced context (recommended). |
| **More chunks (8 to 20)** | Wide coverage, higher token use. |

**When to adjust:**

- **Use fewer chunks** for simple Q&A where the answer is usually in one place (a touch panel error message lookup, for example).
- **Use more chunks** when questions need synthesis across sources (a design engineering question that pulls from a Biamp DSP manual, an Extron switcher datasheet, and a network spec).

**Note:** More chunks means more context, but also more tokens and slower responses.

### Hybrid search

**Default: Off**

When on, combines two search strategies:

1. **Chunk-level search**: Finds the chunks most similar to the query.
2. **Document-level search**: Considers which documents are most relevant overall.

This helps when the best answer comes from a document that is highly relevant overall, even if no single chunk perfectly matches the query.

**When to enable:**

- You have many documents on similar topics (a full set of Q-SYS Lua reference docs, for example).
- Users ask broad questions that span sections.
- You notice the agent missing context from documents you know are relevant.

**When to keep off:**

- Simple, focused knowledge bases.
- When chunk-level matching is already working well.

### Document weight

**Default: 0.30** | Range: 0.00 to 1.00 | Only visible when Hybrid Search is on.

Controls the balance between chunk-level and document-level relevance when Hybrid Search is enabled.

| Value | Behavior |
|---|---|
| **Lower (0.00 to 0.25)** | Prioritize individual chunk matches (chunk focus). |
| **Balanced (0.25 to 0.50)** | Equal weight to both signals. |
| **Higher (0.50 to 1.00)** | Prioritize chunks from highly relevant documents (document focus). |

**When to adjust:**

- **Lower values** when your documents cover very different topics and chunk relevance is most important.
- **Higher values** when you have long documents (a 300-page programming guide) where context from the same document is worth keeping together.

## Recommended configurations

### Field tech support agent

```
Relevance Threshold: 0.20
Max Chunks: 5
Hybrid Search: Off
```

Good for FAQ-style knowledge bases where answers are self-contained, like a touch panel error code lookup.

### Design engineering assistant

```
Relevance Threshold: 0.10
Max Chunks: 10
Hybrid Search: On
Document Weight: 0.40
```

Pulls more context for synthesizing answers across multiple manufacturer manuals and internal standards.

### Programming reference agent

```
Relevance Threshold: 0.25
Max Chunks: 7
Hybrid Search: On
Document Weight: 0.30
```

Balances precision with coverage for Crestron SIMPL, SIMPL#, and Q-SYS Lua questions.

### RFP and compliance agent

```
Relevance Threshold: 0.15
Max Chunks: 8
Hybrid Search: On
Document Weight: 0.50
```

Keeps relevant policy and standards documents (corporate AV standards, accessibility requirements, network security policies) well-represented.

## Troubleshooting

### Agent does not find information that exists in my documents

1. Lower **Relevance Threshold** to 0.10.
2. Raise **Max Chunks** to 8 to 10.
3. Turn on **Hybrid Search** if you have multiple related documents.

### Responses include irrelevant information

1. Raise **Relevance Threshold** to 0.25 to 0.35.
2. Drop **Max Chunks** to 3 to 4.
3. Review your document organization.

### Token usage is too high

1. Drop **Max Chunks** to 3 to 4.
2. Raise **Relevance Threshold** to cut low-quality matches.
3. Consider splitting large documents into focused topics (per manufacturer or per system, for example).

### Agent gives conflicting information

1. Raise **Relevance Threshold** to be more selective.
2. With Hybrid Search on, raise **Document Weight** to favor cohesive document sources.
3. Audit documents for outdated or contradictory content (old AS-builts vs. current ones).

## Resetting to defaults

Click **Reset to defaults** in the Advanced RAG Settings panel to restore all values. Useful if you have been experimenting and want to start fresh.

## Using with MCP

You can manage knowledge sources and RAG settings through code using the AVCodex MCP Server.

### Available tools

| Tool | Description |
|---|---|
| `list_knowledge_sources` | List all sources with processing status. |
| `add_url_source` | Add a URL with crawl depth options. |
| `add_document_source` | Upload documents (base64 encoded). |
| `delete_knowledge_source` | Remove a knowledge source. |
| `refresh_knowledge_source` | Re-crawl or re-process a source. |
| `update_settings` | Modify RAG settings (topK, temperature, etc.). |

### Example prompts

```
"List all knowledge sources for my field tech agent"
"Add https://docs.crestron.com with crawl depth 3"
"Refresh the outdated Biamp programming guide"
"Update my agent to retrieve 10 chunks instead of 5"
```

### Workflow: knowledge base setup

```
You: Set up knowledge sources for my service desk agent.

AI: [Calls add_url_source for docs site]
[Calls add_url_source for FAQ page]
Added 2 knowledge sources:
- docs.crestron.com (crawling, depth 2)
- support.qsc.com/faq (crawling, depth 1)

You: Increase max chunks to 8 for better coverage.

AI: [Calls update_settings with topK=8]
Updated RAG settings. Your agent will now retrieve up to 8
chunks per query.
```

> **Note:** MCP server access requires a Builder plan or higher. See the [MCP Setup Guide](../guides/mcp/setup) to get started.

*AVCodex · Your AV expertise. Amplified by AI.*