How to Build a Temporal Knowledge Graph with Graphiti

Graphiti is an open-source framework from Zep for building temporally-aware knowledge graphs aimed at AI agents. Unlike a static graph, every edge has a validity window, so when a fact changes the old version is invalidated rather than overwritten. Ask a question and you get what was true then, not a merged blur.

It is Python, runs against Neo4j or FalkorDB, and pairs with a Neo4j graph database you host yourself. If you are building memory for an agent that needs to reason about state over time — subscriptions, org charts, inventory — Graphiti is built for exactly that.

What is Graphiti?

Graphiti is a library that ingests data as “episodes” and extracts entities and relationships into a graph, timestamping each fact. It supports incremental updates, so new episodes merge into the existing graph, and hybrid search that mixes semantic and keyword retrieval.

What do you need before starting?

• Python 3.10 or newer.
• A running Neo4j (or FalkorDB) instance with credentials.
• An LLM API key for entity extraction (OpenAI or compatible).
• Optionally an embedding model for semantic search.

Neo4j Aura’s free tier works for testing.

How do you install and connect?

1. pip install graphiti-core
2. Set NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD in your environment.
3. Set your model API key.
4. Initialize the client pointed at the graph.
5. Build indexes once before the first ingest.

Index building takes a bit the first time, then ingests are fast.

How do you add data?

You add episodes — text, JSON or message objects. Graphiti runs entity extraction, links new nodes to existing ones, and records when each relationship became valid. Point it at a stream of updates (a CRM feed, a changelog) and it keeps the graph current instead of rebuilding it.

How do you query it?

Search combines semantic similarity with keyword and graph traversal. You can ask for an entity and get its current relationships, or ask a time-bounded question and get only facts valid in that window. This temporal filter is the part that separates it from a plain vector store, which would return stale chunks alongside fresh ones.

What are the trade-offs?

You run and pay for a graph database, and entity extraction costs LLM tokens per episode, so ingesting everything is expensive. Noisy input produces a noisy graph. It also adds real complexity — for a simple FAQ bot, a vector database is easier and cheaper. Graphiti earns its keep when relationships and time matter.

Key Takeaways

• Graphiti builds temporally-aware knowledge graphs for AI agents.
• Every edge has a validity window; old facts are invalidated, not deleted.
• Needs Python 3.10+, Neo4j/FalkorDB and an LLM key.
• Ingests data as episodes with incremental updates.
• Worth it when time and relationships matter; overkill for simple search.

Last updated October 2026. Details at Graphiti.