Data Isolation and Multi-Tenancy

​

How Cognee isolates memory

With multi-user mode on (the default since 0.5.0 when your storage supports it), Cognee keeps each user’s and each team’s memory separate on a single instance. The isolation boundary is the dataset: each dataset has its own graph and vector store (see the table below), and every read or write is checked against dataset-level permissions. Those permissions are granted to three kinds of principals:

• Users own datasets and can be given read, write, share or delete permission on other users’ datasets.
• Roles group users inside a tenant, for example one team, and can be granted permissions as a group.
• Tenants represent an organization; a permission granted to a tenant applies to all of its members.

​

What multi-user mode is

Multi-user mode is the architectural directive in Cognee that enforces strict data isolation between different users and datasets. It is primarily controlled by the environment variable ENABLE_BACKEND_ACCESS_CONTROL. Starting with version 0.5.0, this mode is enabled by default when your configured storage setup supports it. This keeps Cognee secure by default without forcing unsupported database combinations into multi-user mode.

​

Upgrading to v0.5.0 or Later

For configuration requirements and supported handler/provider combinations, see Permissions Setup and Dataset Database Handlers.

​

When multi-user mode is active

When multi-user mode is active, the system unlocks several multi-tenant features:

• Isolated Recall: Retrieval operations are strictly scoped to datasets the authenticated user has explicit read access to. To learn more about the permissions system and access types, read about our Permission System.
• Granular Management: Remembering or forgetting documents is scoped at the dataset level, preventing global knowledge pool pollution.
• Automatic Routing: The system automatically determines which local/cloud database or logical schema to connect to based on the dataset. This is done with the help of Dataset Database Handlers.

​

Where isolation happens: datasets vs. databases

Dataset isolation is handled differently depending on whether backend access control is enabled. This applies to the graph and vector stores, not the relational store: So a “workspace” or “tenant” is not a database boundary. The database boundary in multi-user mode is the dataset: each dataset is routed to its own physical graph/vector store, while tenants and users simply control who can reach which datasets.