Adding Business Data

Use graph.add to add business records, documents, events, and communications to a Context Graph. Zep supports three data types: JSON, text, and message.

Choose the destination and source information

Use graph_id when the context belongs to a shared customer account, project, product, organization, or business domain. Use user_id when the context belongs to one application user. Set exactly one of these identifiers.

Use source_description to give a human-readable description of the source. Use metadata for source attributes that your application will use for search filters, traceability, or access policies.

import json
new_episode = client.graph.add(
    graph_id="account-acme",
    type="json",
    data=json.dumps({
        "account_id": "acme",
        "plan": "Enterprise",
        "region": "eu-west",
    }),
    source_description="Account record from the CRM",
    metadata={"source": "crm", "account_id": "acme"},
)

The source description and metadata do not establish that the source content is true. See Source traceability for the relationship between episodes and derived graph data.

The message type is ideal for adding data in the form of chat messages that are not directly associated with a Zep Thread’s chat history. This encompasses any communication with a designated speaker, such as emails or previous chat logs.

The text type is designed for raw text data without a specific speaker attribution. This category includes content from internal documents, wiki articles, or company handbooks. It’s important to note that Zep does not process text directly from links or files.

The JSON type may be used to add any JSON document to Zep. This may include REST API responses or JSON-formatted business data.

Adding Message Data

Here’s an example demonstrating how to add message data to the graph:

from zep_cloud.client import Zep
client = Zep(
    api_key=API_KEY,
)
message = "Paul (user): I went to Eric Clapton concert last night"
new_episode = client.graph.add(
    user_id="user123",    # Optional: You can use graph_id instead of user_id
    type="message",       # Specify type as "message"
    data=message
)

Adding Text Data

Here’s an example demonstrating how to add text data to the graph:

from zep_cloud.client import Zep
client = Zep(
    api_key=API_KEY,
)
new_episode = client.graph.add(
    user_id="user123",  # Optional: You can use graph_id instead of user_id
    type="text",        # Specify type as "text"
    data="The user is an avid fan of Eric Clapton"
)

Adding JSON Data

Here’s an example demonstrating how to add JSON data to the graph:

from zep_cloud.client import Zep
import json
client = Zep(
    api_key=API_KEY,
)
json_data = {"name": "Eric Clapton", "age": 78, "genre": "Rock"}
json_string = json.dumps(json_data)
new_episode = client.graph.add(
    user_id=user_id,  # Optional: You can use graph_id instead of user_id
    type="json",
    data=json_string,
)

Setting data timestamps

When adding data via the graph.add method, you can provide the created_at timestamp in RFC3339 format. The created_at timestamp represents the time when the data was originally created. For messages, this would be when the message was originally sent. For events represented as JSON, this would be when the event occurred. Setting the created_at timestamp ensures the user’s Context Graph has accurate temporal understanding of user history (since this time is used in our fact invalidation process).

from zep_cloud.client import Zep
import json
client = Zep(
    api_key=API_KEY,
)
# Example: Adding a JSON event with its original timestamp
event_data = {"event": "purchase", "item": "laptop", "amount": 1299.99}
json_string = json.dumps(event_data)
new_episode = client.graph.add(
    user_id="user123",
    type="json",
    data=json_string,
    created_at="2025-06-01T13:11:12Z"  # Time the event originally occurred
)

Grouping episodes with a document ID

Assign a document_id when extraction of a later episode needs earlier episodes. For example, an earlier episode can identify the subject of a pronoun.

Pass the same ID on each add in the group. See Documents.

Zep scopes prior-episode context to that ID, so extraction can resolve pronouns and other references against the earlier episodes. Zep also generates an incremental document summary.

Omit document_id for independent records that share only a folder, customer, or export. document_id is optional and 1 to 100 characters. Use a stable identifier from the source system.

Data Size Limit and Chunking

The graph.add endpoint has a data size limit of 10,000 characters when adding data to the graph. If you need to add a document which is more than 10,000 characters, see our Chunking Large Documents cookbook for a complete implementation with contextualized retrieval and best practices for chunking for Zep. Pass the same document_id on every chunk so Zep treats them as one source.

Episode metadata

You can attach key-value metadata to episodes when adding data. Metadata is useful for tagging episodes with their data source, category, priority, or other attributes. Zep projects this metadata onto every graph artifact derived from the episode, which is what lets you filter graph search results so that only facts derived from matching episodes are returned.

Metadata values must be scalars (string, number (int/float), or boolean) or non-empty arrays of such scalars, such as {"tags": ["red", "blue"]}. A maximum of 10 keys are allowed per episode. Nested objects are not supported, and empty arrays or arrays containing null are rejected.

from zep_cloud.client import Zep
client = Zep(
    api_key=API_KEY,
)
new_episode = client.graph.add(
    user_id="user123",
    type="text",
    data="Patient blood glucose level was 95 mg/dL, within normal range.",
    metadata={"source": "lab_report", "priority": 5, "reviewed": True},
)

Updating episode metadata

You can update an episode’s metadata after creation using merge semantics: new keys are added, existing keys are overwritten, and keys set to null are removed.

from zep_cloud.client import Zep
client = Zep(
    api_key=API_KEY,
)
# Original metadata: {"source": "lab_report", "priority": 5, "reviewed": True}
updated_episode = client.graph.episode.update(
    uuid_=episode_uuid,
    metadata={"priority": 10, "department": "endocrinology", "reviewed": None},
)
# Result: {"source": "lab_report", "priority": 10, "department": "endocrinology"}
# "priority" was overwritten, "department" was added, "reviewed" was removed

Managing Your Data on the Graph

The graph.add method returns the episode that was created when you added the data. You can maintain a mapping between your data and its episode. You can then delete specific data from the graph with the delete episode method.