Episodes

Overview

An episode is a raw data artifact a developer hands to Zep — a chat message, a freeform text chunk, or a JSON object. Zep stores each episode verbatim alongside the entities, edges, and summaries it derives from that data, so the original source remains available even after extraction has finished. Thread messages are also episodes: each call to thread.add_messages persists a message episode on the user’s graph.

Reach for episodes when an agent needs grounded context with the exact source truth — quoting the original wording behind a fact, citing a source, or recovering surrounding context that did not become a fact in its own right.

Ingestion

Episodes enter Zep in two ways:

• thread.add_messages for conversational data — each message becomes a message episode.
• graph.add for non-conversational data, with type set to text (a document excerpt, note, or transcript) or json (a structured record such as a CRM entry, ticket, or event).

Retrieval

The SDK lets you list recent episodes for a user, fetch one by UUID, or search a graph specifically for episodes.

List and fetch

1
from zep_cloud.client import Zep
2
3
client = Zep(api_key=API_KEY)
4
5
# List the most recent episodes on a user's graph.
6
recent = client.graph.episode.get_by_user_id(user_id="emily-painter", lastn=20)
7
for ep in recent.episodes:
8
    print(ep.created_at, ep.source, ep.content)
9
10
# Fetch a single episode by UUID.
11
ep = client.graph.episode.get(uuid_="...")

Episode listing uses lastn (the most recent N items) rather than cursor pagination.

Search

To pull episodes most relevant to a query — for example, the source quotes behind a fact in the Context Block — use graph search with scope="episodes". Results land on results.episodes.

Episodes and the Context Block

Episodes are included in the default Context Block: the episodes most relevant to the user’s recent messages are rendered alongside facts and entities. To customize which episodes appear or how they are formatted, define a context template using the %{episodes} variable, or build a custom block via advanced context block construction.