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

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

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

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

## Prerequisites

### Run FalkorDB with Docker

The fastest way to get started:

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

```bash theme={null}
docker compose --profile falkordb up
```

## Configuration

### Environment Variables

```bash .env theme={null}
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:

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

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

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

```python theme={null}
await driver.build_indices_and_constraints(delete_existing=True)
```

## Complete Example

```python theme={null}
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](https://docs.falkordb.com/)
* [FalkorDB GitHub](https://github.com/FalkorDB/FalkorDB)
* [RedisSearch Syntax](https://redis.io/docs/interact/search-and-query/)