Ingest | Zep Documentation

Zep builds Context Graphs from the data you provide. Choose a method by the kind of write: a live conversation turn, a bulk or historical import, or an individual write from your application.

This is the Ingest stage of Working with Context. Before designing any import, review Prepare Data for Ingestion to preserve entity identity, source context, and event time.

Choose an ingestion path

What you are adding	Use
A message in a live conversation, as your agent sends and receives it	`thread.add_messages` in the Zep SDK
Historical data you are loading for the first time: documents, transcripts, email, Slack exports, or past conversations	`zep-ingest`
A recurring bulk import (hourly or nightly dump, ETL output)	`zep-ingest`
An individual document, API response, or webhook payload that your application already holds	`graph.add`

Live conversation turns: use the SDK

Add each message to Zep as your agent sends and receives it, using thread.add_messages. The SDK already runs inside the service handling the conversation, and a chat turn needs no preparation beyond the message itself. See Adding messages.

Backfills and bulk imports: use `zep-ingest`

zep-ingest is the recommended path for a one-time backfill of your history, or a recurring job that prepares records and then ingests them. You put the data in the form the package requires. Built-in loaders take a path or glob. The package prepares, previews, submits in order, and monitors.

You do not have to use zep-ingest. It is a convenience layer over the Zep SDK, so calling graph.add or the Batch API directly is fully supported.

Individual writes: use `graph.add`

When your application already holds the data — a webhook body, an API response, a single document — call graph.add directly. Built-in zep-ingest loaders do not accept in-memory payloads today, so routing those through the package means writing a custom loader yourself; for most event-driven paths the SDK call is simpler. See Adding business data.

When a chunk reads better against earlier chunks of the same source, most often to resolve a pronoun, pass a document_id so Zep groups those chunks for prior-episode context and summarization. Do not share an ID across independent records.

Available methods

Method	Data Type	Best For
Create an Ingestion Pipeline	Multiple source types	Backfills and bulk imports, with preparation, preview, and monitoring
Adding messages	Chat messages	Live conversation turns from your agent
Adding business data	Text, JSON, or message format	Individual documents, API responses, emails, or other business data
Batch ingestion	Many episodes and/or messages in one batch	The transport `zep-ingest` submits through, or your own large imports

Next: shape the graph

After ingesting data, Zep processes it to build Context Graphs. Customize extraction and summaries under Shape the Graph.