Documents

Overview

A document in Zep is a grouping of episodes, not a file type. Pages of a PDF, a Slack thread, and an email thread are all valid documents. Any sequence whose later episodes need the earlier ones as context qualifies.

Assign a document_id when extraction of a later episode needs that prior context, most often to resolve a pronoun.

Documents are the graph analogue of threads on user graphs. Zep scopes prior-episode context to the same document_id, which gives extraction the earlier episodes as context. Zep also generates incremental document summaries from them.

document_id is optional. When present it must be 1 to 100 characters. Use a stable identifier from the source system, such as a file name and version or a conversation ID. The same document_id on different graphs identifies different documents.

Pass document_id on graph.add and on batch graph_episode items. You can target a standalone graph with graph_id or a user graph with user_id. Listing episodes and document summaries takes graph_id.

When to assign a document ID

Zep loads earlier episodes with the same document_id when it extracts from a new episode. Share an ID across a group when a later episode is easier to interpret with the earlier ones in view.

A pronoun is the clearest case. In these two chunks, She resolves to Alice only because the first chunk names her:

Alice joined Acme Corp as a designer.
She reports to the product team in Austin.

Without a shared document_id, Zep extracts the second chunk alone and cannot resolve She.

Other references behave the same way, including definite phrases such as the company or that ticket, a heading or preamble that only the first chunk carries, and facts stated once and assumed afterward.

Use a document_id for any of these groups:

• Chunks of one file, such as pages of a PDF or sections of a handbook
• Messages in a Slack thread or email thread that you add with graph.add

Do not assign a document_id only because records share a folder, customer, export, or other business grouping. Independent JSON records, unrelated tickets, and separate files in one directory are each self-contained, so extraction gains nothing from the others. Omit document_id for those episodes.

Conversational messages on a user graph already get this grouping through a thread. Use document_id on graph.add and batch graph_episode items. Do not pass it on thread.add_messages.

Add episodes with a document ID

Pass optional document_id when you add episodes, or when you append graph_episode batch items. Episodes that share a document_id on the same graph are associated together.

1
from zep_cloud import Zep
2
3
client = Zep(api_key="YOUR_API_KEY")
4
5
client.graph.episode.add(
6
    graph_uuid="graph_uuid",
7
    data="Alice joined Acme Corp as a designer.",
8
    document_id="handbook-v1",
9
)
10
client.graph.episode.add(
11
    graph_uuid="graph_uuid",
12
    data="She reports to the product team in Austin.",
13
    document_id="handbook-v1",
14
)

Send each later episode with the same graph identifier and document_id.

The Batch API accepts the same optional document_id on graph_episode items.

List episodes for a document

1
episodes = client.graph.episode.list_for_document(
2
    graph_uuid="graph_uuid",
3
    document_id="handbook-v1",
4
)

List document summaries for a graph

Document summaries are generated asynchronously after episodes are associated. Listing returns one summary per document that has been summarized.

1
summaries = client.graph.document_summary.list(
2
    graph_uuid="graph_uuid",
3
)
4
for summary in summaries:
5
    print(summary.document_id, summary.summary)

Related

• Threads — message grouping on user graphs
• Thread summaries — per-thread incremental summaries
• Adding business data — graph.add fields, including document_id
• Prepare data for ingestion — when to group chunks of one source
• Chunking large documents — split sources that exceed the episode size limit