Graph Database Drivers

Connect Graphiti to Neo4j, FalkorDB, Amazon Neptune, or Kùzu graph databases

Graphiti supports multiple graph database backends through a unified driver interface. Choose the database that best fits your deployment needs.

Supported Databases

Neo4j

Production-ready graph database with full Cypher support

FalkorDB

Redis-based graph database for in-memory performance

Amazon Neptune

Fully managed graph database service on AWS

Kùzu

Embedded graph database for local-first applications

Neo4j Driver

Neo4j is the default and most widely used graph database with Graphiti.

Installation

Neo4j support is included in the base Graphiti installation:

pip install graphiti-core

Connection

from graphiti_core import Graphiti

graphiti = Graphiti(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="your_password"
)

Connection Parameters

Parameter	Type	Description	Default
uri	str	Neo4j connection URI	Required
user	str	Database username	Required
password	str	Database password	Required

Environment Variables

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password

Neo4j Desktop Setup

1. Download Neo4j Desktop

   Download from neo4j.com/download

2. Create a Project

   Open Neo4j Desktop and create a new project

3. Add a Database

   Click “Add” → “Local DBMS” and set a password

4. Start the Database

   Click the play button to start your local DBMS

5. Connect from Graphiti

   graphiti = Graphiti(
       uri="bolt://localhost:7687",
       user="neo4j",
       password="password"  # Your chosen password
   )
   

Neo4j Aura (Cloud)

For managed Neo4j hosting:

graphiti = Graphiti(
    uri="neo4j+s://xxxxx.databases.neo4j.io",
    user="neo4j",
    password="your_password"
)

FalkorDB Driver

FalkorDB is a Redis module that provides graph database capabilities with in-memory performance.

Installation

Install the FalkorDB driver:

pip install graphiti-core[falkordb]

Connection

from graphiti_core import Graphiti
from graphiti_core.driver.falkordb_driver import FalkorDriver

# Create FalkorDB driver
driver = FalkorDriver(
    host="localhost",
    port="6379",
    username=None,  # Optional
    password=None   # Optional
)

# Initialize Graphiti with FalkorDB
graphiti = Graphiti(graph_driver=driver)

Connection Parameters

Parameter	Type	Description	Default
host	str	FalkorDB server host	"localhost"
port	str	FalkorDB server port	"6379"
username	str	Username (optional)	None
password	str	Password (optional)	None

Environment Variables

FALKORDB_HOST=localhost
FALKORDB_PORT=6379
FALKORDB_USERNAME=  # Optional
FALKORDB_PASSWORD=  # Optional

Running FalkorDB

Docker

docker run -p 6379:6379 falkordb/falkordb:latest

FalkorDB Cloud

For managed FalkorDB hosting, set your connection credentials:

driver = FalkorDriver(
    host="your-instance.falkordb.cloud",
    port="6379",
    username="your_username",
    password="your_password"
)

Amazon Neptune Driver

Amazon Neptune is a fully managed graph database service optimized for AWS deployments.

Installation

pip install graphiti-core[neptune]

Connection

from graphiti_core import Graphiti
from graphiti_core.driver.neptune_driver import NeptuneDriver

driver = NeptuneDriver(
    host="your-neptune-cluster.cluster-xxxxx.us-east-1.neptune.amazonaws.com",
    port=8182,
    use_https=True
)

graphiti = Graphiti(graph_driver=driver)

Connection Parameters

Parameter	Type	Description
host	str	Neptune cluster endpoint
port	int	Port number (typically 8182)
use_https	bool	Use HTTPS connection

AWS IAM Authentication

Neptune supports IAM authentication for enhanced security:

driver = NeptuneDriver(
    host="your-cluster.cluster-xxxxx.us-east-1.neptune.amazonaws.com",
    port=8182,
    use_https=True,
    use_iam=True  # Enable IAM authentication
)

Ensure your AWS credentials are configured:

aws configure

Kùzu Driver

Kùzu is an embedded graph database perfect for local-first applications.

Installation

pip install graphiti-core[kuzu]

Connection

from graphiti_core import Graphiti
from graphiti_core.driver.kuzu_driver import KuzuDriver

driver = KuzuDriver(
    database_path="./my_graph_db"  # Local directory path
)

graphiti = Graphiti(graph_driver=driver)

Connection Parameters

Parameter	Type	Description
database_path	str	Path to database directory

Use Cases

Kùzu is ideal for:

• Local development and testing
• Desktop applications
• Edge deployments
• Embedded graph analytics

Driver Interface

All drivers implement a unified interface, allowing you to switch databases without changing your application code:

from graphiti_core import Graphiti
from graphiti_core.driver.neo4j_driver import Neo4jDriver
from graphiti_core.driver.falkordb_driver import FalkorDriver

# Both drivers work the same way
driver = Neo4jDriver(uri="bolt://localhost:7687", user="neo4j", password="password")
# OR
driver = FalkorDriver(host="localhost", port="6379")

graphiti = Graphiti(graph_driver=driver)

# Same API regardless of driver
await graphiti.add_episode(...)
results = await graphiti.search(...)

Passing Custom Drivers

You can pass a pre-configured driver to Graphiti:

from graphiti_core import Graphiti
from graphiti_core.driver.neo4j_driver import Neo4jDriver

# Configure driver separately
driver = Neo4jDriver(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password"
)

# Pass to Graphiti
graphiti = Graphiti(graph_driver=driver)

This approach is useful when:

• You need custom driver configuration
• You want to reuse a driver across multiple Graphiti instances
• You’re testing with different database backends

Database Initialization

After connecting, build indices and constraints:

# Required for all drivers
await graphiti.build_indices_and_constraints()

This creates:

• Vector indices for semantic search
• Full-text indices for keyword search
• Uniqueness constraints on UUIDs
• Performance-optimized indices

Always run build_indices_and_constraints() once before using a new database. This ensures optimal performance.

Choosing a Database

Neo4j

Best for:

• Production deployments
• Large-scale graphs
• Complex queries
• Mature ecosystem

Considerations:

• Requires separate database server
• Commercial licensing for production

FalkorDB

Best for:

• In-memory performance
• Real-time applications
• Redis-based infrastructure
• Simple deployment

Considerations:

• Limited to available memory
• Fewer features than Neo4j

Neptune

Best for:

• AWS-native deployments
• Managed infrastructure
• High availability
• Compliance requirements

Considerations:

• AWS-only
• Higher cost

Kùzu

Best for:

• Local development
• Desktop applications
• Edge deployments
• No server setup

Considerations:

• Single-user access
• Limited to single machine

Connection Pooling

Drivers handle connection pooling automatically:

# Connections are pooled and reused
graphiti = Graphiti(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password"
)

# Multiple operations share the connection pool
await graphiti.add_episode(...)
await graphiti.search(...)
await graphiti.add_episode(...)

Closing Connections

Always close the driver when done:

try:
    await graphiti.add_episode(...)
    results = await graphiti.search(...)
finally:
    await graphiti.close()  # Close all connections

Or use as a context manager:

async with Graphiti(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password"
) as graphiti:
    await graphiti.add_episode(...)
    results = await graphiti.search(...)
# Automatically closed

Multi-Database Support

Some drivers support multiple databases:

# Use different databases with the same driver
driver = Neo4jDriver(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password"
)

# Clone for different database
driver_production = driver.clone(database="production")
driver_staging = driver.clone(database="staging")

graphiti_prod = Graphiti(graph_driver=driver_production)
graphiti_stage = Graphiti(graph_driver=driver_staging)

Next Steps

Adding Episodes

Start adding content to your graph database

LLM Providers

Configure your LLM provider

Embeddings

Set up embedding providers