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
-
Sign up for a Zep Cloud account.
-
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
- Ensure that you have a
.env
file in your working directory that includes yourZEP_API_KEY
andOPENAI_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>
1 import os 2 import json 3 import uuid 4 5 from openai import AsyncOpenAI 6 import rich 7 8 from dotenv import load_dotenv 9 from zep_cloud.client import AsyncZep 10 from zep_cloud import Message 11 12 load_dotenv() 13 14 zep = AsyncZep(api_key=os.environ.get("ZEP_API_KEY")) 15 16 oai_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.
1 bot_name = "SupportBot" 2 3 user_name = "Emily" 4 user_id = user_name + str(uuid.uuid4())[:4] 5 session_id = str(uuid.uuid4()) 6 7 await 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 14 await 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.
1 support_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 35 chat_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 74 transactions = [ 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 100 account_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 111 def 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. 131 await 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. 136 for 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 143 for 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.
1 all_user_edges = await zep.graph.edge.get_by_user_id(user_id=user_id) 2 rich.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.
1 memory = await zep.memory.get(session_id=session_id) 2 rich.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>
1 rich.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.
1 r = await zep.graph.search(user_id=user_id, query="Why are there so many goats?", limit=4, scope="edges") 2 rich.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.
1 new_session_id = str(uuid.uuid4()) 2 3 emily_message = "Hi, I can't log in!" 4 5 await 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 9 await zep.memory.add( 10 session_id=new_session_id, 11 messages=[Message(role_type="user", role=user_name, content=emily_message)], 12 )
1 system_message = """ 2 You are a customer support agent. Carefully review the facts about the user below and respond to the user's question. 3 Be helpful and friendly. 4 """ 5 6 memory = await zep.memory.get(session_id=new_session_id) 7 8 messages = [ 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 23 response = await oai_client.chat.completions.create( 24 model="gpt-4o-mini", 25 messages=messages, 26 temperature=0, 27 ) 28 29 print(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.
1 rich.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>