Key Concepts

How Graph Creation Works

How Zep turns episodes into a Context Graph of entities, relationships, and facts.

When you send data to Zep, it is stored as an episode — the raw source material remains searchable and retrievable. An LLM-driven pipeline also extracts structure from that episode and writes it into a temporal Context Graph: entities (nodes), relationships and facts (edges), tied back to the episodes they came from.

Zep also derives other context artifacts from the graph over time — for example observations and thread summaries. This page focuses on the core ingestion path that produces entities and edges.

From episode to graph

An episode is one unit of source material you send to Zep — a message, a document chunk, a JSON record, or similar. After Zep accepts the episode, each major step below uses a language model, guided by the graph’s ontology and any custom instructions.

StepWhat happens
1. Extract entitiesThe model finds candidate entities in the episode (people, teams, products, and so on).
2. Extract relationships / factsThe model finds relationships between those entities and the facts that describe them.
3. Date factsA separate model pass assigns temporal bounds when the source supports them (valid_at / invalid_at), using the episode’s event time as reference.
4. Resolve entitiesEach extracted entity is matched against nodes already in the graph. Unresolved mentions become new nodes.
5. Resolve relationships / factsEach extracted fact is compared to existing edges: duplicates merge, and contradictions invalidate older facts rather than leaving conflicting truths side by side.
6. Summarize entitiesNode summaries (and related user-graph summaries) are updated from the new evidence so later retrieval has concise entity context.

Zep then embeds and persists the episode, nodes, and edges into the Context Graph.

How entity resolution works

Entity resolution is best-effort. Natural language varies (Sarah vs Sarah Brown, nicknames, abbreviations), and Zep will not always collapse every alias into one node.

When identity is unclear, Zep prefers under-merge over over-merge: better to leave two nodes than to fuse the wrong ones. A wrong merge corrupts identity in ways that are hard to undo, while duplicate nodes are usually recoverable — high-recall retrieval often still surfaces both Sarah and Sarah Brown for the same query, so incomplete identity resolution often does not break the agent path.

Directly added nodes (graph.add_nodes) are not deduplicated by name: each call creates new nodes. Keep the UUIDs Zep returns if you need to update those nodes later.

Manually updating the graph

Alongside Zep’s automatic extraction process, you can write manual updates to the graph — for example adding known nodes or fact triples directly. See Manually Updating the Graph.

What to do before ingest

For best practices on preparing source data before ingestion, see Prepare Data for Ingestion.