Knowledge Retrieval Settings

When you add knowledge sources (documents, websites, etc.) to your Chipp app, your AI uses Retrieval-Augmented Generation (RAG) to find and use that content. This guide explains how retrieval actually works and which settings tune it.

How Your AI Uses Your Documents

Retrieval is a tool, not a reflex

Your AI does not search the knowledge base on every message. Instead, when your app has knowledge sources, the AI is given a searchKnowledge tool and told the knowledge base exists. On each message it decides for itself whether the question needs your content:

• “Hi, how are you?” gets answered directly. No search, no wasted tokens.
• “What’s your refund policy?” triggers a search with a query the AI writes itself.
• A complex question can trigger several searches with refined queries, the way a person would try a second search after skimming the first results.

This matters for three reasons:

1. Cost: simple messages don’t pay the retrieval tax.
2. Query quality: the AI writes better search queries than raw user messages. “It’s still broken” becomes a search for the actual product and error discussed earlier in the conversation.
3. Iteration: if the first search misses, the AI can reformulate and search again instead of answering badly.

What is a “chunk”?

When you upload a document, Chipp automatically breaks it into smaller pieces called chunks (typically a paragraph or a few paragraphs). Chunks let a search return the exact relevant section instead of a whole 50-page document.

Example: A 50-page PDF might be split into 200 chunks. A search scores all 200 and returns only the top few.

How each search works

Every search is a hybrid search combining two strategies at once:

1. Semantic search (70% of the score by default): the query and your chunks are compared as embeddings, so “How do I cancel my subscription?” matches a chunk about “ending your membership” even with zero shared words.
2. Keyword search (30% by default): classic full-text matching, so exact product names, error codes, and rare terms are never lost to fuzzy matching.

Chunks below the relevance threshold are dropped, and the top results (up to your chunk limit) are returned to the AI along with which document each one came from.

Document boosting

For large knowledge bases, an optional third signal can be enabled: document boosting. Each document gets an AI-generated summary and its own embedding; when a search runs, chunks from documents that are relevant overall get boosted above stray chunks that merely share some words with the query.

Example: A user asks about “return policies.” Plain search might rank a chunk from a random product page above your Returns & Refunds document. With document boosting, chunks from the Returns document win because the document itself is highly relevant.

Settings You Can Change in the Builder

Max chunks per query

Default: 5 | Range: 1 - 25 | Build tab → Knowledge section

The maximum number of chunks each search returns to the AI.

Use fewer chunks for FAQ-style apps where answers live in one place; use more when questions require synthesizing information scattered across documents. More chunks means more context per search, but also higher token usage on every knowledge-backed answer.

This setting takes effect when you re-publish the app.

Advanced Tuning

The remaining retrieval parameters are deliberately kept out of the builder UI (they’re easy to hurt yourself with), but every app has them and they can be tuned through the Chipp MCP Server, the builder API, or simply by asking the Alchemist copilot:

Example, in the Alchemist panel:

"Raise my app's knowledge relevance threshold to 0.25 and
retrieve 8 chunks per search."

Troubleshooting

AI doesn’t find information that exists in my documents

1. Increase Max chunks per query to 8-10
2. Lower minScore toward 0.10
3. Enable useDocumentBoosting if you have many related documents
4. Check the knowledge source actually finished processing (its status should be COMPLETED)

Responses include irrelevant information

1. Raise minScore to 0.25-0.35
2. Decrease Max chunks per query to 3-4
3. Review your documents for overlapping or contradictory content

Token usage is too high

1. Reduce Max chunks per query to 3-4
2. Raise minScore to filter low-quality matches

Remember that retrieval is tool-based, so messages that don’t need knowledge don’t incur retrieval cost at all; the levers above only affect knowledge-backed answers.

AI gives conflicting information

1. Raise minScore to be more selective
2. Enable document boosting with a higher documentWeight so answers stay within cohesive sources
3. Remove or update outdated documents

Using with MCP

You can manage knowledge sources and retrieval settings programmatically using the Chipp MCP Server.

Available Tools

Example Prompts

"List all knowledge sources for my FAQ bot"
"Add https://docs.example.com with crawl depth 3"
"Refresh the outdated product manual"
"Update my app to retrieve 10 chunks instead of 5"