Threads

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

Overview

Threads represent a conversation. Each User can have multiple threads, and each thread is a sequence of chat messages.

Chat messages are added to threads using thread.add_messages, which adds the messages to the thread history and ingests them into the user’s Context Graph. The user Context Graph contains data from all of that user’s threads.

Relationship Between Users and Threads

A thread belongs to one user. Create the user first. Then call thread.create with the uuid of the user as user_uuid.

Zep gives each thread a UUID when you create it. You cannot select the thread identifier. Read uuid from the thread.create response and store it in your application database next to your own conversation ID, for example in a zep_thread_uuid column. Use the stored UUID as thread_uuid on every later call, such as thread.add_messages. Threads have no metadata field, so keep the relation between your conversation ID and the thread UUID in your application.

Automatic graph warming

When you create a new thread, Zep sends a warm-up request for the user’s Context Graph in the background. This request prepares the graph data for retrieval.

The operation runs asynchronously and does not block the thread creation response. Zep sends this request when you create a thread for a user with an existing graph.

For manual graph warming, see Warming the User Cache.

Next Steps

Now that you understand how Threads work, you can:

• Learn about Users and User Graphs
• Discover how to add messages to threads
• Learn how to retrieve context for your agent
• Read per-thread Thread summaries
• Understand more about the graph
• Use Documents to group graph episodes the way threads group messages