Zep v4 API is generally available
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.
Graph navigation in the v4 API
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.
Debug logs and Ingestion Traces in the v4 API
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.
Zep UUIDs and safe retries in the v4 API
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.
Stable error codes in the v4 API
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.
One search method for each scope in the v4 API
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.
Custom attributes keep stored values
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.