Object Storage

Use object storage for the data and system directories when running Cognee in distributed environments (containers, Kubernetes, multi‑node). Amazon S3 and any S3-compatible service (Cloudflare R2, MinIO, etc.) are supported today via the AWS_ENDPOINT_URL environment variable.

When to use

Containers/servers without a shared local disk
Centralized storage for data_root_directory and system_root_directory
Easy backups and lifecycle policies

Configuration

Amazon S3
Cloudflare R2
MinIO

Use this for native AWS S3 buckets.

STORAGE_BACKEND=s3
STORAGE_BUCKET_NAME=my-cognee-bucket
AWS_ACCESS_KEY_ID=<aws-access-key-id>
AWS_SECRET_ACCESS_KEY=<aws-secret-access-key>
AWS_REGION=us-east-1
DATA_ROOT_DIRECTORY=s3://my-cognee-bucket/cognee/data
SYSTEM_ROOT_DIRECTORY=s3://my-cognee-bucket/cognee/system

AWS_ENDPOINT_URL is not required for standard Amazon S3.For AWS-hosted deployments, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are optional when the runtime already has ambient AWS credentials. If both values are omitted, Cognee defers to boto3/s3fs’s default credential resolution chain, including EC2 instance profiles, ECS task roles, EKS IRSA (IAM Roles for Service Accounts), shared credentials files, and AWS_PROFILE.If you set either AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY explicitly, set both. AWS_SESSION_TOKEN is also supported when using temporary credentials.

Use this for Cloudflare R2 buckets through the S3-compatible API.

STORAGE_BACKEND=s3
STORAGE_BUCKET_NAME=my-cognee-bucket
AWS_ACCESS_KEY_ID=<r2-access-key-id>
AWS_SECRET_ACCESS_KEY=<r2-secret-access-key>
AWS_ENDPOINT_URL=https://<account-id>.r2.cloudflarestorage.com
AWS_REGION=auto
DATA_ROOT_DIRECTORY=s3://my-cognee-bucket/cognee/data
SYSTEM_ROOT_DIRECTORY=s3://my-cognee-bucket/cognee/system

Get your R2 credentials from the Cloudflare dashboard under R2 → Manage API tokens. R2 is region-less, so AWS_REGION=auto is a convenient placeholder. Keep explicit R2 credentials configured for this S3-compatible endpoint.

Use this for self-hosted or local MinIO deployments.

STORAGE_BACKEND=s3
STORAGE_BUCKET_NAME=my-cognee-bucket
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
AWS_ENDPOINT_URL=http://localhost:9000
AWS_REGION=us-east-1
DATA_ROOT_DIRECTORY=s3://my-cognee-bucket/cognee/data
SYSTEM_ROOT_DIRECTORY=s3://my-cognee-bucket/cognee/system

Create the bucket in MinIO before starting Cognee, for example with mc mb myminio/my-cognee-bucket. Keep explicit MinIO credentials configured for this S3-compatible endpoint.

The same STORAGE_BACKEND=s3 backend is used for all three options. For S3-compatible providers, Cognee relies on AWS_ENDPOINT_URL to route requests to the correct API endpoint.

Programmatic directories

import os
import cognee

bucket = os.getenv("STORAGE_BUCKET_NAME", "my-cognee-bucket")
data_dir = os.path.join("s3://", bucket, "data")
system_dir = os.path.join("s3://", bucket, "system")

cognee.config.data_root_directory(data_dir)
cognee.config.system_root_directory(system_dir)

Verify

import cognee

await cognee.add("hello from s3")
await cognee.cognify()
res = await cognee.search("hello")
print(f"S3 OK, results: {len(res)}")

How it works

AWS_ENDPOINT_URL is passed directly to s3fs as endpoint_url, which boto3/s3fs then uses instead of the default AWS endpoint. Any service that implements the S3 API will work.

Next steps

Short workflow: S3 Storage guide
Deployment variants: how-to-guides/cognee-sdk/deployment/index

Getting Started

Core Concepts

Setup Configuration

Guides

Examples

CLI

Rust SDK

TypeScript SDK

OSS

When to use

Configuration

Programmatic directories

Verify

How it works

Next steps

​When to use

​Configuration

​Programmatic directories

​Verify

​How it works

​Next steps

When to use

Configuration

Programmatic directories

Verify

How it works

Next steps