---
name: cognee-forget
description: Use when removing data from cognee memory with forget() in the SDK, HTTP API, or CLI — finding which dataset and document hold the content to delete (listing datasets and data items, reading raw content), choosing between deleting one document, a whole dataset, or only the graph/vector memory, and doing it safely.
---

# Remove data with forget()

`forget()` is cognee's one deletion API. It removes one document, a whole
dataset, or only the derived memory (graph + vectors) while keeping the raw
files. Deletion cannot be undone, so the workflow is always **find, read,
confirm, then delete**.

> **Hard limits for agents**
> - Delete only what the user asked to forget. Identify it by reading the
>   content first; never guess from a file name alone.
> - Confirm the exact items with the user before deleting, unless they
>   already named exact ids.
> - The widest deletion you may run is `forget(everything=True)`, and only
>   when the user explicitly asks to wipe all of their memory. Never use any
>   other reset or wipe mechanism to delete data.

## Use it

### 1. Find the dataset

```python
import cognee

datasets = await cognee.datasets.list_datasets()  # datasets the user can read
for ds in datasets:
    print(ds.id, ds.name)
```

HTTP: `GET /api/v1/datasets`. CLI: `cognee-cli datasets list`.

### 2. List its documents

```python
items = await cognee.datasets.list_data(dataset_id)  # all Data rows, oldest first
for item in items:
    print(item.id, item.name, item.extension, item.created_at)
```

HTTP: `GET /api/v1/datasets/{dataset_id}/data?limit=100&offset=0` (limit up
to 1000; `GET .../data/count` for the total; example:
`examples/python/dataset_data_pagination.py`). CLI:
`cognee-cli datasets data <dataset_uuid>`.

Each item has `id`, `name`, `created_at`, `extension`, `mime_type`,
`raw_data_location`, `dataset_id`, `label`, `external_metadata` (including
any `node_set`), and `data_size`.

### 3. Read the content before deciding

Names are often `text_<hash>.txt`, so read the content to find what the user
means.

- HTTP: `GET /api/v1/datasets/{dataset_id}/data/{data_id}/raw` returns the
  stored file (404 if it is gone).
- SDK: there is no "get raw" helper; open the stored location:

```python
from cognee.infrastructure.files.utils.open_data_file import open_data_file

async with open_data_file(item.raw_data_location, mode="rb") as f:
    preview = f.read(2000).decode("utf-8", errors="replace")
```

Judge matches by meaning, not only by keywords, and show the user the
candidates (name + a short preview) before deleting.

### 4. Delete

| Goal | Call | What remains |
|---|---|---|
| One document | `forget(data_id=..., dataset_id=...)` (or `dataset="name"`) | Nothing of that document; shared entities stay while another document still references them |
| A whole dataset | `forget(dataset="name")` or `forget(dataset_id=...)` | The dataset is deleted outright: the record, its data rows, graph and vector stores, and attributed sessions |
| Rebuild a dataset's graph later | `forget(dataset="name", memory_only=True)` | Raw files and data rows; graph, vectors, sessions and pipeline status are reset, so the data can be re-processed |
| One document's memory only | `forget(dataset="name", data_id=..., memory_only=True)` | That document's raw file and row |
| Every dataset the user can delete | `forget(everything=True)` | Nothing, in any dataset the user has `delete` on in the current tenant (shared ones included). Only on explicit request (see the hard limits) |

Return values: `{"data_id", "dataset_id", "search_history_removed", "status"}`
for a document, `{"dataset_id", "search_history_removed", "status"}` for a
dataset (plus `data_records_reset` with `memory_only`), `{"datasets_removed",
"search_history_removed", "status"}` for everything (`datasets_removed`
counts the datasets the user can *read*, not the delete set).
`search_history_removed` is `True` for a dataset or everything forget: every
recorded question and answer for the deleted datasets is gone, whoever asked.
It does not cover rows saved without a dataset (history from before cognee
1.5.0, or a search over several datasets with access control off): a dataset
forget leaves them, and an everything forget removes only the caller's own.
It is `False` for a document forget, which never purges history (rows are
recorded per dataset, so answers that quoted the document stay until the
dataset itself is forgotten). If the history purge fails, the forget raises
before any data is deleted, so retry the same forget.

**HTTP:** `POST /api/v1/forget` with a JSON body; camelCase and snake_case
keys both work: `{"datasetId": "...", "dataId": "..."}`,
`{"dataset": "name", "memoryOnly": true}`, `{"everything": true}`. Invalid
combinations return 422.

**CLI:** `cognee-cli forget --dataset NAME | --dataset-id UUID
[--data-id UUID] [--memory-only]`, or `--everything` / `--all`. The CLI
**does not ask for confirmation**; confirm with the user first.

## Pitfalls

- **A `data_id` that is not in the dataset returns success and deletes
  nothing.** The delete path treats an unknown id as a custom-graph-model
  delete. Always take the id from `list_data` for that same dataset, and
  check it is still listed afterwards if it matters.
- **Pass either `dataset` or `dataset_id`, not both** (`ValueError`).
  `data_id` and `memory_only` both need a dataset.
- **`memory_only` is ignored when `everything=True`** in the SDK (the CLI
  rejects the combination). `everything=True` always deletes everything.
- **Not found and not allowed look the same.** An unknown dataset name and
  one the user cannot delete both raise `DatasetNotFoundError`. Deleting
  needs the `delete` permission on the dataset (see the `cognee-permissions`
  skill). `everything=True` deletes every dataset the user has `delete`
  permission on in the current tenant, including datasets shared to them
  with delete rights, not only the ones they own.
- **Sessions that cited deleted data are invalidated** so recall stops
  returning answers built on it. Agent-trace entries are not invalidated.
- **Changing a document is not a delete.** To replace a document's content,
  use `cognee.update(data_id=..., data=..., dataset_id=...)`, which keeps its
  id and re-extracts only the changed parts.
- `cognee.delete()` is deprecated; use `forget()`.

## How it works

`forget()` resolves the dataset with the `delete` permission, then:

- **One document** → `datasets.delete_data()`: takes the dataset lock,
  deletes the graph nodes and edges the document owns, the matching vectors
  and edge evidence, invalidates sessions that cited them, then deletes the
  `Data` row. Ownership is tracked per document (source-refs on graph
  elements), so an entity shared by two documents survives until both are
  deleted. Raw files are reference-counted by storage location.
- **A dataset** → `datasets.empty_dataset()`.
- **`memory_only`** → drops the dataset's graph/vector memory and resets its
  pipeline status, leaving raw data for a rebuild.
- **`everything`** → `datasets.delete_all()` over every dataset the user has
  `delete` on in the current tenant, plus a full prune of the session cache
  (when caching or usage logging is on). This wipes **every user's**
  sessions (Redis FLUSHDB / the whole fs cache / all SQL cache tables), not
  just this user's.

Key files:

- `cognee/api/v1/forget/forget.py` (SDK), `routers/get_forget_router.py`
  (HTTP), `cognee/cli/commands/forget_command.py` (CLI)
- `cognee/api/v1/datasets/datasets.py` (`list_datasets`, `list_data`,
  `delete_data`, `empty_dataset`, `delete_all`)
- `cognee/api/v1/datasets/routers/get_datasets_router.py` (list, count, raw)
- `cognee/infrastructure/databases/provenance/source_refs.py` (per-document
  ownership of graph elements)
- `cognee/infrastructure/files/utils/open_data_file.py`

## Extending it

- Anything new that writes graph nodes or edges for a document must record
  its source-refs, or `forget(data_id=...)` cannot find and remove it.
- Anything new that stores per-document data outside the graph (like edge
  evidence) needs a cleanup step in the delete path and in `memory_only`.
- Unit tests for `forget()` are in `cognee/tests/unit/api/v1/forget/`
  (argument validation, the HTTP endpoint, `memory_only`); cover both the
  document and the `memory_only` paths for new deletion behaviour.