Zep

Use Zep to manage users, conversation threads, messages, and retrieved context across workflow runs. Add messages after an interaction, then retrieve user context for a later agent step.

Usage Instructions

Integrate Zep for long-term memory management. Create threads, add messages, retrieve context with AI-powered summaries and facts extraction.

Actions

Create Thread

Start a new conversation thread in Zep

Input

Parameter	Type	Required	Description
`threadId`	string	Yes	Unique identifier for the thread (e.g., "thread_abc123")
`userId`	string	Yes	User ID associated with the thread (e.g., "user_123")
`apiKey`	string	Yes	Your Zep API key

Output

Parameter	Type	Description
`threadId`	string	Thread identifier
`userId`	string	Associated user ID
`uuid`	string	Internal UUID
`createdAt`	string	Creation timestamp (ISO 8601)
`projectUuid`	string	Project UUID

Get Threads

List all conversation threads

Input

Parameter	Type	Required	Description
`pageSize`	number	No	Number of threads to retrieve per page (e.g., 10, 25, 50)
`pageNumber`	number	No	Page number for pagination (e.g., 1, 2, 3)
`orderBy`	string	No	Field to order results by (created_at, updated_at, user_id, thread_id)
`asc`	boolean	No	Order direction: true for ascending, false for descending
`apiKey`	string	Yes	Your Zep API key

Output

Parameter	Type	Description
`threads`	array	Array of thread objects
↳ `threadId`	string	Thread identifier
↳ `userId`	string	Associated user ID
↳ `uuid`	string	Internal UUID
↳ `createdAt`	string	Creation timestamp (ISO 8601)
↳ `updatedAt`	string	Last update timestamp (ISO 8601)
↳ `projectUuid`	string	Project UUID
↳ `metadata`	object	Custom metadata (dynamic key-value pairs)
`responseCount`	number	Number of items in this response
`totalCount`	number	Total number of items available

Delete Thread

Delete a conversation thread from Zep

Input

Parameter	Type	Required	Description
`threadId`	string	Yes	Thread ID to delete (e.g., "thread_abc123")
`apiKey`	string	Yes	Your Zep API key

Output

Parameter	Type	Description
`deleted`	boolean	Whether the thread was deleted

Get User Context

Retrieve user context from a thread with summary or basic mode

Input

Parameter	Type	Required	Description
`threadId`	string	Yes	Thread ID to get context from (e.g., "thread_abc123")
`mode`	string	No	Context mode: "summary" (natural language) or "basic" (raw facts)
`minRating`	number	No	Minimum rating by which to filter relevant facts
`apiKey`	string	Yes	Your Zep API key

Output

Parameter	Type	Description
`context`	string	The context string (summary or basic mode)

Get Messages

Retrieve messages from a thread

Input

Parameter	Type	Required	Description
`threadId`	string	Yes	Thread ID to get messages from (e.g., "thread_abc123")
`limit`	number	No	Maximum number of messages to return (e.g., 10, 50, 100)
`cursor`	string	No	Cursor for pagination
`lastn`	number	No	Number of most recent messages to return (overrides limit and cursor)
`apiKey`	string	Yes	Your Zep API key

Output

Parameter	Type	Description
`messages`	array	Array of message objects
↳ `uuid`	string	Message UUID
↳ `role`	string	Message role (user, assistant, system, tool)
↳ `roleType`	string	Role type (AI, human, tool)
↳ `content`	string	Message content
↳ `name`	string	Sender name
↳ `createdAt`	string	Timestamp (RFC3339 format)
↳ `metadata`	object	Message metadata (dynamic key-value pairs)
↳ `processed`	boolean	Whether message has been processed
`rowCount`	number	Number of rows returned
`totalCount`	number	Total number of items available

Add Messages

Add messages to an existing thread

Input

Parameter	Type	Required	Description
`threadId`	string	Yes	Thread ID to add messages to (e.g., "thread_abc123")
`messages`	json	Yes	Array of message objects with role and content (e.g., [{"role": "user", "content": "Hello"}])
`apiKey`	string	Yes	Your Zep API key

Output

Parameter	Type	Description
`threadId`	string	Thread identifier
`added`	boolean	Whether messages were added successfully
`messageIds`	array	Array of added message UUIDs

Add User

Create a new user in Zep

Input

Parameter	Type	Required	Description
`userId`	string	Yes	Unique identifier for the user (e.g., "user_123")
`email`	string	No	User email address
`firstName`	string	No	User first name
`lastName`	string	No	User last name
`metadata`	json	No	Additional metadata as JSON object (e.g., {"key": "value"})
`apiKey`	string	Yes	Your Zep API key

Output

Parameter	Type	Description
`userId`	string	User identifier
`email`	string	User email address
`firstName`	string	User first name
`lastName`	string	User last name
`uuid`	string	Internal UUID
`createdAt`	string	Creation timestamp (ISO 8601)
`metadata`	object	User metadata (dynamic key-value pairs)

Get User

Retrieve user information from Zep

Input

Parameter	Type	Required	Description
`userId`	string	Yes	User ID to retrieve (e.g., "user_123")
`apiKey`	string	Yes	Your Zep API key

Output

Parameter	Type	Description
`userId`	string	User identifier
`email`	string	User email address
`firstName`	string	User first name
`lastName`	string	User last name
`uuid`	string	Internal UUID
`createdAt`	string	Creation timestamp (ISO 8601)
`updatedAt`	string	Last update timestamp (ISO 8601)
`metadata`	object	User metadata (dynamic key-value pairs)

Get User Threads

List all conversation threads for a specific user

Input

Parameter	Type	Required	Description
`userId`	string	Yes	User ID to get threads for (e.g., "user_123")
`limit`	number	No	Maximum number of threads to return (e.g., 10, 25, 50)
`apiKey`	string	Yes	Your Zep API key

Output

Parameter	Type	Description
`threads`	array	Array of thread objects
↳ `threadId`	string	Thread identifier
↳ `userId`	string	Associated user ID
↳ `uuid`	string	Internal UUID
↳ `createdAt`	string	Creation timestamp (ISO 8601)
↳ `updatedAt`	string	Last update timestamp (ISO 8601)
↳ `projectUuid`	string	Project UUID
↳ `metadata`	object	Custom metadata (dynamic key-value pairs)
`totalCount`	number	Total number of items available

On this page