Context retention | Zep Documentation

This page is the canonical description of context retention in Zep Cloud. It applies to agent memory, enterprise context graphs, and customer and account context. Other pages link here instead of repeating these rules.

Default retention

Zep keeps context until one of these events removes it:

A caller deletes the context through the API, the SDK, or the dashboard.
The account or project that holds the context is deleted.
A retention policy deletes the context.
Zep deletes an inactive free-plan account. This applies only to free-plan accounts in the US region of Zep Cloud.

Zep does not expire context on a time schedule by default. A graph, a user, a thread, or an episode that no caller deletes stays in Zep while the account exists.

An authenticated API request or dashboard request is activity on the account. When a free-plan account has no activity for 60 days, Zep sends a warning email to the Account Owner. Zep sends more warnings before day 90. When the account has no activity for 90 days, Zep deletes the account. Zep does not delete paid accounts, enterprise accounts, BYOC accounts, or accounts outside the US region for inactivity.

Context includes users, threads and their messages, episodes, and the user graphs and shared graphs that hold them. Context also includes every object that Zep derives from episodes: entity nodes, edges, summaries, and other graph artifacts.

Retention scopes

Context has a hierarchy. A deletion at one level removes the levels below it.

Scope	What the scope holds	How to remove the scope
Account	All projects of the account	The Account Owner deletes the account.
Project	All users, threads, and graphs of the project	Delete the project in the dashboard.
User	The user, the threads of the user, and the user graph	Delete the user.
Shared graph	The episodes of the graph and all objects derived from them	Delete the graph through the API or with `zepctl graph delete`, or attach a whole-graph retention policy.
Thread	The messages of the thread and the episodes made from them	Delete the thread.
Episode	One unit of ingested data and its contribution to derived objects	Delete the episode, or attach an object-level retention policy.

When you delete an episode or a thread, Zep keeps a derived node or edge that other episodes also support. Deleting data from the graph gives the rules for each object type.

Deletion behavior

After Zep deletes context, the deleted objects are not returned by reads:

A search or a list does not include the deleted objects. A search that matches only deleted objects returns an empty 200 response.
A request for a deleted object by its UUID returns 404 Not Found.

A deletion is permanent. Zep has no undelete operation. A new user or graph gets a new UUID and is empty. This is also true when a new user has the same user_id as a deleted user. When you ingest the same content again, Zep creates new objects. Zep does not restore the deleted objects.

Some internal copies keep the deleted data after the deletion. No API, SDK, or dashboard operation reads these copies.

Internal copy	How long the copy keeps deleted data
Database backups for disaster recovery	Zep cannot remove one customer’s data from a backup. The data stays until the backup expires. The longest backup period is 365 days.
Graph write log	The log keeps each change to a graph for up to 90 days.
Earlier versions of a graph snapshot	When you delete a user, a graph, or a project, Zep removes all snapshot versions of the graph. When you delete an episode or a thread, earlier snapshot versions keep the data until 150 newer versions replace them. A graph that has no new changes keeps its earlier versions with no time limit. To remove these versions, delete the graph. When object-level retention deletes an episode, Zep also removes the earlier versions.

Records outside the graph

Zep keeps some records about requests and ingestion separately from the Context Graph. Deletion of context does not delete these records. Each record type expires at the end of its own period.

Record	Retention period	Deleted with context
Ingestion Traces	30 days	No
API Logs in the dashboard	7 days for Flex Plus, 30 days for Enterprise	No
API Logs archive	1 year, or 7 years for HIPAA accounts	No
Audit Logs in the dashboard	30 days	No
Audit Logs archive	1 year, or 7 years for HIPAA accounts	No

Retention policies

A retention policy deletes context automatically after the context is idle for a set period. Use a retention policy when your data-minimization or compliance rules set a maximum period for context that is no longer in use.

Retention policies are policy sets that contain only retention entries. A retention policy set cannot also contain authorization entries. Zep has two kinds of retention policy.

	Whole-graph retention	Object-level retention
Deletes	A whole graph and everything in the graph	Episodes, and the derived objects that only those episodes support
Selects by	A graph-ID pattern in a project, and optionally a list of graph UUIDs	Episode metadata, in all graphs of a project
Idle clock	The last time a caller changed the graph	The time that Zep ingested the episode
Policy entry	`retain_for`, and optionally `resources`	`retain_for` and `attributes`

Whole-graph retention

A whole-graph retention policy deletes a graph after no caller changes the graph for the retention period. The policy applies to user graphs and to shared graphs.

policy_set:
  name: short_lived_graphs
  mode: report_only
  spec:
    policies:
      - id: expire_idle_after_30d
        type: retention
        retain_for: 30d

You attach the policy set to a project with a graph-ID pattern. The pattern matches the graph_id of a shared graph, or the user_id of the user that owns a user graph. The pattern does not match the graph UUID.

Pattern	Graphs that the pattern matches
`alice`	Only the graph with the ID `alice`
`scratch-*`	All graphs with an ID that starts with `scratch-`
`*`	All graphs in the project, including graphs that have no `graph_id` or `user_id`

The pattern also matches graphs that callers create after you attach the policy set. A * pattern deletes the graph of every user that stays idle for the retention period.

Select graphs by UUID

A graph that you create without a graph_id has only a UUID. To set a retention period for specific graphs by UUID, add a resources mapping with canonical_graph_uuids to the retention entry. This is the same key that a graph selector on an API key uses. The policy set must declare resource_selector_version: 1.

policy_set:
  name: expire_one_graph
  mode: report_only
  spec:
    resource_selector_version: 1
    policies:
      - id: expire_scratch_graph_after_7d
        type: retention
        retain_for: 7d
        resources:
          canonical_graph_uuids:
            - 2f6d9ff7-8f63-4d4d-a7f0-429eb75546d6

Attach the policy set to the project with the pattern *. The entry then applies only to the graphs that it lists. These rules apply:

Each UUID must identify a graph in the project of the policy set. Zep rejects the policy set if a UUID does not identify a graph.
The selector selects standalone graphs only. The selector does not select a user graph.
A retention entry does not accept graph_uuids or agent_uuids.
An object-level retention entry does not accept resources.

Every caller write changes the idle clock of a graph. Caller writes include ingestion and deletion of objects in the graph. Internal operations, such as snapshots, re-indexing, and migrations, do not change the idle clock.

Object-level retention

An object-level retention policy deletes episodes that match a metadata selector when the episode age reaches the retention period. The selector uses the same attributes form and the same exact-match rule as source-based policies.

policy_set:
  name: expire_scratch_sources
  mode: report_only
  spec:
    policies:
      - id: expire_scratch_after_7d
        type: retention
        retain_for: 7d
        attributes:
          source: [scratch]

You attach an object-level policy set to the whole project with the pattern *. The policy applies to the episodes of all graphs in the project. Set spec.subset_match: true to use subset matching for the selector.

Zep deletes a node, an edge, or a summary when all of its contributing episodes are deleted. A derived object that other episodes also support stays in the graph, and Zep rebuilds its summary from the remaining episodes. Zep also removes the deleted episodes from the earlier snapshot versions of the graph.

An object-level deletion does not change the idle clock of the graph. A graph that a whole-graph policy also governs does not become active because of an object-level deletion.

Retention periods

The retain_for value is a whole number of days, written as Nd. For example, 30d is 30 days.

Zep rejects other units, such as hours or weeks, and fractional values.
0d deletes matched context at the next evaluation.
When several policies apply to the same graph or episode, the shortest period applies.

Zep evaluates retention policies once each day. A graph or an episode that no retention policy matches has no retention period, so Zep keeps it until it is deleted.

Modes

Each retention policy set has a required mode.

Mode	Effect
`off`	Zep does not evaluate the policy set.
`report_only`	Zep evaluates the policy set and records the context that it would delete. Zep does not delete context.
`enforce`	Zep evaluates the policy set and deletes the eligible context.

A retention deletion is permanent. Start every retention policy in report_only, and change it to enforce only after you review the would-delete records. The review is most important for a * pattern, a broad selector, or a short period.

Managing retention policies

Only account administrators can manage retention policies. Project API keys cannot manage them. Zep records each create, update, delete, attach, and detach operation as an audit event. For whole-graph retention, Zep records an audit event for each graph that Zep deletes or would delete. For object-level retention, Zep records one audit event for each project in each evaluation. This event gives the number of deleted or would-delete episodes and a sample of their IDs. It does not give the ID of each episode. The audit events do not contain the deleted data.

Use zepctl to validate and create a retention policy set:

zepctl policy-set validate --file retention.yaml
zepctl policy-set create   --file retention.yaml

zepctl does not attach a retention policy set to a graph-ID pattern. Contact Zep to attach a retention policy set.

Interaction with other controls

Access policies

Access policies and retention policies are separate controls. An access policy hides objects from a caller, and the objects stay in Zep. A retention policy deletes objects for every caller. An access policy does not change which objects a retention policy selects or when Zep deletes them.

Bring Your Own Key

With BYOK, you control the AWS KMS key that encrypts your data at rest. When you disable or delete the key, Zep cannot read the encrypted data. The data becomes unreadable at that time, but retention and deletion do not change.

Bring Your Own LLM

With BYOM, Zep sends model requests through your LLM provider account. The retention of prompts and responses at the provider follows the data-retention settings of your provider account.

Bring Your Own Cloud

In a BYOC deployment, Zep runs in your cloud account, and your cloud account holds the context and its backups. The backup periods on this page apply to Zep Cloud. Contact the Zep Enterprise team for the retention settings of a BYOC deployment.

Deleting data from the graph: the delete operations and the rules for derived objects.
Agent access: policy sets, modes, and zepctl.
Episode metadata projection: the metadata that object-level retention selects.
Audit logging: the record of retention management and retention actions.