Cognee’s multi-tenant system uses file-based database isolation with Kuzu (graph database) and LanceDB (vector database) to ensure complete data separation between users and datasets.

​
Key Features

Complete Data Isolation

Zero Data LeakageEach context gets separate graph and vector stores with file-based database isolation.

Dataset-Level Permissions

Fine-grained ControlGranular access control with read, write, delete, and share permissions per dataset.

Hierarchical Permissions

Organized StructureSupport for tenants, roles, and users with inherited permission management.

File-Based Isolation

Maximum SecurityUses Kuzu and LanceDB for completely separate database instances per user per dataset.

​
Quick Setup

1

Enable Permissions

Set the environment variable to activate the multi-tenant permissions system.
2

Start Backend

Run the Cognee backend server with permissions enabled.
3

Create Users

Register users and assign them to tenants with appropriate roles.
4

Manage Permissions

Grant dataset-specific permissions to control access.

​
Configuration

To enable Cognee’s multi-tenant permissions system, set the following environment variable: 
ENABLE_BACKEND_ACCESS_CONTROL=True
Important: When this is enabled, Cognee will:
  • Ignore user-configured graph and vector database settings
  • Enforce the use of Kuzu (file-based graph db) and LanceDB (file-based vector db)
  • Deploy completely separate database instances per user per dataset
This approach ensures complete data isolation and prevents any possibility of data leakage between contexts.

​
Permission Hierarchy

The multi-tenant system follows a clear hierarchical structure: 
Tenant
├── Users (belong to tenant)
├── Roles (defined within tenant)
└── Datasets
    ├── Data (documents/files)
    └── Permissions (read, write, delete, share)

Tenants

​
Database Isolation Architecture

The system creates separate database directories for each user-dataset combination, ensuring complete data isolation: 
.cognee_system/
├── databases/
│   ├── user_1/
│   │   ├── dataset_a/
│   │   │   ├── kuzu_graph/      # Separate graph database
│   │   │   └── lancedb_vectors/ # Separate vector database
│   │   └── dataset_b/
│   │       ├── kuzu_graph/
│   │       └── lancedb_vectors/
│   └── user_2/
│       └── dataset_a/
│           ├── kuzu_graph/
│           └── lancedb_vectors/
This file-based isolation ensures that each user-dataset combination gets completely separate database instances, preventing any possibility of data leakage between contexts.

​
Permission Types

Cognee supports four types of permissions for fine-grained access control:

Read

View AccessView and search dataset contents. Required for all query operations.

Write

Modify AccessAdd new data to the dataset. Required for data ingestion and cognify operations.

Delete

Remove AccessRemove documents from the dataset. Required for data cleanup operations.

Share

Permission ManagementGrant permissions to other users. Required to manage access to datasets.

​
Permission Management Rules

Dataset Creation

​
ACL (Access Control List) Structure

Permissions are managed through a relational database with the following key tables:

Database Schema

​
API Integration

Programmatic Access
import cognee
import os

# Enable permissions
os.environ["ENABLE_BACKEND_ACCESS_CONTROL"] = "True"

# Set user context
cognee.set_user("user_123")

# Operations are automatically scoped to user permissions
await cognee.add("data", dataset_id="dataset_a")  # Requires write permission
await cognee.cognify()  # Requires write permission
results = await cognee.search("query")  # Requires read permission

​
Best Practices

Security First

Secure Defaults
  • Start with minimal permissions and grant as needed
  • Use roles for common permission patterns
  • Regularly audit user permissions
  • Monitor access patterns for anomalies

Performance

Optimize Access
  • Cache permission lookups for frequently accessed datasets
  • Use role-based permissions to reduce direct grants
  • Monitor database performance with large user bases
  • Consider permission inheritance for efficiency

User Management

Organized Structure
  • Group users into tenants for organizational boundaries
  • Use descriptive role names and clear permission sets
  • Document permission policies for your organization
  • Implement user onboarding workflows

Data Governance

Compliance Ready
  • Maintain audit logs of permission changes
  • Implement data retention policies per tenant
  • Use dataset-level permissions for compliance boundaries
  • Regular permission reviews and cleanup

​
Troubleshooting

Permission Denied Errors

​
Next Steps

User Permissions Guide

Complete TutorialDetailed step-by-step guide with screenshots for setting up and testing the permissions system.

REST API Server

API IntegrationSet up REST API endpoints for multi-tenant applications with authentication.

Configuration

Advanced SetupConfigure advanced multi-tenant settings and performance optimizations.

Deployment Guide

Production DeploymentDeploy multi-tenant Cognee applications in production environments.