> This page is for version v4 (default).
> For other versions, use one of these documentation indexes:
> - v4 (default): https://docs-beta.getzep.com/v4/llms.txt
> - v3: https://docs-beta.getzep.com/v3/llms.txt
> - v2: https://docs-beta.getzep.com/v2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-beta.getzep.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-beta.getzep.com/_mcp/server.

# Graph directory

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](/searching-the-graph) 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](/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](/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.

**`Python`**

```python Python
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)
```

**`TypeScript`**

```typescript TypeScript
import { ZepClient } from "@getzep/zep-cloud";

const client = new ZepClient({
  apiKey: API_KEY,
});

// All Context Graphs in the project, 50 per page
const page = await client.graph.list({ limit: 50 });
for await (const graph of page) {
  console.log(graph.uuid, graph.name);
}

// Narrow by routing metadata when you know the kind of context you need
const matches = await client.graph.list({
  search: "EMEA support",
  limit: 20,
});

for await (const graph of matches) {
  console.log(graph.uuid, graph.name, graph.description);
}
```

**`Go`**

```go Go
import (
    "context"
    "fmt"
    "log"

    "github.com/getzep/zep-go/v4"
    zepclient "github.com/getzep/zep-go/v4/client"
    "github.com/getzep/zep-go/v4/option"
)

ctx := context.TODO()

client := zepclient.NewClient(
    option.WithAPIKey(apiKey),
)

// Narrow by routing metadata when you know the kind of context you need
page, err := client.Graph.List(ctx, &zep.GraphListRequest{
    Search: zep.String("EMEA support"),
    Limit:  zep.Int(20),
})
if err != nil {
    log.Fatalf("Failed to search graph directory: %v", err)
}

iter := page.Iterator()
for iter.Next(ctx) {
    graph := iter.Current()
    graphUUID, name, description := "", "", ""
    if graph.UUID != nil {
        graphUUID = *graph.UUID
    }
    if graph.Name != nil {
        name = *graph.Name
    }
    if graph.Description != nil {
        description = *graph.Description
    }
    fmt.Println(graphUUID, name, description)
}
if err := iter.Err(); err != nil {
    log.Fatalf("Failed to list graphs: %v", err)
}
```

After you select a graph, search its contents with
[`graph.search_edges` and the other search methods](/searching-the-graph) (or add data with
[`graph.episode.add`](/adding-business-data)). Pass the `uuid` of the graph.

## Context MCP exposure

When [Context Graph access](/context-mcp-server/authentication#shared-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:

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

Which graphs appear depends on the connection's
[Context Graph authorization](/context-mcp-server/standalone-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](/context-mcp-server) and
[Connecting a client](/context-mcp-server/connect) 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).