Zep deep dive: how Graphiti's bi-temporal knowledge graph actually works

Every write to Zep is an "episode" — a chunk of text or structured JSON. Graphiti runs an LLM call over that episode (OpenAI, Anthropic, Gemini, or Groq; structured-output support is required, which is why the README warns smaller local models can produce malformed extractions) to pull out entities and relationships as subject-predicate-object triplets. That write-path cost is the same shape as a fact-extraction layer like Mem0's add() — one LLM call per write — and it's the actual bottleneck: Graphiti ships a concurrency knob (SEMAPHORE_LIMIT) specifically to avoid hitting LLM-provider rate limits during bulk ingestion. The bi-temporal model doesn't avoid that cost; what it changes is what happens next.

When a new triplet contradicts an existing one, Graphiti doesn't ask an LLM to adjudicate. It applies a deterministic rule: the old edge's validity window closes (an invalid_at timestamp is set), a new edge opens, and nothing is deleted. The full provenance chain stays queryable, so "what did we know about this account on March 3rd" is a real, answerable query — not a reconstruction. Retrieval is where the design pays off operationally: a hybrid pass over vector similarity, BM25 keyword matching, and graph traversal, reranked by distance from central entity nodes, with no LLM call in the loop. That's why Zep Cloud reports sub-200ms p95 retrieval even at large graph scale — the expensive judgment call happens once, at write time, not on every read.

Adoption cost is where the marketing glosses fastest. Self-hosting Zep doesn't mean running "Zep" — the Community Edition was deprecated, so what you actually stand up is the open-source Graphiti engine (Apache-2.0) against your own graph database: Neo4j 5.26+, FalkorDB, or Amazon Neptune (Kuzu is supported but deprecated upstream and unmaintained). The full "Zep" product — Context Lake, SOC 2 Type II, HIPAA BAA, BYOC — only exists on the managed cloud. Integration surfaces are solid either way: a first-party MCP server (stdio for Claude Desktop, SSE/HTTP for Cursor and VS Code), Python (graphiti-core) and TypeScript SDKs, a REST API, and an official LangGraph adapter that uses the user entity as the retrieval anchor.

Three profiles fit cleanly. The first is anyone tracking facts that genuinely change — customer profiles, subscription tiers, evolving relationships, project status — where the question isn't just "what's the current value" but "what was it, and when did it change." A fact store that overwrites loses that history; Zep's graph keeps it by construction. The second is the enterprise multi-agent deployment with a compliance bar: SOC 2 Type II, HIPAA BAA, and BYOC deployment are cloud-tier features, paired with sub-200ms retrieval SLAs at scale. The third is anyone who needs point-in-time historical queries as a first-class capability — "what did the agent believe about this customer on a given date" — rather than something bolted on with timestamped log rows. If none of those is your binding constraint, the graph is solving a problem you don't have yet.

Independent comparisons converge on the same shape: Zep wins where temporal or multi-hop structure matters and loses on simplicity. A March 2026 comparison found Zep's pricing doesn't gate graph capability behind a higher tier the way Mem0 does — "all features are available at every tier, just volume limits" — but flagged that self-hosting now means managing Neo4j yourself since the Community Edition's retirement, a real operational step up from Mem0's cleaner self-host story. A June 2026 independent test was blunter about the cost of the graph itself: "a temporal graph traversal is more expensive than a vector nearest-neighbor lookup, and deep multi-hop queries can land in the low hundreds of milliseconds rather than the tens of milliseconds a vector lookup costs" — and recommended benchmarking on your own graph density rather than trusting a vendor number.

The bi-temporal pitch also gets pushback from people building competing systems, not just from neutral reviewers. On a 2025 Hacker News thread, a competing memory-graph founder characterized Zep's behavior on preference changes as "old preference vanishes" rather than tracked with reasoning, prompting a direct reply from a Graphiti maintainer defending the project's breadth of adoption and open MCP support — a live example of the supersession claim being tested in public rather than taken on faith.

Zep's own June 2026 engineering posts are a useful signal of what running it at scale actually involves: one post shows that where you place the retrieved Context Block in the prompt — system prompt versus a trailing message — changes whether prompt caching survives, with measured token savings up to 2x from placement alone; a companion post argues plain markdown files work for a single agent and a single user but break down under concurrent writes and fact contradictions once you scale past that. Both read less like marketing and more like operational lessons from people running the system in production.

The operational footprint is real: a dedicated graph database (Neo4j 5.26+, FalkorDB plus Redis, or Neptune), LLM and embedding provider configuration, and Kuzu users specifically need a migration plan since that backend is unmaintained upstream. Cloud cost is episode-driven — one credit per 350 bytes ingested — so a chatty agent can burn through the free 10,000-credit tier faster than the headline price suggests; estimate episode volume before committing to a tier.

The deeper caveat is construct validity, not operations. A 2026 multi-party benchmark (SocialMemBench) tested four leading memory frameworks — Mem0, LangMem, Graphiti, and Cognee — on group social settings and found all four clustered at 0.12–0.18 (question-weighted), below a plain uncompressed-retrieval baseline of 0.345. Graphiti's bi-temporal graph, tuned for tracking how one entity's facts change, didn't transfer to multi-party settings where the failure modes are different — entity merging across many people, cross-persona knowledge leakage, norm-versus-individual conflation — and the structured layer scored worse than just retrieving raw context. It's a single-author, synthetic-persona result, but it's a real data point that the graph's structure can subtract value outside the dyadic, single-subject case it's built for. And the headline benchmark numbers Zep publishes (LoCoMo, DMR) are self-reported, like every vendor's; independently reproduced comparisons in this catalog are thinner, so treat the gap over flat retrieval as a starting hypothesis to verify on your own graph density, not a settled fact.

If your facts are mostly stable — stated preferences, fixed goals, past interactions that don't get revised — you don't need temporal correctness, and a fact-extraction layer like Mem0 gets you there with a lighter self-host story (no dedicated graph database) and faster time-to-working-agent; the Mem0 vs Zep comparison digs into that tradeoff directly. If your real need is accumulating and reasoning over a large, heterogeneous corpus — documents, multi-hop research questions — rather than tracking how individual facts supersede each other, Cognee's ontology-grounded graph is built for corpus accumulation; it's weaker at "this new fact replaces that old one," which is specifically Zep's lane. Cognee also lacks SOC 2/HIPAA as of mid-2026, so it's not a substitute where Zep's compliance posture is the reason you're there. And if your setting is multi-party rather than per-account state, weigh the SocialMemBench result above before assuming the graph will outperform plain retrieval.

Primary sources and recent material on Zep and Graphiti, newest first.