prune

Methods for deleting stored data and resetting Cognee system state.

cognee.prune

Static class with methods for cleaning up Cognee data and system state.

Methods

prune.prune_data()

await cognee.prune.prune_data()

Removes all raw data files from the file storage backend (local disk or S3, configured via DATA_ROOT_DIRECTORY). Does not remove database records — use prune_system(metadata=True) for that.

prune.prune_system()

await cognee.prune.prune_system(
    graph: bool = True,
    vector: bool = True,
    metadata: bool = False,
    cache: bool = True,
)

Cleans up system database resources selectively. Does not delete files from storage — call prune_data() first if you also need to wipe raw files.

graph · bool · default: "True"

Delete all data from the graph database (e.g., Kuzu, Neo4j).

vector · bool · default: "True"

Delete all data from the vector store (e.g., LanceDB, Qdrant).

metadata · bool · default: "False"

Delete the relational metadata database (datasets, data records, pipeline state). Defaults to False to prevent accidental loss of metadata.

cache · bool · default: "True"

Clear the cache. This wipes the cache directory (CACHE_ROOT_DIRECTORY — e.g. downloaded ontologies and tutorial data) and, when session caching or usage logging is enabled, also prunes the session cache backend (conversation history and usage logs). It does not touch graph, vector, or relational data.

prune_system has no permission checks and will wipe all graph and vector data regardless of which user or dataset it belongs to. Only use it in local development or test environments.

With ENABLE_BACKEND_ACCESS_CONTROL="false" and PGVector sharing the relational Postgres database, a vector-only prune — including the bare await cognee.prune.prune_system(), since metadata defaults to False — raises SharedDatabasePruneError before anything is deleted. Pass metadata=True, or give PGVector a dedicated database by setting all five VECTOR_DB_* values; see the FAQ below for both options.

Prune cannot target a single dataset. Neither prune_data() nor prune_system() accepts a dataset_id — both always operate globally across every dataset. To remove a single dataset, use cognee.datasets.empty_dataset(dataset_id), which deletes that dataset’s graph content, data records, and the dataset entity itself while leaving other datasets untouched. To remove a single data item, use cognee.datasets.delete_data(dataset_id, data_id).

Examples

import cognee

# Full reset: remove raw files, databases, and metadata
await cognee.prune.prune_data()           # wipes raw files from disk / S3
await cognee.prune.prune_system(metadata=True)  # wipes graph, vector, relational DB, and cache

# Partial reset: clear graph and vector stores only (keep metadata and files)
await cognee.prune.prune_system(graph=True, vector=True, metadata=False, cache=False)

# Clear only the cache (session history, usage logs, cached files)
await cognee.prune.prune_system(graph=False, vector=False, metadata=False, cache=True)

FAQ

How do I re-cognify data without deleting my PostgreSQL metadata?

Keep metadata=False (the default) if you want to preserve the relational database. But for a true re-cognify of already-processed data, prune_system() is not enough by itself: it clears graph/vector/cache storage, but it does not reset the per-data-item cognify_pipeline status that incremental cognify() uses to decide what to skip.

For the safe rebuild flow, use forget(..., memory_only=True) on the dataset you want to re-process. That preserves raw files, datasets, and data records while clearing graph/vector memory and resetting cognify status:

# Remove only derived memory for one dataset, keep files + metadata
await cognee.forget(dataset="my_dataset", memory_only=True)
await cognee.cognify(datasets="my_dataset")

Setting metadata=True would delete the datasets, data records, and pipeline state from the relational database (PostgreSQL or SQLite), forcing you to add() your data again before re-cognifying.

Do I need to prune when switching vector databases?

If you switch VECTOR_DB_PROVIDER, the new vector store starts empty, so you do need to rebuild memory for the datasets you want to query. The safest documented flow is dataset-scoped: update VECTOR_DB_PROVIDER (see Vector Stores), then clear only the dataset’s derived memory and re-cognify it:

await cognee.forget(dataset="my_dataset", memory_only=True)
await cognee.cognify(datasets="my_dataset")

This preserves the dataset’s files and relational metadata while rebuilding the graph and embeddings against the new vector store.

If you use prune_system(vector=True, metadata=False), remember that it clears the vector storage globally but does not reset cognify status for existing data items, so a plain follow-up cognify() may skip them.

Why does prune_system() raise SharedDatabasePruneError?

You are running PGVector with ENABLE_BACKEND_ACCESS_CONTROL="false" against the same Postgres database as your relational metadata, and you asked for a vector-only prune (with access control on, each dataset has its own vector database and prune_system removes those instead). Pruning the vector store there would mean dropping tables in a database that also holds data, datasets, dataset_data, users, and permissions, so the adapter refuses:

SharedDatabasePruneError: PGVector cannot be pruned independently while it shares
the relational PostgreSQL database. Use prune_system(metadata=True) to delete the
shared database (this also deletes users, datasets and permissions), or set
VECTOR_DB_NAME to a different, dedicated database.

SharedDatabasePruneError is a plain RuntimeError subclass — it carries no HTTP status code, which is fine because prune_system is not exposed over the REST API. Import it from cognee.infrastructure.databases.vector.exceptions if you want to catch it.

Fix it one of two ways:

1. Prune the shared database as a whole with metadata=True. The refusal is caught and logged in this case, and the relational delete_database() removes the collection tables along with everything else — a single authoritative deletion rather than two overlapping ones:

   await cognee.prune.prune_system(metadata=True)
   

   This also deletes datasets, data records, users, and permissions, so you will need to add() your data again.

2. Give PGVector its own database. Set all five of VECTOR_DB_HOST, VECTOR_DB_PORT, VECTOR_DB_USERNAME, VECTOR_DB_PASSWORD, and VECTOR_DB_NAME, with VECTOR_DB_NAME different from DB_NAME — see Vector Stores. Cognee then builds a dedicated engine for the vector store, and prune_system(vector=True, metadata=False) drops only that database’s tables. Setting VECTOR_DB_NAME alone is not enough: with any of the five missing, Cognee logs a warning and falls back to the relational DB_* settings, which is the shared case again.

Nothing has been deleted when the error is raised — the vector step runs before graph deletion precisely so the refusal comes first.

What exactly does cache=True clear?

It removes the cache directory (CACHE_ROOT_DIRECTORY, holding cached files such as downloaded ontologies and tutorial data) and, when session caching or usage logging is enabled, prunes the session cache backend (conversation history and usage logs). It never deletes graph, vector, or relational data, so clearing the cache is safe to combine with any re-cognify workflow.