ZepGraphiti builds and queries temporal context graphs for AI agents. A context graph is a graph of entities, relationships, and facts in which every fact carries a validity window: when it became true and when, if ever, it was superseded. Entities keep summaries that evolve over time, and everything traces back to episodes, the raw text or JSON that was ingested. Graphiti constructs these graphs autonomously from unstructured and structured data, invalidating rather than deleting old facts when information changes, so you can query what is true now or what was true at a given point in time.
Compared with batch-oriented retrieval-augmented generation (RAG), Graphiti integrates new data incrementally without recomputing the whole graph. Retrieval is hybrid, combining semantic embeddings, BM25 keyword search, and graph traversal, and does not rely on LLM summarization at query time. Ontology can be prescribed up front with Pydantic entity and edge types or learned from the data.
| Component | What it stores |
|---|---|
| Entities (nodes) | People, products, policies, concepts, with summaries that evolve over time |
| Facts / relationships (edges) | Entity → relationship → entity triplets with temporal validity windows |
| Episodes (provenance) | Raw data as ingested; every derived fact traces back here |
| Custom types (ontology) | Developer-defined entity and edge types via Pydantic models |
Graphiti is the open-source core of Zep, a managed context-graph service. Zep adds a proprietary graph engine, built-in user and thread management, pre-configured retrieval, dashboards, and SDKs; Graphiti is self-hosted and brings its own third-party graph database. The framework is the subject of the paper "Zep: A Temporal Knowledge Graph Architecture".
Requirements are Python 3.10 or higher and a graph backend: Neo4j 5.26, FalkorDB 1.1.2 (including an embedded FalkorDB Lite on Python 3.12+), or Amazon Neptune with an OpenSearch Serverless collection for full-text search; the Kuzu driver still ships but is deprecated. LLM inference and embeddings default to OpenAI, with Anthropic, Google Gemini (including a Gemini reranker), Groq, and Azure OpenAI supported directly, and any OpenAI-compatible endpoint, hosted (DeepSeek, Together, OpenRouter, Fireworks) or local (Ollama, vLLM, llama.cpp, LM Studio), usable through OpenAIGenericClient. Providers that support structured output are recommended because ingestion depends on correct output schemas. Ingestion concurrency is governed by SEMAPHORE_LIMIT, which defaults to 10 to avoid provider rate-limit errors.
Two service wrappers are included: an MCP server that exposes episode, entity, search, group, and maintenance operations to AI assistants and can be deployed with Docker and Neo4j, and a FastAPI REST service.
Features
- Temporal facts: validity windows on every edge, with old facts invalidated rather than deleted
- Provenance: each entity and relationship links back to the episode that produced it
- Prescribed or learned ontology: define entity and edge types with Pydantic models, or let structure emerge from the data
- Incremental construction: new episodes integrate immediately, without batch recomputation
- Hybrid retrieval: semantic, BM25 keyword, and graph-traversal search, with reranking by graph distance or a cross-encoder
- Graph backends: Neo4j, FalkorDB, and Amazon Neptune, with a deprecated Kuzu driver
- Model providers: OpenAI by default; Anthropic, Gemini, Groq, Azure OpenAI, and OpenAI-compatible or local endpoints
- MCP server: episode, entity, search, group, and maintenance tools for AI assistants
- REST service: a FastAPI API for interacting with a Graphiti instance
- Configurable concurrency: SEMAPHORE_LIMIT tunes parallel ingestion against provider rate limits
