The previous lecture built the simplest durable memory: a notes file that the agent reads and writes. A notes file holds conclusions, such as "the student struggles with off-by-one errors." It drops the specific events behind those conclusions. This lecture covers episodic memory, which keeps those events. It first covers what an episode should store and how to store it. It then turns to the harder question of which episodes to bring into the context, using recency and relevance.
The lecture continues the tutoring agent from the previous lecture: an agent that helps a student learn to program over many sessions. The complete example is in episodic_memory.py.
Episodic memory stores specific events: what happened, when, and in what context. Each entry records one event, much like an entry in a diary. For the tutoring agent, a few episodes might read:
range(1, n) and missed the last item; a hint about the end value fixed it.while loop ran one time too many; tracing the loop variable found the bug.RecursionError showed why.The notes file says the student struggles with off-by-one errors. The episodes say when each mistake happened, what code caused it, and what fixed it. That last detail lets the agent reuse a hint that worked.
Episodes are also more useful than raw session transcripts. A transcript records everything, including small talk, false starts, and long stretches of code. An episode records only the event that mattered, in a compact and consistent form. A long-running log of episodes gives the agent a rich history of its work with a user, over weeks or months, without the bulk of the transcripts.
The central design decision is what fields one episode holds. A tutoring agent's episode might look like this:
{
"time": "YYYY-MM-DDTHH:MM+00:00",
"session": 4,
"topic": "loops",
"event": "Wrote range(1, n) and missed the last item.",
"outcome": "A hint that range stops before its end value fixed it."
}
Each field serves retrieval:
The outcome field is the one most often left out, and it is the most valuable when a problem recurs.
The right fields depend on the agent. A coding agent might store the file it changed, the command it ran, and the error it saw. Whatever the fields, an episode should be small and structured. Structure is what makes episodes easy to filter, sort, and search later.
The storage format matters less. Episodes can be lines in a JSON file, rows in a database, or separate files on disk with a timestamp in each name. Any of these works, as long as the episodes persist beyond the end of the session.
Episodic and semantic memory are easy to confuse, but they store different things:
| Episodic | Semantic | |
|---|---|---|
| Stores | Events | Facts |
| Timestamp | Yes | No |
| Example | "Session 4: missed the last item with range(1, n); a hint fixed it" |
"The student makes off-by-one errors in loops" |
| Comes from | Recorded as sessions happen | Distilled from many episodes |
An episode is recorded as soon as something happens. Semantic memory comes afterward: it summarizes many events into a fact. The episodes from sessions 4 and 5 support one semantic fact about the student's off-by-one errors. Turning episodes into facts is called consolidation, the subject of the next lecture.
The two kinds of memory work together. A typical agent keeps a notes file for semantic facts, like the one from the previous lecture, and a separate, structured log for episodes. A note is a conclusion the agent writes for itself and reads back as a whole. An episode is a timestamped record of one event, retrieved selectively.
The shared word "semantic" causes a second confusion. Semantic memory means stored facts. Semantic search means searching by meaning with embeddings. The two ideas are unrelated: either kind of memory can be searched either way.
The simplest store is an append-only log with one JSON line per episode. The record function from episodic_memory.py captures the time automatically and appends the episode to the log:
LOG = "episodes.jsonl"
def record(session, topic, event, outcome):
episode = {
"time": datetime.now(timezone.utc).isoformat(timespec="minutes"),
"session": session,
"topic": topic,
"event": event,
"outcome": outcome,
}
with open(LOG, "a") as f:
f.write(json.dumps(episode) + "\n")
The store needs no database and no embeddings. Because the log lives on disk, it survives the end of the session, which is the whole point of memory.
In an agent, record is usually exposed as a tool. The system prompt tells the model when to use it: "When something happens that would be useful to remember, call record_episode." This is the same pattern the previous lecture used for save_note.
Over a semester of tutoring, the log grows to hundreds of episodes. The context can hold only a few. Loading all of them into every session would waste the context and bury the useful ones. Suppose the student opens a session near the end of the semester to study for a final exam. Which episodes should the agent see?
The answer depends on the question the agent is trying to answer. Two kinds of questions come up:
Both matter, and they call for different techniques.
Recency is simple. The log is append-only, so it is already in time order, and the newest episodes are at the end:
def load():
with open(LOG) as f:
return [json.loads(line) for line in f]
def recent(n=3):
return load()[-n:]
At the start of session 7, recent(2) returns the two episodes from session 6. Filters on session or topic work the same way. Recency needs no index and no embeddings, and it covers the most common need: loading the last several episodes at the start of every session, so the agent remembers what it was doing.
Recency has a clear limit. It cannot find an old episode about a problem the student now describes in new words.
A student's question rarely uses the words stored in the episode. The question "Why does my for loop stop one number early?" and the episode "Wrote range(1, n) and missed the last item" describe the same problem with almost no words in common. Keyword search would miss the match. Keyword search is still a valid retrieval method, as Lecture 8.3 showed, and it is cheaper, but it handles different wording poorly.
Embeddings match meaning instead of words. Finding relevant episodes is therefore RAG, exactly as Module 8 described it, with one change: the source is the agent's own history instead of a document collection. Each episode is embedded once. The question is embedded when it arrives, and the closest episodes are returned. The query can be the user's message itself, or a query the model writes. The vectors live in a vector database from Lecture 8.2. ChromaDB stores text, vectors, and metadata together. FAISS is a fast similarity-search library for the vectors alone.
episodic_memory.py builds a ChromaDB index from the log and queries it:
def build_index(episodes):
index = chromadb.Client().get_or_create_collection("episodes")
index.add(
ids=[str(i) for i in range(len(episodes))],
documents=[f"{e['event']} {e['outcome']}" for e in episodes],
)
return index
def relevant(index, episodes, question, k=2):
result = index.query(query_texts=[question], n_results=k)
return [episodes[int(i)] for i in result["ids"][0]]
For the question "Why does my for loop stop one number early?", the index returns the while loop episode from session 5 and the range episode from session 4. Neither contains the words "stop" or "early." ChromaDB embeds text with a small local model by default, so the example runs without an API key. Any embedding model works for a small store. Hosted options include Voyage, Anthropic's recommended partner, and OpenAI's text-embedding-3-small. Vectors from different models cannot be compared, so the index must be rebuilt after a change of model.
The log stays the source of truth, and the vector index is a copy built from it. If the index is lost, or the agent switches embedding models, the index can be rebuilt from the log without losing any memory.
Embeddings are a retrieval choice, not part of the definition of episodic memory. A text log searched by recency and topic is a complete episodic memory. Embeddings are added when the agent needs to find episodes by meaning.
Most memory systems combine several signals to decide what to inject. The Generative Agents paper (Park et al., 2023) scores each memory on three:
Each score is normalized, and the three are added: score = recency + importance + relevance. Relevance alone can rank an old, trivial match above a recent, important event. Recency alone would bury lasting facts: a user's name or goals matter in every session, no matter how long ago they were recorded. Importance is simply one more field stored with each episode.
The same paper adds reflection: the agent periodically reviews recent events and writes higher-level conclusions from them. Reflection is an early form of the consolidation covered in the next lecture. Open-source memory systems such as Mem0 implement these ideas and let developers adjust the weights and strategies.
Module 8 posed a choice for RAG: the developer's code can retrieve before calling the model, or the model can retrieve through a tool. Episodic memory faces the same choice, for both writing and reading:
| Harness | Model | |
|---|---|---|
| Write | Code records each exercise result | A record_episode tool, cued by the system prompt |
| Read | Code loads recent episodes at startup | A recall(question) tool the model calls when needed |
| Strength | Never forgets | Chooses what matters |
| Risk | Records noise | May forget to write or read |
A common split assigns each signal to the side that suits it. Recency fits the harness, because the same step runs at the start of every session: load the last several episodes into the context. Relevance fits a tool, because only the model knows when a question calls for history, and the model can write a good search query. Model writes are selective only when the system prompt says clearly what to record.
An append-only log is easy to write and easy to search, but it only grows. Over months of use, it fills with episodes that no longer matter, facts that later events contradict, and the same lesson recorded many times. Recency and relevance keep each retrieval small, but they do not clean up the store itself. The next lecture covers consolidation: turning episodes into semantic facts, and keeping that semantic memory current.
An episode records one event: when it happened, in what context, what happened, and how it turned out. Choosing those fields is the main design decision. Semantic memory stores facts distilled from many episodes, and it is unrelated to semantic search. An append-only log on disk is enough to store episodes. Recency finds what just happened, and relevance finds related events described in new words. Relevance uses embeddings and a vector database, which makes it RAG over the agent's own past. The harness usually handles recency at startup, while the model uses a tool to search for relevant history.