> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/getzep/graphiti/llms.txt
> Use this file to discover all available pages before exploring further.

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

<CodeGroup>
  ```bash pip theme={null}
  pip install graphiti-core[kuzu]
  ```

  ```bash uv theme={null}
  uv add graphiti-core[kuzu]
  ```
</CodeGroup>

## Configuration

### Database Location

Kuzu can run in-memory or persist to disk:

```python theme={null}
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:

```python theme={null}
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

```python theme={null}
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](https://kuzudb.com/docs/)
* [Kuzu GitHub](https://github.com/kuzudb/kuzu)
* [DuckDB Documentation](https://duckdb.org/docs/)