> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Brains

> Upload documents to build searchable knowledge graphs.

# Brain

Upload documents to build searchable knowledge graphs.

The **Brain** page (route `/datasets`) lists all the brains in your workspace. A brain is a container for documents and all subsequent operations. See [Datasets](/core-concepts/further-concepts/datasets) for the underlying concept; the API, SDK, route names, and analytics events continue to use "dataset" ("Brains" in analytics), while the UI uses the singular **Brain**.

## Brain list

The page uses a Finder-style two-column layout:

* The **left column** lists your brains. Each brain shows a **status dot**, its **document count**, and **Share** and **Delete** actions.
* The **right column** lists the documents in the currently selected brain.

Select a brain in the left column to load its documents on the right.

### Status dots

The status dot reflects the brain's processing state:

| State                         | Color    |
| ----------------------------- | -------- |
| Pending / Running             | Amber    |
| Completed                     | Green    |
| Failed                        | Red      |
| Failed — insufficient credits | Lavender |
| Empty / Loading               | Gray     |

A brain whose graph is **outdated** (its config changed after files were processed) also shows an amber dot.

A build that ran out of workspace credits part-way through is reported separately from a generic failure: the dot is lavender and labelled **Failed — insufficient credits**, with the hint *"Your workspace ran out of credits mid-run — top up on the billing page"*. The same distinction appears on the brain detail status pill and on the [Mindmap](/cognee-cloud/ui/knowledge-graph) status chip, where the label links straight to [Billing](/cognee-cloud/functionality/account-and-billing).

## Create a brain

Click **New brain** to open the **Create brain** modal, enter a name, and click **Create brain**. Names cannot contain spaces or periods — otherwise you'll see the error **Dataset name cannot contain spaces or periods.** Names are lowercased on create. The name field uses the placeholder **e.g. product-docs, sec-filings...**.

Newly created brains are automatically granted tenant-level `read` and `write` permissions, so every member of the current tenant can see and write to them. To restrict a brain to specific users, revoke the tenant grant and assign per-user permissions through the [permissions API](/cognee-cloud/functionality/permissions-and-access-control#dataset-permissions).

## Manage documents

The documents column header includes two actions:

* **Add files** — Browse and upload files. Supported formats: PDF, CSV, TXT, Markdown, JSON, DOCX.
* **Paste text** — Open a textarea modal and paste raw text. The text is saved as `pasted-text-{timestamp}.txt`.

You can also drag files anywhere onto the documents column — a **Drop to upload** overlay appears while dragging.

You can upload at most **100 files in a single batch**. Selecting more shows **You selected {n} files. Please upload 100 or fewer at a time.** and the upload is not started.

If the estimated cost of the selected files reaches your workspace credit balance, a **This upload might use more credits than you have** dialog appears before the upload is sent, offering **Cancel** and **Top up first** — the upload does not proceed until the balance covers it. See [When credits run out](/cognee-cloud/functionality/account-and-billing#when-credits-run-out) for how the estimate is framed.

Each document row shows a **file-type badge** (PDF, DOC, MD, TXT, CSV, JSON), the file **size**, the upload **date**, and a **Delete** button (confirm dialog **Delete document**).

Uploaded files appear in the document list automatically — no manual page refresh is needed. Because the background ingestion step can save document records a few moments after the upload call returns, the page keeps polling for the new documents and updates the list as soon as they are available.

After upload, the [add](/core-concepts/main-operations/legacy-operations/add) and [cognify](/core-concepts/main-operations/legacy-operations/cognify) pipeline runs in the background. Once the files are saved, the upload is treated as successful — a later failure in status polling or the background graph build is reported separately and no longer surfaces as a false **Upload failed** error.

## Refresh and polling

Click **Refresh** to re-poll dataset statuses on demand. The page also polls automatically every 5 seconds while any brain is in a **pending** or **running** state, updating the status dots as processing completes.

## Brain detail

The brain detail page (route `/datasets/[id]`) shows a single brain. The header displays the dataset name (with a **Default** badge for `default_dataset`), the document count, and a **status pill**:

| Pill                          | Meaning                                                                       |
| ----------------------------- | ----------------------------------------------------------------------------- |
| Processing                    | Pipeline is pending or running                                                |
| Failed                        | Processing failed                                                             |
| Failed — insufficient credits | Processing stopped because the workspace ran out of credits; links to Billing |
| Outdated                      | Config changed after files were processed; re-process needed                  |
| Ready                         | Graph built and current                                                       |
| Empty                         | No documents yet                                                              |

Header actions:

* **Sync** — Re-runs cognify. Appears only for connected (integration) sources.
* **Delete** — Removes the brain. Hidden for `default_dataset`.
* **Share** — Manage access.
* **Upload files** — Add documents.

Per-brain config (graph model, prompt, ontology) is set here and on the [Memory Schema](/cognee-cloud/ui/schema) page. Changing config when a brain already has files marks the brain **Outdated** until it is re-processed.

When a knowledge-graph build fails, the brain shows **Building the knowledge graph failed. Your files are still here — you can retry the build.** with a **Retry build** action, so a failed build never loses your uploaded documents. The same retry is offered from the failed-brain banner on the [Brain list](#brain-list).

When the build failed specifically because the workspace ran out of credits, the banner instead reads **Building the knowledge graph failed — your workspace ran out of credits mid-run. Your files are still here.** and offers **Go to billing** rather than a retry, because retrying on an empty balance fails the same way.

## Sync a brain

For brains connected to an external (integration) source, the brain detail header includes a **Sync** button that re-runs the cognify pipeline against the current contents. Use this to rebuild the knowledge graph after source data changes without uploading new files again. Brains without a connected source do not show this button.

## Share a brain

Use the **Share** action (on a brain in the left column or in the brain detail header) to open the **Share brain** modal. From here you can:

* **Share with your whole workspace** — Grant access to **Everyone in workspace**, which covers all current *and future* members. Choose **Can edit** (read and write — members can query the brain and run cognify on it) or **Can view** (read-only). This grants the permission to the workspace (tenant) principal, so newly added members are included automatically without any per-member step.
* **Share with individual agents and users** — Grant **read-only** access to a specific agent or user from the list.

Sharing is applied immediately for the current session. The modal does not yet list shares granted previously; to manage grants in detail, use the [permissions API](/cognee-cloud/functionality/permissions-and-access-control#dataset-permissions).

## Brain selector

The brain selector appears on the pages where filtering by brain is relevant: **Search**, **Mindmap** (knowledge graph), **Memory Schema**, **Overview** (dashboard), and the brain detail page. On other pages the breadcrumb shows only the workspace and current page name.

Selecting a brain is global — it filters content across all applicable pages:

* The **Search** page queries only that brain.
* The **Mindmap** page visualizes only that brain's graph.
* The **Overview** dashboard scopes its search terminal to that brain. The KPI counters, however, always report workspace-wide totals and are **not** narrowed by the selected brain.

To search or visualize across all brains, set the selector back to **All datasets**.

## Empty state

When you have no brains yet, the page shows **No brains yet** with a **Create brain** call to action.

If the brain list *fails to load* (for example, while a large upload is still processing and the server is briefly unreachable), the page shows a distinct error state — **Couldn't load your brains** with **Your brains are safe — we just couldn't reach the server** and a **Retry** button — rather than the empty **No brains yet** state. A failed fetch is never mistaken for a genuinely empty account.

## Delete a brain

Use the **Delete** action on a brain (in the left column or the brain detail header). The confirm dialog warns that this will **permanently remove the dataset and all its files. This action cannot be undone.**

The `default_dataset` brain cannot be deleted: it has no **Delete** button and shows a **Default** badge on its detail page.

<Note>
  Dataset operations are also available through the [REST API](/cognee-cloud/functionality/dataset-management) and the [Cloud SDK](/cognee-cloud/connections/cloud-sdk).
</Note>