FalkorDB Integration

Use FalkorDB as a lightweight, Redis-based graph database backend for Graphiti

FalkorDB is a lightweight graph database built on Redis, offering a simpler alternative to Neo4j with RedisSearch-powered fulltext indexing.

Installation

Install Graphiti with FalkorDB support:

pip

pip install graphiti-core[falkordb]

Prerequisites

Run FalkorDB with Docker

The fastest way to get started:

docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest

This starts:

• FalkorDB on port 6379 (Redis protocol)
• FalkorDB Browser UI on port 3000

Run with Docker Compose

From the Graphiti repository:

docker compose --profile falkordb up

Configuration

Environment Variables

.env

FALKORDB_HOST=localhost
FALKORDB_PORT=6379
FALKORDB_USERNAME=  # Optional, leave empty for local
FALKORDB_PASSWORD=  # Optional, leave empty for local

Basic Setup

Initialize Graphiti with FalkorDB:

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

# Create FalkorDB driver
driver = FalkorDriver(
    host=os.getenv("FALKORDB_HOST", "localhost"),
    port=int(os.getenv("FALKORDB_PORT", "6379")),
    username=os.getenv("FALKORDB_USERNAME"),  # None for local
    password=os.getenv("FALKORDB_PASSWORD")   # None for local
)

# Initialize Graphiti
graphiti = Graphiti(graph_driver=driver)

Custom Database Name

FalkorDB supports multiple graphs (databases) per instance:

from graphiti_core.driver.falkordb_driver import FalkorDriver

driver = FalkorDriver(
    host="localhost",
    port=6379,
    database="my_custom_graph"  # Custom graph name
)

Driver Implementation

The FalkorDriver (graphiti_core/driver/falkordb_driver.py:109) provides:

• Redis Protocol: Uses FalkorDB’s async Redis client
• Multi-tenancy: Support for multiple graphs in a single instance
• RedisSearch: Fulltext search using RedisSearch syntax
• Lightweight: Embedded or standalone deployment options

Connection Parameters

Parameter	Type	Default	Description
host	str	"localhost"	FalkorDB server host
port	int	6379	FalkorDB server port
username	str | None	None	Authentication username (optional)
password	str | None	None	Authentication password (optional)
database	str	"default_db"	Graph database name
falkor_db	FalkorDB | None	None	Existing FalkorDB client instance

Fulltext Search

FalkorDB uses RedisSearch syntax for fulltext queries:

# Search uses @ prefix for field queries
# Group filtering: (@group_id:value1|value2)
# Text search: (word1 | word2)
results = await graphiti.search("California Governor")

The driver automatically:

• Sanitizes special characters
• Removes stopwords
• Builds RedisSearch-compatible query strings

Index Management

Graphiti automatically creates:

• Range Indices: On UUID, timestamps, and group_id fields
• Fulltext Indices: On entity/edge facts and episode content

To rebuild indices:

await driver.build_indices_and_constraints(delete_existing=True)

Complete Example

import asyncio
import os
from datetime import datetime, timezone
from graphiti_core import Graphiti
from graphiti_core.driver.falkordb_driver import FalkorDriver
from graphiti_core.nodes import EpisodeType

async def main():
    # Initialize FalkorDB driver
    driver = FalkorDriver(
        host=os.getenv("FALKORDB_HOST", "localhost"),
        port=int(os.getenv("FALKORDB_PORT", "6379"))
    )
    
    # 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 FalkorDB")
        
        # 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("FalkorDB connection closed")

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

When to Use FalkorDB

Choose FalkorDB if you:

• Need a lightweight, Redis-based solution
• Want simpler deployment (single binary)
• Prefer RedisSearch for fulltext indexing
• Need embedded database capabilities
• Are prototyping or building smaller-scale applications

Choose Neo4j if you:

• Need enterprise-grade production features
• Require advanced graph algorithms
• Need clustering and high availability
• Want extensive tooling and ecosystem support

Production Considerations

• Persistence: Configure Redis persistence (AOF/RDB) for data durability
• Memory: FalkorDB is in-memory; ensure adequate RAM for your dataset
• Clustering: Use Redis Cluster for horizontal scaling
• Monitoring: Use Redis monitoring tools (RedisInsight, etc.)

Related Resources

• FalkorDB Documentation
• FalkorDB GitHub
• RedisSearch Syntax