Assembling ContextContext Types

Episode metadata projection

How an episode's associations and metadata propagate to the context Zep derives from it

Overview

Every piece of context Zep produces — a fact on an edge, an entity, an observation — is derived from one or more episodes, the raw messages, text, or JSON you ingested. Zep records these links as episode associations.

Associations provide provenance: you can trace any artifact back to the episodes it was created from. That provenance is the foundation for several of Zep’s other capabilities. Metadata you attach to an episode is projected along its associations onto every artifact derived from it, which powers attribute-based access control and episode metadata filtering during search. Associations also preserve graph integrity when you delete an episode: an edge or node is only removed once no associated episodes remain.

How episodes associate with each context type

Each context type accumulates episode associations in its own way:

  • Edges (facts). Facts live on edges. An edge is associated with the episode that first extracted the relationship, plus any later episode that either reaffirms the same fact (recorded as a duplicate) or invalidates it.
  • Entities (nodes). An entity is associated with every episode that mentions it. If a user mentions “Paris” in three separate conversations, the “Paris” node is associated with all three episodes.
  • Observations. An observation is associated with the episodes that serve as its supporting evidence — the episodes behind the facts it was synthesized from.
  • Thread summaries. A thread summary is associated with the message episodes it summarizes, meaning every message in that thread.
  • User summary. The user summary lives on the user’s central entity node, which is associated with episodes exactly as any other entity node is: every episode that mentions the user. The user node is created before any episodes exist and is never deleted when an episode is deleted, but it accumulates episode associations in the same way as any other node.

You can inspect these associations using the API:

  • Edge → episodes: The episodes field on an edge object is a list of episode UUIDs associated with that edge.
  • Node → episodes: Use the get episodes for a node endpoint to retrieve all episodes that mention a given node.
  • Episode → nodes and edges: Use the get episode mentions endpoint to retrieve all nodes and edges mentioned in an episode.

How episode metadata projects onto artifacts

When you attach metadata to an episode, that metadata is projected onto every artifact associated with the episode. An edge or node does not carry metadata of its own — its effective metadata is derived from the metadata of the episodes associated with it.

Because an artifact can be associated with more than one episode, its effective metadata is the combined, deduplicated union of those episodes’ metadata. Each key maps to a list of the values contributed across the associated episodes:

  • A key present in only one associated episode maps to a single-value list.
  • A key present in several associated episodes maps to the list of their distinct values.

For example, suppose an edge is associated with two episodes:

1// Episode 1 metadata
2{ "source": "crm", "priority": 5 }
3
4// Episode 2 metadata
5{ "source": "support_ticket", "reviewed": true }

source appears in both episodes, while priority and reviewed each appear in only one. The edge’s effective metadata is:

1{
2  "source": ["crm", "support_ticket"],
3  "priority": [5],
4  "reviewed": [true]
5}

The overlapping source key holds both values, and the keys unique to a single episode each hold one value.

Effective metadata is also what attribute-based access control evaluates: source-based policies match a rule’s required values against an object’s effective metadata to decide which objects an API key may read. This is why the metadata you attach at ingestion governs not only what you can filter for, but what an access-controlled key is allowed to see.

Filtering by episode metadata

The same episode associations that carry projected metadata also power episode metadata filtering in graph search: an edge, node, or episode result matches when at least one of its associated episodes satisfies the filter. Matching is evaluated per episode, not against the merged effective metadata above — a set of ANDed conditions matches only when a single associated episode satisfies all of them.