Graph directory | Zep Documentation

Agents that can reach more than one shared Context Graph need a bounded catalog of what each graph contains. The graph directory is that catalog: project-scoped metadata for shared Context Graphs, with cursor pagination and a text search over name and description.

The directory does not search facts, entities, episodes, or other graph contents. Use graph search after you select a graph by its uuid.

What the directory returns

Each entry is one shared Context Graph in the authenticated project.

Field	Role
`uuid`	Stable address of the graph for later graph operations
`name`	Optional short label
`description`	Optional plain-text explanation of subject matter, intended use, and boundaries
`created_at`	Creation time
`updated_at`	Last metadata update time

Names and descriptions are customer-authored routing metadata. Zep does not generate them from graph contents. Graphs without a name or description still appear. Clients should show the uuid when a graph has no name.

The directory excludes user graphs and graphs outside the authenticated project. To find a user graph, read the graph_uuid of the user. For how to create shared Context Graphs and set routing metadata, see Create graph.

List and search with the SDKs

The SDK entry point is graph.list (POST /graphs/list). Omit search for an unfiltered list. Pass search to keep only the graphs whose name or description contains the search text (case-insensitive). The search text is one substring. Zep does not split it into terms. A graph that was migrated from v3 can also match on its legacy graph_id. See Migrating from v3.

Parameter	Behavior
`limit`	Page size. Default 50 when omitted; valid range 1–200
`cursor`	Opaque cursor for the next page. The SDK pager sends it for you
`search`	Optional metadata filter. The graph matches when its `name` or `description` contains the text
`order_by`	`created_at`, `name`, or `uuid`
`order`	`asc` or `desc`

The default order is newest first (created_at descending). When two graphs have the same value in the sort field, uuid breaks the tie. search does not change the order.

The response is a page with items, next_cursor, and total_size (the number of graphs that match the filter). The SDKs return a pager that fetches the next page when you iterate past the current page. When next_cursor is absent, there are no more pages.

from zep_cloud.client import Zep
client = Zep(
    api_key=API_KEY,
)
# All Context Graphs in the project, 50 per page
for graph in client.graph.list(limit=50):
    print(graph.uuid_, graph.name)
# Narrow by routing metadata when you know the kind of context you need
matches = client.graph.list(
    search="EMEA support",
    limit=20,
)
for graph in matches:
    print(graph.uuid_, graph.name, graph.description)

After you select a graph, search its contents with graph.search_edges and the other search methods (or add data with graph.episode.add). Pass the uuid of the graph.

Context MCP exposure

When Context Graph access is enabled on the project connection, Context MCP exposes the same directory contract through two surfaces:

Surface	Role
`zep://graphs/directory`	Read-only resource for a paginated overview (`graph_id`, name, description). The template `zep://graphs/directory{?page,page_size}` requests later pages. Default `page_size` is 50; maximum is 100 (same as the API).
`list_graphs`	Directory search tool. Optional `search` (omit or empty for an unfiltered list; every whitespace-separated term must match at least one of `graph_id`, `name`, or `description`; longer than 200 Unicode code points after whitespace normalization is invalid), `page` (default 1), and `limit` (default 20, maximum 50).

Use the returned graph_id with search_graph_in (and the other _in tools) to work with one selected Context Graph. Context MCP returns and accepts graph_id, not the uuid that the API and SDK directory returns: graph_id is the identifier the application assigned when it created the graph with the v3 API. A graph created with the v4 API has no graph_id; it appears in the MCP directory with an empty graph_id, and the _in tools cannot select it. Directory metadata search is not the same as content search: list_graphs matches routing metadata; search_graph and search_graph_in search graph contents.

Suggested agent flow:

Read zep://graphs/directory for an overview, or call list_graphs with search when you know the kind of context you need.
Pick a matching graph_id.
Call search_graph_in (or another _in tool) on that graph.
Do not query every accessible graph when one or a few clearly match.

Which graphs appear depends on the connection’s Context Graph authorization mode. Project-wide mode lists every live Context Graph in the token-bound project. UserGroup ABAC mode applies the same graph.search grants as search_graph_in before search, sort, count, and pagination. Hidden graphs do not appear in results, counts, or ranking.

See Context MCP Server and Connecting a client for setup and tool lists.

Limits

The directory is metadata-only. It does not list user graphs or search graph contents.
Descriptions are optional and customer-authored. Missing metadata does not hide a graph.
Cursor pagination is forward-only. A graph that is created during a walk can be absent from the results. When the walk orders by name, a graph that is renamed during the walk can be missed or returned twice. Order by created_at or uuid when you need each graph exactly once.
Page-size defaults differ: the API defaults to 50 (max 200), the zep://graphs/directory resource defaults to 50 (max 100), and MCP list_graphs defaults to 20 (max 50).