Kuzu Integration

Use Kuzu as an embedded graph database backend for Graphiti applications

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

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

Parameter	Type	Default	Description
db	str	":memory:"	Database path or :memory: for in-memory
max_concurrent_queries	int	1	Maximum 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)

Related Resources

• Kuzu Documentation
• Kuzu GitHub
• DuckDB Documentation