Knowledge Sources

Knowledge sources are URLs and files that Gnosari crawls, indexes, and makes searchable for your AI agents. When an agent needs domain-specific information during a conversation, it retrieves relevant content from its assigned knowledge sources.

Overview

The Knowledge page at /knowledge displays a flat list of all knowledge sources in your account. Each source shows its name, status, document count, and which agents use it.

Quick Stats Dashboard

At the top of the page, real-time statistics summarize your knowledge base:

Stat	Description
Total Sources	Number of knowledge sources (websites, documents, etc.)
Total Documents	Number of indexed document chunks across all sources
Index Health	System health indicator (Active, Processing, or Error)

---

Source List

The source list provides a unified view of all knowledge sources with search and pagination.

Source Cards

Each source card displays:

• Name: Source name
• Status Badge: Processing, Ready, or Error state
• Document Count: Number of indexed document chunks
• Agent Badges: Which agents use this source
• Actions Menu: Edit, Reload, Delete options

Pagination

Navigate through large source lists with configurable page size and page controls.

---

Adding a Source

Clicking "Add Source" on the Knowledge page opens a quick-create modal with a single field:

1. Paste any website URL (e.g. https://docs.example.com) — no source type to pick
2. Click the submit button

That's it — the source is created immediately, and the type (website, sitemap, or discovery) is resolved automatically on the server based on what the site exposes (see Websites below for what each type means).

Need more control? The quick-create modal has an Advanced link that opens the full manual form at /knowledge/new, where you can enter multiple URLs, pick an explicit source type, and set a custom name and description.

The source begins processing immediately. A status indicator shows progress.

---

Source Data Types

Knowledge sources support five categories of content:

1. Documents

Upload files for AI agents to learn from:

Type	Formats	Example
PDF Files	.pdf	User manuals, reports, presentations
Word Documents	.docx, .doc	Policies, procedures, templates
Markdown Files	.mdx, .md	Technical docs, README files
Text Files	.txt, .log	Plain text content

2. Websites

In the default quick-create flow (see Adding a Source), you don't pick a website type at all — paste a URL and the server resolves it automatically. The table below describes what happens under the hood, and what's selectable as an explicit Source Type in the Advanced manual form:

Type	Description	Example
Website	Single page or an explicit list of URLs you provide	https://example.com/about
Sitemap	Reads a sitemap.xml (or sitemap_index.xml) directly	https://example.com/sitemap.xml
Discovery	Crawl-based whole-site discovery via NeoReader — used automatically when quick-create can't find a sitemap	https://example.com

3. APIs

Connect to REST APIs for dynamic data:

Type	Description	Example
REST API	Standard API endpoint	https://api.example.com/v1/data
OpenAPI	OpenAPI/Swagger spec	https://api.example.com/openapi.json

4. Databases

Connect directly to databases:

Type	Description	Example
PostgreSQL	PostgreSQL database	postgresql://user:pass@host:5432/db
MySQL	MySQL database	mysql://user:pass@host:3306/db

5. Cloud Storage

Sync from cloud storage services:

Type	Description	Example
Google Drive	Google Drive folder	https://drive.google.com/folder/id
Dropbox	Dropbox files	https://dropbox.com/s/abc123/file.pdf
GitHub	GitHub repository	https://github.com/user/repo

---

Source Processing

When you add a source:

1. Status: Set to processing
2. Indexing: Content is fetched, parsed, and indexed
3. Ready: Status changes to active when complete
4. Error: Status shows error if processing fails

Processing Indicators

Status	Badge	Meaning
Active	Green checkmark	Source successfully loaded and ready
Processing	Amber spinner	Currently being indexed
Taking too long	Amber warning	Still processing after 15 minutes. The load has probably stalled: click "Update" to retry
Error	Red X	Failed to load (check details for error message)
Inactive	Gray circle	Source disabled

Reloading Sources

If content changes or errors occur, force re-indexing:

1. Open source actions menu
2. Click "Reload"
3. Source will be re-fetched and re-indexed

---

Managing Sources

Editing a Source

1. Open the source actions menu (three dots)
2. Click "Edit"
3. Update name, description, or configuration
4. Click "Save Changes"

Deleting a Source

1. Open the source actions menu
2. Click "Delete"
3. Confirm deletion
4. Source and all its indexed documents are removed

---

Using Sources with Agents

Assign knowledge sources directly to agents:

1. Navigate to Agents (/gnosaris)
2. Click Edit on an agent
3. Go to the Knowledge section
4. Select sources to assign
5. Save the agent

The agent can now reference content from assigned sources during conversations.

Example:

Source: FAQ Website (https://example.com/faq)
Source: Product Documentation (https://docs.example.com)
Source: Troubleshooting Guide (PDF)

Agent: Support Assistant
  Assigned Sources: FAQ Website, Product Documentation, Troubleshooting Guide

Result: The Support Assistant answers questions using information
from the FAQ, product docs, and troubleshooting guide.

---

Tips & Best Practices

Naming Conventions

Use clear, descriptive names:

Good: "2024 Product Launch Materials"
Avoid: "Stuff" or "Docs 2"

Source Organization

Keep sources focused on a single domain concept:

Good:
- API Documentation
- Customer Support FAQ
- Product User Guide

Avoid:
- All Documents
- Random Files

Source Size

• Small sources (1-50 pages): Fast to load, easy to maintain
• Large sources (500+ pages): May take longer to process; consider using sitemap type

---

Troubleshooting

Source Shows Error Status

Problem: Source failed to load Solution:

1. Click the source to view error details
2. Common issues:
   • Invalid URL or file path
   • Access denied (password-protected content)
   • Server timeout (large files)
   • Unsupported file format
3. Fix the issue and click "Reload"

Processing Takes Too Long

Problem: Source stuck in "Processing" status Solution:

1. Large sources can take several minutes to index
2. After 15 minutes the source shows "Taking too long", meaning the load has probably stalled
3. Click "Update" on the source to retry. The button stays available while a source is stalled
4. Stalled sources are also detected automatically in the background and moved to the error state, from which you can retry them the same way
5. Contact support if the problem persists after a retry

---

What's Next

• Documents Tab: Browse and manage individual indexed documents
• Search Tab: Semantic search across all knowledge sources
• Assign to Agents: Enable AI agents to use your knowledge sources