Skip to main content
An AI agent is only as good as what it can retrieve. Most disappointing agent answers are not a model problem, they are a source document problem: the answer exists, buried in a 40-page handbook, in a screenshot, or in a folder the agent cannot see. This page is about making documents retrievable. It applies to whatever source you sync from, because Ravenna does not distinguish between them: it searches every connected folder equally and ranks by relevance.

​
How retrieval actually works

The agent uses hybrid search: semantic embeddings that match meaning, plus BM25 keyword matching for exact terminology, combined and re-ranked. That has two practical consequences:
  • Exact terminology still matters. Your internal tool name, the error string, the acronym. If the document never contains the words employees type, keyword matching contributes nothing.
  • Meaning matters too, so you do not need to guess every phrasing. One clearly written answer beats five keyword-stuffed variants.
Write for the phrasing your employees use, and keep the official terminology in the document too.
Learn more about how search works

​
Six rules for source documents

One topic per page

A page that covers VPN setup, VPN troubleshooting, and VPN policy will get retrieved for all three and answer none of them well. Split it.The heuristic: if a page could reasonably have three different titles, it should be three pages.
“Requesting a new laptop” retrieves. “IT Procedures v3” does not. “Hardware” is worse.Titles carry disproportionate weight in retrieval and in how the agent decides whether a document is relevant.
Lead with the answer, then the detail. If the agent has to synthesize an answer from paragraph nine of a background section, it will sometimes get it wrong, and it will always be vague.
Content that relies on images or tables with no text context is invisible to retrieval. If the steps are only in a screenshot, write the steps out too. Keep the screenshot for the humans.The same applies to a table of values with no surrounding sentences explaining what it is.
Structure is what lets a long document be chunked usefully. A 5,000-word page with no headings retrieves as an undifferentiated blob.Raw meeting notes and pasted chat logs are the worst possible source material for the same reason.
Two documents that disagree produce an agent that answers correctly about half the time, which is worse than one that says it does not know. When you find a contradiction, fix the source and archive the loser.
Learn more about knowledge quality patterns

​
Scope folders deliberately

Scoping has two dimensions and they are both AND conditions:
  • Channel scoping. By default a folder is reachable from any channel where agents are present. Turn off “Knowledge to all channels” to restrict it.
  • Agent scoping. An agent only searches folders connected to it.
An agent must have the folder connected AND be deployed in a channel with access to that folder. Getting one of the two right and not the other is the most common reason an agent cannot find an article that plainly exists. Patterns that work: Prefer several focused folders over one large collection. Scoping is the only lever you have for keeping irrelevant results out, and it only works if the folders are separable.
Learn more about scoping strategies

​
Test before you deploy, not after

The Chat panel on the KB Documents screen answers from your knowledge without touching a channel. Use it every time you add a source. Ask the five questions your team is actually asked, in the words employees actually use. Then fix the source document, sync, and ask again. This loop takes ten minutes and it is the difference between an agent people trust and one they stop using in week two.

​
Know what sync does and does not do

  • Folders auto-sync every 24 hours, at a randomized time within the window. Manual sync is available whenever you need it.
  • Folder hierarchy from the source is preserved, so Notion page trees and Confluence space structures come across intact.
  • A document deleted at the source is marked with an error, not removed. This deliberately protects content the agent depends on, which means you have to archive it yourself if it is genuinely gone.
  • Failed syncs retry on the next scheduled run, but a sync that fails because credentials expired keeps failing until you reconnect the integration.
Archiving excludes a document from search while keeping it for reference. Archiving a parent cascades to every child, and new documents added under an archived folder at the source arrive already archived.
Learn more about syncing and monitoring

​
Then let the gaps tell you what to write

You cannot predict what to document. Ship what you have, then work the Gaps screen weekly: it groups the questions the agent could not answer into ranked topics, so your next article is chosen by evidence rather than by guessing.
Learn more about closing knowledge gaps

​
Where teams get this wrong

Contradictions and stale pages get retrieved just as readily as good ones. Start with the folders you trust.
Split by topic or accept vague answers.
Invisible to retrieval.
Half a configuration, and it fails silently.
Every problem on this page is findable in ten minutes there.
It is a weekly loop driven by gaps.

​
Next

Close knowledge gaps

The weekly loop that keeps knowledge current.

Writing agent rules

Point rules at the folders you just organized.
Last modified on September 17, 2026