Overview
This node integrates with Zep v3, a cloud-based memory service designed to persist conversation threads for AI agents. It allows storing and retrieving conversational context (threads) associated with users, enabling AI agents to maintain stateful interactions over time.
Common scenarios include:
- Chatbots or virtual assistants that need to remember past conversations.
- AI workflows requiring persistent memory across multiple executions.
- Summarizing or retrieving conversation history for context-aware responses.
Practical examples:
- A customer support bot that recalls previous user issues by loading the full message history.
- An AI assistant that summarizes prior interactions in natural language to provide concise context.
- Clearing conversation memory at the start of a new session to reset context.
Properties
| Name | Meaning |
|---|---|
| Thread ID | Identifier of the thread in Zep v3 (replaces the old sessionId). Used to load or save conversation memory. |
| Context Mode | Determines how the context is loaded: - Mensagens Completas: Loads all messages from the thread (default behavior). - Resumo (Modo Basic): Returns raw context summary similar to basic memory. - Resumo (Natural Language): Requests a natural language summary of the context. |
| User ID | Identifier of the user associated with the thread. Automatically created if it does not exist. |
| Limpar Memória ao Iniciar | If enabled, deletes the thread in Zep before executing the workflow, effectively clearing memory. |
| Input Key | The field name in the input payload used as the user's input when saving memory. |
| Output Key | The field name used to record the agent's response when saving memory. |
| Habilitar Logs de Depuração | Enables debug logging of read/write operations in the n8n logs for troubleshooting purposes. |
Output
The node outputs a single JSON object under the key chat_history containing an array of messages representing the conversation memory. Each message has the structure:
{
"role": "user" | "assistant" | "system",
"content": "string",
"name": "string (optional)"
}
- When using Mensagens Completas, this array contains all messages in the thread.
- When using Resumo (Modo Basic) or Resumo (Natural Language), it contains one summarized message representing the context.
- No binary data output is produced by this node.
Dependencies
- Requires an API key credential for authenticating with the Zep Cloud API.
- Uses the official Zep Cloud SDK (
@getzep/zep-cloud) to interact with the service. - Requires network access to the Zep Cloud API endpoints.
- No additional environment variables are needed beyond the API key credential configured in n8n.
Troubleshooting
- Missing or invalid API key: The node will throw an error if the API key credential is missing or invalid. Ensure the API key is correctly configured.
- Thread not found errors: If the specified thread ID does not exist, the node attempts to create it automatically. If creation fails, verify the thread ID and user ID values.
- User not found errors: The node auto-creates the user if missing. Persistent failures may indicate permission or API issues.
- Empty context or no messages: If no messages exist in the thread, the output will be an empty array. This is expected for new threads.
- Enabling debug logs can help trace issues by providing detailed operation logs in n8n.
- Network connectivity problems or API rate limits may cause request failures; check your network and API usage.