DEV Community

WonderLab
WonderLab

Posted on

Open Source Project of the Day (Part 28): Graphiti - Building Real-Time Knowledge Graphs for AI Agents

#ai #llm #rag #agents

Introduction

"Traditional RAG is batch-oriented and static. When data changes continuously and you need to know 'what happened at that moment,' you need a temporally-aware graph."

This is Part 28 of the "Open Source Project of the Day" series. Today we explore Graphiti (GitHub), open-sourced by getzep.

Knowledge graphs express facts as "entity-relationship-entity" triples, suitable for structured retrieval and reasoning. But most solutions are either batch-processed or have weak temporal semantics, making it difficult to support continuously-updated conversations, business data, and external information. Graphiti targets exactly these scenarios: building and querying temporally-aware knowledge graphs for AI Agents operating in dynamic environments. It supports real-time incremental writes, a dual temporal data model (event time and ingestion time), hybrid retrieval (semantic + keyword BM25 + graph traversal), and custom entities (Pydantic) — all without full graph recomputation for historical queries. It also provides an MCP service (for Claude, Cursor, etc.), a REST API (FastAPI), and supports Neo4j, FalkorDB, Kuzu, and Amazon Neptune graph backends — the core open-source component of Zep's context engineering platform.

What You'll Learn

  • Graphiti's positioning: a real-time, temporally-aware knowledge graph framework for AI Agents
  • Differences from traditional RAG and GraphRAG: incremental vs. batch, dual temporal vs. simple timestamps
  • Core capabilities: Episode writes, hybrid retrieval, custom entities, multi-backend and multi-LLM support
  • Installation, quick start, and MCP/REST integration
  • The driver architecture (11 Operations ABC) and its relationship to Zep

Prerequisites

  • Basic understanding of knowledge graphs (nodes, edges, triples)
  • Rough familiarity with the differences between RAG, vector retrieval, and graph traversal
  • Experience with Python 3.10+, pip/uv; setting up your own graph database requires one of Neo4j/FalkorDB/Kuzu/Neptune

Project Background

Project Introduction

Graphiti is a framework for building and querying temporally-aware knowledge graphs, specifically designed for AI Agents operating in dynamic environments. It continuously integrates user interactions, structured and unstructured business data, and external information into a queryable graph, supporting incremental updates and precise historical (point-in-time) queries without full graph recomputation. Unlike traditional RAG, which relies on batch processing and static summaries, Graphiti emphasizes real-time writes, dual temporal modeling, and hybrid retrieval (semantic + keyword + graph), with support for defining custom entity types via Pydantic. Its core capabilities are used by the Zep context engineering and Agent memory platform; Graphiti is provided as an open-source framework for building your own graph storage and retrieval layer.

Core problems the project solves:

  • With continuously changing data, batch RAG has high latency and difficulty reflecting "current state" and "past state"
  • Need to explicitly distinguish between "event occurrence time" and "system ingestion time" for auditing and historical queries
  • Want to combine semantic, keyword, and graph structure for retrieval, not just a single vector or single summary
  • Need pluggable graph backends (local Neo4j/FalkorDB/Kuzu or cloud Neptune) for flexible deployment based on scale and compliance

Target user groups:

  • Developers building AI Agent memory, conversation context, and multi-turn reasoning
  • RAG/knowledge base scenarios requiring "dynamic data + graph structure + temporal queries"
  • Teams who want to build their own graph layer and connect to Claude/Cursor via MCP
  • Engineers researching or implementing "graph + time + Agent" architectures

Author/Team Introduction

Project Stats

Main Features

Core Purpose

Graphiti's core purpose is to provide AI Agents with real-time, queryable, temporally-aware knowledge graph capabilities:

  1. Episode writes: Write text or structured JSON as "episodes" into the graph, automatically extracting entities and relationships — incremental, no full graph reprocessing needed
  2. Dual temporal model: Records both event occurrence time and ingestion time, supporting point-in-time and time-range historical queries
  3. Hybrid retrieval: Semantic embedding + keyword (BM25) + graph traversal, with optional graph-distance reranking, targeting sub-second latency
  4. Custom entities: Define node/edge types via Pydantic to fit domain ontologies
  5. Multiple backends: Neo4j, FalkorDB, Kuzu, Amazon Neptune (including Neptune Analytics + OpenSearch Serverless) with pluggable drivers
  6. Multiple LLMs: Default OpenAI; supports Azure OpenAI, Google Gemini, Anthropic, Groq, Ollama (local), etc. for extraction and embedding
  7. MCP and REST: MCP service for Claude/Cursor calls; REST service (FastAPI) for self-built frontends or service integration

Use Cases

  1. Agent long-term memory

    • Write conversations and actions as Episodes to the graph, retrieve by time and topic, supporting multi-turn reasoning and state recovery

  2. Dynamic business knowledge base

    • Orders, tickets, documents continuously updated — use graph + time modeling to capture "who was related to what at when," supporting auditing and historical queries

  3. Graph RAG as a replacement for batch RAG

    • When data changes frequently, use Graphiti for incremental graph building and hybrid retrieval, replacing "full rerun + pure vector" pipelines

  4. Integration with Claude/Cursor

    • Provide "graph memory" to assistants via Graphiti MCP Server: add episodes, manage entities, semantic/hybrid search, grouping and maintenance

  5. Research and reproduction

    • Reproduce "temporal knowledge graph + Agent memory" based on the paper and open-source implementation, or extend with new drivers and retrieval strategies

Quick Start

Environment: Python 3.10+; one of Neo4j 5.26 / FalkorDB 1.1.2 / Kuzu 0.11.2 / Amazon Neptune; OpenAI API key (default LLM/embedding). Recommended: models supporting Structured Output (e.g., OpenAI, Gemini) for best extraction quality.

Installation:

pip install graphiti-core
# or
uv add graphiti-core

# For FalkorDB
pip install graphiti-core[falkordb]

# For Kuzu
pip install graphiti-core[kuzu]

# For Neptune
pip install graphiti-core[neptune]

# Optional multi-LLM
pip install graphiti-core[anthropic,google-genai,groq]
Enter fullscreen mode Exit fullscreen mode

Start FalkorDB with Docker:

docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest
Enter fullscreen mode Exit fullscreen mode

Minimal example (Neo4j): After setting OPENAI_API_KEY, refer to the repo's examples/quickstart: connect to graph database → initialize indexes and constraints → add Episodes (text or JSON) → hybrid search edges/nodes → rerank by graph distance → use search recipes. See the Quick Start documentation for full steps.

MCP integration: See repo mcp_server/README, supports Episode add/delete/query, entity and relationship management, semantic/hybrid search, grouping and graph maintenance — compatible with Claude, Cursor, and other MCP clients.

Core Features

  1. Real-time incremental updates: New Episodes enter the graph immediately, no batch full recomputation needed
  2. Dual temporal data model: Event time + ingestion time, supports accurate point-in-time/range queries
  3. Hybrid retrieval: Semantic + BM25 + graph traversal, optional graph-distance reranking, low latency (sub-second target)
  4. Pluggable graph drivers: GraphDriver ABC + 11 Operations interfaces, supports Neo4j, FalkorDB, Kuzu, Neptune — build new backends yourself
  5. Custom entities: Pydantic-defined node/edge types for domain ontologies
  6. Multi-LLM/embedding: OpenAI, Azure, Gemini, Anthropic, Groq, Ollama, etc. for cloud and local deployment
  7. MCP and REST: Integration with AI assistants (Claude, Cursor) and self-built services
  8. Telemetry can be disabled: Anonymous usage statistics, disable via GRAPHITI_TELEMETRY_ENABLED=false

Graphiti vs. GraphRAG vs. Zep

Dimension Traditional GraphRAG Graphiti Zep (commercial platform)
Primary use Static document summarization Dynamic data and temporal-aware graphs Managed context and memory
Data updates Primarily batch Continuous, incremental Managed, out-of-the-box
Temporal modeling Simple timestamps Dual temporal (occurrence + ingestion) Platform built-in
Retrieval LLM summary chain dependent Semantic + BM25 + graph + rerank Pre-configured, sub-200ms
Query latency Seconds to tens of seconds Typically sub-second Sub-200ms level
Custom entities Generally not supported Supported (Pydantic) Depends on product capabilities
Deployment Self-hosted Self-hosted (multiple backends) Managed or cloud

Why choose Graphiti?

  • When you need graph + time + incremental and want to control the graph database and retrieval yourself, Graphiti provides a complete open-source implementation
  • Same origin as Zep (Zep uses Graphiti underneath) — validate self-hosted first, then consider migrating to Zep managed
  • MCP and multi-backend, multi-LLM support makes it easy to embed into existing Agents and infrastructure

Detailed Project Analysis

Data Model and Pipeline Overview

  • Episode: A single input unit (a text passage or structured JSON) — upon writing, entities and relationships are extracted via LLM, written to the graph with time-related edges (e.g., NextEpisode).
  • Entities and edges: Entity nodes, Episode nodes, Community and Saga nodes, etc.; edge types include inter-entity relationships, Episode-to-entity associations, Episode sequences, etc. Supports temporal edge invalidation to handle contradictions and changes.
  • Retrieval: Combines semantic retrieval (embeddings), keyword search (FTS/BM25), graph traversal, and communities; results can be reranked by graph distance without relying on long LLM summary chains.

Graph Driver Architecture (11 Operations)

Graphiti uses pluggable drivers to abstract away graph database differences:

  • GraphDriver: Abstract base class defining connection, session, and index/constraint lifecycle, exposing 11 Operations interfaces (accessed via @property).
  • 11 Operations: Node classes (EntityNode, EpisodeNode, CommunityNode, SagaNode), edge classes (EntityEdge, EpisodicEdge, CommunityEdge, HasEpisode, NextEpisode), search, and graph maintenance. Each backend implements these 11 interfaces; query statements are generated in the appropriate dialect by a shared query builder based on the GraphProvider enum.
  • Adding new backends: Add enum to GraphProvider → implement GraphDriver subclass and 11 Operations → add dialect for new block in node_db_queries.py / edge_db_queries.py → register optional dependency in pyproject.toml. README documents Neo4j, FalkorDB, Kuzu, and Neptune as reference implementations.

Concurrency and Rate Limiting

  • The ingestion pipeline supports high concurrency; defaults to limiting concurrency via SEMAPHORE_LIMIT (e.g., 10) to avoid LLM provider 429 errors. Can be raised to improve throughput or lowered to handle rate limits.

Documentation and Roadmap

  • Documentation: help.getzep.com/graphiti, including Quick Start and building Agents with LangGraph.
  • Roadmap: Custom graph schema, retrieval enhancement, and MCP Server are live; continuously expanding tests and stability.

Project Resources

Official Resources

Related Resources

Who Should Use This

  • Agent and memory system developers: Need temporally-aware, incrementally-updatable graph storage and retrieval
  • Advanced RAG/knowledge base users: Upgrading from pure vector or batch GraphRAG to dynamic graphs + hybrid retrieval
  • Graph database users: Already using Neo4j/FalkorDB/Kuzu/Neptune, want to integrate LLM extraction and semantic retrieval
  • Claude/Cursor integration: Providing "graph memory" and retrieval capabilities to assistants via MCP

Welcome to visit my personal homepage for more useful knowledge and interesting products

Top comments (0)