Knowledge bases

A knowledge base is a single source, a document or a set of related web addresses, that Stoa has read and indexed so it can search inside it and cite it. When you ask a question, Stoa retrieves the most relevant passages from the knowledge bases you have access to and uses them to compose a cited answer.

Each knowledge base holds one thing: one file, or one group of URLs treated as a unit. If you have twenty documents, you'll typically end up with twenty knowledge bases, not one knowledge base holding twenty files. That's deliberate: it keeps each one describable, searchable, and easy to hand to the right agents.

Browsing knowledge bases

From the main navigation, open Knowledge Bases. You'll see a table of every knowledge base shared with you: its name and description, its status, how many passages it produced, whether it came from a file or from web addresses, and when it was last updated. Search by name and page through the list; ten show at a time, and you can change that from the page size control.

Click any row to open its detail page. You'll see:

• Its status, source (file or URLs, with the file name or the addresses listed), and how many passages it indexed.
• Tags, if any were set.
• For a web-based knowledge base, the extracted text Stoa actually read, so you can check it captured the page correctly.
• If you have permission: buttons to edit its name, description, and tags, download the original file, reindex it, or delete it.

Creating a knowledge base

If you have permission, click New Knowledge Base from the knowledge bases screen. This opens its own page where you:

1. Give it a name and a description. The description matters more than it looks: it's what tells Stoa (and your colleagues) what this source covers and when to reach for it.
2. Choose its type: a File you upload, or one or more URLs Stoa fetches and reads.
3. Optionally add tags to help you find it later.

Once you save, Stoa reads and indexes the source in the background.

Adding many documents at once

If you have a pile of documents to bring in, don't create them one by one. Use Bulk from the knowledge bases screen instead: drop in as many files as you like, and each one becomes its own knowledge base, automatically named, described, and tagged by reading its contents. You can edit any of them afterwards from their own page.

Status

A knowledge base moves through a small set of states as it's processed:

• Embedding. The source is being read and indexed for the first time.
• Reindexing. It's being rebuilt, either because you asked for a reindex or because your administrators updated how indexing works.
• Available. It's indexed and searchable.
• Error. Something went wrong; the reason is shown on its row and its detail page.

Most documents finish within a few seconds. Very large files take longer, and the list refreshes itself while anything is still processing.

A knowledge base that finished indexing but produced no passages is worth a second look: it reads as "Available" but has nothing for Stoa to search, and the list flags a zero passage count so it doesn't look identical to one that worked.

How searches work, in plain language

There's no separate search box on a knowledge base's page. You search a knowledge base by asking a question in a chat with an agent that has access to it; Stoa does the retrieval as part of answering.

Under the hood, Stoa uses a combination of techniques to find the right passages:

• Semantic search, which understands meaning (so a search for "remote work policy" can find a passage that says "telecommuting guidelines").
• Keyword search, which catches exact terms and proper nouns.
• Reranking, which sorts the candidate passages by how relevant they actually are to your specific question.

You don't need to do anything special to use these. They run automatically, and what they found comes back as citations on the answer.

Deleting and reindexing

If you have permission, you can delete a knowledge base or trigger a reindex from its detail page, or reindex every knowledge base at once from the main screen.

• Delete removes it and everything indexed from it. Agents that searched it will find nothing there afterwards.
• Reindex rebuilds its search index. You typically only do this after a deployment update, or if a document is misbehaving in search.

Permissions

You only see knowledge bases that have been shared with you. If you can't find one you think you should have access to, talk to your administrator.

What to put in a knowledge base

Some practical guidance:

• One source per knowledge base, which is how it works anyway: don't try to force unrelated documents into one entry.
• Write a real description. It's what Stoa reads to decide whether this source is relevant to a question, and what a colleague reads to decide whether to attach it to an agent.
• Curated, not dumped. Garbage in, garbage out applies here. An out-of-date document will show up in answers as if it were current.
• Versioned where possible. If a document gets updated, replace it rather than leaving both the old and new versions searchable.

Where to next

• Chats for how to query knowledge bases through conversation.
• Citations for how to read and verify what Stoa returned.
• Agents for how knowledge bases get attached to a specialist.
• Deep research for knowledge-base-grounded research workflows.