Changelog

The framework integration pages were updated for the released v4 integration packages.

The graph visualizer assistant now states the facts of an answer directly. When the graph has no context for a question, the assistant gives one fixed sentence. The assistant reports a count as a total only when the retrieved evidence is complete. Starter questions now come from the five most connected named nodes of the graph.

Zep now updates the observations of a graph when the graph has message episodes from a deleted thread. Before, the observation update failed for that graph.

When an episode fails after its last retry, Zep now records the failure of the episode. Before, some failed episodes stayed in progress and did not finish.

Context retention documentation was added to the Governance section.

You can now use the Zep v4 API with the v4 SDKs for Python, TypeScript, and Go at version 4.0.0. The v4 API is a Context API for agents that call Zep while they work. The v4 documentation is now the default version of the documentation site. The v3 API continues to work, and v3 and v4 serve the same project data. Thus, you can move an application to v4 in steps.

You can now read a graph by connection. The graph.node.list method lists the most connected nodes first when order_by is degree. The graph.node.list_neighbors method returns the nodes that connect to one node, with the edges between them. The graph.get_subgraph method expands from up to 20 seed nodes and tells you when a limit stopped the expansion. The Context MCP Server gives the same navigation with the get_node_neighbors and get_subgraph tools.

You can now read the debug logs and the Ingestion Traces of an episode through the API and the SDKs. The debug_log.enable method turns on debug mode for a limited time. The graph.episode.get_debug_logs and graph.episode.list_ingestion_traces methods return the records for one episode. An Ingestion Trace shows why an extraction step made its decision, so you can find the cause of a wrong fact.

The v4 API identifies each user, thread, and graph by a UUID that Zep generates. A create call returns the UUID, and each later call takes it. Store the UUID with your own record. The v3 user_id, thread_id, and graph_id values become legacy names. The SDKs send an idempotency key when they retry a create call, so a retry does not make a second resource.

Each v4 error response now has an error object with a stable code. Your code or your agent can use this code to select the next step. The object also gives the request field that caused the error. It also gives a request ID. The X-Zep-Request-ID header of each v4 response has the same request ID.

Each search scope has its own v4 method: graph.search_edges, graph.search_nodes, graph.search_episodes, graph.search_observations, and graph.search_thread_summaries. Each method has one response type, so an agent can use each method as a separate tool. List methods use an opaque cursor in place of page numbers.

When an episode does not give a value for a custom attribute, Zep now keeps the stored value on the node or the edge. Before, Zep could replace a stored value with a value that the text did not support.

You can now limit an API key to specific standalone graphs with graph selectors in a policy set. The guide gives the setup steps.

The v4 graph.search_edges method now returns one edge for each hyperedge. The returned edge is the best-ranked member of the hyperedge, and page_size and the cursor count facts. Before, the members of one hyperedge could fill the results. Use graph.hyperedge.get to read all of the members.

A v4 batch.process task with the status failed or partial now always includes an error object. The error code is batch_failed, batch_partial, or batch_canceled, and each code has a fixed message. Give the task uuid to Zep support when you report a failed batch.

Zep now retries the ingest.batch.completed webhook when an attempt to send the webhook fails. Before, a failed attempt could cause a lost webhook. A retry carries the original completion time of the batch.

The zep-ingest guide was updated for zep-ingest 0.4.0 and the v4 API.

The Context MCP Server tools for shared Context Graphs now take graph_uuid in place of graph_id. The list_graphs tool and the zep://graphs/directory resource return graph_uuid and use cursor pagination with cursor and page_size. A call that sends limit fails. Update agent prompts and saved tool calls that use the previous arguments.

A user, a graph, or the project-wide default now stores at most five custom instructions. The same limit applies to user summary instructions. Zep rejects a request with a new name above the limit with a 400 error. Zep then writes no instructions from the request. An update to a stored name does not add to the total. Before, repeated requests could store more than five instructions in one scope.

You can now set an agent model for an account or a project that uses Bring Your Own Model (BYOM). The Graph Assistant uses the agent model. Graph ingestion continues to use the primary and fallback models. Open LLM Providers in the account settings or in the project settings to set the agent model.