Coding Quickstart

Familiarize yourself with Zep and the Zep Python SDK, culminating in building a simple chatbot.

For an introduction to Zep’s memory layer, Knowledge Graph, and other key concepts, see the Concepts Guide.

A Jupyter notebook version of this guide is available here.

In this guide, we’ll walk through a simple example of how to use Zep Cloud to build a chatbot. We’re going to upload a number of datasets to Zep, building a graph of data about a user.

Then we’ll use the Zep Python SDK to retrieve and search the data.

Finally, we’ll build a simple chatbot that uses Zep to retrieve and search data to respond to a user.

Set up your environment

  1. Sign up for a Zep Cloud account.

  2. Ensure you install required dependencies into your Python environment before running this notebook. See Installing Zep SDKs for more information. Optionally create your environment in a virtualenv.

$pip install zep-cloud openai rich python-dotenv
  1. Ensure that you have a .env file in your working directory that includes your ZEP_API_KEY and OPENAI_API_KEY:

Zep API keys are specific to a project. You can create multiple keys for a single project. Visit Project Settings in the Zep dashboard to manage your API keys.

ZEP_API_KEY=<key>
OPENAI_API_KEY=<key>
1import os
2import json
3import uuid
4
5from openai import AsyncOpenAI
6import rich
7
8from dotenv import load_dotenv
9from zep_cloud.client import AsyncZep
10from zep_cloud import Message
11
12load_dotenv()
13
14zep = AsyncZep(api_key=os.environ.get("ZEP_API_KEY"))
15
16oai_client = AsyncOpenAI(
17    api_key=os.getenv("OPENAI_API_KEY"),
18)

Create User and add a Session

Users in Zep may have one or more chat sessions. These are threads of messages between the user and an agent.

Include the user’s full name and email address when creating a user. This improves Zep’s ability to associate data, such as emails or documents, with a user.

1bot_name = "SupportBot"
2
3user_name = "Emily"
4user_id = user_name + str(uuid.uuid4())[:4]
5session_id = str(uuid.uuid4())
6
7await zep.user.add(
8    user_id=user_id,
9    email=f"{user_name}@painters.com",
10    first_name=user_name,
11    last_name="Painter",
12)
13
14await zep.memory.add_session(
15    user_id=user_id,
16    session_id=session_id,
17)

Datasets

We’re going to use the memory and graph APIs to upload an assortment of data to Zep. These include past dialog with the agent, CRM support cases, and billing data.

1support_cases = [
2    {
3        "subject": "Bug: Magic Pen Tool Drawing Goats Instead of Boats",
4        "messages": [
5            {
6                "role": "user",
7                "content": "Whenever I use the magic pen tool to draw boats, it ends up drawing goats instead.",
8                "timestamp": "2024-03-16T14:20:00Z",
9            },
10            {
11                "role": "support_agent",
12                "content": f"Hi {user_name}, that sounds like a bug! Thanks for reporting it. Could you let me know exactly how you're using the tool when this happens?",
13                "timestamp": "2024-03-16T14:22:00Z",
14            },
15            {
16                "role": "user",
17                "content": "Sure, I select the magic pen, draw a boat shape, and it just replaces the shape with goats.",
18                "timestamp": "2024-03-16T14:25:00Z",
19            },
20            {
21                "role": "support_agent",
22                "content": "Got it! We'll escalate this to our engineering team. In the meantime, you can manually select the boat shape from the options rather than drawing it with the pen.",
23                "timestamp": "2024-03-16T14:27:00Z",
24            },
25            {
26                "role": "user",
27                "content": "Okay, thanks. I hope it gets fixed soon!",
28                "timestamp": "2024-03-16T14:30:00Z",
29            },
30        ],
31        "status": "escalated",
32    },
33]
34
35chat_history = [
36    {
37        "role": "assistant",
38        "name": bot_name,
39        "content": f"Hello {user_name}, welcome to PaintWiz support. How can I assist you today?",
40        "timestamp": "2024-03-15T10:00:00Z",
41    },
42    {
43        "role": "user",
44        "name": user_name,
45        "content": "I'm absolutely furious! Your AI art generation is completely broken!",
46        "timestamp": "2024-03-15T10:02:00Z",
47    },
48    {
49        "role": "assistant",
50        "name": bot_name,
51        "content": f"I'm sorry to hear that you're experiencing issues, {user_name}. Can you please provide more details about what's going wrong?",
52        "timestamp": "2024-03-15T10:03:00Z",
53    },
54    {
55        "role": "user",
56        "name": user_name,
57        "content": "Every time I try to draw mountains, your stupid app keeps turning them into fountains! And what's worse, all the people in my drawings have six fingers! It's ridiculous!",
58        "timestamp": "2024-03-15T10:05:00Z",
59    },
60    {
61        "role": "assistant",
62        "name": bot_name,
63        "content": f"I sincerely apologize for the frustration this is causing you, {user_name}. That certainly sounds like a significant glitch in our system. I understand how disruptive this can be to your artistic process. Can you tell me which specific tool or feature you're using when this occurs?",
64        "timestamp": "2024-03-15T10:06:00Z",
65    },
66    {
67        "role": "user",
68        "name": user_name,
69        "content": "I'm using the landscape generator and the character creator. Both are completely messed up. How could you let this happen?",
70        "timestamp": "2024-03-15T10:08:00Z",
71    },
72]
73
74transactions = [
75    {
76        "date": "2024-07-30",
77        "amount": 99.99,
78        "status": "Success",
79        "account_id": user_id,
80        "card_last_four": "1234",
81    },
82    {
83        "date": "2024-08-30",
84        "amount": 99.99,
85        "status": "Failed",
86        "account_id": user_id,
87        "card_last_four": "1234",
88        "failure_reason": "Card expired",
89    },
90    {
91        "date": "2024-09-15",
92        "amount": 99.99,
93        "status": "Failed",
94        "account_id": user_id,
95        "card_last_four": "1234",
96        "failure_reason": "Card expired",
97    },
98]
99
100account_status = {
101    "user_id": user_id,
102    "account": {
103        "account_id": user_id,
104        "account_status": {
105            "status": "suspended",
106            "reason": "payment failure",
107        },
108    },
109}
110
111def convert_to_zep_messages(chat_history: list[dict[str, str | None]]) -> list[Message]:
112    """
113    Convert chat history to Zep messages.
114
115    Args:
116    chat_history (list): List of dictionaries containing chat messages.
117
118    Returns:
119    list: List of Zep Message objects.
120    """
121    return [
122        Message(
123            role_type=msg["role"],
124            role=msg.get("name", None),
125            content=msg["content"],
126        )
127        for msg in chat_history
128    ]
129
130# Zep's high-level API allows us to add a list of messages to a session.
131await zep.memory.add(
132    session_id=session_id, messages=convert_to_zep_messages(chat_history)
133)
134
135# The lower-level data API allows us to add arbitrary data to a user's Knowledge Graph.
136for tx in transactions:
137    await zep.graph.add(user_id=user_id, data=json.dumps(tx), type="json")
138
139    await zep.graph.add(
140        user_id=user_id, data=json.dumps(account_status), type="json"
141    )
142
143for case in support_cases:
144    await zep.graph.add(user_id=user_id, data=json.dumps(case), type="json")

Wait a minute or two!

We’ve batch uploaded a number of datasets that need to be ingested into Zep’s graph before they can be queried. In ordinary operation, this data would stream into Zep and ingestion latency would be negligible.

Retrieve data from Zep

We’ll start with getting a list of facts, which are stored on the edges of the graph. We’ll see the temporal data associated with facts as well as the graph nodes the fact is related to.

This data is also viewable in the Zep Web application.
1all_user_edges = await zep.graph.edge.get_by_user_id(user_id=user_id)
2rich.print(all_user_edges[:3])
[
    EntityEdge(
        created_at='2025-02-20T20:31:01.769332Z',
        episodes=['0d3a35c7-ebd3-427d-89a6-1a8dabd2df64'],
        expired_at='2025-02-20T20:31:18.742184Z',
        fact='The transaction failed because the card expired.',
        invalid_at='2024-09-15T00:00:00Z',
        name='HAS_FAILURE_REASON',
        source_node_uuid='06c61c00-9101-474f-9bca-42b4308ec378',
        target_node_uuid='07efd834-f07a-4c3c-9b32-d2fd9362afd5',
        uuid_='fb5ee0df-3aa0-44f3-889d-5bb163971b07',
        valid_at='2024-08-30T00:00:00Z',
        graph_id='8e5686fc-f175-4da9-8778-ad8d60fc469a'
    ),
    EntityEdge(
        created_at='2025-02-20T20:31:33.771557Z',
        episodes=['60d1d20e-ed6c-4966-b1da-3f4ca274a524'],
        expired_at=None,
        fact='Emily uses the magic pen tool to draw boats.',
        invalid_at=None,
        name='USES_TOOL',
        source_node_uuid='36f5c5c6-eb16-4ebb-9db0-fd34809482f5',
        target_node_uuid='e337522d-3a62-4c45-975d-904e1ba25667',
        uuid_='f9eb0a98-1624-4932-86ca-be75a3c248e5',
        valid_at='2025-02-20T20:29:40.217412Z',
        graph_id='8e5686fc-f175-4da9-8778-ad8d60fc469a'
    ),
    EntityEdge(
        created_at='2025-02-20T20:30:28.499178Z',
        episodes=['b8e4da4c-dd5e-4c48-bdbc-9e6568cd2d2e'],
        expired_at=None,
        fact="SupportBot understands how disruptive the glitch in the AI art generation can be to Emily's artistic process.",
        invalid_at=None,
        name='UNDERSTANDS',
        source_node_uuid='fd4ab1f0-e19e-40b7-aaec-78bd97571725',
        target_node_uuid='8e5686fc-f175-4da9-8778-ad8d60fc469a',
        uuid_='f8c52a21-e938-46a3-b930-04671d0c018a',
        valid_at='2025-02-20T20:29:39.08846Z',
        graph_id='8e5686fc-f175-4da9-8778-ad8d60fc469a'
    )
]

The high-level memory API provides an easy way to retrieve memory relevant to the current conversation by using the last 4 messages and their proximity to the User node.

The memory.get method is a good starting point for retrieving relevant conversation context. It shortcuts passing recent messages to the graph.search API and returns a context string, raw facts, and historical chat messages, providing everything needed for your agent’s prompts.

1memory = await zep.memory.get(session_id=session_id)
2rich.print(memory.context)
FACTS and ENTITIES represent relevant context to the current conversation.
# These are the most relevant facts and their valid date ranges
# format: FACT (Date range: from - to)
<FACTS>
  - SupportBot understands how disruptive the glitch in the AI art generation can be to Emily's artistic process. (2025-02-20 20:29:39 - present)
  - SupportBot sincerely apologizes to Emily for the frustration caused by the issues with the AI art generation. (2025-02-20 20:29:39 - present)
  - Emily has contacted SupportBot for assistance regarding issues she is experiencing. (2025-02-20 20:29:39 - present)
  - The user Emily reported a bug regarding the magic pen tool drawing goats instead of boats. (2024-03-16 14:20:00 - present)
  - The bug report has been escalated to the engineering team. (2024-03-16 14:27:00 - present)
  - Emily is a user of the AI art generation. (2025-02-20 20:29:39 - present)
  - user has the name of Emily Painter (2025-02-20 20:29:39 - present)
  - Emily5e57 is using the landscape generator. (2025-02-20 20:29:39 - 2025-02-20 20:29:39)
  - user has the id of Emily5e57 (2025-02-20 20:29:39 - present)
  - user has the email of [email protected] (2025-02-20 20:29:39 - present)
  - Emily is furious about the stupid app. (2025-02-20 20:29:39 - present)
  - Emily claims that the AI art generation is completely broken. (2025-02-20 20:29:39 - present)
</FACTS>
# These are the most relevant entities
# ENTITY_NAME: entity summary
<ENTITIES>
  - Emily Painter: Emily Painter contacted PaintWiz support for assistance, where she was welcomed by the support bot that inquired about the specific issues she was facing to provide better help.
  - [email protected]: user with the email of [email protected]
  - Emily5e57: Emily5e57, a user of the PaintWiz AI art generation tool, successfully processed a transaction of $99.99 on July 30, 2024, using a card ending in '1234'. However, she is experiencing
significant frustration with the application due to malfunctions, such as the landscape generator incorrectly transforming mountains into fountains and characters being depicted with six fingers. 
These issues have led her to question the reliability of the tool, and she considers it to be completely broken. Emily has reached out to PaintWiz support for assistance, as these problems are 
severely disrupting her artistic process.
  - PaintWiz support: PaintWiz is an AI art generation platform that provides tools for users to create art. Recently, a user named Emily reported significant issues with the service, claiming that
the AI art generation is not functioning properly. The support bot responded to her concerns, apologizing for the disruption to her artistic process and asking for more details about the specific 
tool or feature she was using. This interaction highlights PaintWiz's commitment to customer support, as they actively seek to assist users with their inquiries and problems related to their 
products.
  - SupportBot: A support agent named Emily addressed a user's report about a bug in a drawing application where the magic pen tool incorrectly produced goats instead of boats. After confirming the
issue, she escalated it to the engineering team and suggested a temporary workaround of manually selecting the boat shape. Meanwhile, SupportBot, a virtual assistant for PaintWiz, also assisted 
another user named Emily who was frustrated with the AI art generation feature, acknowledging her concerns and requesting more details to help resolve the problem.
  - AI art generation: Emily, a user, expressed her frustration regarding the AI art generation, stating that it is completely broken.
  - options: The user reported a bug with the magic pen tool, stating that when attempting to draw boats, the tool instead draws goats. The support agent acknowledged the issue and requested more 
details about how the user was utilizing the tool. The user explained that they select the magic pen and draw a boat shape, but it gets replaced with goats. The support agent confirmed they would 
escalate the issue to the engineering team and suggested that the user manually select the boat shape from the options instead of drawing it with the pen. The user expressed hope for a quick 
resolution.
</ENTITIES>
1rich.print(memory.messages)
[
    Message(
        content='Hello Emily, welcome to PaintWiz support. How can I assist you today?',
        created_at='2025-02-20T20:29:39.08846Z',
        metadata=None,
        role='SupportBot',
        role_type='assistant',
        token_count=0,
        updated_at='0001-01-01T00:00:00Z',
        uuid_='e2b86f93-84d6-4270-adbc-e421f39b6f90'
    ),
    Message(
        content="I'm absolutely furious! Your AI art generation is completely broken!",
        created_at='2025-02-20T20:29:39.08846Z',
        metadata=None,
        role='Emily',
        role_type='user',
        token_count=0,
        updated_at='0001-01-01T00:00:00Z',
        uuid_='ec39e501-6dcc-4f8c-b300-f586d66005d8'
    )
]

We can also use the graph API to search edges/facts for arbitrary text. This API offers more options, including the ability to search node summaries and various re-rankers.

1r = await zep.graph.search(user_id=user_id, query="Why are there so many goats?", limit=4, scope="edges")
2rich.print(r.edges)
[
    EntityEdge(
        created_at='2025-02-20T20:31:33.771566Z',
        episodes=['60d1d20e-ed6c-4966-b1da-3f4ca274a524'],
        expired_at=None,
        fact='The magic pen tool draws goats instead of boats when used by Emily.',
        invalid_at=None,
        name='DRAWS_INSTEAD_OF',
        source_node_uuid='e337522d-3a62-4c45-975d-904e1ba25667',
        target_node_uuid='9814a57f-53a4-4d4a-ad5a-15331858ce18',
        uuid_='022687b6-ae08-4fef-9d6e-17afb07acdea',
        valid_at='2025-02-20T20:29:40.217412Z',
        graph_id='8e5686fc-f175-4da9-8778-ad8d60fc469a'
    ),
    EntityEdge(
        created_at='2025-02-20T20:31:33.771528Z',
        episodes=['60d1d20e-ed6c-4966-b1da-3f4ca274a524'],
        expired_at=None,
        fact='The user Emily reported a bug regarding the magic pen tool drawing goats instead of boats.',
        invalid_at=None,
        name='REPORTED_BY',
        source_node_uuid='36f5c5c6-eb16-4ebb-9db0-fd34809482f5',
        target_node_uuid='cff4e758-d1a4-4910-abe7-20101a1f0d77',
        uuid_='5c3124ec-b4a3-4564-a38f-02338e3db4c4',
        valid_at='2024-03-16T14:20:00Z',
        graph_id='8e5686fc-f175-4da9-8778-ad8d60fc469a'
    ),
    EntityEdge(
        created_at='2025-02-20T20:30:19.910797Z',
        episodes=['ff9eba8b-9e90-4765-a0ce-15eb44410f70'],
        expired_at=None,
        fact='The stupid app generates mountains.',
        invalid_at=None,
        name='GENERATES',
        source_node_uuid='b6e5a0ee-8823-4647-b536-5e6af0ba113a',
        target_node_uuid='43aaf7c9-628c-4bf0-b7cb-02d3e9c1a49c',
        uuid_='3514a3ad-1ed5-42c7-9f70-02834e8904bf',
        valid_at='2025-02-20T20:29:39.08846Z',
        graph_id='8e5686fc-f175-4da9-8778-ad8d60fc469a'
    ),
    EntityEdge(
        created_at='2025-02-20T20:30:19.910816Z',
        episodes=['ff9eba8b-9e90-4765-a0ce-15eb44410f70'],
        expired_at=None,
        fact='The stupid app keeps turning mountains into fountains.',
        invalid_at=None,
        name='TRANSFORMS_INTO',
        source_node_uuid='43aaf7c9-628c-4bf0-b7cb-02d3e9c1a49c',
        target_node_uuid='0c90b42c-2b9f-4998-aa67-cc968f9002d3',
        uuid_='2f113810-3597-47a4-93c5-96d8002366fa',
        valid_at='2025-02-20T20:29:39.08846Z',
        graph_id='8e5686fc-f175-4da9-8778-ad8d60fc469a'
    )
]

Creating a simple Chatbot

In the next cells, Emily starts a new chat session with a support agent and complains that she can’t log in. Our simple chatbot will, given relevant facts retrieved from Zep’s graph, respond accordingly.

Here, the support agent is provided with Emily’s billing information and account status, which Zep retrieves as most relevant to Emily’s login issue.

1new_session_id = str(uuid.uuid4())
2
3emily_message = "Hi, I can't log in!"
4
5await zep.memory.add_session(user_id=user_id, session_id=new_session_id)
6
7# we need to add the Emily's message to the session in order for memory.get to return 
8# relevant facts related to the message 
9await zep.memory.add(
10    session_id=new_session_id,
11    messages=[Message(role_type="user", role=user_name, content=emily_message)],
12)
1system_message = """
2You are a customer support agent. Carefully review the facts about the user below and respond to the user's question. 
3Be helpful and friendly.
4"""
5
6memory = await zep.memory.get(session_id=new_session_id)
7
8messages = [
9    {
10        "role": "system",
11        "content": system_message,
12    },
13    {
14        "role": "assistant",
15        "content": memory.context,
16    },
17    {
18        "role": "user",
19        "content": emily_message,
20    },
21]
22
23response = await oai_client.chat.completions.create(
24    model="gpt-4o-mini",
25    messages=messages,
26    temperature=0,
27)
28
29print(response.choices[0].message.content)
Hi Emily! I'm here to help you. It looks like your account is currently suspended due to a payment failure. This might be the reason you're unable to log in. 
The last transaction on your account failed because the card you were using has expired. If you update your payment information, we can help you get your account reactivated. Would you like assistance with that?

Let’s look at the memory context string Zep retrieved for the above memory.get call.

1rich.print(memory.context)
FACTS and ENTITIES represent relevant context to the current conversation.
# These are the most relevant facts and their valid date ranges
# format: FACT (Date range: from - to)
<FACTS>
  - Account with ID 'Emily1c2e' has a status of 'suspended'. (2025-02-24 23:24:29 - present)
  - user has the id of Emily1c2e (2025-02-24 23:24:29 - present)
  - User with ID 'Emily1c2e' has an account with ID 'Emily1c2e'. (2025-02-24 23:24:29 - present)
  - The bug report has been escalated to the engineering team. (2024-03-16 14:27:00 - present)
  - user has the name of Emily Painter (2025-02-24 23:24:29 - present)
  - Emily is the person being assisted by SupportBot. (2025-02-24 23:24:28 - present)
  - Emily1c2e is using the character creator. (2025-02-24 23:24:28 - present)
  - The reason for the account status 'suspended' is 'payment failure'. (2025-02-24 23:24:29 - present)
  - SupportBot is part of PaintWiz support. (2025-02-24 23:24:28 - present)
  - user has the email of [email protected] (2025-02-24 23:24:29 - present)
  - Emily is a user of PaintWiz. (2025-02-24 23:24:28 - present)
  - The support agent suggested that Emily manually select the boat shape from the options. (2025-02-24 23:24:29 - 
present)
  - All the people in Emily1c2e's drawings have six fingers. (2025-02-24 23:24:28 - present)
  - Emily1c2e is using the landscape generator. (2025-02-24 23:24:28 - present)
  - Emily is a user of the AI art generation. (2025-02-24 23:24:28 - present)
  - Emily states that the AI art generation is completely broken. (2025-02-24 23:24:28 - present)
  - The magic pen tool draws goats instead of boats when used by Emily. (2025-02-24 23:24:29 - present)
  - Emily1c2e tries to draw mountains. (2025-02-24 23:24:28 - present)
</FACTS>
# These are the most relevant entities
# ENTITY_NAME: entity summary
<ENTITIES>
  - goats: In a recent support interaction, a user reported a bug with the magic pen tool in a drawing application,
where attempting to draw boats resulted in the tool drawing goats instead. The user, Emily, described the issue, 
stating that whenever she selects the magic pen and draws a boat shape, it is replaced with a goat shape. The 
support agent acknowledged the problem and confirmed it would be escalated to the engineering team for resolution. 
In the meantime, the agent suggested that Emily could manually select the boat shape from the available options 
instead of using the pen tool. Emily expressed her hope for a quick fix to the issue.
  - failure_reason: Two transactions failed due to expired cards: one on September 15, 2024, and another on August 
30, 2024, for the amount of $99.99 associated with account ID 'Emily1c2e'.
  - status: User account "Emily1c2e" is suspended due to a payment failure. A transaction of $99.99 on September 
15, 2024, failed because the card ending in "1234" had expired. This card had previously been used successfully for
the same amount on July 30, 2024, but a failure on August 30, 2024, resulted in the account's suspension.
  - bug: A user reported a bug with the magic pen tool, stating that when attempting to draw boats, the tool 
instead draws goats. The support agent acknowledged the issue and requested more details about how the user was 
utilizing the tool. The user explained that they select the magic pen and draw a boat shape, but it gets replaced 
with goats. The support agent confirmed the bug and stated that it would be escalated to the engineering team for 
resolution. In the meantime, they suggested that the user manually select the boat shape from the options instead 
of using the pen. The user expressed hope for a quick fix.
  - user_id: Emily reported a bug with the magic pen tool in a drawing application, where attempting to draw boats 
resulted in goats being drawn instead. A support agent acknowledged the issue and requested more details. Emily 
explained her process, and the agent confirmed the bug, stating it would be escalated to the engineering team. As a
temporary workaround, the agent suggested manually selecting the boat shape. Emily expressed hope for a quick 
resolution. Additionally, it was noted that another user, identified as "Emily1c2e," has a suspended account due to
a payment failure.
  - people: Emily is frustrated with the AI art generation feature of PaintWiz, specifically mentioning that the 
people in her drawings are depicted with six fingers, which she finds ridiculous.
  - character creator: Emily is experiencing significant issues with the character creator feature of the app. She 
reports that when using the landscape generator and character creator, the app is malfunctioning, resulting in 
bizarre outcomes such as people in her drawings having six fingers. Emily expresses her frustration, stating that 
the AI art generation is completely broken and is not functioning as expected.
</ENTITIES>
Built with