Users

Overview

A User represents an individual interacting with your application. Each User can have multiple Threads associated with them, allowing you to track and manage their interactions over time. Additionally, each user has an associated User Graph which stores the memory for that user.

The unique identifier for each user is their UserID. This can be any string value, such as a username, email address, or UUID.

In the following sections, you will learn how to manage Users and their associated Threads.

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

You can associate rich business context with a User:

• user_id: A unique identifier of the user that maps to your internal User ID.
• email: The user’s email.
• first_name: The user’s first name.
• last_name: The user’s last name.

Adding a User

You can add a new user by providing the user details.

1
from zep_cloud.client import Zep
2
3
client = Zep(api_key=API_KEY)
4
5
new_user = client.user.add(
6
    user_id=user_id,
7
    email="[email protected]",
8
    first_name="Jane",
9
    last_name="Smith",
10
)

Learn how to associate Threads with Users

User Summary Instructions

$
git clone https://github.com/getzep/zep.git
>
cd zep/examples/python/user-summary-instructions-example

User summary instructions customize how Zep generates the entity summary for each user in their knowledge graph. You can create up to 5 custom instructions per user, set of users, or project-wide. Each instruction consists of a name (unique identifier) and text (the instruction content, maximum 100 characters).

Default instructions

Zep applies the following default instructions to generate user summaries when no custom instructions are specified:

1. What are the user’s key personal and lifestyle details?
2. What are the user’s important relationships or social connections?
3. What does the user do for work, study, or main pursuits?
4. What are the user’s preferences, values, and recurring goals?
5. What procedural or interaction instructions has the user given for how the AI should assist them?

These default instructions ensure comprehensive user summaries that capture essential information across personal, professional, and interaction contexts.

Custom instructions

Instructions are managed through dedicated methods that allow you to add, list, and delete them. You can apply instructions to specific users by providing user IDs, or set them as project-wide defaults by omitting user IDs.

1
from zep_cloud.client import Zep
2
from zep_cloud.types import UserInstruction
3
4
client = Zep(api_key=API_KEY)
5
6
# Add instructions for specific users
7
client.user.add_user_summary_instructions(
8
    instructions=[
9
        UserInstruction(
10
            name="professional_background",
11
            text="What are the user's key professional skills and career achievements?",
12
        )
13
    ],
14
    user_ids=[user_id],
15
)
16
17
# Add project-wide default instructions (applied to all users without custom instructions)
18
client.user.add_user_summary_instructions(
19
    instructions=[
20
        UserInstruction(
21
            name="communication_style",
22
            text="How does the user prefer to receive information and assistance?",
23
        )
24
    ],
25
)
26
27
# List instructions for a user
28
instructions = client.user.list_user_summary_instructions(user_id=user_id)
29
30
# Delete specific instructions for a user
31
client.user.delete_user_summary_instructions(
32
    instruction_names=["professional_background"],
33
    user_ids=[user_id],
34
)

Utilizing user summary

User summaries are automatically included in Zep’s Context Block. You can toggle whether the user summary is included in the Context Block on the Projects page of the web app. Accounts created before November 10, 2025 will need to enable this setting manually, while new accounts have it enabled by default.

Alternatively, you can build a custom context block by retrieving the user node and including its summary. See this example for a complete implementation.

Getting a User

You can retrieve a user by their ID.

1
user = client.user.get("user123")

Updating a User

You can update a user’s details by providing the updated user details.

1
updated_user = client.user.update(
2
    user_id=user_id,
3
    email="[email protected]",
4
    first_name="Jane",
5
    last_name="Smith",
6
)

Deleting a User

You can delete a user by their ID.

1
client.user.delete("user123")

Getting a User’s Threads

You can retrieve all Threads for a user by their ID.

1
threads = client.user.get_threads("user123")

Listing Users

You can list all users, with optional limit and cursor parameters for pagination.

1
# List the first 10 users
2
result = client.user.list_ordered(page_size=10, page_number=1)

Get the User Node

You can also retrieve the user’s node from their graph:

1
results = client.user.get_node(user_id=user_id)
2
user_node = results.node
3
print(user_node.summary)

The user node might be used to get a summary of the user or to get facts related to the user (see “How to find facts relevant to a specific node”).

Default Ontology for Users

User graphs utilize Zep’s default ontology, consisting of default entity types and default edge types that affect how the graph is built. You can read more about default and custom graph ontology here.

Definition

Each user graph comes with default entity and edge types that help classify and structure information extracted from conversations. View the full default ontology definition.

Disabling Default Ontology

You can disable the default entity and edge types for specific users if you need precise control over your graph structure. Learn how to disable the default ontology.