Documents

Overview

A document is a customer-facing grouping for episodes on a graph. Use a document_id when you ingest chunks of the same logical source — for example pages of a PDF, sections of a JSON export, or messages from a Slack channel.

Documents are the graph analogue of threads on user graphs. Prior-episode context during ingestion is scoped to the same document_id, which improves pronoun resolution and continuity across chunks. Zep also generates incremental document summaries from those episodes.

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, a Slack channel ID, or an export 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.

Add episodes with a document ID

Pass optional document_id when calling graph.add (or when appending 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.add(
6
    graph_id="my-graph",
7
    type="text",
8
    data="Alice joined Acme Corp as a designer.",
9
    document_id="handbook-v1",
10
)
11
client.graph.add(
12
    graph_id="my-graph",
13
    type="text",
14
    data="She reports to the product team in Austin.",
15
    document_id="handbook-v1",
16
)

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

List episodes for a document

1
episodes = client.graph.get_episodes_for_document(
2
    document_id="handbook-v1",
3
    graph_id="my-graph",
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.get_by_graph_id(
2
    graph_id="my-graph",
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