Graphiti

Build Temporal Context Graphs for AI Agents

[!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.

⭐ Help us reach more developers and grow the Graphiti community. Star this repo!

 

[!TIP] Check out the new MCP server for Graphiti! Give Claude, Cursor, and other MCP clients powerful context graph-based memory with temporal awareness.

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 context graphs that evolve with every interaction — tracking what's true now and what was true before.
• Give agents rich, structured context instead of flat document chunks or raw chat history.
• Query across time, meaning, and relationships with hybrid retrieval (semantic + keyword + graph traversal).

 

<img src="https://github.com/getzep/graphiti/raw/v0.29.2/images/graphiti-graph-intro.gif" alt="Graphiti temporal walkthrough" width="700px">

 

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 temporal context graph engine at the core of Zep's context infrastructure for AI agents. Zep manages context graphs at scale, providing governed, low-latency context retrieval and assembly for production agent deployments.

Using Graphiti, we've demonstrated Zep is the State of the Art in Agent Memory.

Read our paper: Zep: A Temporal Knowledge Graph Architecture for Agent Memory.

We're excited to open-source Graphiti, believing its potential as a context graph engine reaches far beyond memory applications.

<a href="https://arxiv.org/abs/2501.13956"><img src="https://github.com/getzep/graphiti/raw/v0.29.2/images/arxiv-screenshot.png" alt="Zep: A Temporal Knowledge Graph Architecture for Agent Memory" width="700px"></a>

Zep vs Graphiti

Aspect	Zep	Graphiti
What they are	Managed context graph infrastructure for AI agents	Open-source temporal context graph engine
Context graphs	Manages vast numbers of per-user/entity context graphs with governance	Build and query individual context graphs
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 vs. GraphRAG

Aspect	GraphRAG	Graphiti
Primary Use	Static document summarization	Dynamic, evolving context for agents
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. 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

Installing with FalkorDB Support

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

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:

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:

pip install graphiti-core[neptune]

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

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]

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.

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:

```bash do