cognee-forget
GitHub指导如何安全地从 Cognee 记忆系统中删除数据。通过列出数据集和文档、读取内容确认、获取用户确认后,使用 forget() API 执行删除操作,支持单文档、整数据集或仅清理图/向量内存等不同粒度。
触发场景
安装
npx skills add topoteretes/cognee --skill cognee-forget -g -y
SKILL.md
Frontmatter
{
"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
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
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}/rawreturns the stored file (404 if it is gone). - SDK: there is no "get raw" helper; open the stored location:
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. A search finds nothing afterwards, but the data is not deleted |
| One document's memory only | forget(dataset="name", data_id=..., memory_only=True) |
That document's raw file and row |
| One document and your own search history | forget(data_id=..., dataset_id=..., clean_history=True) |
Nothing of that document; the caller's recorded questions and answers are gone in every dataset, other users' stay |
| Only your own search history | forget(clean_history=True) |
All data; only the caller's recorded questions and answers are deleted |
| 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). clean_history=True on any forget deletes the
caller's own history first (every row this user owns, in any dataset) and
the result carries history_cleaned: True; without it a document forget
reports history_cleaned: False. If a 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_idthat 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 fromlist_datafor that same dataset, and check it is still listed afterwards if it matters. - Pass either
datasetordataset_id, not both (ValueError).data_idandmemory_onlyboth need a dataset. memory_onlyis ignored wheneverything=Truein the SDK (the CLI rejects the combination).everything=Truealways deletes everything.- An empty search after
memory_onlyis not deletion. The raw file and the data row are still there and the next cognify re-processes them. Use a plainforget(dataset=...)orforget(data_id=...)to remove the data. - Deleted bytes can outlive the delete inside the storage engines. Every mode removes the records and the memory it names; it does not scrub the engines' files. LanceDB keeps deleted rows in its append-only fragments until compaction rewrites them, and it rewrites a fragment only once enough of it is deleted, so a small delete in a large table can stay on disk indefinitely. The embedded graph file has no user-facing compaction. For a byte-level erasure guarantee run the engine's own compaction or vacuum, or start a new store.
- Not found and not allowed look the same. An unknown dataset name and
one the user cannot delete both raise
DatasetNotFoundError. Deleting needs thedeletepermission on the dataset (see thecognee-permissionsskill).everything=Truedeletes every dataset the user hasdeletepermission 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; useforget().
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 theDatarow. 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 hasdeleteon 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 / 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 incognee/tests/unit/api/v1/forget/(argument validation, the HTTP endpoint,memory_only); cover both the document and thememory_onlypaths for new deletion behaviour.
版本历史
-
525b1d1
当前 2026-11-02 22:48
新增支持在不指定目标的情况下单独清除调用者的搜索历史;为 forget 操作添加 clean_history 标志,允许在删除数据时同步清理相关历史记录。
- 37f788b 2026-10-19 05:49


