Zep: Give Your AI Agents Long-Term Memory with a Temporal Knowledge Graph

Have you ever chatted with a bot that forgets everything about you the moment you open a new conversation? You spend ages explaining your preferences, your project names, all the important technical details, and the next day it greets you like a total stranger. Super frustrating, right? This happens because, by default, Large Language Models (LLMs) are stateless. They only know what lives inside a single context window. Once a conversation gets long or a new session starts, all that memory is gone.

In this tutorial I want to introduce you to Zep, a memory layer for AI agents that, in my opinion, cleans up the way we give agents "memory" in a really elegant way. It does not just dump raw chat history into a database. Instead, Zep builds something called a temporal knowledge graph. It extracts important facts from your conversations, arranges them into a graph of relationships, and records when each fact became valid and when it changed. When your agent needs context, Zep hands back a relevant summary you can inject straight into the prompt. Practical, and token-efficient.

I will walk you through this from the ground up: why memory matters for agents, how to sign up for Zep Cloud and grab an API key, how to install the SDK, how to create users and sessions, add messages, retrieve memory and context, search the graph, and finally wire it all into a simple chatbot loop that actually remembers you. Every example uses Python so it is easy to follow along. Let us dive in.

Introduction

Why memory matters for AI agents

Picture having a human personal assistant. Their main value is not only that they can answer questions, but that they remember your context. They know you are allergic to peanuts, they know you are working on a database migration project, they know you prefer answers that get straight to the point. An assistant who remembers these things feels far smarter and more personal than one you have to re-brief every single day.

The AI agents we build are the same. Without memory, our agents are just reactive and generic. With long-term memory, an agent can:

• Personalize responses based on interaction history.
• Continue multi-session tasks without the user re-explaining context.
• Make more consistent decisions because it knows prior preferences and facts.
• Reduce token cost, because we do not have to drag the entire long transcript into every request.

That last point is often underestimated. If you are naive and send the whole conversation history to the LLM every single time, your token cost explodes and latency grows as the conversation gets longer. On top of that, there is a hard context window limit. So we need a smart system that picks what is relevant instead of hoarding everything.

What Zep is and how it differs from plain history storage

The most primitive way to give an agent memory is to store the entire array of messages in a database and reload all of them every conversation. Easy, but it does not scale. A second, fairly popular approach is RAG over chat history: we embed each message, store it in a vector store, then retrieve similar messages. Better, but it still pulls raw conversation chunks without understanding which facts actually matter.

Zep takes a smarter approach. Behind the scenes, Zep runs a process it calls extraction and knowledge graph construction. Every time you add a message to Zep, the system will:

Store the raw message in the session history.

Extract entities and facts from that message (for example "Ruby likes coffee without sugar", "the Aurora project deadline is August").

Store those facts as nodes and relationships in the temporal knowledge graph.

Record validity timestamps for the facts, so if the user later says "now I like coffee with sugar", the old fact is marked as no longer valid and a new fact is created.

The word "temporal" is the key here. The world changes, user preferences change, project status changes. Zep stores this time dimension, so your agent not only knows the latest fact but can also trace the history of how facts changed. That is what sets Zep apart from a plain key-value store or ordinary vector search.

When we ask Zep for the context of a session, it returns a concise block of text containing the relevant facts, ready to paste into the system prompt. So our agent gets dense, relevant "memory" without having to read through thousands of tokens of transcript.

Core concepts you need to understand

Before we start coding, here are a few terms that will show up a lot: