# How to Configure the Data Root Directory in Cognee

> Learn how to configure the data root directory in Cognee by calling cognee.config.data_root_directory. Easily change where Cognee stores files and embeddings.

- Repository: [Topoteretes/cognee](https://github.com/topoteretes/cognee)
- Tags: how-to-guide
- Published: 2026-03-16

---

**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`](https://github.com/topoteretes/cognee/blob/main/cognee/base_config.py), the `BaseConfig` class defines the default as follows:

```python
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`](https://github.com/topoteretes/cognee/blob/main/cognee/api/v1/config/config.py) updates the cached configuration instance that all downstream components reference.

```python

# 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.

```python
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`](https://github.com/topoteretes/cognee/blob/main/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:

```python
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:

```python
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:

```python
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`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/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.