Knowledge is an indexed document collection that belongs to one conversation. You add it through the same Add attachments picker used for uploads and workspace links, and SoAI parses, chunks, and embeds the files in the background so a model can search them with a tool call instead of reading them in the prompt. Chat covers preparing an embedding model and the steps for adding documents inside a conversation; this page covers what the indexing and retrieval settings actually do.
Knowledge and ordinary attachments
A Knowledge collection is an attachment in almost every visible sense. It comes from Add attachments > Knowledge, it produces an attachment card above the composer and keeps that card in the transcript after you send, it counts toward the 6 cards shown inline before the rest move into Message attachments, where the filters separate Attachments, Knowledge, and SoAI links, and it has to reach a terminal state before the message will send, exactly like a direct upload that is still processing.
What differs is what reaches the model. A direct upload is parsed and its text goes into the request, where it
competes with every other inline attachment for a bounded share of the model's context. A Knowledge attachment sends
only a short reference line naming the collection and how many items it holds, so it costs almost nothing in the
prompt, and the passages arrive later only if the model calls knowledge_search and only for the query it
asks. That is why a collection too large to attach directly is still usable as Knowledge, and why a Knowledge answer
that misses something is usually a retrieval problem rather than a size problem.
Failure looks familiar too. A Knowledge card can go unavailable after the fact the way a SoAI link can, because items linked from another conversation record a reason and go unavailable when their source is removed, and cloning a conversation copies ready direct files but not the indexed collection, which leaves the clone's Knowledge cards unavailable until you add the documents again. Attachments and file context covers the picker, the other methods, and every server-side limit.
What indexing does
Each document moves through the same pipeline, and the Knowledge pane names the stage it reached: Queued for processing, Fetching content, Parsing content, Creating searchable chunks, and Creating embeddings. A document ends completed, cancelled, or in error, and a file SoAI could open but could not extract text from is marked Unreadable. When the batch settles, the pane says whether the files are ready or whether some need attention, and the per-file card carries the error for the ones that failed. Use Remove on the attachment card to take the collection out of the current conversation.
Chunking happens before embedding and decides what a search can return, because a retrieved passage is a chunk rather than a document.
Choose a chunking strategy
token_based is the default and measures both size and overlap in cl100k_base tokens, which
keeps a chunk close to what the embedding model actually consumes. fixed_size walks the same way over
characters. paragraph groups whole paragraphs up to the size limit and ignores the overlap value
entirely. semantic groups sentence-like segments up to the limit and turns the overlap value into a
count of repeated sentences instead of using it directly, so a small nonzero value already means one sentence of
overlap.
Overlap exists so a sentence split across a boundary still appears whole in one chunk. Match the strategy to the
source, because prose with real paragraph breaks does well on paragraph, while transcripts, reference
material, and anything without reliable structure are usually better on the default.
Choose a retrieval strategy
similarity returns the closest matches by vector distance and is the right starting point.
mmr gives up some of that closeness for variety, which helps when a collection repeats itself and the
top results would otherwise be near-duplicates of one passage. hybrid combines the vector search with
keyword matching against the sparse index, which is what you want when the answer turns on an exact term, an
identifier, or a name that a purely semantic match blurs.
Top K sets how many passages come back and Similarity threshold discards the weak ones. A higher Top K widens the evidence and spends more of the model's context, while a higher threshold makes retrieval stricter and can legitimately return nothing when the collection does not hold the answer.
Reindex after a change
Changing the embedding model does not re-embed what is already indexed, and neither does changing the chunk size, overlap, or strategy. Existing chunks keep the vectors they were built with, so a collection holding two generations of embeddings retrieves badly. Select Reindex in Add attachments > Knowledge after any of those changes. SoAI builds a fresh collection, re-embeds every document into it, then swaps it in and removes the old one.
What retrieval needs
SoAI turns the Knowledge tools on for a conversation by itself, but only while all four of these hold: Enable RAG is on under Chat configuration > Knowledge, the collection has at least one document, the Knowledge access tools are available, and the conversation model supports tool calling. Miss one and the tools stay off and the answer comes from the prompt alone, with ready documents sitting unsearched. While the conditions do hold, the ordinary Tools control cannot remove those tools, so turn off Enable RAG first if that is what you want.
Knowledge actions require RAG access
(RAG_USE), and
Load from Workspace requires Files reading
(FILE_EXPLORER_READ) as well. The default
policy grants both to Administrator and Standard user accounts. An Administrator with
ACL administration (ACL_ADMIN)
can change that: in the SoAI WebUI, select the Settings button at the right of the header, choose
Settings, then open ACL.
Agent and MCP tools
Three tools read a collection, and they are the three SoAI enables on its own. knowledge_search runs a
query with the strategy, Top K, and threshold it is given, knowledge_list reports the documents and
their processing status, and knowledge_config_get returns the conversation's Knowledge settings.
Two more manage a collection and stay off until you select them. knowledge_reindex rebuilds the
collection with a named embedding model, refuses auto, and requires confirmation because it is
destructive. knowledge_web_fetch fetches a URL and ingests it into the collection, which is the whole
difference from web_fetch, since that one returns the content without storing it.
All of them act on one conversation's collection and no other. They are also not part of what MCP server mode
publishes by default, so a third-party client connected to SoAI as an MCP server sees web_fetch and the
web search tools, and an administrator has to add a Knowledge tool to the exposed list before that client can reach
a collection at all. MCP overview covers server-mode exposure and permissions.
Server defaults and storage
Global defaults are available to an Administrator with Configuration changes
(CONFIG_PATCH). Select the
Settings button at the right of the header, then Settings, then
Advanced in the page header. Open Tools, use Search settings...
to find a path, change the value, and select Save.
TOOLS.RAG.ENABLED turns the capability on
and ships on. A conversation that has not chosen its own values takes
TOOLS.RAG.DEFAULT_EMBEDDING_MODEL
(auto),
TOOLS.RAG.DEFAULT_CHUNK_SIZE
(500),
TOOLS.RAG.DEFAULT_CHUNK_OVERLAP
(100),
TOOLS.RAG.DEFAULT_TOP_K (5), and
TOOLS.RAG.DEFAULT_SIMILARITY_THRESHOLD
(0.3). The size and overlap defaults are read in the unit of the active strategy, so 500 is 500 tokens under the
default token_based and 500 characters under the others.
SoAI keeps the vectors under
TOOLS.RAG.CHROMA_PATH
(chroma_rag) and the keyword index that hybrid retrieval uses under
TOOLS.RAG.SPARSE_INDEX_DIR
(rag_sparse_index), both resolved inside the system data directory.
Data storage, retention, and relocation covers moving that directory. Web ingestion
has its own controls in
TOOLS.RAG.WEB.ENABLED,
TOOLS.RAG.WEB.MAX_URL_SIZE_MB
(10), and
TOOLS.RAG.WEB.REQUEST_TIMEOUT
(30).