Quickstart

$
git clone https://github.com/getzep/zep.git
>
cd zep/examples/python/agent-memory-full-example

Zep is a context engineering platform that systematically assembles personalized context—user preferences, traits, and business data—for reliable agent applications. Zep combines agent memory, Graph RAG, and context assembly capabilities to deliver comprehensive personalized context that reduces hallucinations and improves accuracy. This quickstart will walk you through Zep’s two core capabilities: giving your agent persistent memory of user interactions through Agent Memory, and providing your agent with up-to-date knowledge through Dynamic Graph RAG.

Make sure to set up your environment before getting started.

Provide your agent with up-to-date user memory (Agent Memory)

Create user graph

1
# Create a new user
2
user_id = "user123"
3
new_user = client.user.add(
4
    user_id=user_id,
5
    email="[email protected]",
6
    first_name="Jane",
7
    last_name="Smith",
8
)

Create thread

1
import uuid
2
3
# Generate a unique thread ID
4
thread_id = uuid.uuid4().hex
5
6
# Create a new thread for the user
7
client.thread.create(
8
    thread_id=thread_id,
9
    user_id=user_id,
10
)

Optional: Customize user summary

You can provide custom instructions for how Zep generates summaries of user data in their knowledge graph. This allows you to tailor the user summary to emphasize information most relevant to your application. Learn more about user summary instructions.

Add messages

Add chat messages to a thread using the thread.add_messages method. These messages will be stored in the thread history and used to build the user’s knowledge graph.

1
# Define messages to add
2
from zep_cloud.types import Message
3
4
messages = [
5
    Message(
6
        name="Jane",
7
        content="Hi, my name is Jane Smith and I work at Acme Corp.",
8
        role="user",
9
    ),
10
    Message(
11
        name="AI Assistant",
12
        content="Hello Jane! Nice to meet you. How can I help you with Acme Corp today?",
13
        role="assistant",
14
    )
15
]
16
17
# Add messages to the thread
18
client.thread.add_messages(thread_id, messages=messages)

Optional: Add business data

You can add business data directly to a user’s graph using the graph.add method. This data can be in the form of messages, text, or JSON.

1
# Add JSON data to a user's graph
2
import json
3
json_data = {
4
    "employee": {
5
        "name": "Jane Smith",
6
        "position": "Senior Software Engineer",
7
        "department": "Engineering",
8
        "projects": ["Project Alpha", "Project Beta"]
9
    }
10
}
11
client.graph.add(
12
    user_id=user_id,
13
    type="json",
14
    data=json.dumps(json_data)
15
)
16
17
# Add text data to a user's graph
18
client.graph.add(
19
    user_id=user_id,
20
    type="text",
21
    data="Jane Smith is working on Project Alpha and Project Beta."
22
)

Retrieve context

Use the thread.get_user_context method to retrieve relevant context for a thread. This includes a context block with a user summary and facts that can be used in your prompt.

The Context Block provides low latency (P95 < 200ms) while preserving detailed information from the user’s graph. Read more about Zep’s context block here.

1
# Get memory for the thread
2
memory = client.thread.get_user_context(thread_id=thread_id)
3
4
# Access the context block (for use in prompts)
5
context_block = memory.context
6
print(context_block)

The Context Block includes a user summary and relevant facts:

# This is the user summary
<USER_SUMMARY>
Emily Painter is a user with account ID Emily0e62 who uses digital art tools for creative work. She maintains an active account with the service, though has recently experienced technical issues with the Magic Pen Tool. Emily values reliable payment processing and seeks prompt resolution for account-related issues. She expects clear communication and efficient support when troubleshooting technical problems.
</USER_SUMMARY>
# These are the most relevant facts and their valid date ranges
# format: FACT (Date range: from - to)
<FACTS>
  - Emily is experiencing issues with logging in. (2024-11-14 02:13:19+00:00 - present)
  - User account Emily0e62 has a suspended status due to payment failure. (2024-11-14 02:03:58+00:00 - present)
  - user has the id of Emily0e62 (2024-11-14 02:03:54 - present)
  - The failed transaction used a card with last four digits 1234. (2024-09-15 00:00:00+00:00 - present)
  - The reason for the transaction failure was 'Card expired'. (2024-09-15 00:00:00+00:00 - present)
  - user has the name of Emily Painter (2024-11-14 02:03:54 - present)
  - Account Emily0e62 made a failed transaction of 99.99. (2024-07-30 00:00:00+00:00 - 2024-08-30 00:00:00+00:00)
</FACTS>

You can also directly search the user graph and assemble the context block for more customized results.

View your knowledge graph

Since you’ve created memory, you can view your knowledge graph by navigating to the Zep Dashboard, then Users > “user123” > View Graph. You can also click the “View Episodes” button to see when data is finished being added to the knowledge graph.

Explore further

Refer to our agent memory walk-through for a more complete example.

Provide your agent with up-to-date knowledge (Dynamic Graph RAG)

Create graph

1
graph = client.graph.create(
2
    graph_id="some-graph-id", 
3
    name="Graph Name",
4
    description="This is a description."
5
)

Add data

You can add business data directly to a graph using the graph.add method. This data can be in the form of text or JSON.

1
# Add JSON data to a graph
2
import json
3
json_data = {
4
    "employee": {
5
        "name": "Jane Smith",
6
        "position": "Senior Software Engineer",
7
        "department": "Engineering",
8
        "projects": ["Project Alpha", "Project Beta"]
9
    }
10
}
11
graph_id = "engineering_team"
12
client.graph.add(
13
    graph_id=graph_id,
14
    type="json",
15
    data=json.dumps(json_data)
16
)
17
18
# Add text data to a graph
19
client.graph.add(
20
    graph_id=graph_id,
21
    type="text",
22
    data="The engineering team is working on Project Alpha and Project Beta."
23
)

Search the graph

Use the graph.search method to search for edges, nodes, or episodes in the graph. This is useful for finding specific information about a user or graph.

1
query = "What projects is Jane working on?"
2
3
# Search for edges in a graph
4
edge_results = client.graph.search(
5
    graph_id=graph_id,
6
    query=query,
7
    scope="edges",  # Default is "edges"
8
    limit=5
9
)
10
11
# Search for nodes in a graph
12
node_results = client.graph.search(
13
    graph_id=graph_id,
14
    query=query,
15
    scope="nodes",
16
    limit=5
17
)
18
19
# Search for episodes in a graph
20
episode_results = client.graph.search(
21
    graph_id=graph_id,
22
    query=query,
23
    scope="episodes",
24
    limit=5
25
)

Assemble context block

Using the search results, you can build a context block to include in your prompts. For a complete example with helper functions and code samples, see our Advanced context block construction cookbook.

View your knowledge graph

Since you’ve created memory, you can view your knowledge graph by navigating to the Zep Dashboard, then Users > “user123” > View Graph. You can also click the “View Episodes” button to see when data is finished being added to the knowledge graph.

Use Zep as an Agentic Tool

Zep’s memory retrieval methods can be used as agentic tools, enabling your agent to query Zep for relevant information. The example below shows how to create a LangChain LangGraph tool to search for facts in a user’s graph.

1
from zep_cloud.client import AsyncZep
2
3
from langchain_core.tools import tool
4
from langchain_openai import ChatOpenAI
5
from langgraph.graph import StateGraph, MessagesState
6
from langgraph.prebuilt import ToolNode
7
8
zep = AsyncZep(api_key=os.environ.get('ZEP_API_KEY'))
9
10
@tool
11
async def search_facts(state: MessagesState, query: str, limit: int = 5):
12
    """Search for facts in all conversations had with a user.
13
    
14
    Args:
15
        state (MessagesState): The Agent's state.
16
        query (str): The search query.
17
        limit (int): The number of results to return. Defaults to 5.
18
    Returns:
19
        list: A list of facts that match the search query.
20
    """
21
    search_results = await zep.graph.search(
22
      user_id=state['user_name'], 
23
      query=query, 
24
      limit=limit, 
25
    )
26
27
    return [edge.fact for edge in search_results.edges]
28
29
tools = [search_facts]
30
tool_node = ToolNode(tools)
31
llm = ChatOpenAI(model='gpt-4o-mini', temperature=0).bind_tools(tools)

Next Steps

Now that you’ve learned the basics of using Zep, you can:

• Learn more about Key Concepts
• Explore the Graph API for adding and retrieving data
• Understand Users and Threads in more detail
• Learn about our Context Block for building better prompts
• Explore Graph Search for advanced search capabilities