Graphiti Deep Guide: Building Temporal Knowledge Graphs for AI Agents

Key Points

Overview

• What it is: Graphiti is Zep AI's open-source temporal knowledge graph engine, designed as the memory layer for AI agents.
• Why temporal: Traditional RAG and static knowledge graphs struggle with fact changes, cross-session dialogue memory, heterogeneous data fusion, real-time updates, and historical queries. Graphiti tracks the validity window of every fact.
• Benchmarks (from the Zep paper):
• DMR accuracy: 94.8% (vs MemGPT 93.4%)
• LongMemEval: up to +18.5% accuracy, 90% lower latency
• Token cost: −98% vs naive methods
• Query latency: sub-second (vs seconds–tens of seconds for GraphRAG)

Core Data Model

• Episode: the atomic ingestion unit; carries raw content, source type (text / json), source description, reference_time (event/world time), and created_at (system/transaction time) — this is the bi-temporal model.
• EntityNode: a node with name, labels (e.g. Person, Company), a time-evolving summary, optional structured attributes, and provenance via episodes.
• EntityEdge (Fact): a temporal relationship with fact (natural language), valid_at, invalid_at (None = still true), and source episodes. When new information supersedes an old fact, the old invalid_at is set and a new edge is created with no invalid time.
• Context Graph vs traditional KG: Graphiti attaches a time-evolving summary per entity and supports point-in-time state reconstruction.

Architecture

1. Ingestion layer: text, JSON, documents, message streams. 2. Pipeline: LLM-based entity extraction → LLM-based relation extraction → dedup (vector + rules) → summarization → embedding generation (entity + edge + BM25). 3. Storage: Neo4j, FalkorDB, or Kuzu with vector + full-text indexes. 4. Retrieval: semantic search, BM25, graph traversal, temporal filtering — combined via recipes.

Quick Start

• Install: pip install graphiti-core (or [falkordb], [anthropic,groq,google-genai] extras), or uv add graphiti-core.
• Run Neo4j via Docker with APOC + GDS plugins on ports 7474/7687.
• Configure .env with OPENAI_API_KEY, NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD.
• Minimal flow: await graphiti.build_indices_and_constraints() → await graphiti.add_episode(...) → await graphiti.search(query, num_results=N) → await graphiti.close().

Using Episodes

• Text episodes for unstructured content (meeting notes, chat).
• JSON episodes for structured records (HR data, product info).
• Batch ingestion is recommended; control concurrency with asyncio.Semaphore and process in batches of ~10.

Retrieval

• graphiti.search(query, num_results=N) runs hybrid semantic + BM25 + graph traversal by default.
• Center-node reranking: re-rank by graph distance from a seed node, useful for queries like "Who is X's colleague?".
• Predefined recipes in graphiti_core.search.search_config_recipes:
• COMBINED_HYBRID_SEARCH_RRF — hybrid + RRF rerank
• COMBINED_HYBRID_SEARCH_MMR — hybrid + MMR diversity rerank (tune mmr_lambda)
• COMBINED_HYBRID_SEARCH_CROSS_ENCODER — hybrid + cross-encoder rerank
• EDGE_HYBRID_SEARCH_NODE_DISTANCE — graph-distance rerank
• NODE_HYBRID_SEARCH_RRF — node-only retrieval

Custom Entity & Edge Types

• Define Pydantic models (e.g. Person, Company, Product) and pass entity_types, edge_types, edge_type_map to add_episode.
• edge_type_map constrains which (source_label, target_label) pairs may use which relation names — improves extraction precision.

Advanced Features

• Community detection: build_communities(driver) produces clustered community summaries.
• Maintenance: remove_episode(driver, episode_uuid) cascades, clear_data(driver) wipes all, build_indices_and_constraints() rebuilds indexes.
• Point-in-time query: pass effective_at=datetime(...) in SearchConfig to retrieve facts valid at that moment.

Example: Conversation Memory System

• A ConversationMemory class wraps Graphiti with start_session(user_id), add_message(role, content, metadata), get_relevant_context(query), summarize_user_preferences(user_id).
• Sessions, messages, and user attributes are stored as JSON episodes so retrieval surfaces facts like "User is a backend engineer" or "Graphiti features temporal tracking" without manual summarization.

Performance Optimization

• Always call build_indices_and_constraints() on first deployment (vector + BM25 + property indexes for temporal filtering).
• Batch ingestion with concurrency limits; avoid unbounded parallelism.
• Embedder selection:
• Dev: text-embedding-3-small (1536d, cheap)
• Prod: text-embedding-3-large (3072d, higher quality)
• Local: sentence-transformers/all-MiniLM-L6-v2 (384d, free)
• LLM cost control: use gpt-4o-mini for entity/relation extraction and a stronger model (e.g. gpt-4o) only for summary generation.
• Enable debug logging to inspect extraction behavior.

Graphiti vs Zep Cloud

• Graphiti is the open-source core engine (self-hosted, your own Neo4j/FalkorDB, pay only LLM/embedding API costs).
• Zep Cloud is the managed service with hosted infrastructure, automatic scaling, built-in evaluation tooling, and enterprise support.
• Choose Graphiti for full control, customization, and on-prem deployments; choose Zep Cloud for turnkey operation and SLAs.