> ## 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. ## What you can do * Connect documentation from Slack, Notion, Google Drive, Confluence, Coda, Guru, Zendesk, and websites * Organize content into folders scoped to specific channels or agents * Test agent responses using the chat panel * Sync content automatically or on-demand * Archive outdated content while preserving it for reference ## Creating a knowledge folder Knowledge folders organize your imported content and control how agents access it through channel and agent scoping. Click the **Knowledge** tab in the left navigation. Click the **Create** button to add a new knowledge folder. Set your folder name. ### Adding documents Navigate to a knowledge folder. Documents can only exist within a parent folder. Click **Add Documents** in the top right corner. Select your knowledge source and complete the authentication flow to grant Ravenna access. ### Searching across folders Use the search bar on the Knowledge page to find folders and documents together from a single query, without opening each folder first. * Searching from the **Folders** tab matches both folder names and document titles across every folder in the workspace. * Each result shows whether it is a folder or a document, and which knowledge folder owns it. * Selecting a document result opens the document directly; selecting a folder result opens the folder with your search term preserved, so you can keep narrowing inside it. * Filters and sort apply to folder-only browsing. While a search is active, results use the search ranking instead. Use root-level search to jump straight to a specific runbook or policy when you don't remember which folder owns it. ## Knowledge sources Ravenna supports multiple knowledge sources to help you centralize your organization's information: Import messages and threads from your Slack channels. Sync your Notion pages and databases. Import documents from Google Drive. Sync your Confluence spaces and pages. Import your Coda documents and pages. Sync your Guru cards and collections. Import Zendesk Help Center articles. Import content from public websites. ## Testing your knowledge Test agent responses using the chat panel before deploying your knowledge to production. Click **Chat** in the top right of the KB Documents screen. Ask questions related to your imported content to see how agents respond. Update source documents based on test results, then sync to validate improvements. Use the chat panel to validate agent responses before scoping knowledge to channels or agents. ### How search works Agents use hybrid search to find relevant content: * **Semantic search**: AI embeddings understand query meaning and context, finding conceptually similar content even without exact keyword matches. * **BM25 keyword search**: Traditional text search finds exact matches and specific terminology. * **Hybrid ranking**: Results from both methods combine and rank to surface the most relevant documents. This dual approach handles both conceptual questions and specific keyword queries. ## Scoping knowledge Control which channels and agents can access specific knowledge folders. Restrict knowledge to specific Slack channels for targeted support. Navigate to your knowledge folder's Details panel. Turn off the **Knowledge to all channels** toggle. Select the specific channels that should have access to this knowledge. By default, knowledge folders are accessible from any channel where agents are present. Assign knowledge folders to specific agents to control which content each agent can access. Navigate to your knowledge folder's Details panel. Select which agents should have access to this knowledge folder. Learn how to [reference knowledge in agent rules](/documentation/automate/agents/configure#rules) Route agent knowledge lookups to different folders based on the user's question using conditional logic in agent rules. When a rule contains natural language conditions with different knowledge folder or document references in each branch, the agent searches only the sources from the matching branch. Navigate to your agent's configuration and open the Rules section. Use the **@** mention picker within your rule text to insert specific knowledge folders or documents. If a folder contains subfolders, press **Tab** or **→** to drill into it and select a nested folder or document. Selecting a folder grants the agent access to everything inside, including subfolders. Different branches of your rule can reference different knowledge sources. Write natural language conditions in your rule that direct the agent to search specific knowledge sources based on the topic. **Example rule:** IF the user asks about engineering processes, search @Engineering Docs. IF the user asks about HR policies, search @HR Handbook. Otherwise, search @General Knowledge Base. Conditional KB routing prevents the agent from searching irrelevant sources, improving response accuracy and reducing noise in answers. Channel and agent scoping work together. An agent can only access knowledge if both the channel and agent have the appropriate permissions. ## Syncing and monitoring Knowledge folders sync automatically once every 24 hours by default to keep content up-to-date. Navigate to your knowledge folder and view the Details panel on the right. Toggle auto-sync on or off in the **Auto-sync** section. Sync timing is randomized within each 24-hour period to distribute load. Trigger a manual sync to immediately update your knowledge base with the latest content from your source. Click the **Sync** button in the top right of your knowledge folder. Manual syncs run a full resync: every document in the folder is re-fetched and re-extracted from the source, regardless of whether it changed. Use this when source updates are not yet reflected in Ravenna or when a previous auto-sync missed a change. Monitor the status of your knowledge folder syncs in real-time: * **Sync state badge**: View the current sync status in the folder's Details panel * `Done`: Sync completed successfully * `In Progress`: Sync is currently running * `Queued`: Sync is scheduled to run * `Errored`: Sync encountered an error * **Progress indicator**: Track sync completion percentage for large imports * **Last sync timestamp**: See when the folder was last successfully synced * **Documents synced count**: View how many documents have been imported Sync progress updates automatically - no need to refresh the page to see the latest status. When a sync fails, Ravenna provides detailed error information to help you resolve issues: * **Error messages**: View specific error details in the folder's Details panel under "Sync state" * **Common errors**: * Authentication expired: Reconnect your integration to restore access * Source unavailable: The source content or service is temporarily inaccessible * Permission denied: Ravenna no longer has access to the content * Content not found: The source document or page has been deleted or is inaccessible * **Automatic retry**: Failed syncs are automatically retried during the next scheduled sync * **Manual retry**: Click the **Sync** button to immediately retry a failed sync * **Document preservation**: If a document disappears from the source, Ravenna marks it with an error but doesn't delete it from your knowledge base to protect content your bot depends on If a sync error persists, check your integration connection and ensure Ravenna still has the necessary permissions to access your content. ## Managing documents Ravenna preserves the organizational structure from your source systems: * **Preserved organization**: Original folder and page structures from services like Notion or Confluence are maintained in Ravenna. * **Easy navigation**: Navigate the knowledge base using the familiar structure from your source system. * **Automatic updates**: When documents are moved or reorganized in the source service, the hierarchy updates during the next sync. This mirroring approach ensures your knowledge base feels familiar and maintains the organizational logic you've already established. You can edit documents directly in Ravenna only when they were created in Ravenna. Documents synced from an external integration (Notion, Google Drive, Confluence, Coda, Guru, Zendesk, Slack, or a website) are read-only in Ravenna, and the **Edit** button is hidden on their detail view. To change the content of an externally-synced document, update it in the source system and wait for the next sync — or trigger a manual sync to pull the change in immediately. This keeps Ravenna and the source of truth in sync. Edits made in Ravenna would be overwritten on the next sync from the external source. ## Knowledge gaps The **Gaps** tab on the Knowledge page surfaces topics where your agents could not find an answer. Each gap represents a question or topic that came up in conversation but had no matching documentation. Use knowledge gaps to prioritize which articles to write or update next. Gaps include the frequency of occurrence and example conversations so you can assess impact before creating content. ## Archiving documents Archive documents and folders to exclude them from agent responses while keeping them in your knowledge base for reference. * **Selective exclusion**: Archive specific documents or entire folders to prevent them from being used in agent responses. * **Preserved structure**: Archived content remains in your knowledge base for reference but won't influence agent answers. * **Cascade archiving**: When you archive a parent folder, all child documents and subfolders are automatically archived. * **Smart sync behavior**: During auto-sync, new documents added to archived folders in your source system are automatically archived in Ravenna. * **Easy recovery**: Unarchive content anytime to make it available to agents again. Archiving is useful for: * Outdated documentation that's no longer relevant. * Deprecated processes or procedures. * Sensitive information that should be retained but not actively used by agents. * Historical content that needs to be preserved for compliance. ## 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.