# How to Configure Kuzu as a Graph Database in Cognee

> Configure Kuzu as your graph database in Cognee easily. Activate the native Kuzu adapter by setting the graph database provider before initializing your pipeline for seamless graph operations.

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

---

**To configure Kuzu as your graph database in Cognee, call `cognee.config.set_graph_db_config({"graph_database_provider": "kuzu"})` before initializing your pipeline, which activates the native Kuzu adapter and routes all graph operations through KuzuDB.**

Cognee supports pluggable graph database backends, allowing you to switch storage layers without changing your application code. To configure Kuzu as a graph database in Cognee, you use the public `cognee.config.set_graph_db_config` API to specify the provider and connection details. Once configured, Cognee lazily initializes the `KuzuAdapter` class to handle all node and edge operations.

## Setting the Graph Database Provider

The configuration entry point is the `set_graph_db_config` method on the global config object. This method accepts a dictionary where the key `graph_database_provider` determines which backend to instantiate.

Set the provider to `"kuzu"` to activate the native adapter:

```python
import cognee

cognee.config.set_graph_db_config({
    "graph_database_provider": "kuzu"
})

```

In [`cognee/infrastructure/databases/graph/kuzu/adapter.py`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/kuzu/adapter.py), the `KuzuAdapter` class initializes the database connection during its first use (lines 43-53). The adapter automatically creates the required schema, including `Node` and `EDGE` tables, using native Kuzu Cypher statements (lines 62-82).

## Local Kuzu Configuration

For local development, Kuzu stores data in a file-based database. You can optionally specify the path using `graph_db_path`, or let Cognee use a temporary directory.

```python
import cognee
from cognee.modules.search.types import SearchType

async def main():
    # Configure Kuzu as the graph database provider

    cognee.config.set_graph_db_config({
        "graph_database_provider": "kuzu"
    })
    
    # Optional: set persistent storage location

    # cognee.config.graph_db_path("/path/to/kuzu/data")

    
    # Run standard Cognee operations

    await cognee.add(["KuzuDB is a fast graph DB."], "demo")
    await cognee.cognify(["demo"])
    
    result = await cognee.search(
        query_type=SearchType.GRAPH_COMPLETION,
        query_text="KuzuDB"
    )
    print(result)

import asyncio
asyncio.run(main())

```

This example mirrors the official configuration sample in [`examples/configurations/database_examples/kuzu_graph_database_configuration.py`](https://github.com/topoteretes/cognee/blob/main/examples/configurations/database_examples/kuzu_graph_database_configuration.py) (lines 19-24).

## Remote Kuzu REST Endpoint Configuration

If you run Kuzu behind an HTTP service, configure the remote adapter by including `api_url` in your configuration dictionary. When `api_url` is present, Cognee uses the `RemoteKuzuAdapter` instead of the local adapter.

```python
cognee.config.set_graph_db_config({
    "graph_database_provider": "kuzu",
    "api_url": "https://my-kuzu.example.com/api",
    "username": "admin",
    "password": "secret"  # Use environment variables in production

})

```

The remote implementation lives in [`cognee/infrastructure/databases/graph/kuzu/remote_kuzu_adapter.py`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/kuzu/remote_kuzu_adapter.py) (lines 24-40). This adapter forwards all Cypher-style queries over HTTP, allowing you to separate your Cognee application from the database server.

## Configuring Storage Backends for Kuzu

Cognee supports multiple storage backends for the Kuzu database files. By default, Kuzu uses local disk storage, but you can configure S3 persistence using environment variables.

**Local Disk (Default):** Kuzu writes to the path specified by `graph_db_path` or a system temporary directory.

**Amazon S3:** Set the `STORAGE_BACKEND` environment variable to `"s3"` and provide bucket credentials:

```python
import os

os.environ["STORAGE_BACKEND"] = "s3"
os.environ["S3_BUCKET"] = "my-cognee-bucket"

cognee.config.set_graph_db_config({
    "graph_database_provider": "kuzu"
})

```

When using S3, the `KuzuAdapter` automatically synchronizes database checkpoints using the `push_to_s3` and `pull_from_s3` methods defined in [`cognee/infrastructure/databases/graph/kuzu/adapter.py`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/kuzu/adapter.py).

## How the Kuzu Adapter Initializes the Schema

When you first run a pipeline after configuring Kuzu as a graph database in Cognee, the adapter performs automatic schema setup. In [`cognee/infrastructure/databases/graph/kuzu/adapter.py`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/kuzu/adapter.py), the initialization logic:

1. Creates the database file or connects to the existing one.
2. Installs the Kuzu JSON extension for complex property storage.
3. Executes `CREATE NODE TABLE` and `CREATE REL TABLE` statements to establish the graph schema.

All higher-level graph operations—adding nodes, creating edges, querying neighbors, and retrieving feedback weights—route through this adapter. Your existing Cognee pipelines using `cognify`, `search`, and other methods work unchanged regardless of the underlying storage.

## Summary

- **Use `cognee.config.set_graph_db_config`** with `{"graph_database_provider": "kuzu"}` to activate the Kuzu backend.
- **Local development** requires no additional configuration beyond setting the provider.
- **Remote deployments** add `api_url`, `username`, and `password` to use `RemoteKuzuAdapter`.
- **S3 persistence** works by setting `STORAGE_BACKEND=s3` and `S3_BUCKET` environment variables.
- **Schema creation** happens automatically in [`cognee/infrastructure/databases/graph/kuzu/adapter.py`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/kuzu/adapter.py) when the adapter first connects.

## Frequently Asked Questions

### How do I migrate existing Cognee data to Kuzu?

Cognee includes migration utilities in [`cognee/infrastructure/databases/graph/kuzu/kuzu_migrate.py`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/kuzu/kuzu_migrate.py) that handle version upgrades when the on-disk Kuzu format changes. Run these utilities after upgrading the Cognee package to ensure compatibility with your existing database files.

### Can I switch from Neo4j to Kuzu without changing my code?

Yes. Since you configure the graph database provider through `set_graph_db_config`, changing the `graph_database_provider` value from `"neo4j"` to `"kuzu"` redirects all operations to the Kuzu adapter without requiring changes to your `add`, `cognify`, or `search` calls. The adapter interface abstracts the underlying storage differences.

### Where does Kuzu store data when I don't specify a path?

When `graph_db_path` is not explicitly set, Cognee initializes Kuzu with a temporary directory that persists for the session duration. For production deployments, always configure a persistent path or use the S3 storage backend to prevent data loss between process restarts.

### Does the Kuzu adapter support all Cognee search types?

Yes. The `KuzuAdapter` in [`cognee/infrastructure/databases/graph/kuzu/adapter.py`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/kuzu/adapter.py) implements the full graph interface, supporting all `SearchType` variants including `GRAPH_COMPLETION`, `INSIGHTS`, and `CHUNKS`. The adapter translates these high-level queries into optimized Kuzu Cypher statements.