Skip to main content

​
cognee.forget()

​
Description

forget() is the unified deletion API in Cognee v1.0.
  • Use it to remove a single data item from a dataset.
  • Use it to delete an entire dataset.
  • Use everything=True to remove all memory owned by the current user.
  • Use memory_only=True to clear graph and vector memory while keeping raw dataset records so the content can be reprocessed.
For the full behavior walkthrough, see Forget.

​
Parameters

​
Optional[UUID]
default:"None"
Specific data item to remove. Requires dataset or dataset_id to also be set.
​
Optional[str]
default:"None"
Dataset name. When used alone, deletes the whole dataset. When paired with data_id, deletes only that item from the dataset.
​
Optional[UUID]
default:"None"
Dataset UUID — the alternative to dataset, and the only way to address a dataset whose name is ambiguous. Passing both raises ValueError: Provide either dataset or dataset_id, not both.
​
bool
default:"False"
Deletes all datasets and memory owned by the current user.
​
bool
default:"False"
Deletes only graph and vector memory for the target dataset or data item while keeping underlying dataset records.Deletion is driven by provenance, so it only reaches nodes recorded as belonging to the target dataset or data item. Nodes written by a custom pipeline whose payload is not a tracked data item — the code-graph pipeline, for instance, which takes a repository path — carry no provenance and are left in place. To clear those, use prune instead: code-graph ingestion skips a repository whose snapshot identity still matches the marker on its CodeRepository node, and only removing that node makes the next run reload every fact.
​
Any
default:"None"
Runs the operation under a specific user context instead of the default user.

​
Return value

forget() returns a summary dictionary. Depending on the mode, it includes fields like status, dataset_id, data_id, or datasets_removed.

​
Troubleshooting

Every mode except everything=True resolves the dataset to an id before deleting anything: dataset is matched by name against the datasets you hold the delete permission on, in your own tenant. When nothing in that set matches, the call fails with:
The message is deliberately the same whether the dataset does not exist or you simply cannot delete it — distinguishing the two would leak which dataset names exist. Over HTTP the same failure returns 404 with {"detail": "Dataset 'product_docs' not found or not accessible. [DatasetNotFoundError]"}.
Before this fix — which means every release up to and including the current one — this case crashed with AttributeError: 'NoneType' object has no attribute 'id', and the HTTP endpoint reported it as a generic 500 {"error": "An error occurred during deletion."}. If you match on that traceback or on the 500, switch to catching DatasetNotFoundError / the 404.
The error points at dataset resolution, not at your data — and it is the same for forget(dataset="product_docs") and forget(dataset="product_docs", memory_only=True), since both resolve the dataset the same way. Common causes:
  • No dataset with that name. A typo, a dataset that was already forgotten, or content that actually landed in the default main_dataset because no dataset_name was passed to remember().
  • No delete grant. read and write access are not enough: resolution only considers datasets you can delete, so a dataset you can read is indistinguishable from one that does not exist. The ACL troubleshooting entry lists the datasets you can delete and shows how to grant the permission.
  • A dataset in another tenant. Resolution keeps only datasets whose tenant matches yours, so a name reachable across a tenant boundary never resolves.
Because names are matched rather than derived, a dataset someone else shared with you does resolve by name, provided the share carries delete and you are in the same tenant. The reverse case is the one to watch: when two datasets you can delete share a name, resolution picks whichever comes first, so pass dataset_id=UUID(...) whenever the name is ambiguous.dataset_id fails differently — an id you cannot delete raises PermissionDeniedError: Request owner does not have necessary permission: [delete] for all datasets requested. (or ... for any dataset. when you have no deletable datasets at all) instead of DatasetNotFoundError, and returns 403 over HTTP. Both are CogneeApiError subclasses, so a single except covers the pair:
Catch DatasetNotFoundError (from cognee.modules.data.exceptions) or PermissionDeniedError (from cognee.modules.users.exceptions) individually when the two cases need different handling. Invalid parameter combinations are unchanged: they still raise ValueError and return 422.To find the right name or id, list your datasets first, as in Inspect what you’ve stored before forgetting. Bear in mind that list_datasets() filters by read, so a name that appears there can still fail to resolve for forget().

​
Examples

For lower-level data-management APIs, see datasets, delete(), and prune.