Concepts

How RAG Search Works

Brain uses Retrieval-Augmented Generation (RAG) to answer questions based on your documents. There are three stages: indexing, searching, and generation.

Indexing

When you upload a document:

1. The text is split into overlapping chunks of configurable size.
2. Each chunk is converted to a vector embedding that captures its semantic meaning.
3. Chunks are stored and indexed for fast similarity search.

To avoid redundant API calls, the system caches embeddings at the chunk level. If a document is re-indexed after a small edit, only the chunks that actually changed are re-embedded. See Embedding Deduplication for details.

Indexing runs in the background. You can track progress from the dashboard or via the Jobs API.

Searching

When you send a query to /search:

1. Your query text is converted to a vector embedding using the same model.
2. The most semantically similar chunks are retrieved and ranked by similarity score.
3. If hybrid BM25 search is enabled, a BM25 keyword search also runs in parallel. Results from both are merged — duplicates are deduplicated by document, and the higher score is kept.
4. Results above the score threshold are returned, grouped by source document.

AI Generation

When you send a query to /ai-search:

1. Search retrieves relevant chunks (vector, BM25, or both — same as above).
2. Those chunks are passed as context to an LLM.
3. The LLM generates an answer grounded in your documents.
4. Both the AI response and the source documents are returned.

When streaming is enabled, the response is sent as Server-Sent Events (SSE). Some models support thinking tokens — internal reasoning that the model produces before its final answer. These are streamed as separate thinking events so you can display them differently in your UI (e.g., in a collapsible block).

Documents and Chunks

A document is a file you upload — text, markdown, HTML, or other text-based formats. Each document is automatically split into chunks, smaller pieces that can be independently searched and retrieved.

Chunks overlap slightly to preserve context at boundaries. You don't need to manage chunks directly — upload documents and the system handles the rest.

Folder Organization

Documents can be organized by path. Upload a document with filename guides/setup.md and it's automatically tagged with folder guides/. You can then filter searches to specific folders:

{
  "query": "How do I deploy?",
  "filters": {
    "type": "and",
    "filters": [{ "key": "folder", "value": "guides/" }]
  }
}

This is useful for scoping search results to specific sections of your knowledge base.

Projects and API Keys

• Project — An isolated container for documents. Each project has its own document index and configuration.
• API Key — Credentials for accessing a project via the API. Keys can have read (search only) or write (search + upload/delete) permissions.

One account can have multiple projects. Use separate projects for different use cases or environments.