Graphiti Knowledge Graph System

Fabricating Evolving Knowledge Graphs to Empower Autonomous Agents

:star: A repository star helps expand the visibility of the Graphiti project! Show your support.

[!TIP] Explore the integrated MCP intermediary server for Graphiti! This unlocks potent, Knowledge Graph-backed persistence for AI entities utilizing Claude, Cursor, and other MCP-compliant clients.

Graphiti constitutes a specialized architectural framework for constructing and querying knowledge structures that possess temporal awareness, explicitly designed for autonomous agents operating amidst fluctuating conditions. Diverging from conventional Retrieval-Augmented Generation (RAG) paradigms, Graphiti systematically assimilates agent interactions, both structured organizational artifacts and unstructured inputs, and external data streams into a cohesive, searchable graph topology. The platform supports continuous data modifications and low-latency lookups, including precise queries concerning historical states, rendering it indispensable for constructing sophisticated, context-sensitive AI deployments.

Leverage Graphiti for:

• Unifying and sustaining evolving interaction logs and proprietary operational datasets.
• Facilitating sophisticated state-driven inferencing and automated sequence execution for agents.
• Interrogating complex, mutable data via combined methodologies: semantic proximity, lexical indexing, and graph traversal.

A knowledge graph fundamentally maps interrelated facts, exemplified by the proposition "Elara possesses affinity for Adidas footwear." Each datum is structured as a "triplet" comprising two terminators (nodes: "Elara", "Adidas footwear") connected by an association (edge: "possesses affinity for"). While knowledge graphs are well-established in information retrieval, Graphiti's distinctiveness lies in its capability to autonomously construct this graph while dynamically managing relationship shifts and preserving chronological context.

Graphiti Integrated with Zep's Context Engineering Stack

Graphiti functions as the foundational mechanism powering Zep, a comprehensive, ready-to-deploy context engineering suite for AI entities. Zep furnishes agent persistence layers, dynamic data handling via Graph RAG, and optimized context assembly routines.

Through the application of Graphiti, Zep has established itself as a leader in the field of Agent Persistence Mechanisms.

Consult our academic contribution: Zep: A Temporal Knowledge Graph Architecture for Agent Memory.

We are pleased to release Graphiti into the open-source ecosystem, recognizing its applicability extends significantly beyond immediate AI memory contexts.

Differentiating Factors of Graphiti

Standard RAG methodologies frequently depend on bulk processing and static data abstraction, leading to inefficiencies when datasets change frequently. Graphiti resolves these limitations by offering:

• Immediate, Iterative Data Integration: New data instances are incorporated instantly without requiring full structural recalculation.
• Bi-Temporal Data Schema: Explicit chronological markers for both event occurrence and system ingestion, enabling precise temporal slicing during queries.
• Optimized Hybrid Retrieval: Merges vector similarity, lexical matching (BM25), and graph pathfinding for rapid lookups, minimizing reliance on resource-intensive LLM summarization.
• Pydantic-Based Entity Definition: Facilitates creation of custom ontologies and developer-defined entity schemas via familiar Pydantic structures.
• Enterprise Scalability: Efficiently manages massive data volumes through parallelized processing pipelines.

Graphiti vs. GraphRAG Comparison

Graphiti is specifically engineered to conquer the hurdles presented by highly mutable and frequently updated datasets, making it the superior choice for applications demanding real-time responsiveness and strictly accurate historical reconstruction.

Deployment Prerequisites

Minimum Requirements:

• Runtime Environment: Python version 3.10 or later
• Persistent Storage Backends:
  • Neo4j (Version 5.26)
  • FalkorDB (Version 1.1.2)
  • Kuzu (Version 0.11.2)
  • AWS Neptune Cluster or Neptune Analytics combined with Amazon OpenSearch Serverless (for full-text indexing)
• API Key: OpenAI credentials (default for LLM reasoning and vector generation)

[!IMPORTANT] Graphiti performs optimally when interfacing with Language Models that natively support Structured Output generation (e.g., OpenAI, Gemini). Utilizing other services risks schema misalignment and ingestion process failures, a common issue particularly with smaller, less capable models.

Optional Dependencies:

• API Keys for alternative LLM providers: Google Gemini, Anthropic, or Groq

[!TIP] The simplest path to establishing a Neo4j instance is via Neo4j Desktop. This utility streamlines the management of Neo4j installations and databases. Alternatively, FalkorDB can be deployed locally via Docker, allowing immediate activation using the quickstart example:

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

pip install graphiti-core

or

uv add graphiti-core

FalkorDB Backend Installation

If FalkorDB is designated as the graph storage solution, install with the specified extra package:

pip install graphiti-core[falkordb]

# or using uv
uv add graphiti-core[falkordb]

Kuzu Backend Installation

For deployments utilizing Kuzu as the graph engine, use the Kuzu extra:

pip install graphiti-core[kuzu]

# or using uv
uv add graphiti-core[kuzu]

Amazon Neptune Backend Installation

When integrating with Amazon Neptune, include the Neptune package option:

pip install graphiti-core[neptune]

# or using uv
uv add graphiti-core[neptune]

Optional LLM Provider Add-ons

You may install supplementary LLM integration capabilities as extras:

# Add support for Anthropic models
pip install graphiti-core[anthropic]

# Add support for Groq acceleration
pip install graphiti-core[groq]

# Add support for Google Gemini services
pip install graphiti-core[google-genai]

# Install multiple providers simultaneously
pip install graphiti-core[anthropic,groq,google-genai]

# Install FalkorDB alongside Anthropic and Gemini integrations
pip install graphiti-core[falkordb,anthropic,google-genai]

# Install Neptune support
pip install graphiti-core[neptune]

Concurrency Defaults and LLM Rate Limiting (HTTP 429 Errors)

Graphiti's data ingestion pipelines are architected for high operational concurrency. By default, this concurrency level is deliberately kept low to mitigate potential HTTP 429 'Too Many Requests' errors originating from external LLM providers.

The concurrency threshold is managed via the SEMAPHORE_LIMIT environment variable. Its default setting is 10 simultaneous operations, intended as a safeguard against rate limits imposed by your LLM service. Should you observe these 429 errors, consider reducing this threshold. Conversely, if your provider supports higher request volumes, elevating SEMAPHORE_LIMIT can significantly accelerate episode ingestion throughput.

Initialization Workflow

[!IMPORTANT] Graphiti defaults to leveraging OpenAI for all LLM inference and embedding tasks. Consequently, setting the OPENAI_API_KEY environment variable is mandatory. Support for Anthropic and Groq inference APIs is also built-in.

For a complete, executable demonstration, consult the Quickstart Example located within the examples module. This example meticulously illustrates:

1. Establishing connectivity to databases (Neo4j, Amazon Neptune, FalkorDB, or Kuzu).
2. Establishing required Graphiti indices and constraints.
3. Ingesting data episodes (both raw text and structured JSON payloads).
4. Executing hybrid queries to identify relationships (edges).
5. Applying graph-distance heuristics for result refinement (reranking).
6. Performing node lookups utilizing predefined operational recipes.

The example guide provides exhaustive documentation covering setup procedures and subsequent operational steps for every demonstrated feature.

Model Context Protocol (MCP) Intermediary

The mcp_server sub-directory houses an implementation of the Model Context Protocol (MCP) server component for Graphiti. This server exposes Graphiti's knowledge graph capabilities to AI assistants through the standardized MCP interface.

Core functionalities exposed by the MCP server:

• Persistence operations for episodes (creation, retrieval, removal).
• Management routines for entities and their interconnections.
• Access to semantic and hybrid query mechanisms.
• Support for logical data segmentation via grouping features.
• Utility functions for graph integrity maintenance.

The MCP server is deployable easily via Docker, often integrated alongside a Neo4j instance, facilitating seamless embedding into your AI assistant architecture.

Refer to the MCP server README for exhaustive deployment guides and usage scenarios.

RESTful Interaction Layer

The server directory contains a dedicated API gateway built atop the FastAPI framework for interfacing with the Graphiti system.

Please consult the server README for comprehensive documentation regarding this REST service.

Optional Environment Configuration Variables

Beyond the essential credentials for Neo4j and OpenAI-compatible endpoints, Graphiti recognizes several optional environment variables. If employing alternative supported models, such as those from Anthropic or Voyage, the corresponding environment variables must be correctly populated.

Database Connectivity Customization

Database names are typically configured directly within the respective driver initialization calls:

• Neo4j: The default database name is hardcoded as neo4j (within Neo4jDriver).
• FalkorDB: The default database name is hardcoded as default_db (within FalkorDriver).

Since version v0.17.0, advanced configuration allows developers to bypass default settings by programmatically instantiating a database driver and supplying it to the main Graphiti constructor via the graph_driver argument.

Customizing Neo4j Database Selection

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

# Constructing a Neo4j driver instance specifying a non-default database
driver = Neo4jDriver(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    database="my_custom_database"  # Explicitly setting the target database
)

# Injecting the customized driver into Graphiti
graphiti = Graphiti(graph_driver=driver)

Customizing FalkorDB Database Selection

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

# Constructing a FalkorDB driver instance with a specific graph name
driver = FalkorDriver(
    host="localhost",
    port=6379,
    username="falkor_user",  # Optional authentication details
    password="falkor_password",  # Optional authentication details
    database="my_custom_graph"  # Custom graph identifier
)

# Injecting the customized driver into Graphiti
graphiti = Graphiti(graph_driver=driver)

Kuzu Configuration

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

# Kuzu driver initialization specifies the file path for the database
driver = KuzuDriver(db="/tmp/graphiti.kuzu")

# Injecting the customized driver into Graphiti
graphiti = Graphiti(graph_driver=driver)

Amazon Neptune Configuration

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

# Neptune driver setup requires endpoint specifications for both graph and search components
driver = NeptuneDriver(
    host= < NEPTUNE
ENDPOINT >,
aoss_host = < Amazon
OpenSearch
Serverless
Host >,
port = < PORT >  # Defaulting to 8182 if omitted
         aoss_port = < PORT >  # Defaulting to 443 if omitted
)

driver = NeptuneDriver(host=neptune_uri, aoss_host=aoss_host, port=neptune_port)

# Injecting the customized driver into Graphiti
graphiti = Graphiti(graph_driver=driver)

Utilizing Graphiti with Azure OpenAI Endpoints

Graphiti natively accommodates Azure OpenAI for both large language model inference and vector embedding generation. Azure setups frequently mandate distinct endpoints for the LLM services versus the embedding services, and sometimes separate deployments for standard versus specialized models.

[!IMPORTANT] Mandatory Azure OpenAI v1 API Opt-in for Structured Results

Graphiti relies on the client.beta.chat.completions.parse() function for generating structured output schemas. Azure OpenAI deployments must be configured to enable the v1 API specification. Failure to opt-in results in '404 Resource Not Found' exceptions during episode ingestion.

To activate v1 API compatibility within your Azure OpenAI deployment, refer to Microsoft's official documentation on versioning: Azure OpenAI API version lifecycle.

from openai import AsyncAzureOpenAI
from graphiti_core import Graphiti
from graphiti_core.llm_client import LLMConfig, OpenAIClient
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient

# Azure OpenAI credential matrix
api_key = "<your-api-key>"
api_version = "<your-api-version>"
llm_endpoint = "<your-llm-endpoint>"  # Example: "https://your-llm-resource.openai.azure.com/"
embedding_endpoint = "<your-embedding-endpoint>"  # Example: "https://your-embedding-resource.openai.azure.com/"

# Instantiate distinct Azure OpenAI clients for separate service responsibilities
llm_client_azure = AsyncAzureOpenAI(
    api_key=api_key,
    api_version=api_version,
    azure_endpoint=llm_endpoint
)

embedding_client_azure = AsyncAzureOpenAI(
    api_key=api_key,
    api_version=api_version,
    azure_endpoint=embedding_endpoint
)

# Define LLM configuration using your specific Azure deployment identifiers
azure_llm_config = LLMConfig(
    small_model="gpt-4.1-nano",
    model="gpt-4.1-mini",
)

# Initialize Graphiti, injecting the specific Azure clients
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=OpenAIClient(
        config=azure_llm_config,
        client=llm_client_azure
    ),
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            embedding_model="text-embedding-3-small-deployment"  # Name of your Azure embedding resource deployment
        ),
        client=embedding_client_azure
    ),
    cross_encoder=OpenAIRerankerClient(
        config=LLMConfig(
            model=azure_llm_config.small_model  # Utilize the smaller model for reranking tasks
        ),
        client=llm_client_azure
    )
)

# Graphiti is now configured to communicate with your Azure OpenAI services.

Ensure all bracketed placeholders are substituted with your actual Azure credentials and deployment names that match your Azure OpenAI service configuration.

Integrating Google Gemini Capabilities

Graphiti provides native integration for Google's Gemini family of models, covering LLM reasoning, vector generation, and cross-encoding/reranking functions. Activation requires configuring the LLM client, the embedder, and the reranker component with your Google API key.

Installation command:

uv add "graphiti-core[google-genai]"

# or

pip install "graphiti-core[google-genai]"

from graphiti_core import Graphiti
from graphiti_core.llm_client.gemini_client import GeminiClient, LLMConfig
from graphiti_core.embedder.gemini import GeminiEmbedder, GeminiEmbedderConfig
from graphiti_core.cross_encoder.gemini_reranker_client import GeminiRerankerClient

# Google API key provisioned from environment or secret store
api_key = "<your-google-api-key>"

# Initializing Graphiti with Gemini clients for all primary operations
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=GeminiClient(
        config=LLMConfig(
            api_key=api_key,
            model="gemini-2.0-flash"
        )
    ),
    embedder=GeminiEmbedder(
        config=GeminiEmbedderConfig(
            api_key=api_key,
            embedding_model="embedding-001"
        )
    ),
    cross_encoder=GeminiRerankerClient(
        config=LLMConfig(
            api_key=api_key,
            model="gemini-2.5-flash-lite-preview-06-17"
        )
    )
)

# Graphiti is now operational, routing all AI computation through Google Gemini services.

The Gemini reranker component defaults to utilizing the gemini-2.5-flash-lite-preview-06-17 model, which is fine-tuned for expense-effective, low-latency classification workloads. It employs the identical boolean assessment logic as the OpenAI reranker, leveraging Gemini's native log probability capabilities for ranking relevance scores.

Interfacing Graphiti with Ollama (Local LLMs)

Graphiti supports Ollama for local execution of both language models and embedding routines via Ollama's adherence to the OpenAI-compatible API specification. This configuration is optimal for environments prioritizing data sovereignty or minimizing external service expenditures.

Required model installation via Ollama:

ollama pull deepseek-r1:7b # For core reasoning tasks
ollama pull nomic-embed-text # For vector embedding computation

from graphiti_core import Graphiti
from graphiti_core.llm_client.config import LLMConfig
from graphiti_core.llm_client.openai_generic_client import OpenAIGenericClient
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient

# Configuration pointing to the local Ollama API gateway
llm_config = LLMConfig(
    api_key="ollama",  # A placeholder key is required by the generic client structure
    model="deepseek-r1:7b",
    small_model="deepseek-r1:7b",
    base_url="http://localhost:11434/v1",  # Standard Ollama HTTP endpoint
)

llm_client = OpenAIGenericClient(config=llm_config)

# Initializing Graphiti utilizing Ollama clients
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=llm_client,
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            api_key="ollama",  # Placeholder API key
            embedding_model="nomic-embed-text",
            embedding_dim=768,
            base_url="http://localhost:11434/v1",
        )
    ),
    cross_encoder=OpenAIRerankerClient(client=llm_client, config=llm_config),
)

# Graphiti is now leveraging local Ollama models for all requisite AI operations.

Ensure the Ollama daemon is active (ollama serve) and the specified models have been successfully downloaded prior to execution.

Comprehensive Documentation

• Official Guides and Full API Reference.
• Getting Started Tutorial
• Tutorial: Constructing an agent with LangChain's LangGraph and Graphiti

Telemetry Reporting Details

Graphiti incorporates anonymous usage data collection to inform project development priorities, ensuring the framework remains relevant and robust. Full transparency regarding collection policies is maintained below.

Data Captured

Upon instantiation of a Graphiti object, the following non-identifying metrics are gathered:

• Anonymous ID: A randomly generated Universally Unique Identifier stored locally at ~/.cache/graphiti/telemetry_anon_id
• System Context: Operating system environment, Python version, and hardware architecture metrics.
• Framework Version: The specific version number of Graphiti in use.
• Configuration Footprint:
  • Chosen LLM service provider type (e.g., OpenAI, Azure, Anthropic, Local).
  • Persistent Storage engine selected (Neo4j, FalkorDB, Kuzu, Amazon Neptune).
  • Vectorization service provider.

Data Exclusions (Privacy Pledge)

We uphold a strict commitment to user confidentiality. The following data will never be transmitted:

• Any personally identifiable details or unique user markers.
• Confidential API keys or system credentials.
• Content associated with your graph data, queries, or episodic records.
• Network identifiers (IP addresses) or host machine names.
• Local file system paths or operating system specifics beyond high-level versioning.
• Any textual content from nodes or edges.

Rationale for Collection

This aggregated, anonymous data serves to:

• Identify the most frequently used infrastructural configurations for targeted testing and support.
• Determine which database and LLM integrations warrant further development resources.
• Model adoption trends to shape the future roadmap.
• Verify ongoing compatibility across diverse operating systems and Python runtimes.

By consenting to share this anonymized telemetry, you directly contribute to enhancing Graphiti for the entire developer community.

Inspecting Telemetry Logic

The corresponding implementation code for telemetry handling can be located here.

Deactivating Telemetry Collection

Telemetry is designed to be opt-out by default and can be disabled instantly via any of the following methods.

Method 1: Environment Variable Setting

export GRAPHITI_TELEMETRY_ENABLED=false

Method 2: Shell Profile Configuration

Update your shell configuration file to persist the setting:

# For Bash users (in ~/.bashrc or ~/.bash_profile)
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.bashrc

# For Zsh users (in ~/.zshrc)
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.zshrc

Method 3: Programmatic Disablement within a Python Session

import os

os.environ['GRAPHITI_TELEMETRY_ENABLED'] = 'false'

# Initialize Graphiti after setting the environment flag
from graphiti_core import Graphiti

graphiti = Graphiti(...) # Initialization proceeds with telemetry off

Telemetry mechanisms are automatically bypassed during automated testing procedures (when the pytest utility is detected).

Technical Underpinnings

• Analytics processing is managed by the PostHog platform for anonymity.
• All telemetry operations are designed to be non-disruptive; they are engineered to fail silently without impacting Graphiti's core operational flow or performance.
• The anonymous identifier is strictly locally scoped and bears no correlation to any personal identity or system metadata.

Project Trajectory and Future Scope

Graphiti is an actively evolving project. While maintaining stability in the core API surface, ongoing development focuses on:

• [x] Advanced Custom Schema Support:
  • Enabling developers to supply bespoke node and edge class definitions during data ingestion.
  • Allowing knowledge representation to be precisely tailored to specific application domain models.
• [x] Refining Retrieval Algorithms with more granular and configurable parameters.
• [x] Deployment of the Graphiti MCP Server.
• [ ] Broadening comprehensive automated test coverage to ensure robustness against complex edge cases.

Community Engagement

We warmly welcome all contributions, encompassing source code submissions, documentation improvements, resolution of reported GitHub Issues, or assistance provided in the Graphiti Discord channel. For detailed guidelines on code contribution standards, please consult the CONTRIBUTING documentation.

Assistance Channels

Join the official Zep Discord server and navigate to the dedicated #Graphiti channel for direct communication and support!