Thread summaries | Zep Documentation

Overview

A thread summary is a natural-language summary of the messages in a single thread, generated and incrementally updated by Zep. There is one summary per thread, and it is persisted on the user’s Context Graph alongside the data Zep already extracts from messages.

Thread summaries are useful as an extra type of context to give your agent a different view of a user’s history — for example, what problem the user had in a given conversation and how it was resolved. Where facts and entity summaries describe the user across all their threads, a thread summary describes the arc of one specific conversation.

How they’re generated

Thread summaries are generated and updated automatically as new messages arrive in a thread. There is no manual “summarize now” call — clients only read summaries, they do not create them.

A thread that has never received messages will not have a summary, and the single-thread endpoint will return 404 until the first summary has been generated.

Get the summary for a thread

Use this when you have a specific thread in hand and want its summary. Pass the uuid that thread.create returns. Store this UUID in your application database next to your own conversation ID.

from zep_cloud import Zep
client = Zep(api_key="YOUR_API_KEY")
# The uuid of the thread, from your application database.
summary = client.thread.get_summary(zep_thread_uuid)
print(summary.summary)             # the natural-language summary
print(summary.last_summarized_at)  # timestamp of the most recent update

The last_summarized_at field on the returned object is the timestamp of the most recent summary update. A 404 response means Zep has not yet generated a summary for this thread (for example, a thread with no messages yet).

List summaries for a user or graph

Use graph.thread_summary.list to retrieve summaries across many threads — for example, when building a per-user dashboard. Pass the graph_uuid of a user to list the summaries of that user’s threads, or pass the uuid of another graph. The method returns a page of ThreadSummary objects. The SDK pager fetches the next page when you iterate. Set limit to control the page size.

# All thread summaries across a user's threads.
# zep_graph_uuid is the graph_uuid of the user, from your application database.
summaries = client.graph.thread_summary.list(zep_graph_uuid, limit=20)
for s in summaries:
    print(s.thread_uuid, "—", s.summary)

Search thread summaries

graph.search_thread_summaries searches over thread summary content directly. The call returns one page of ThreadSummary objects.

results = client.graph.search_thread_summaries(
    zep_graph_uuid,
    query="payment failures and account recovery",
    limit=5,
)
for s in results.items or []:
    print(s.thread_uuid, "—", s.summary)

Thread summaries and the Context Block

The default Context Block can include thread summaries when Smart Context Assembly selects them. Use a context template to always include thread summaries or set a limit.

Retrieve summaries directly or use advanced Context Block construction when you need full control.

Retrieving context — the user-wide Context Block.
Threads — the underlying primitive being summarized.
Documents — document summaries, the analogue for grouped graph episodes.
Entities — entity-level summaries, a separate concept.
Context types — overview of the other context types.