Graphiti

​

Overview

• Track temporal changes: Understand how entities and relationships evolve over time
• Support multi-tenancy: Isolated memory spaces for different users or agents
• Enable hybrid search: Combine semantic search with graph traversal
• Scale efficiently: Built on top of FalkorDB’s high-performance graph engine

​

Why Graphiti + FalkorDB?

​

FalkorDB’s Added Value

• Multi-tenant, multi-agent memory: Isolated graph instances for different users or agents, each with their own persistent memory
• High performance: Fast graph operations and efficient memory usage
• Cloud and on-premises ready: Works with FalkorDB Cloud or your own deployment
• Easy integration: Seamless connection with Graphiti for scalable, production-ready knowledge graphs

​

Use Cases

• AI memory for multi-agent systems: Provide persistent, context-rich memory for each agent
• Enterprise knowledge management: Aggregate and search across documents, conversations, and structured data
• Conversational AI: Track facts, entities, and relationships over time for more accurate responses
• E-commerce: Manage inventory, personalize recommendations, and track customer interactions over time
• Research and analytics: Temporal and semantic search across large, heterogeneous datasets

​

Getting Started

​

Prerequisites

• Python 3.10 or higher
• FalkorDB instance (Cloud or self-hosted)
• OpenAI API key (for embeddings and LLM features)

​

Installation

pip install graphiti-core[falkordb]

​

Quick Start Example

import asyncio
from datetime import datetime
from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType

async def main():
    # Initialize Graphiti with FalkorDB
    graphiti = Graphiti(
        uri="falkor://localhost:6379",  # Your FalkorDB connection string
        # For FalkorDB Cloud:
        # uri="falkor://your-instance.falkordb.cloud:6379",
        # username="default",
        # password="your-password"
    )

    # Build indices (run once during setup)
    await graphiti.build_indices_and_constraints()

    # Add an episode (information to be stored in the graph)
    episode_body = """
    Alice met Bob at the AI conference in San Francisco on March 15, 2024.
    They discussed the latest developments in graph databases and decided to 
    collaborate on a new project using FalkorDB.
    """

    await graphiti.add_episode(
        name="Conference Meeting",
        episode_body=episode_body,
        episode_type=EpisodeType.text,
        reference_time=datetime(2024, 3, 15),
        source_description="Conference notes"
    )

    # Search the knowledge graph
    search_results = await graphiti.search(
        query="What did Alice and Bob discuss?",
        num_results=5
    )

    print("Search Results:")
    for result in search_results:
        print(f"- {result}")

    # Close the connection
    await graphiti.close()

# Run the example
asyncio.run(main())

​

Understanding the Code

1. Initialize Graphiti: Connect to your FalkorDB instance with the connection URI
2. Build Indices: Create necessary graph indices and constraints (one-time setup)
3. Add Episodes: Store information as “episodes” - chunks of text or structured data with temporal context
4. Search: Query the graph using natural language or specific parameters
5. Close: Clean up connections when done

​

Advanced Features

​

Hybrid Search

# Node search - find specific entities
nodes = await graphiti.retrieve_nodes(
    query="Alice",
    num_results=10
)

# Episode search - find specific conversations/events
episodes = await graphiti.retrieve_episodes(
    query="conference meeting",
    num_results=5
)

# Combined hybrid search
results = await graphiti.search(
    query="project collaboration",
    num_results=10
)

​

Temporal Queries

from datetime import datetime

# Get the state of knowledge at a specific time
results = await graphiti.search(
    query="What projects was Alice working on?",
    reference_time=datetime(2024, 3, 1),
    num_results=5
)

​

Multi-Tenant Architecture

# User 1's graph
graphiti_user1 = Graphiti(
    uri="falkor://localhost:6379",
    graph_name="user1_memory"
)

# User 2's graph
graphiti_user2 = Graphiti(
    uri="falkor://localhost:6379",
    graph_name="user2_memory"
)

​

Configuration Options

​

Connection Parameters

graphiti = Graphiti(
    uri="falkor://localhost:6379",
    username="your-username",  # For authenticated instances
    password="your-password",
    graph_name="my_graph",     # Custom graph name
    llm_provider="openai",     # LLM provider for entity extraction
    embedding_provider="openai" # Embedding provider for vector search
)

​

Custom LLM Configuration

from graphiti_core.llm_client import OpenAIClient

llm_client = OpenAIClient(
    api_key="your-openai-key",
    model="gpt-4",
    temperature=0.7
)

graphiti = Graphiti(
    uri="falkor://localhost:6379",
    llm_client=llm_client
)

​

Best Practices

1. Batch Episodes: When loading large amounts of data, batch your episodes for better performance
2. Set Reference Times: Always provide reference times for temporal tracking
3. Use Descriptive Names: Give episodes meaningful names for easier retrieval
4. Index Strategy: Build indices once during setup, not on every run
5. Connection Pooling: Reuse Graphiti instances when possible instead of creating new connections

​

Troubleshooting

​

Connection Issues

• Verify your connection string format: falkor://host:port
• Check if FalkorDB is running: redis-cli ping
• Ensure credentials are correct for authenticated instances

​

Performance Optimization

• Use batching for bulk operations
• Monitor memory usage with GRAPH.MEMORY USAGE command
• Consider graph partitioning for very large knowledge bases

​

Resources

• 📚 Graphiti Documentation
• 🎥 Workshop: How to Build a Knowledge Graph ft. Graphiti
• 📓 Blog: Get Started with Graphiti
• 💻 Graphiti GitHub Repository
• 📝 Google Colab Example
• 🔗 FalkorDB Configuration Guide

​

Next Steps

• Explore Cognee for alternative memory management approaches
• Learn about GenAI Tools for graph reasoning and LLM integrations

​

Frequently Asked Questions