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

# Overview

> Connect knowledge sources, organize them into folders scoped to channels or agents, and power AI answers in Slack with searchable docs and wikis.

Knowledge folders provide searchable documentation, wikis, and resources that power agent responses in Slack. Scope folders to specific channels or agents, sync automatically from multiple sources, and test responses before deployment.

## Mental model

Knowledge is the agent's reference library. Knowledge folders contain documents synced from external sources (Slack, Notion, Google Drive, Confluence, Coda, Guru, Zendesk, websites). When a user asks a question, the agent searches connected knowledge folders using hybrid search (semantic + keyword) and returns sourced answers.

Key relationships:

* One workspace has many knowledge folders.
* One knowledge folder has many documents from one or more sources.
* Knowledge folders are scoped to specific agents and/or channels.
* An agent can only search knowledge folders explicitly connected to it.
* A knowledge folder can be connected to multiple agents.

Knowledge is the primary way to make the agent accurate and context-aware. Without knowledge, the agent relies solely on its base training and rules. With knowledge, it can answer questions using your organization's actual documentation.

***

## How search works

The agent uses hybrid search combining two approaches:

1. **Semantic search**: AI embeddings match query meaning to document meaning. Finds conceptually similar content even without exact keyword matches.
2. **BM25 keyword search**: Traditional text matching finds exact terms and specific terminology.
3. **Hybrid ranking**: Results from both methods are combined and ranked by relevance.

This means the agent handles both "What is our PTO policy?" (conceptual) and "How do I configure SAML SSO?" (specific terminology) effectively.

***

## Scoping strategies

Knowledge scoping controls which agents and channels can access which folders. Two dimensions:

**Channel scoping**: By default, knowledge folders are accessible from any channel where agents are present. Disable "Knowledge to all channels" to restrict a folder to specific channels.

**Agent scoping**: Assign knowledge folders directly to specific agents. An agent only searches folders connected to it.

Both scoping dimensions work together. An agent must have access to the folder AND be deployed in a channel that has access to the folder.

Common patterns:

* **Department-specific knowledge**: IT knowledge folder scoped to IT agent and IT channels only. HR knowledge folder scoped to HR agent and HR channels.
* **Shared knowledge**: Company-wide policies folder available to all agents and channels.
* **Sensitive knowledge**: Compliance or security documentation scoped to a single private channel and specific agent.
* **Conditional routing**: Write natural language conditions in agent rules to reference different knowledge folders per branch. The agent only searches the folders from the matching branch, preventing irrelevant results.

***

## Knowledge quality patterns

**What makes good knowledge content:**

* Clear, well-structured documentation with headings and sections.
* Frequently asked questions with direct answers.
* Step-by-step procedures for common tasks.
* Policy documents with clear statements.

**What produces poor agent responses:**

* Raw meeting notes or chat logs without structure.
* Documents with outdated or contradictory information.
* Very long documents without clear section breaks.
* Content that relies heavily on images or tables without text context.

**Improving agent accuracy:**

* Use the chat panel to test agent responses before deployment.
* Archive outdated documents to prevent stale answers.
* Organize content into focused folders rather than one large collection.
* Update source documents based on test results, then sync.

***

## Sync behavior

* Knowledge folders auto-sync every 24 hours by default. Sync timing is randomized within each 24-hour period.
* Manual sync is available at any time.
* Sync preserves the folder hierarchy from the source system (Notion page trees, Confluence space structures).
* If a document disappears from the source, Ravenna marks it with an error but does not delete it. This protects content the agent depends on.
* Failed syncs retry automatically during the next scheduled sync.

***

## Constraints and gotchas

* Knowledge folders are workspace-scoped. There is no cross-workspace knowledge sharing.
* An agent can only search knowledge folders explicitly connected to it. Connecting a folder to a channel is not enough if the agent is not also connected.
* Archived documents are excluded from agent searches but remain in the knowledge base for reference.
* Archiving a parent folder cascades to all child documents and subfolders.
* New documents added to an archived folder in the source system are automatically archived in Ravenna during sync.
* Sync requires active integration authentication. If credentials expire, sync fails until reconnected.
* Knowledge referenced in agent rules with `@Knowledge Folder Name` grants the agent access to that folder for search during rule execution.
* The agent does not distinguish between knowledge sources. It searches all connected folders equally and ranks results by relevance.