Thread summaries

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 knowledge 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.

1
from zep_cloud import Zep
2
3
client = Zep(api_key="YOUR_API_KEY")
4
5
summary = client.thread.get_summary(thread_id="thread-42")
6
7
print(summary.summary)             # the natural-language summary
8
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 these endpoints to retrieve summaries across many threads — for example, when building a per-user dashboard. Both endpoints return a flat array of ThreadSummary objects and accept an optional pagination body.

1
# All thread summaries across a user's threads.
2
page = client.graph.thread_summary.get_by_user_id(
3
    user_id="user-42",
4
    limit=20,
5
)
6
7
for s in page:
8
    print(s.thread_id, "—", s.summary)
9
10
# Continue with a cursor (the uuid of the last item from the previous page).
11
next_page = client.graph.thread_summary.get_by_user_id(
12
    user_id="user-42",
13
    limit=20,
14
    uuid_cursor=page[-1].uuid_,
15
)
16
17
# Or list summaries on a named (non-user) graph.
18
graph_summaries = client.graph.thread_summary.get_by_graph_id(
19
    graph_id="my-graph",
20
    limit=20,
21
)

Search thread summaries

graph.search accepts scope="thread_summaries" to search over thread summary content directly. Results are returned in a thread_summaries field on the search response.

1
results = client.graph.search(
2
    user_id="emily-painter",
3
    query="payment failures and account recovery",
4
    scope="thread_summaries",
5
    limit=5,
6
)
7
8
for s in results.thread_summaries or []:
9
    print(s.thread_id, "—", s.summary)

Thread summaries and the Context Block

Thread summaries may be included in the default Context Block when Smart Context Assembly selects them as relevant to the current conversation. To always include them — or to pin a specific count — use a context template. For full control over which summaries appear and how they’re formatted, retrieve them directly with the SDK methods above, or build a custom block via advanced context block construction.

Related

• Retrieving Context — the user-wide Context Block.
• Threads — the underlying primitive being summarized.
• Entities — entity-level summaries, a separate concept.
• Context Types — overview of the other context types.