How to Configure Kuzu as a Graph Database in Cognee

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:

import cognee

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

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

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

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 (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:

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.

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

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