Working with ContextRetrieveContext 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 agent access 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 episode listing with mentioned_node_uuids to page through every episode that mentions a given node.
  • Episode → nodes and edges: Use node and edge listing with the episode_uuids filter to retrieve the entities and facts an episode contributed to.

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 agent access 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.