> This page is for version v4 (default). > For other versions, use one of these documentation indexes: > - v4 (default): https://help.getzep.com/v4/llms.txt > - v3: https://help.getzep.com/v3/llms.txt > - v2: https://help.getzep.com/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://help.getzep.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.getzep.com/_mcp/server. # Context retention > How long Zep retains users, threads, episodes, and Context Graphs, what deletion removes, how long logs, traces, and backups are kept, and how retention policies delete idle context. 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](#retention-policies) 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](/users-and-user-graphs#privacy-and-rtbf-capabilities). | | Shared graph | The episodes of the graph and all objects derived from them | Delete the graph through the API or with [`zepctl graph delete`](/zepctl-cli), or attach a [whole-graph retention policy](#whole-graph-retention). | | Thread | The messages of the thread and the episodes made from them | [Delete the thread](/deleting-data-from-the-graph#delete-a-thread). | | Episode | One unit of ingested data and its contribution to derived objects | [Delete the episode](/deleting-data-from-the-graph#delete-an-episode), or attach an [object-level retention policy](#object-level-retention). | 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](/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](#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](/debug-mode) | 30 days | No | | [API Logs](/api-logging) in the dashboard | 7 days for Flex Plus, 30 days for Enterprise | No | | [API Logs](/api-logging) archive | 1 year, or 7 years for HIPAA accounts | No | | [Audit Logs](/audit-logging) in the dashboard | 30 days | No | | [Audit Logs](/audit-logging) 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](/attribute-based-access-control) 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. ```yaml 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](/attribute-based-access-control#graph-selectors) on an API key uses. The policy set must declare `resource_selector_version: 1`. ```yaml 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](/attribute-based-access-control#source-based-policies). ```yaml 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](/attribute-based-access-control#opt-in-to-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: ```bash 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](/policy-based-access-control) 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](/bring-your-own-key), 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](/bring-your-own-llm), 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](https://www.getzep.com/enterprise) 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. ## Related * [Deleting data from the graph](/deleting-data-from-the-graph): the delete operations and the rules for derived objects. * [Agent access](/attribute-based-access-control): policy sets, modes, and `zepctl`. * [Episode metadata projection](/episode-metadata-projection): the metadata that object-level retention selects. * [Audit logging](/audit-logging): the record of retention management and retention actions.