getzep/graphiti

Graphiti is a Python library and service ecosystem designed to build and manage graph-based AI applications by ingesting unstructured data into knowledge graphs. It provides a modular core for entity and relationship extraction, supporting multiple LLM providers and embedding services to populate graph databases like Neo4j, FalkorDB, and Amazon Neptune. The system exposes this functionality through a FastAPI REST service and an MCP server, enabling external agents to retrieve and interact with structured knowledge.

23 changes.

This period established the foundational Graphiti Core library, introducing a modular architecture for LLM clients, embedders, and search with support for multiple graph database backends. It also launched the initial FastAPI-based graph service and a suite of example applications to demonstrate ingestion and retrieval workflows. Comprehensive test coverage and security hardening were implemented to validate the new core components and API endpoints.

15 changes.

This period focused on the initial release of the Graphiti MCP Server, establishing a modular architecture with multi-provider LLM and embedder support alongside comprehensive Docker deployment options. Significant work was dedicated to integrating FalkorDB as a primary graph database driver, expanding the system's backend capabilities beyond Neo4j. The release was accompanied by extensive test coverage for drivers, embedders, and the server itself, along with diverse quickstart examples for various database and AI provider combinations.

This location introduces a new example demonstrating a hybrid entity extraction approach using the GLiNER2 model. The example configures a \GLiNER2Client\ to handle local, CPU-based Named Entity Recognition (NER) for custom entity types (Person, Organization, Location, Initiative), while delegating edge extraction, deduplication, and summarization to a general-purpose LLM (Google Gemini). It includes the necessary setup files (\.env.example\, \README.md\) and the main script (\gliner2\_neo4j.py\) to run this hybrid workflow against a Neo4j graph.

examples/gliner2 · high confidence

The node persistence layer now generates provider-specific Cypher queries to support Amazon Neptune, Kuzu, and FalkorDB alongside Neo4j. This ensures correct handling of provider-specific features, such as Neptune's string-based list serialization for entity edges and Kuzu's explicit property assignment, allowing the system to save and retrieve episodic and entity nodes correctly across these different graph database backends.

_graphiti\core/models/nodes · high confidence

The system now supports FalkorDB as a graph database provider alongside Neo4j. This change introduces a new driver implementation in the \graphiti\_core/driver\ module, including a base \GraphDriver\ architecture, FalkorDB-specific fulltext query construction with sanitization and stopword filtering, and a complete set of graph operations (entity, episode, community, and saga nodes/edges) tailored for FalkorDB's RediSearch capabilities. Users can now configure FalkorDB as their backend, benefiting from its multi-tenant graph isolation where reads are automatically routed to the correct group-specific graph namespace.

_graphiti\core/driver · high confidence

This change introduces the core data models for the new graph service, defining the structure for ingesting and retrieving knowledge graph data. Users can now send messages and entity nodes via \AddMessagesRequest\ and \AddEntityNodeRequest\, and retrieve facts using \SearchQuery\ and \GetMemoryRequest\. The \FactResult\ model structures the returned facts, including source and target node UUIDs and associated episodes, while \Message\ handles content, roles, and timestamps.

_server/graph\service/dto · high confidence

This change introduces the Graphiti Core package, providing the foundational classes and utilities for building graph-based AI applications. It includes the main Graphiti client for managing episodes, nodes, and edges, along with support for multiple graph database backends (Neo4j, FalkorDB, Kuzu, and Neptune) via a unified driver interface. The library also features built-in telemetry via PostHog, distributed tracing through OpenTelemetry, and robust error handling with specific validation for group IDs and entity types.

_graphiti\core · high confidence

The Graphiti MCP Server is now available as a standalone component, providing a Model Context Protocol interface for interacting with Graphiti's knowledge graph. This release introduces a complete setup environment, including a \.env.example\ file that documents configuration for Neo4j and FalkorDB databases, OpenAI and Azure OpenAI LLM providers, and concurrency controls. A detailed \README.md\ guides users through installation via \uv\ or Docker Compose, explaining supported transports (HTTP and stdio), database backends, and LLM integrations. The server entry point (\main.py\) is established to launch the MCP service, and the dependency lockfile (\uv.lock\) ensures reproducible builds with Python 3.10+.

_mcp\server · high confidence

This change introduces the core API endpoints for the new graph service, enabling users to ingest data and retrieve knowledge. The ingest router provides endpoints to add messages (queued for async processing), add entity nodes, delete specific entity edges, episodes, or entire groups, and clear all graph data. The retrieve router exposes search capabilities (supporting group filtering), retrieval of specific entity edges and episodes, and a memory lookup feature that composes queries from message history. These endpoints form the foundation of the service's interaction with the underlying graph database.

_server/graph\service/routers · high confidence

The repository has been initialized with foundational project files, including a \.gitignore\ for Python artifacts, a \Dockerfile\ for the FastAPI server, and a \Makefile\ for build and test automation. Comprehensive documentation has been added, including \README.md\ (project overview, installation, and Zep comparison), \CONTRIBUTING.md\ (guidelines and RFC requirements), \AGENTS.md\ and \CLAUDE.md\ (AI agent and development instructions), \OTEL\_TRACING.md\ (OpenTelemetry setup), and \SECURITY.md\ (vulnerability reporting). The project is licensed under Apache 2.0 and includes a \CODE\_OF\_CONDUCT.md\.

(repo-wide) · high confidence

A new graph service has been added, providing a FastAPI-based API for ingesting and retrieving graph data. The service supports configurable database backends (Neo4j or FalkorDB) via environment settings and integrates with OpenAI for LLM and embedding model configuration. It includes a healthcheck endpoint, lifespan management for client initialization, and specific logic for handling entity nodes, edges, and group deletion within the ZepGraphiti implementation.

_server/graph\service · high confidence

The embedder module has been restructured around a new \EmbedderClient\ abstract base class, allowing users to swap embedding providers without changing core logic. This change adds dedicated implementations for OpenAI (\OpenAIEmbedder\), Azure OpenAI (\AzureOpenAIEmbedderClient\), Google Gemini (\GeminiEmbedder\), and VoyageAI (\VoyageAIEmbedder\), each exposing \create\ and \create\_batch\ methods for generating vector embeddings. Users can now configure specific models, API keys, and batch sizes per provider via dedicated configuration classes (e.g., \OpenAIEmbedderConfig\, \GeminiEmbedderConfig\), enabling flexible integration with different embedding services.

_graphiti\core/embedder · high confidence

The MCP server has been restructured into a modular codebase under \mcp\_server/src\, introducing a unified configuration system via \config/schema.py\ that supports YAML files with environment variable expansion. This change enables multi-provider support for LLMs (OpenAI, Azure OpenAI, Anthropic, Gemini, Groq) and embedders (OpenAI, Azure OpenAI, Gemini, Voyage), allowing users to configure different providers for different tasks. The server now includes factory classes for creating clients, defined entity and edge types for custom knowledge graph structures, and a queue service for managing episode processing. Users benefit from improved configuration flexibility, support for OpenAI-compatible providers like Ollama, and better control over structured output modes.

_mcp\server/src · high confidence

The search module now exposes a dedicated configuration system that allows users to define search scopes (edges, nodes, episodes, communities) and select specific search methods (BM25, cosine similarity, BFS) and rerankers (RRF, MMR, cross-encoder, node distance, episode mentions) for each scope. This change introduces \SearchConfig\ and \SearchFilters\ classes, enabling precise control over query behavior, including date-based and property-based filtering, as well as providing pre-built 'recipes' for common hybrid search patterns.

_graphiti\core/search · high confidence

Added a new example demonstrating how to use Graphiti with Azure OpenAI and Neo4j to build a knowledge graph. This includes configuration files for Azure OpenAI endpoints and deployments, as well as a Python script that initializes the Graphiti client with Azure-specific LLM and embedder clients, ingests text and JSON episodes, and performs hybrid and center-node searches.

examples/azure-openai · high confidence

The \mcp\_server/docker\ directory now provides complete Docker support for deploying the Graphiti MCP Server. A new combined image (\Dockerfile\) bundles the MCP server with the FalkorDB graph database and its web UI in a single container, simplifying local development and deployment. A standalone image (\Dockerfile.standalone\) is also introduced for users who prefer to connect to an external database (Neo4j or FalkorDB). Both images include Socket Firewall enforcement for secure dependency fetching, support optional provider extras (including Azure), and are accompanied by Docker Compose configurations (\docker-compose.yml\, \docker-compose-falkordb.yml\, \docker-compose-neo4j.yml\) and build scripts to streamline the setup process.

_mcp\server/docker · high confidence

Added a new runnable example in the \examples/ecommerce\ directory that demonstrates how to use the Graphiti library to ingest product data and conversation history into a Neo4j knowledge graph. The example includes both a Python script (\runner.py\) and a Jupyter notebook (\runner.ipynb\) that load product information from a JSON file and simulate a customer service conversation, illustrating the core workflow of adding episodes and building indices.

examples/ecommerce · high confidence

The examples/quickstart directory now includes dedicated Python scripts and documentation for running Graphiti with three supported graph databases. Users can now run quickstart\_neo4j.py to connect to a local Neo4j instance, quickstart\_falkordb.py to connect to a FalkorDB server, or quickstart\_neptune.py to connect to Amazon Neptune (including OpenSearch for vector search). Each example demonstrates the full workflow of initializing database indices, adding text and JSON episodes, performing hybrid semantic/BM25 searches, and using graph-distance reranking. A new dense\_vs\_normal\_ingestion.py example also illustrates how the system automatically chunks high-density structured data (like AWS cost reports) versus processing low-density prose in a single call.

examples/quickstart · high confidence

Added a new Jupyter notebook example (\agent.ipynb\) in the \examples/langgraph-agent\ directory that demonstrates building a sales agent using LangGraph and Graphiti. The example shows how to persist chat turns to a Graphiti knowledge graph, recall relevant facts, query product information, and maintain agent state using an in-memory MemorySaver, requiring a Neo4j database for the underlying graph storage.

examples/langgraph-agent · high confidence

Added a new example in the examples/opentelemetry directory that demonstrates how to configure Graphiti with OpenTelemetry to output trace spans to stdout. The example includes a Python script (otel\_stdout\_example.py) showing how to set up a TracerProvider with a ConsoleSpanExporter, integrate it with a Kuzu graph driver, and run basic episode ingestion and search operations. It also provides a .env.example file for the required OPENAI\_API\_KEY and a README with setup instructions.

examples/opentelemetry · high confidence

The \graphiti\_core/cross\_encoder\ module now provides pluggable reranking clients that improve search relevance by re-scoring retrieved passages. It introduces \OpenAIRerankerClient\, which uses the OpenAI API (defaulting to \gpt-4.1-nano\) to classify passage relevance via log-probabilities, and \GeminiRerankerClient\, which uses the Google Gemini API (defaulting to \gemini-2.5-flash-lite\) to score passages on a 0-100 scale. Both clients implement the \CrossEncoderClient\ interface, allowing them to be swapped in for ranking logic, while the previous BGE reranker client has been removed from the initial module exports.

_graphiti\_core/cross\encoder · high confidence

The \graphiti\_core/utils/maintenance\ package introduces a suite of utilities for managing graph data and entity extraction. This includes \attribute\_utils\ for capping string attribute lengths to prevent LLM meta-reasoning bleed, \dedup\_helpers\ for deterministic and fuzzy entity deduplication using MinHash and Jaccard similarity, and \combined\_extraction\ for extracting nodes and edges in a single LLM call to reduce orphaned entities. The package also provides \node\_operations\ and \edge\_operations\ for extracting and building graph structures, \community\_operations\ for in-memory label propagation community detection, and \graph\_data\_operations\ for clearing data and retrieving episodic nodes with support for specific graph providers like Kuzu and Neptune.

_graphiti\core/utils/maintenance · high confidence

Added two new example applications in the \examples/podcast\ and \examples/wizard\_of\_oz\ directories that demonstrate how to ingest structured data into the knowledge graph. The podcast example introduces support for the embedded FalkorDB graph database, allowing users to run the runner without an external database instance, and supports both bulk and single-episode ingestion with custom entity and edge type definitions. The Wizard of Oz example demonstrates parsing and ingesting a classic text using the Anthropic LLM client and a standard Neo4j connection.

examples/podcast · high confidence

This change introduces several new utility modules in \graphiti\_core/utils\ to support bulk ingestion and improved data processing. \bulk\_utils.py\ provides functions for bulk adding nodes and edges, including directed UUID mapping for deduplication and bulk retrieval of previous episodes. \content\_chunking.py\ adds logic to estimate token counts and determine if content (JSON or text) has high entity density, deciding whether to chunk it for LLM processing. \datetime\_utils.py\ standardizes UTC datetime handling with \utc\_now()\ and conversion functions to ensure consistent serialization across different graph drivers. \text\_utils.py\ adds helpers for truncating summaries at sentence boundaries and concatenating episodes with headers for LLM context.

_graphiti\core/utils · high confidence

The edge model layer now includes provider-specific Cypher queries for saving and returning entity and episodic edges, adding support for Kuzu, Amazon Neptune, and FalkorDB alongside the existing Neo4j implementation. This ensures that edge operations such as saving facts with embeddings and reading relationship directions are handled correctly according to each database's specific syntax and capabilities.

_graphiti\core/models/edges · high confidence

The core graph data models (nodes and edges) and the main Graphiti class have been removed from the codebase. This eliminates the previous implementation of EpisodicNode, SemanticNode, EpisodicEdge, and SemanticEdge classes, along with their associated Neo4j persistence logic and the Graphiti driver wrapper.

core · high confidence

The LLM client layer has been restructured into a modular, provider-specific architecture. This introduces dedicated client implementations for OpenAI, Azure OpenAI, Anthropic, Gemini, Groq, and the local GLiNER2 model, all unified under a common LLMClient interface. Key behavioral changes include the introduction of retry logic with exponential backoff for transient errors, a new SQLite-based response cache (replacing the previous diskcache implementation to address a security vulnerability), and configurable max token limits that vary by model. The system now supports structured output parsing, reasoning model features (such as effort and verbosity settings for GPT-5), and language-aware extraction instructions.

_graphiti\_core/llm\client · high confidence

The prompt library has been restructured into a modular architecture with dedicated files for node and edge deduplication (\dedupe\_nodes.py\, \dedupe\_edges.py\), extraction (\extract\_nodes.py\, \extract\_edges.py\, \extract\_nodes\_and\_edges.py\), and summarization (\summarize\_nodes.py\). This change introduces stricter entity naming rules to prevent generic extractions (e.g., requiring 'Nisha's dad' instead of 'dad'), enforces specific temporal resolution using ISO 8601 timestamps, and adds a combined node+edge extraction path for single-pass processing. Additionally, the system now supports custom edge types and includes an evaluation module (\eval.py\) for assessing extraction quality.

_graphiti\core/prompts · high confidence

Added end-to-end graph building evaluation suite; Added live end-to-end regression test for the graph\_service REST API; Added test coverage for graph maintenance utilities; Added tests for BGE and Gemini reranker clients; Added tests for episode concatenation and content chunking utilities; Added unit and integration tests for LLM client providers and utilities; Added unit tests for FalkorDB and Neo4j driver routing and operations; Added unit tests for Gemini, OpenAI, and VoyageAI embedders; Added unit tests for search utilities and security hardening; Comprehensive test suite for Graphiti MCP Server; Expanded test coverage for graph operations, concurrency fixes, and security hardening.

This release updates core dependencies across the project, including upgrading graphiti-core to version 0.30.2, the MCP server to 1.1.0 (requiring graphiti-core \>=0.30.1), and the graph service to 0.1.0 (requiring graphiti-core \>=0.28.2). The MCP server now requires openai \>=2.41.0 and includes optional provider dependencies for google-genai, anthropic, groq, and voyageai. New example projects have been added: an OpenTelemetry stdout example using Kuzu and a quickstart example using python-dotenv. The server component also updates its dependency on uvicorn to \>=0.44.0.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 70.

• Code Health 87
• Architecture 98
• Maturity 62
• Readiness 71
• Security 76

• 300 commits — 236 feature/other, 64 fixes

• signatures/version1 — 120 commits
• (root) — 56 commits
• .github/workflows — 25 commits
• graphiti_core/driver — 18 commits
• mcp_server/pyproject.toml — 16 commits
• graphiti_core/llm_client — 9 commits
• graphiti_core/utils — 9 commits
• mcp_server/src — 8 commits
• mcp_server/docker — 6 commits
• graphiti_core/prompts — 5 commits
• graphiti_core/search — 5 commits
• mcp_server/config — 4 commits
• graphiti_core/graphiti.py — 3 commits
• .github/prompts — 2 commits
• examples/podcast — 2 commits
• graphiti_core/decorators.py — 2 commits
• graphiti_core/models — 2 commits
• mcp_server/uv.lock — 2 commits
• server/graph_service — 2 commits
• examples/gliner2 — 1 commit

• fix: Consolidate overlapping backend fixes (#1695)
• fix: Fix Azure OpenAI integration for v1 API compatibility (#1192)
• fix: Fix Ollama/OpenAI-compatible provider support (#1146)
• fix: Fix dependabot security vulnerabilities (#1184)
• fix: Fix entity extraction for large episode inputs with adaptive chunking (#1129)
• fix: Fix limited number of edges (#1124)
• fix: Fix/model name config (#1094)
• fix: Land contributor fixes from #1686 #1689 #1720 #1761 (#1856)
• fix: Potential fix for code scanning alert no. 26: Workflow does not contain permissions (#1426)
• fix: Refresh README content and fix image refs (#1313)
• fix: Revert "Fix dependabot security vulnerabilities" (#1185)
• fix: Update mcp_server/uv.lock to fix Dependabot alerts [ZEPAI-3570] (#1882)
• fix: Update mcp_server/uv.lock to fix httpx2/httpcore2 Dependabot alerts [ZEPAI-3570] (#1884)
• fix: Update root uv.lock to fix Dependabot alerts [ZEPAI-3570] (#1881)
• fix: chore(deps): fix all Dependabot security alerts (#1599)
• fix: chore(deps): update dependencies to fix dependabot alerts (#1225)
• fix: ci(server): live end-to-end regression test + PR check (#1560)
• fix: ci: fix (id-token) and harden Claude review/triage workflows (#1540)
• fix: fix edge cross-encoder shortlist via balanced merge (#1642) (#1754)
• fix: fix(attributes): preserve prior node attributes when no entity type applies
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

getzep/graphiti was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.