Skip to main content
Kuzu is an embedded graph database designed for fast analytical queries, offering an in-process alternative to client-server databases like Neo4j.

​
Installation

Install Graphiti with Kuzu support: 
pip install graphiti-core[kuzu]

​
Configuration

​
Database Location

Kuzu can run in-memory or persist to disk: 
from graphiti_core import Graphiti
from graphiti_core.driver.kuzu_driver import KuzuDriver

# In-memory database (for testing)
driver = KuzuDriver(db=":memory:")

# Persistent database (recommended for production)
driver = KuzuDriver(db="/path/to/graphiti.kuzu")

# Initialize Graphiti
graphiti = Graphiti(graph_driver=driver)

​
Concurrency Control

Control the number of concurrent queries: 
driver = KuzuDriver(
    db="/tmp/graphiti.kuzu",
    max_concurrent_queries=4  # Default is 1
)

​
Driver Implementation

The KuzuDriver (graphiti_core/driver/kuzu_driver.py:135) provides:
  • Embedded Architecture: Runs in-process, no separate server needed
  • Schema Enforcement: Explicit schema defined at startup
  • Fast Analytics: Optimized for analytical graph queries
  • DuckDB Integration: Built on DuckDB’s columnar storage

​
Connection Parameters

ParameterTypeDefaultDescription
dbstr":memory:"Database path or :memory: for in-memory
max_concurrent_queriesint1Maximum number of concurrent queries

​
Schema Definition

Kuzu requires an explicit schema. Graphiti defines the following node and relationship types:

​
Node Tables

  • Episodic: Episode nodes with content and metadata
  • Entity: Entity nodes with embeddings and summaries
  • Community: Community nodes for entity groupings
  • RelatesToNode_: Edge representation as nodes (workaround for Kuzu limitations)
  • Saga: Saga nodes for episode sequencing

​
Relationship Tables

  • RELATES_TO: Entity relationships
  • MENTIONS: Episodic to Entity connections
  • HAS_MEMBER: Community membership
  • HAS_EPISODE: Saga to Episode connections
  • NEXT_EPISODE: Episode sequencing
The schema is automatically created during driver initialization (graphiti_core/driver/kuzu_driver.py:54).

​
Edge Representation

Kuzu currently doesn’t support fulltext indexes on edge properties. Graphiti works around this by representing RELATES_TO edges as intermediate nodes: 
Before: (Entity)-[:RELATES_TO]->(Entity)
After:  (Entity)-[:RELATES_TO]->(RelatesToNode_)-[:RELATES_TO]->(Entity)
This allows fulltext search on relationship facts while maintaining query compatibility.

​
Complete Example

import asyncio
from datetime import datetime, timezone
from graphiti_core import Graphiti
from graphiti_core.driver.kuzu_driver import KuzuDriver
from graphiti_core.nodes import EpisodeType

async def main():
    # Initialize Kuzu driver with persistent database
    driver = KuzuDriver(
        db="/tmp/graphiti.kuzu",
        max_concurrent_queries=2
    )
    
    # Initialize Graphiti
    graphiti = Graphiti(graph_driver=driver)
    
    try:
        # Add an episode
        await graphiti.add_episode(
            name="California Politics 1",
            episode_body="Kamala Harris is the Attorney General of California.",
            source=EpisodeType.text,
            reference_time=datetime.now(timezone.utc)
        )
        print("Added episode to Kuzu database")
        
        # Search the graph
        results = await graphiti.search("Who was the California Attorney General?")
        for result in results:
            print(f"Fact: {result.fact}")
    
    finally:
        await graphiti.close()
        print("Kuzu database closed")

if __name__ == "__main__":
    asyncio.run(main())

​
When to Use Kuzu

Choose Kuzu if you:
  • Need an embedded database (no separate server)
  • Want fast analytical queries over large graphs
  • Prefer simpler deployment (single process)
  • Are building desktop or edge applications
  • Need DuckDB-compatible analytics
Choose Neo4j/FalkorDB if you:
  • Need client-server architecture
  • Require production-ready clustering
  • Want extensive ecosystem support
  • Need dynamic schema updates

​
Performance Characteristics

  • Write Performance: Optimized for batch writes
  • Read Performance: Excellent for analytical queries and graph traversals
  • Storage: Columnar storage for efficient compression
  • Memory: Lower memory footprint than in-memory databases

​
Index Management

Kuzu’s schema-based approach means indices are defined during schema creation. The build_indices_and_constraints() method is a no-op for Kuzu, as indices are built automatically from the schema.

​
Production Considerations

  • Database Path: Use absolute paths for persistent databases
  • Concurrency: Tune max_concurrent_queries based on workload
  • Backups: Copy the database directory for backups
  • Version Compatibility: Kuzu is under active development; test version upgrades carefully
  • Schema Changes: Require database recreation (no dynamic schema evolution)

Build docs developers (and LLMs) love

Get started for freeTalk to us