Zep

ZepTools enable an Agent to interact with a Zep memory system, providing capabilities to store, retrieve, and search memory data associated with user sessions.

Prerequisites

The following example requires the zep-cloud and openai Python packages and a Zep API key.

uv pip install agno zep-cloud openai

export ZEP_API_KEY=your_api_key

The Agent model uses an OpenAI key, separately from any toolkit provider credentials.

Set OpenAI Key

Set your OPENAI_API_KEY as an environment variable. You can get one from OpenAI.

export OPENAI_API_KEY=sk-***

Example

The following example demonstrates how to create an agent with access to Zep memory:

cookbook/91_tools/zep_tools.py

import time

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.zep import ZepTools

# Initialize the ZepTools
zep_tools = ZepTools(user_id="agno", session_id="agno-session", add_instructions=True)

# Initialize the Agent
agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[zep_tools],
    dependencies={"memory": zep_tools.get_zep_memory(memory_type="context")},
    add_dependencies_to_context=True,
)

# Interact with the Agent so that it can learn about the user
agent.print_response("My name is John Billings")
agent.print_response("I live in NYC")
agent.print_response("I'm going to a concert tomorrow")

# Allow the memories to sync with Zep database
time.sleep(10)

# Refresh the context
agent.dependencies["memory"] = zep_tools.get_zep_memory(memory_type="context")

# Ask the Agent about the user
agent.print_response("What do you know about me?")

Toolkit Params

Parameter	Type	Default	Description
`session_id`	`Optional[str]`	`None`	Optional session ID. Auto-generated if not provided.
`user_id`	`Optional[str]`	`None`	Optional user ID. Auto-generated if not provided.
`api_key`	`Optional[str]`	`None`	Zep API key. If not provided, uses ZEP_API_KEY env var.
`ignore_assistant_messages`	`bool`	`False`	Whether to ignore assistant messages when adding to memory.
`enable_add_zep_message`	`bool`	`True`	Enables the `add_zep_message` tool.
`enable_get_zep_memory`	`bool`	`True`	Enables the `get_zep_memory` tool.
`enable_search_zep_memory`	`bool`	`True`	Enables the `search_zep_memory` tool.
`instructions`	`Optional[str]`	`None`	Custom instructions for using the Zep tools.
`add_instructions`	`bool`	`False`	Whether to add default instructions.
`all`	`bool`	`False`	Enables all tools when set to True.

Toolkit Functions

Function	Description
`add_zep_message`	Adds a message to the current Zep session memory. Takes `role` (str) for the message sender and `content` (str) for the message text. Returns a confirmation or error message.
`get_zep_memory`	Retrieves memory for the current Zep session. Takes optional `memory_type` (str) parameter with options "context" (default) or "messages". Returns the requested memory content or an error.
`search_zep_memory`	Searches the Zep knowledge graph for relevant facts or nodes. Takes `query` (str) to find relevant results and optional `search_scope` (str) parameter with options "edges" (default, for facts) or "nodes". Returns search results or an error message.

The ZepAsyncTools class provides asynchronous versions of the toolkit functions. Its constructor takes plain booleans add_zep_message, get_zep_memory, and search_zep_memory instead of the enable_* names above, and it has no all parameter. Its search_zep_memory also takes scope and limit instead of search_scope.

Developer Resources

Tools