Agent Skills › topoteretes/cognee › cognee-forget

cognee-forget

GitHub

指导如何安全地从 Cognee 记忆系统中删除数据。通过列出数据集和文档、读取内容确认、获取用户确认后,使用 forget() API 执行删除操作,支持单文档、整数据集或仅清理图/向量内存等不同粒度。

.agents/skills/cognee-forget/SKILL.md topoteretes/cognee

触发场景

用户要求删除或遗忘特定数据 需要清理 Cognee 记忆系统中的文档或数据集

安装

npx skills add topoteretes/cognee --skill cognee-forget -g -y
更多选项

非标准路径

npx skills add https://github.com/topoteretes/cognee/tree/main/.agents/skills/cognee-forget -g -y

不安装直接使用

npx skills use topoteretes/cognee@cognee-forget

指定 Agent (Claude Code)

npx skills add topoteretes/cognee --skill cognee-forget -a claude-code -g -y

安装 repo 全部 skill

npx skills add topoteretes/cognee --all -g -y

预览 repo 内 skill

npx skills add topoteretes/cognee --list

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}/raw returns 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_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.
  • An empty search after memory_only is not deletion. The raw file and the data row are still there and the next cognify re-processes them. Use a plain forget(dataset=...) or forget(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 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 / 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.

版本历史

  • 525b1d1 当前 2026-11-02 22:48

    新增支持在不指定目标的情况下单独清除调用者的搜索历史;为 forget 操作添加 clean_history 标志,允许在删除数据时同步清理相关历史记录。

  • 37f788b 2026-10-19 05:49

同 Skill 集合

.agents/skills/cognee-cli/SKILL.md
.agents/skills/cognee-community/SKILL.md
.agents/skills/cognee-custom-graph-models/SKILL.md
.agents/skills/cognee-custom-pipelines/SKILL.md
.agents/skills/cognee-docker/SKILL.md
.agents/skills/cognee-improve-sessions/SKILL.md
.agents/skills/cognee-ingestion/SKILL.md
.agents/skills/cognee-integrations/SKILL.md
.agents/skills/cognee-migrations/SKILL.md
.agents/skills/cognee-performance/SKILL.md
.agents/skills/cognee-permissions/SKILL.md
.agents/skills/cognee-recall/SKILL.md
.agents/skills/cognee-server/SKILL.md
.agents/skills/company-brain-company-qa/SKILL.md
.agents/skills/company-brain-follow-up-agent/SKILL.md
.agents/skills/google-workspace-memory/SKILL.md
.agents/skills/multiagent-memory-setup/SKILL.md
.agents/skills/personalized-email/SKILL.md
.agents/skills/self-hosted-companion/SKILL.md
.claude/skills/cognee-cli/SKILL.md
.claude/skills/cognee-community/SKILL.md
.claude/skills/cognee-docker/SKILL.md
.claude/skills/cognee-integrations/SKILL.md
.claude/skills/cognee-permissions/SKILL.md
.claude/skills/cognee-server/SKILL.md
examples/demos/skill_feedback_loop/skills/skill-feedback-writer/SKILL.md
examples/demos/skill_feedback_loop/skills/pr-comment-evaluator/SKILL.md
examples/demos/skill_feedback_loop/skills/diff-risk-explainer/SKILL.md

元信息

文件数
0
版本
525b1d1
Hash
ea46a416
收录时间
2026-10-19 05:49

首页 - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-18 08:17
浙ICP备14020137号-1