> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rightbrain.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rightbrain.ai/_mcp/server.

# Collections

> Rightbrain Collections are RAG knowledge bases — upload or connect documents, embed them, and ground Tasks (and through them, agents) in your own content.

A **Collection** is a knowledge base for retrieval-augmented generation (RAG). You add documents to it, Rightbrain embeds them, and a [Task](/docs/concepts/tasks) can retrieve the most relevant passages at run time to ground its answer in your own content.

Collections are how you get grounded, source-backed output without stuffing everything into a prompt.

## When to use a Collection

Use a Collection when a Task needs to answer from a specific body of knowledge — a product manual, a policy handbook, a support archive, a contract set — rather than the model's general training. Wire the Collection into the Task's RAG config and the Task retrieves the relevant chunks each time it runs.

Keep each Collection aligned to a coherent retrieval domain. The Task can then synthesize across the retrieved passages and apply an explicit fallback when the available evidence does not answer the request.

> **Tip**
>
> Curate, don't dump. Retrieval quality depends on clean, well-scoped sources and useful document structure, not volume alone.

## How it connects to Tasks and agents

This is the key relationship to get right:

* A **Collection** plugs into a **[Task](/docs/concepts/tasks)** through that Task's revision **RAG config** (its per-collection retrieval options).
* An **[agent](/docs/concepts/agents)** never attaches a Collection directly — it gets the knowledge through a Task tool whose revision has the Collection wired in.

## How a Collection is structured

A Collection groups embedded documents and carries a `title`, a `summary`, and optional metadata. Documents get there two ways:

* **Direct upload** — add files to the Collection.
* **Datasource connectors** — sync from a connected source: Box, Confluence, Dropbox, Google Drive, Notion, OneDrive, or SharePoint.

Once added, documents are embedded into a vector store (pgvector) and become queryable. You can query a Collection directly, inspect its stats, and refresh its summary.

### Retrieval and tuning

At run time, retrieval is a short pipeline: the Task's RAG config can first rewrite the incoming question into a cleaner search query, then a vector search pulls candidate chunks, the best of them are fitted to a context budget, and only that context reaches the Task's model.

```mermaid
flowchart LR
  Q[Incoming question] --> RW["Query rewrite<br />(rewrite_mode)"]
  RW --> VS["Vector search<br />(candidate_k)"]
  VS --> FIT["Fit to budget<br />(final_k · max_context_tokens)"]
  FIT --> M["Task's model<br />+ sources if include_sources"]
```

The RAG config exposes the knobs — among them `rewrite_mode`, how many candidates to fetch (`candidate_k`) and keep (`final_k`), a `max_context_tokens` budget, and `include_sources`. The defaults are sensible; tune them only when a Task is retrieving too little or too much.

When `include_sources` is on, a run reports which document chunks it retrieved and used to build its answer — the attribution you need to render citations in a support or research UI.

Retrieval always returns candidates when matching chunks exist; it does not prove that they are relevant enough to answer. Define how the Task should respond when evidence is weak, and inspect selected chunks and source attribution before increasing retrieval limits.

## Minimal example

Create a Collection, add a document, then query it. (In practice you'll usually wire the Collection into a Task's RAG config rather than querying it directly — but a direct query is the quickest way to confirm retrieval works.)

**`Create a collection`**

```bash title="Create a collection"
curl -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/collection \
  -H "Authorization: Bearer $RB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Support docs" }'
```

**`Query it`**

```bash title="Query it"
curl -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/collection/{collection_id}/query \
  -H "Authorization: Bearer $RB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "query": "How do I reset my password?" }'
```

**`Response`**

```json title="Response"
{
  "response": "To reset your password, open Settings and choose Reset password...",
  "query": "How do I reset my password?"
}
```

The query returns a synthesized answer grounded in the collection's documents — the same retrieval a task performs through its RAG config, condensed into a single `response` string.

> **Tip**
>
> To ground a Task, wire the Collection into that Task's revision RAG config rather than querying it directly — retrieval then happens automatically on every run, and no `{context}` placeholder is needed in the prompt.

## Related

#### [Tasks](/docs/concepts/tasks)

Wire a Collection into a Task's RAG config.

#### [Agents](/docs/concepts/agents)

Give an agent knowledge through a Task tool.

#### [Connections](/docs/concepts/connections)

Datasource connectors that feed Collections.

#### [API Reference — Knowledge](/api-reference/api-reference/knowledge)

Full endpoint reference for collections.