graphiti

Installation

Requirements:

• Python 3.10 or higher
• Neo4j 5.26 / FalkorDB 1.1.2 / Amazon Neptune Database Cluster or Neptune Analytics Graph + Amazon OpenSearch Serverless collection (serves as the full text search backend) / Kuzu 0.11.2 (deprecated, see below)
• OpenAI API key (Graphiti defaults to OpenAI for LLM inference and embedding)

[!IMPORTANT] Graphiti works best with LLM services that support Structured Output (such as OpenAI, Anthropic, and Gemini). Using other services may result in incorrect output schemas and ingestion failures. This is particularly problematic when using smaller models.

Optional:

• Google Gemini, Anthropic, or Groq API key (for alternative LLM providers)

[!TIP] The simplest way to install Neo4j is via Neo4j Desktop. It provides a user-friendly interface to manage Neo4j instances and databases. Alternatively, you can use FalkorDB on-premises via Docker and instantly start with 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

You can also install optional LLM providers as extras:

---

# Install with Anthropic support
pip install graphiti-core[anthropic]

---

# Install with Groq support
pip install graphiti-core[groq]

---

# Install with Google Gemini support
pip install graphiti-core[google-genai]

---

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

---

# Install with FalkorDB and LLM providers
pip install graphiti-core[falkordb,anthropic,google-genai]

---

# Install with Amazon Neptune
pip install graphiti-core[neptune]

Quick Start

[!IMPORTANT] Graphiti defaults to using OpenAI for LLM inference and embedding. Ensure that an OPENAI_API_KEY is set in your environment. Support for Anthropic, Gemini, and Groq is available, too. Other LLM providers — both hosted OpenAI-compatible APIs (DeepSeek, Together, OpenRouter, …) and local servers (Ollama, vLLM, llama.cpp, LM Studio) — may be used via their OpenAI-compatible endpoints; see Using Graphiti with OpenAI-compatible providers and local LLMs.

For a complete working example, see the Quickstart Example in the examples directory. The quickstart demonstrates:

1. Connecting to a Neo4j, Amazon Neptune, FalkorDB, or Kuzu database
2. Initializing Graphiti indices and constraints
3. Adding episodes to the graph (both text and structured JSON)
4. Searching for relationships (edges) using hybrid search
5. Reranking search results using graph distance
6. Searching for nodes using predefined search recipes

The example is fully documented with clear explanations of each functionality and includes a comprehensive README with setup instructions and next steps.

Running with Docker Compose

You can use Docker Compose to quickly start the required services:

• Neo4j Docker:

  docker compose up
  

  This will start the Neo4j Docker service and related components.

• FalkorDB Docker:

  docker compose --profile falkordb up
  

  This will start the FalkorDB Docker service and related components.

Quick Start

from openai import AsyncOpenAI
from graphiti_core import Graphiti
from graphiti_core.llm_client.azure_openai_client import AzureOpenAILLMClient
from graphiti_core.llm_client.config import LLMConfig
from graphiti_core.embedder.azure_openai import AzureOpenAIEmbedderClient