Context types | Zep Documentation

Each context type serves a different retrieval purpose. A fact answers a precise question, while a summary preserves a broader narrative.

An episode preserves source content. An observation describes a pattern across graph data.

At a glance

Type	What it captures	In default Context Block	Status
Facts	A discrete, time-scoped relationship between two entities	Yes (when relevant)	Stable
Entities	A noun (person, place, thing, concept) plus a narrative summary of its history	Yes (when relevant)	Stable
Episodes	The raw text, message, or JSON the developer ingested	Yes (when relevant)	Stable
Thread summaries	An incremental summary of a single thread’s messages	Yes (when relevant)	Stable
Observations	A durable, evidence-backed pattern, decision, or commitment across one or more entities	Yes (when relevant)	Stable, Flex Plus / Enterprise
User summary	A persistent, baseline picture of who the user is	Yes (when available)	Stable

The types

Facts are relationships between two entities with temporal validity. Use facts when the agent needs an exact claim and its dates.

Entities are graph nodes that Zep extracts from ingested data. Each entity has a name and a summary of its facts and relationships.

Episodes are the messages, text, and JSON records that you ingest. Use episodes when an agent needs the source content.

Thread summaries summarize the messages in one thread. For example, a summary can describe a problem and its resolution.

Document summaries summarize episodes that have the same document_id.

Observations are evidence-backed patterns that Zep derives from the graph. Use observations for behavior that spans multiple facts or episodes.

User summary is a generated narrative on the user’s central entity node. User summaries only exist on user graphs.

How to assemble these into a prompt

The default Context Block can include all six context types. Smart Context Assembly selects available context that is relevant to the four most recent messages.

You have three options to control the result:

Retrieve them directly with the SDK using the per-type APIs documented on each page.
Define a context template to control which types appear in thread.get_user_context(). Templates can include %{user_summary}, %{edges} (facts), %{entities}, %{episodes}, %{observations}, and %{thread_summaries}. Zep still selects relevant results for those types.
Build a custom block with advanced context block construction to retrieve and format any combination of types.

See the Retrieve overview for a comparison of these methods.