> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-beta.getzep.com/v4/users-and-user-graphs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-beta.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 gives each user a UUID when you create the user. `user.create` does not accept an identifier. Read the `uuid` field of the create response, and store it in your database next to your own user ID, for example in a `zep_user_uuid` column. Use this UUID on every later call for the user. To keep a readable label on the Zep user, put it in the user `metadata`.

> **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 your internal user ID or a display label.
* `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. The create response gives the UUID of the user graph in the `graph_uuid` field. Store it next to the user UUID, and use it with the `graph` methods, for example to add data to the user graph or to search it. 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.

### 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)

> Understanding user management and knowledge graph integration in Zep