> ## 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   |
| Empty / Loading   | Gray  |

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

## 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.

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.

## 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                                            |
| 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.

## 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 metrics and search to that 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.

## 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>