Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/getzep/graphiti

Build Real-Time Knowledge Graphs for AI Agents
https://github.com/getzep/graphiti

agents graph llms rag

Last synced: 1 day ago
JSON representation

Build Real-Time Knowledge Graphs for AI Agents

Awesome Lists containing this project

README 

          


  

    Zep Logo

  






Graphiti



A Framework for Building Temporal Knowledge Graphs






[![Lint](https://github.com/getzep/Graphiti/actions/workflows/lint.yml/badge.svg?style=flat)](https://github.com/getzep/Graphiti/actions/workflows/lint.yml)

[![Unit Tests](https://github.com/getzep/Graphiti/actions/workflows/unit_tests.yml/badge.svg)](https://github.com/getzep/Graphiti/actions/workflows/unit_tests.yml)

[![MyPy Check](https://github.com/getzep/Graphiti/actions/workflows/typecheck.yml/badge.svg)](https://github.com/getzep/Graphiti/actions/workflows/typecheck.yml)



[![GitHub Repo stars](https://img.shields.io/github/stars/getzep/graphiti)](https://github.com/getzep/graphiti/stargazers)

[![arXiv](https://img.shields.io/badge/arXiv-2501.13956-b31b1b.svg?style=flat)](https://arxiv.org/abs/2501.13956)

[![Release](https://img.shields.io/github/v/release/getzep/graphiti?style=flat&label=Release&color=limegreen)](https://github.com/getzep/graphiti/releases)








getzep%2Fgraphiti | Trendshift






> [!NOTE]

> **We're Hiring!** Build context graphs that power reliable, personalized, fast production AI agents.

> Come build with us โ€” we're hiring Engineers and Developer Relations folks. [View open roles](https://www.getzep.com/careers/).



โญ *Help us reach more developers and grow the Graphiti community. Star this repo!*



ย 



Graphiti is a framework for building and querying temporal context graphs for AI agents. Unlike static knowledge graphs,

Graphiti's context graphs track how facts change over time, maintain provenance to source data, and support both

prescribed and learned ontology โ€” making them purpose-built for agents operating on evolving, real-world data.



Unlike traditional retrieval-augmented generation (RAG) methods, Graphiti continuously integrates user interactions,

structured and unstructured enterprise data, and external information into a coherent, queryable graph. The framework

supports incremental data updates, efficient retrieval, and precise historical queries without requiring complete graph

recomputation, making it suitable for developing interactive, context-aware AI applications.



Use Graphiti to:



- Build temporal knowledge graphs that evolve with every interaction โ€” tracking what's true now and what was true before.

- Represent rich, structured context instead of flat document chunks or raw event streams.

- Query across time, meaning, and relationships with hybrid retrieval (semantic + keyword + graph traversal).



ย 





    Graphiti temporal walkthrough




ย 



## What is a Context Graph?



A **context graph** is a temporal graph of entities, relationships, and facts โ€” like *"Kendra loves Adidas shoes (as of

March 2026)."* Unlike traditional knowledge graphs, each fact in a context graph has a validity window: when it became

true, and when (if ever) it was superseded. Entities evolve over time with updated summaries. Everything traces back to

**episodes** โ€” the raw data that produced it.



What makes Graphiti unique is its ability to autonomously build context graphs from unstructured and structured data,

handling changing relationships while preserving full temporal history.



A context graph contains:



| Component | What it stores |

|-----------|---------------|

| **Entities** (nodes) | People, products, policies, concepts โ€” with summaries that evolve over time |

| **Facts / Relationships** (edges) | Triplets (Entity โ†’ Relationship โ†’ Entity) with temporal validity windows |

| **Episodes** (provenance) | Raw data as ingested โ€” the ground truth stream. Every derived fact traces back here |

| **Custom Types** (ontology) | Developer-defined entity and edge types via Pydantic models |



## Graphiti and Zep



Graphiti is the open-source framework for building temporal knowledge graphs at the core of

[Zep's](https://www.getzep.com) context infrastructure. Zep manages context graphs at scale, providing

governed, low-latency context retrieval and assembly for production deployments.



Under the hood, Zep is powered by a proprietary graph database โ€” the

[Context Graph Engine](https://www.getzep.com/platform/context-graph-engine/) โ€” built for millions of context graphs

with low-latency retrieval, so production deployments don't require a separate third-party graph database.



Read our paper: [Zep: A Temporal Knowledge Graph Architecture](https://arxiv.org/abs/2501.13956).





    Zep: A Temporal Knowledge Graph Architecture




## Zep vs Graphiti



| Aspect | Zep | Graphiti |

|--------|-----|---------|

| **What they are** | Managed context graph infrastructure | Open-source framework for building temporal knowledge graphs |

| **Context graphs** | Manages vast numbers of per-user/entity context graphs with governance | Build and query individual context graphs |

| **Graph database** | Proprietary [Context Graph Engine](https://www.getzep.com/platform/context-graph-engine/) โ€” built for millions of context graphs with low-latency retrieval; no third-party graph database vendor required | Bring your own third-party graph database |

| **User & conversation management** | Built-in users, threads, and message storage | Build your own |

| **Retrieval & performance** | Pre-configured, production-ready retrieval with sub-200ms performance at scale | Custom implementation required; performance depends on your setup |

| **Developer tools** | Dashboard with graph visualization, debug logs, API logs; SDKs for Python, TypeScript, and Go | Build your own tools |

| **Enterprise features** | SLAs, support, security guarantees | Self-managed |

| **Deployment** | Fully managed or in your cloud | Self-hosted only |



### When to choose which



**Choose Zep** if you want a turnkey, enterprise-grade platform with security, performance, and support baked in.



**Choose Graphiti** if you want a flexible OSS core and you're comfortable building/operating the surrounding system.



## Why Graphiti?



Traditional RAG approaches often rely on batch processing and static data summarization, making them inefficient for

frequently changing data. Graphiti addresses these challenges by providing:



- **Temporal Fact Management:** Facts have validity windows. When information changes, old facts are

  invalidated โ€” not deleted. Query what's true now, or what was true at any point in time.

- **Episodes & Provenance:** Every entity and relationship traces back to the episodes (raw data) that produced it.

  Full lineage from derived fact to source.

- **Prescribed & Learned Ontology:** Define entity and edge types upfront via Pydantic models (prescribed), or let

  structure emerge from your data (learned). Start simple, evolve as patterns appear.

- **Incremental Graph Construction:** New data integrates immediately without batch recomputation. The graph evolves

  in real-time as episodes are ingested.

- **Hybrid Retrieval:** Combines semantic embeddings, keyword (BM25), and graph traversal for low-latency,

  high-precision queries without reliance on LLM summarization.

- **Scalability:** Efficiently manages large datasets with parallel processing, pluggable graph backends, suitable

  for enterprise workloads.





    Graphiti structured + unstructured demo




## Graphiti vs. GraphRAG



| Aspect | GraphRAG | Graphiti |

|--------|----------|---------|

| **Primary Use** | Static document summarization | Dynamic, evolving temporal knowledge graphs |

| **Data Handling** | Batch-oriented processing | Continuous, incremental updates |

| **Knowledge Structure** | Entity clusters & community summaries | Temporal context graph โ€” entities, facts with validity windows, episodes, communities |

| **Retrieval Method** | Sequential LLM summarization | Hybrid semantic, keyword, and graph-based search |

| **Adaptability** | Low | High |

| **Temporal Handling** | Basic timestamp tracking | Explicit bi-temporal tracking with automatic fact invalidation |

| **Contradiction Handling** | LLM-driven summarization judgments | Automatic fact invalidation with temporal history preserved |

| **Query Latency** | Seconds to tens of seconds | Typically sub-second latency |

| **Custom Entity Types** | No | Yes, customizable via Pydantic models |

| **Scalability** | Moderate | High, optimized for large datasets |



Graphiti is specifically designed to address the challenges of dynamic and frequently updated datasets, making it

particularly suitable for applications requiring real-time interaction and precise historical queries.



## 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](https://neo4j.com/download/). 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

> ```



```bash

pip install graphiti-core

```



or



```bash

uv add graphiti-core

```



### Installing with FalkorDB Support



If you plan to use FalkorDB as your graph database backend, install with the FalkorDB extra:



```bash

pip install graphiti-core[falkordb]



# or with uv

uv add graphiti-core[falkordb]



# or embedded version (requires Python 3.12+)

pip install graphiti-core[falkordblite]

# or with uv

uv add graphiti-core[falkordblite]

```



### Installing with Kuzu Support



> [!WARNING]

> **Kuzu is deprecated** and will be removed in a future release โ€” the upstream Kuzu project is no longer

> maintained. New projects should use Neo4j or FalkorDB. The driver still ships for now but emits a

> `DeprecationWarning`.



If you plan to use Kuzu as your graph database backend, install with the Kuzu extra:



```bash

pip install graphiti-core[kuzu]



# or with uv

uv add graphiti-core[kuzu]

```



### Installing with Amazon Neptune Support



If you plan to use Amazon Neptune as your graph database backend, install with the Amazon Neptune extra:



```bash

pip install graphiti-core[neptune]



# or with uv

uv add graphiti-core[neptune]

```



### You can also install optional LLM providers as extras:



```bash

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

```



## Default to Low Concurrency; LLM Provider 429 Rate Limit Errors



Graphiti's ingestion pipelines are designed for high concurrency. By default, concurrency is set low to avoid LLM

Provider 429 Rate Limit Errors. If you find Graphiti slow, please increase concurrency as described below.



Concurrency controlled by the `SEMAPHORE_LIMIT` environment variable. By default, `SEMAPHORE_LIMIT` is set to `10`

concurrent operations to help prevent `429` rate limit errors from your LLM provider. If you encounter such errors, try

lowering this value.



If your LLM provider allows higher throughput, you can increase `SEMAPHORE_LIMIT` to boost episode ingestion

performance.



## 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](#using-graphiti-with-openai-compatible-providers-and-local-llms).



For a complete working example, see the [Quickstart Example](examples/quickstart/README.md) 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:**



  ```bash

  docker compose up

  ```



  This will start the Neo4j Docker service and related components.



- **FalkorDB Docker:**



  ```bash

  docker compose --profile falkordb up

  ```



  This will start the FalkorDB Docker service and related components.



## MCP Server



The `mcp_server` directory contains a Model Context Protocol (MCP) server implementation for Graphiti. This server

allows AI assistants to interact with Graphiti's context graph capabilities through the MCP protocol.



Key features of the MCP server include:



- Episode management (add, retrieve, delete)

- Entity management and relationship handling

- Semantic and hybrid search capabilities

- Group management for organizing related data

- Graph maintenance operations



The MCP server can be deployed using Docker with Neo4j, making it easy to integrate Graphiti into your AI assistant

workflows.



For detailed setup instructions and usage examples, see the [MCP server README](mcp_server/README.md).



## REST Service



The `server` directory contains an API service for interacting with the Graphiti API. It is built using FastAPI.



Please see the [server README](server/README.md) for more information.



## Optional Environment Variables



In addition to the Neo4j and OpenAi-compatible credentials, Graphiti also has a few optional environment variables.

If you are using one of our supported models, such as Anthropic or Voyage models, the necessary environment variables

must be set.



### Database Configuration



Database names are configured directly in the driver constructors:



- **Neo4j**: Database name defaults to `neo4j` (hardcoded in Neo4jDriver)

- **FalkorDB**: Database name defaults to `default_db` (hardcoded in FalkorDriver)



As of v0.17.0, if you need to customize your database configuration, you can instantiate a database driver and pass it

to the Graphiti constructor using the `graph_driver` parameter.



#### Neo4j with Custom Database Name



```python

from graphiti_core import Graphiti

from graphiti_core.driver.neo4j_driver import Neo4jDriver



# Create a Neo4j driver with custom database name

driver = Neo4jDriver(

    uri="bolt://localhost:7687",

    user="neo4j",

    password="password",

    database="my_custom_database"  # Custom database name

)



# Pass the driver to Graphiti

graphiti = Graphiti(graph_driver=driver)

```



#### FalkorDB with Custom Database Name



```python

from graphiti_core import Graphiti

from graphiti_core.driver.falkordb_driver import FalkorDriver



# Create a FalkorDB driver with custom database name

driver = FalkorDriver(

    host="localhost",

    port=6379,

    username="falkor_user",  # Optional

    password="falkor_password",  # Optional

    database="my_custom_graph"  # Custom database name

)



# Or use embedded FalkorDB Lite (requires Python 3.12+)

# from redislite.async_falkordb_client import AsyncFalkorDB

# falkordb_client = AsyncFalkorDB(dbfilename='/path/to/database.db')

# driver = FalkorDriver(falkor_db=falkordb_client)



# Pass the driver to Graphiti

graphiti = Graphiti(graph_driver=driver)

```



#### Kuzu



> [!WARNING]

> Kuzu is **deprecated** (upstream project unmaintained) and will be removed in a future release. Prefer Neo4j or

> FalkorDB.



```python

from graphiti_core import Graphiti

from graphiti_core.driver.kuzu_driver import KuzuDriver



# Create a Kuzu driver

driver = KuzuDriver(db="/tmp/graphiti.kuzu")



# Pass the driver to Graphiti

graphiti = Graphiti(graph_driver=driver)

```



#### Amazon Neptune



```python

from graphiti_core import Graphiti

from graphiti_core.driver.neptune_driver import NeptuneDriver



# Create a Neptune driver

driver = NeptuneDriver(

    host='',

    aoss_host='',

    port=8182,      # Optional, defaults to 8182

    aoss_port=443,  # Optional, defaults to 443

)



# Pass the driver to Graphiti

graphiti = Graphiti(graph_driver=driver)

```



Contributing a new graph backend? See [Adding a graph driver](CONTRIBUTING.md#adding-a-graph-driver).



## Using Graphiti with Azure OpenAI



Graphiti supports Azure OpenAI for both LLM inference and embeddings using Azure's OpenAI v1 API compatibility layer.



### Quick Start



```python

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



# Initialize Azure OpenAI client using the standard OpenAI client

# with Azure's v1 API endpoint

azure_client = AsyncOpenAI(

    base_url="https://your-resource-name.openai.azure.com/openai/v1/",

    api_key="your-api-key",

)



# Create LLM and Embedder clients

llm_client = AzureOpenAILLMClient(

    azure_client=azure_client,

    config=LLMConfig(model="gpt-5-mini", small_model="gpt-5-mini")  # Your Azure deployment name

)

embedder_client = AzureOpenAIEmbedderClient(

    azure_client=azure_client,

    model="text-embedding-3-small"  # Your Azure embedding deployment name

)



# Initialize Graphiti with Azure OpenAI clients

graphiti = Graphiti(

    "bolt://localhost:7687",

    "neo4j",

    "password",

    llm_client=llm_client,

    embedder=embedder_client,

)



# Now you can use Graphiti with Azure OpenAI

```



**Key Points:**



- Use the standard `AsyncOpenAI` client with Azure's v1 API endpoint format:

  `https://your-resource-name.openai.azure.com/openai/v1/`

- The deployment names (e.g., `gpt-5-mini`, `text-embedding-3-small`) should match your Azure OpenAI deployment names

- See `examples/azure-openai/` for a complete working example



Make sure to replace the placeholder values with your actual Azure OpenAI credentials and deployment names.



## Using Graphiti with Google Gemini



Graphiti supports Google's Gemini models for LLM inference, embeddings, and cross-encoding/reranking. To use Gemini,

you'll need to configure the LLM client, embedder, and the cross-encoder with your Google API key.



Install Graphiti:



```bash

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



# or



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

```



```python

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 configuration

api_key = ""



# Initialize Graphiti with Gemini clients

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"

        )

    )

)



# Now you can use Graphiti with Google Gemini for all components

```



The Gemini reranker uses the `gemini-2.5-flash-lite` model by default, which is optimized for

cost-effective and low-latency classification tasks. It uses the same boolean classification approach as the OpenAI

reranker, leveraging Gemini's log probabilities feature to rank passage relevance.



## Using Graphiti with OpenAI-compatible providers and local LLMs



Graphiti can use any OpenAI-compatible `/v1` endpoint for LLM inference via `OpenAIGenericClient` โ€” both **hosted

providers** (DeepSeek, Together, OpenRouter, Fireworks, etc.) and **local servers** (Ollama, vLLM, llama.cpp, LM

Studio). Local servers are ideal for privacy-focused applications or avoiding API costs. The example below uses Ollama;

for any other provider, point `base_url` at its endpoint and set the appropriate `api_key` and `model`.



**Note:** Use `OpenAIGenericClient` (not `OpenAIClient`) for these endpoints. It is optimized for local models with a

higher default max token limit (16K vs 8K) and handles structured outputs across compatible providers.



Install the models:



```bash

ollama pull deepseek-r1:7b # LLM

ollama pull nomic-embed-text # embeddings

```



```python

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



# Configure Ollama LLM client

llm_config = LLMConfig(

    api_key="ollama",  # Ollama doesn't require a real API key, but some placeholder is needed

    model="deepseek-r1:7b",

    small_model="deepseek-r1:7b",

    base_url="http://localhost:11434/v1",  # Ollama's OpenAI-compatible endpoint

)



llm_client = OpenAIGenericClient(config=llm_config)



# Initialize Graphiti with 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),

)



# Now you can use Graphiti with local Ollama models

```



Ensure Ollama is running (`ollama serve`) and that you have pulled the models you want to use.



### Structured output and small models



Graphiti depends on structured (JSON) output for entity/edge extraction and deduplication, and works best with models

and providers that reliably honor it (OpenAI, Anthropic, Gemini). Reliability varies across OpenAI-compatible providers and

especially on smaller or local models, so `OpenAIGenericClient` exposes a `structured_output_mode`:



- `"json_schema"` (default): requests native structured output via `response_format`. Best on capable models and

  providers that enforce the schema via constrained decoding.

- `"json_object"`: requests plain-JSON mode and injects the schema into the prompt instead. Use this for

  providers/models that don't reliably honor `json_schema` โ€” including some local servers that accept the `json_schema`

  request but don't actually constrain output to it, where `json_object` can be *more* reliable.



When using smaller or local models:



- Prefer the most capable model you can run. Very small models frequently emit JSON that doesn't match the requested

  schema, which surfaces as extraction failures.

- Responses wrapped in Markdown ` ```json ` code fences are stripped automatically.

- Keep `SEMAPHORE_LIMIT` low (see [above](#default-to-low-concurrency-llm-provider-429-rate-limit-errors)) โ€” local

  servers and some providers have limited concurrency.



## Configurable Prompts



Graphiti lets you override LLM prompt builders per client instance. Override callables must return

``ChatPrompt`` (system + user). Response schemas are fixed and not overridable:



```python

from graphiti_core import Graphiti

from graphiti_core.prompts import ChatPrompt, SystemMessage, UserMessage, create_prompt_library



def custom_extract_message(context: dict) -> ChatPrompt:

    return ChatPrompt(

        system=SystemMessage(content='Extract entities for my domain.'),

        user=UserMessage(content=str(context.get('episode_content', ''))),

    )



prompt_library = create_prompt_library({

    'extract_nodes': {

        'extract_message': custom_extract_message,

    },

})



graphiti = Graphiti(..., prompt_library=prompt_library)

```



Unspecified prompts keep the built-in defaults. Returning ``list[Message]`` from an override raises

``TypeError`` โ€” migrate with ``return ChatPrompt(system=..., user=...)``. Unicode handling is applied

via ``ChatPrompt.as_messages()``.



The package-level ``prompt_library`` keeps the existing ``list[Message]`` API.

The opt-in prompt customization API uses ``ChatPromptLibrary`` and

``DefaultChatPromptLibrary``.



For per-prompt routing across providers, pass an opt-in ``llm_runtime``. Create

one ``LLMTransport`` for each provider client. Each ``LLMModel`` binds a provider

model ID to one transport. An unrouted prompt uses the default model.

``llm_runtime`` cannot be combined with ``llm_client`` or ``prompt_library``.

Response schemas stay fixed. You can configure prompt text and model routes:



```python

from typing import Literal



from graphiti_core import Graphiti

from graphiti_core.llm_client.anthropic_client import AnthropicClient

from graphiti_core.llm_client import (

    LLMRuntime,

    LLMTransport,

    OpenAIClient,

    PromptRoutes,

)



OpenAIModels = Literal['gpt-5.1', 'gpt-5-nano']

openai = LLMTransport[OpenAIModels](

    OpenAIClient(),

    models=['gpt-5.1', 'gpt-5-nano'],

)



AnthropicModels = Literal['claude-sonnet-4-5', 'claude-haiku-4-5']

anthropic = LLMTransport[AnthropicModels](

    AnthropicClient(),

    models=['claude-sonnet-4-5', 'claude-haiku-4-5'],

)



main = openai.model('gpt-5.1')

nano = openai.model('gpt-5-nano')

haiku = anthropic.model('claude-haiku-4-5')

runtime = LLMRuntime(

    model=main,

    routes=PromptRoutes(

        extract_nodes=PromptRoutes.ExtractNodes(extract_attributes=nano),

        dedupe_edges=PromptRoutes.DedupeEdges(

            resolve_edge=haiku,

        ),

    ),

)



graphiti = Graphiti(..., llm_runtime=runtime)

```



``LLMModel`` does not have a ``small_id`` field. The runtime passes

``model_size`` for legacy compatibility, but this value does not select a

smaller model. The selected model ID controls provider calls. A routed prompt

uses that model ID. An unrouted prompt uses the default model ID. Route prompts

that need a smaller model to that model explicitly. Legacy calls without

``llm_runtime`` retain ``LLMConfig.small_model`` behavior.



GLiNER2 binds model objects at initialization. It does not support per-prompt

model routing. See ``spec/llm-runtime.md`` for the runtime API.



### Jev dedupe



JevClient routes node dedupe and edge resolution to TypeSafe Jev. Set

``JEV_API_KEY`` before you create the client. The duplicate threshold defaults

to 0.7. The contradiction threshold defaults to 0.8.



Jev is a decision model. It answers typed questions with probabilities. It

does not generate text. Use a general LLM as the default model. Route only

``dedupe_nodes.nodes`` and ``dedupe_edges.resolve_edge`` to Jev. Do not use Jev

for extraction, summaries, or other generation tasks.



TypeSafe hosts the Jev API. Graphiti sends dedupe prompt content to TypeSafe.

See the [FalkorDB Jev dedupe example](examples/jev/) for a runnable example.



```python

from graphiti_core import Graphiti

from graphiti_core.llm_client import (

    JevClient,

    LLMRuntime,

    LLMTransport,

    OpenAIClient,

    PromptRoutes,

    jev_prompt_overrides,

)



openai = LLMTransport(OpenAIClient(), models=['gpt-6-luna'])

jev = LLMTransport(JevClient(), models=['jev-latest'])

jev_dedupe = jev.model('jev-latest', prompt_overrides=jev_prompt_overrides())



runtime = LLMRuntime(

    model=openai.model('gpt-6-luna'),

    routes=PromptRoutes(

        dedupe_nodes=PromptRoutes.DedupeNodes(nodes=jev_dedupe),

        dedupe_edges=PromptRoutes.DedupeEdges(resolve_edge=jev_dedupe),

    ),

)

graphiti = Graphiti(..., llm_runtime=runtime)

```



### OpenAI Decisions dedupe



``OpenAIDecisionsClient`` routes node dedupe and edge resolution to the OpenAI

Decisions API. Use a general LLM as the default model. A decision model

answers typed questions with probabilities and does not generate text. Do not

use it for extraction, summaries, or other generation tasks.



See the [OpenAI Decisions FalkorDB example](examples/openai_decisions/) for a

runnable example.



## Documentation



- [Guides and API documentation](https://help.getzep.com/graphiti).

- [Quick Start](https://help.getzep.com/graphiti/graphiti/quick-start)

- [Building an agent with LangChain's LangGraph and Graphiti](https://help.getzep.com/graphiti/integrations/lang-graph-agent)



## Telemetry



Graphiti collects anonymous usage statistics to help us understand how the framework is being used and improve it for

everyone. We believe transparency is important, so here's exactly what we collect and why.



### What We Collect



When you initialize a Graphiti instance, we collect:



- **Anonymous identifier**: A randomly generated UUID stored locally in `~/.cache/graphiti/telemetry_anon_id`

- **System information**: Operating system, Python version, and system architecture

- **Graphiti version**: The version you're using

- **Configuration choices**:

  - LLM provider type (OpenAI, Azure, Anthropic, etc.)

  - Database backend (Neo4j, FalkorDB, Kuzu, Amazon Neptune Database or Neptune Analytics)

  - Embedder provider (OpenAI, Azure, Voyage, etc.)



### What We Don't Collect



We are committed to protecting your privacy. We **never** collect:



- Personal information or identifiers

- API keys or credentials

- Your actual data, queries, or graph content

- IP addresses or hostnames

- File paths or system-specific information

- Any content from your episodes, nodes, or edges



### Why We Collect This Data



This information helps us:



- Understand which configurations are most popular to prioritize support and testing

- Identify which LLM and database providers to focus development efforts on

- Track adoption patterns to guide our roadmap

- Ensure compatibility across different Python versions and operating systems



By sharing this anonymous information, you help us make Graphiti better for everyone in the community.



### View the Telemetry Code



The Telemetry code [may be found here](graphiti_core/telemetry/telemetry.py).



### How to Disable Telemetry



Telemetry is **opt-out** and can be disabled at any time. To disable telemetry collection:



**Option 1: Environment Variable**



```bash

export GRAPHITI_TELEMETRY_ENABLED=false

```



**Option 2: Set in your shell profile**



```bash

# For bash users (~/.bashrc or ~/.bash_profile)

echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.bashrc



# For zsh users (~/.zshrc)

echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.zshrc

```



**Option 3: Set for a specific Python session**



```python

import os



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



# Then initialize Graphiti as usual

from graphiti_core import Graphiti



graphiti = Graphiti(...)

```



Telemetry is automatically disabled during test runs (when `pytest` is detected).



### Technical Details



- Telemetry uses PostHog for anonymous analytics collection

- All telemetry operations are designed to fail silently - they will never interrupt your application or affect Graphiti

  functionality

- The anonymous ID is stored locally and is not tied to any personal information



## Contributing



We encourage and appreciate all forms of contributions, whether it's code, documentation, addressing GitHub Issues, or

helping others on GitHub. For detailed guidelines on code contributions, please refer

to [CONTRIBUTING](CONTRIBUTING.md).



## Support



Open a [GitHub issue](https://github.com/getzep/graphiti/issues) to ask questions, report bugs, or discuss Graphiti.