How to Configure the Data Root Directory in Cognee

Call cognee.config.data_root_directory("/absolute/path") before any data operations to change where Cognee stores files, embeddings, and vector chunks.

By default, the Cognee framework stores all user-generated artifacts—including uploaded documents, extracted text chunks, and vector embeddings—in a local directory adjacent to the library source. Understanding how to configure the data root directory in Cognee is essential for production deployments where you need to mount external volumes, use temporary workspaces, or separate storage from code.

Understanding the Default Data Root Location

When you import Cognee without custom configuration, the system initializes a BaseConfig object that defines .data_storage as the default data root directory. This path is resolved to an absolute location using the get_absolute_path helper from cognee.root_dir.

In cognee/base_config.py, the BaseConfig class defines the default as follows:

class BaseConfig(BaseSettings):
    data_root_directory: str = get_absolute_path(".data_storage")

This means Cognee creates a .data_storage folder in your repository root to hold all persistent data. While suitable for local development, this default often needs override for containerized environments or shared storage scenarios.

Setting a Custom Data Root Directory

To redirect where Cognee writes data, use the static configuration helper exposed in the public API. The data_root_directory method in cognee/api/v1/config/config.py updates the cached configuration instance that all downstream components reference.

# cognee/api/v1/config/config.py

@staticmethod
def data_root_directory(data_root_directory: str):
    base_config = get_base_config()
    base_config.data_root_directory = data_root_directory

Once called, this change propagates immediately to file-storage adapters, chunk loaders, and vector-database initializers. Configure this value at the start of your script before invoking any data operations.

import cognee

# Set an absolute path to your preferred storage location

cognee.config.data_root_directory("/mnt/bigdisk/cognee_data")

# Verify the configuration

print(cognee.config.get_base_config().data_root_directory)

# Output: /mnt/bigdisk/cognee_data

Path Requirements and Validation

Cognee enforces strict path validation through the ensure_absolute_path function in cognee/root_dir.py. The system requires either an absolute filesystem path or an S3 URL (formatted as s3://bucket/path). If you provide a relative path, the framework raises a ValueError at runtime.

The validation logic ensures:

• Absolute paths only: Relative paths like ./data or ../storage are rejected
• S3 support: Cloud storage URLs are accepted as valid absolute references
• Thread safety: The configuration object uses a ContextVar, making the setting safe across async tasks within the same Python process

Important Configuration Details

Several behavioral nuances affect how the data root directory functions within the Cognee ecosystem:

• Timing matters: You must set the data root before calling cognee.add(), cognee.cognify(), or any method that triggers file writes. The configuration is cached after first access, so late changes may not affect already-initialized components.
• Isolated settings: Changing the data root does not modify system_root_directory, cache_root_directory, or logs_root_directory. Each of these uses separate setters in the same config namespace.
• Persistence: The configuration exists only in memory for the process lifetime. You must call the setter in every new Python session or script execution.

Practical Code Examples

Basic Local Directory Configuration

For standard deployments with local or mounted storage:

import cognee
import pathlib

# Resolve to absolute path and ensure directory exists

data_path = pathlib.Path("/opt/cognee_storage").resolve()
data_path.mkdir(parents=True, exist_ok=True)

# Configure Cognee to use this location

cognee.config.data_root_directory(str(data_path))

# Proceed with normal operations

cognee.add("document.pdf")
cognee.cognify()

S3 Bucket Storage

For cloud-native deployments using object storage:

import cognee

# S3 URLs are treated as valid absolute paths

s3_root = "s3://my-cognee-bucket/data"
cognee.config.data_root_directory(s3_root)

# File adapters will now read/write via S3 backend

cognee.add("s3://source-bucket/document.txt")

Reset to Default Location

To revert to the original .data_storage location:

import cognee
from cognee.root_dir import get_absolute_path

default_path = get_absolute_path(".data_storage")
cognee.config.data_root_directory(default_path)

Summary

Configuring the data root directory in Cognee gives you control over where the framework persists files, embeddings, and vector data. Key points to remember:

• Default location: .data_storage in the repository root, defined in cognee/base_config.py
• Configuration method: cognee.config.data_root_directory("/absolute/path") from the public API
• Validation: Requires absolute paths or S3 URLs via ensure_absolute_path in cognee/root_dir.py
• Timing: Must be set before any data operations like cognee.add() or cognee.cognify()
• Scope: Affects only the data root; system, cache, and log directories require separate configuration

Frequently Asked Questions

What is the default data root directory in Cognee?

By default, Cognee stores data in a .data_storage folder located at the repository root. The BaseConfig class in cognee/base_config.py defines this using get_absolute_path(".data_storage"), which resolves to an absolute filesystem path relative to the Cognee installation location.

Can I use cloud storage like S3 as the data root?

Yes, Cognee supports S3 URLs formatted as s3://bucket-name/path. The ensure_absolute_path helper in cognee/root_dir.py recognizes these as valid absolute paths. When configured with an S3 root, the framework's file-storage adapters automatically use the S3 backend for read and write operations.

When should I configure the data root directory?

You must configure the data root directory before invoking any Cognee operations that write to disk, such as cognee.add(), cognee.cognify(), or vector database initialization. The configuration object is cached in a ContextVar, so setting it at the start of your script ensures all components use the correct path.

Does changing the data root affect logs or cache locations?

No, the data root directory is independent of other storage locations. Changing it via cognee.config.data_root_directory() only affects where uploaded files, chunks, and embeddings are stored. System files, cache data, and logs each have separate configuration methods (system_root_directory, cache_root_directory, and logs_root_directory) in the same config namespace.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}