> 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.

# Users and User Graphs

## Overview

A user represents a person who interacts with your application. A user can have multiple threads.

Each user has a user graph that stores context for that user.

## Users

Zep creates a UUID for each user. Read the `uuid` field from the create response and store it in your database next to your application user ID, for example in a `zep_user_uuid` column. Use this UUID for every v4 call. You can also set `user_id` to an external identity value, such as a claim from your identity provider. Zep stores this value in the same `user_id` field that v3 uses. It is unique within the project, has a 500-character limit, and cannot change after creation. A v3-created user keeps its `user_id` in v4. If you omit `user_id`, the response omits the field. For Custom OIDC identity mapping, set `user_id` to the value returned by the configured [User ID claim](/context-mcp-server/authentication#connection-settings). User `metadata` is not a replacement for the stored UUID.

**`Python`**

```python Python
user = client.user.create(
    user_id="idp-subject-123",
    email="jane@example.com",
)
# Store this UUID in your application database.
zep_user_uuid = user.uuid_
```

**`TypeScript`**

```typescript TypeScript
const user = await client.user.create({
  userId: "idp-subject-123",
  email: "jane@example.com",
});
// Store this UUID in your application database.
const zepUserUuid = user.uuid;
```

**`Go`**

```go Go
subject := "idp-subject-123"
email := "jane@example.com"
user, err := client.User.Create(ctx, &zep.CreateUserRequest{
    UserID: &subject,
    Email:  &email,
})
if err != nil {
    return err
}
// Store this UUID in your application database.
zepUserUUID := user.UUID
```

> **Note**
>
> **Users Enable Simple User Privacy Management**
>
> Deleting a User will delete all Threads and thread artifacts associated with that User with a single API call, making it easy to handle Right To Be Forgotten requests.

### Ensuring Your User Data Is Correctly Mapped to the Knowledge Graph

> **Tip**
>
> Adding your user's `email`, `first_name`, and `last_name` ensures that chat messages and business data are correctly mapped to the user node in the Zep knowledge graph.
>
> For example, if business data contains your user's email address, it will be related directly to the user node.

You can associate rich business context with a User:

* `metadata`: Key-value data about the user, for example a plan or a region.
* `email`: The user's email.
* `first_name`: The user's first name.
* `last_name`: The user's last name.

### UserGroups

You can collect users into [UserGroups](/usergroup-access) and attach [policy-based access control](/policy-based-access-control) policies to a group. Every user in the group inherits its grants, which is how you give a set of Context MCP users access to specific Context Graphs. A UserGroup is a security grouping of users; it is separate from the user graph, which stores each user's context.

## User Graphs

Each user has an associated User Graph that stores their context across all threads. Zep creates the user graph when you create the user. To use the user graph with the `graph` methods, for example to add data to the user graph or to search it, pass the user UUID as the `graph_uuid` argument. You do not need to store a second UUID for the user graph.

The user graph also has its own UUID. The create response gives it in the `graph_uuid` field, and the `graph` methods also accept it. A response always gives the real UUID of the graph in `graph_uuid`. For a user graph, each episode, node, edge, hyperedge, observation, and batch item in a response also includes the `user_uuid` field. A response for a standard graph omits `user_uuid`.

**`Python`**

```python Python
result = client.graph.episode.add(
    zep_user_uuid,
    data="Jane likes hiking on weekends.",
    type="text",
)

edges = client.graph.search_edges(
    zep_user_uuid,
    query="hiking",
)
```

**`TypeScript`**

```typescript TypeScript
const result = await client.graph.episode.add(zepUserUuid, {
  data: "Jane likes hiking on weekends.",
  type: "text",
});

const edges = await client.graph.searchEdges(zepUserUuid, {
  query: "hiking",
});
```

**`Go`**

```go Go
episodeType := graph.AddEpisodeRequestTypeText
result, err := client.Graph.Episode.Add(context.TODO(), zepUserUUID, &graph.AddEpisodeRequest{
    Data: "Jane likes hiking on weekends.",
    Type: &episodeType,
})
if err != nil {
    return err
}

edges, err := client.Graph.SearchEdges(context.TODO(), zepUserUUID, &zep.SearchEdgesRequest{
    Query: "hiking",
})
if err != nil {
    return err
}
```

This graph-based context system provides several important capabilities:

### Cross-Thread Context Integration

> **Note**
>
> The knowledge graph does not separate the data from different threads, but integrates the data together to create a unified picture of the user. So the `thread.get_context` method doesn't return context derived only from that thread, but instead returns whatever user-level context is most relevant to that thread, based on the thread's most recent messages.

This means that insights and information learned in one conversation thread are automatically available in all other threads for the same user, creating a coherent and continuous context experience.

### Content policies

A new user graph copies the current project [content policy](/content-policies) when you create the user. The optional `content_policy` field of the user create body adds categories and rules to that policy, and `content_policy.project_revision` rejects the create with `409 content_policy_revision_stale` when the project policy changed after you read it. The bound policy is read-only after creation. A user who needs a different policy needs a new user graph. Content policies are in closed beta and need the content policy entitlement.

### Privacy and RTBF Capabilities

When you delete a user, all associated data is removed:

* All threads belonging to that user
* All thread artifacts (messages, metadata)
* The entire user graph and all knowledge extracted from conversations

This single-operation approach makes it simple to handle Right To Be Forgotten (RTBF) requests and comply with privacy regulations.

### Default Ontology for User Graphs

User graphs use Zep's default entity and edge types. Read [Customizing graph structure](/customizing-graph-structure) to define custom types.

Each user graph comes with default entity and edge types that help classify and structure information extracted from conversations. You can also disable the default entity and edge types for specific users if you need precise control over your graph structure.

### The User Node

> **Note**
>
> **User summary and the user node**
>
> Each user has a single unique user node in their graph representing the user themselves. The [user summary](/user-summary) generated from user summary instructions lives on this user node. You can retrieve the user node and its summary with the `user.get_node` method. It takes the user UUID.

The user node serves as a central hub in the knowledge graph, connecting all information about that user. It stores a high-level [user summary](/user-summary) — a persistent, baseline picture of who the user is, included by default in every Context Block. Its content can be steered through [User Summary Instructions](/user-summary-instructions).

## Next Steps

Now that you understand how Users and User Graphs work together, you can:

* Learn about [Threads](/threads) and how they relate to users
* Discover how to [add messages to threads](/adding-messages)
* Learn how to [retrieve context for your agent](/retrieving-context)
* Read about the [User Summary](/user-summary) included by default in every Context Block
* Explore [customizing user summaries](/user-summary-instructions)
* Understand more about the [graph](/graph-overview)
* Ask questions about a user graph in the [graph visualizer assistant](/graph-visualizer-assistant)