> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge for AI

> Structure your source documents so a Ravenna agent can retrieve them: one topic per page, explicit titles, text over screenshots, and scoping that actually works.

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.

<Callout icon="link" color="#6B7280">Learn more about [how search works](/documentation/automate/knowledge/overview#how-search-works)</Callout>

## Six rules for source documents

<AccordionGroup>
  <Accordion title="One topic per page" defaultOpen>
    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.
  </Accordion>

  <Accordion title="Titles that state the question or the answer">
    "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.
  </Accordion>

  <Accordion title="Put the answer in the first paragraph">
    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.
  </Accordion>

  <Accordion title="Never let a screenshot be the answer">
    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.
  </Accordion>

  <Accordion title="Use real headings and sections">
    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.
  </Accordion>

  <Accordion title="Delete contradictions">
    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.
  </Accordion>
</AccordionGroup>

<Callout icon="link" color="#6B7280">Learn more about [knowledge quality patterns](/documentation/automate/knowledge/overview#knowledge-quality-patterns)</Callout>

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

| Pattern              | Setup                                                                                                     |
| -------------------- | --------------------------------------------------------------------------------------------------------- |
| Department knowledge | IT folder scoped to the IT agent and IT channels only                                                     |
| Shared policy        | Company-wide policies available to every agent and channel                                                |
| Sensitive content    | Compliance docs scoped to one private channel and one agent                                               |
| Conditional routing  | Reference different folders per branch in agent rules, so only the matching branch's folders are searched |

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.

<Callout icon="link" color="#6B7280">Learn more about [scoping strategies](/documentation/automate/knowledge/overview#scoping-strategies)</Callout>

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

<Callout icon="link" color="#6B7280">Learn more about [syncing and monitoring](/documentation/automate/knowledge/overview#syncing-and-monitoring)</Callout>

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

<Callout icon="link" color="#6B7280">Learn more about [closing knowledge gaps](/guides/how-to/close-knowledge-gaps)</Callout>

## Where teams get this wrong

<AccordionGroup>
  <Accordion title="Syncing the whole wiki on day one">
    Contradictions and stale pages get retrieved just as readily as good ones. Start with the folders you trust.
  </Accordion>

  <Accordion title="One giant handbook">
    Split by topic or accept vague answers.
  </Accordion>

  <Accordion title="Screenshot-only procedures">
    Invisible to retrieval.
  </Accordion>

  <Accordion title="Scoping the folder to the channel but not to the agent">
    Half a configuration, and it fails silently.
  </Accordion>

  <Accordion title="Never testing in the chat panel">
    Every problem on this page is findable in ten minutes there.
  </Accordion>

  <Accordion title="Treating knowledge as a one-time project">
    It is a weekly loop driven by gaps.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Close knowledge gaps" icon="book-open" href="/guides/how-to/close-knowledge-gaps" horizontal>
    The weekly loop that keeps knowledge current.
  </Card>

  <Card title="Writing agent rules" icon="scroll-text" href="/guides/best-practices/writing-agent-rules" horizontal>
    Point rules at the folders you just organized.
  </Card>
</CardGroup>


## Related topics

- [Close knowledge gaps](/guides/how-to/close-knowledge-gaps.md)
- [Emoji actions](/integrations/slack/emoji-actions.md)
- [Knowledge](/integrations/coda/knowledge.md)
- [Knowledge gaps](/documentation/automate/knowledge/knowledge-gaps.md)
- [AI trust & privacy](/documentation/automate/agents/trust-privacy.md)