Zep: A Temporal Knowledge Graph Architecture for Agent Memory

Zep is a commercial memory service for AI agents, and this paper describes its engine, Graphiti, a knowledge graph that is updated continuously from conversations and business data.

The graph has three tiers. Episodes hold raw input (messages, text or JSON) without loss. From each episode, an LLM extracts entities and facts (relationships between two entities, stored as edges), using the previous four messages for context. New entities are matched against existing ones by embedding similarity, full-text search and an LLM judgment, so "Priya" and "Priya Shah" become one node. Communities group strongly connected entities and carry summaries.

The distinctive part is time. Zep uses a bi-temporal model: each fact edge records when it became true and when it stopped being true in the world (valid_at, invalid_at), and when the system created and retired it (created_at, expired_at). Relative dates such as "two weeks ago" are resolved against the message's timestamp. When an LLM finds that a new fact contradicts an existing one over the same period, the old edge's validity is closed at the new fact's start. Nothing is overwritten, so the system can answer both "where does she live now?" and "where did she live in March?"

Retrieval runs cosine similarity, BM25 keyword search and breadth-first graph search, reranks the results, and formats the top facts with their date ranges plus entity summaries.

On LongMemEval, Zep beat putting the whole 115,000-token history in context, using about 1,600 tokens.

Enterprise assistants remember things that go stale: a customer's plan, a contact's role, a shipping address, a project's status. If memory is a pile of retrieved chat snippets, the model sees "I live in Austin" and "we moved to Denver" side by side and has to guess. If memory overwrites, you lose the history and cannot answer "what did we know when we sent that invoice?"

Zep's design gives three ideas worth copying even if you never use the product.

Store facts with validity intervals. A fact is true from one date to another. Closing an interval keeps history; returning date ranges with each fact lets the model answer "now" and "then" questions.

Separate world time from system time. When the assistant learns in April that someone moved in March, the record should show both. That lets you reconstruct what the agent believed when it acted, which matters for audits and complaints.

Keep the source. Every fact links back to the episode it came from. When extraction or entity matching goes wrong, and it will, you can find every fact a bad episode created or closed, and revert them.

The weak points are the ones the paper does not measure. Every message goes through several LLM calls (extraction, resolution, date extraction, contradiction checks), and the paper reports no ingestion cost or delay. Wrong merges and wrong contradiction calls silently change what the assistant believes. Budget for both, and build correction tools.