AI Engineer Roadmap All lessons Interactive Quiz GitHub

Episodic Memory

Intermediate · 7 min read · Updated · By Saurabh Pathak

In short: Episodic memory is a log of the agent's past experiences (what task it tried, what it did, and how it turned out) that it can recall to do better next time.

Play the interactive lesson: Episodic memoryRead on GitHub
On this page
  1. Explain it like I'm new
  2. Watch it
  3. How it works
  4. Code example
  5. When to use it / when not to
  6. Common mistakes
  7. Recap
  8. Interview questions
  9. Go deeper

Level: Intermediate · Reading time: 7 min · Phase: 4 · Agentic AI

Before you start: Long-term Memory and Semantic Memory. You should know how agents save and search information outside the model, and how facts differ from events.

Explain it like I'm new

Last time you assembled flat-pack furniture, you put the doors on before the shelves and had to start over. Next time, you remember that episode and do the shelves first. You're not recalling a general fact; you're recalling a specific event and its lesson.

Agents can do the same. After each task, save a record:

Next time a similar task arrives, the agent looks up similar episodes and adds them to the prompt: "Last time this failed because migrations weren't run." This is the memory side of Reflection; the Reflexion paper stores exactly these kinds of verbal lessons between attempts.

Episodic memory is also gold for you, the developer: it's a record of what the agent did, useful for debugging and evaluation.

Words to know:

Watch it

Episodic memory: A log of what the agent tried and how it turned out.
Episodic memory: A log of what the agent tried and how it turned out.

It plays on a loop. Read the caption in the box, one step at a time. Want to go at your own pace? Step through it with Previous and Next.

How it works

  1. Record at the end of each task (or each attempt): task description, key actions, outcome, timestamp, and an optional lesson. The lesson can come from a reflection step.
  2. Index by task similarity (keywords or embeddings) and time.
  3. Recall the most similar episodes when a new task starts. Prefer recent ones and include both failures (to avoid) and successes (to copy).
  4. Inject a short summary, not the raw logs: "Similar past task: deploy staging → failed. Lesson: migrate first."
  5. Prune old or irrelevant episodes so recall stays useful.
sequenceDiagram
    participant Agent
    participant Episodes as Episodic store
    Agent->>Episodes: recall("deploy to staging")
    Episodes-->>Agent: t=1 failure, lesson "migrate first"
    Agent->>Agent: plan includes "migrate" step
    Agent->>Episodes: record(task, actions, outcome=success)

Worked example

This traces the EpisodicMemory code below (real output).

  1. Attempt 1 at deploy to staging: actions run tests, deploy. It fails. The agent records it with the lesson run migrations before deploy. The record gets time t=1.
  2. Attempt 2 is a different task, write weekly report. It succeeds, so t=2, with no lesson.
  3. Attempt 3 at deploy to staging: this time the agent recalls first. recall("deploy staging") matches only the two deploy episodes, and ranks the newest first. It then adds the migrate step and succeeds (t=3).
  4. Real output of the recall: 3 success ['run tests', 'migrate', 'deploy'] then 1 failure ['run tests', 'deploy'] run migrations before deploy.

The weekly report episode never shows up, because it shares no words with the new task. failures() returns ['run migrations before deploy'].

Code example

From agent_memory.py:

from agent_memory import EpisodicMemory

epi = EpisodicMemory()
epi.record("deploy to staging", ["run tests", "deploy"], "failure", lesson="run migrations before deploy")
epi.record("write weekly report", ["draft"], "success")
epi.record("deploy to staging", ["run tests", "migrate", "deploy"], "success")

for e in epi.recall("deploy staging", k=2):
    print(e["t"], e["outcome"], e["actions"], e["lesson"])
# 3 success ['run tests', 'migrate', 'deploy']
# 1 failure ['run tests', 'deploy'] run migrations before deploy

print([e["lesson"] for e in epi.failures()])   # ['run migrations before deploy']

Turning recalled episodes into prompt text:

def episodes_to_prompt(episodes):
    lines = ["Similar past tasks:"]
    for e in episodes:
        lesson = f" Lesson: {e['lesson']}" if e["lesson"] else ""
        lines.append(f"- {e['task']} -> {e['outcome']} via {', '.join(e['actions'])}.{lesson}")
    return "\n".join(lines)

When to use it / when not to

Common mistakes

Recap

If you remember only three things:

Interview questions

1. What does an episodic memory record usually contain? <details><summary>Answer</summary> The task, the key actions taken, the outcome (success/failure, scores), a timestamp, and optionally a lesson or reflection for next time. </details>

2. How does episodic memory relate to Reflexion? <details><summary>Answer</summary> Reflexion has the agent write verbal reflections after failed attempts and keep them in a memory buffer that is added to the context on later attempts. That buffer is a form of episodic memory. </details>

3. How would you keep episodic memory useful over months? <details><summary>Answer</summary> Retrieve by similarity and recency, store compact summaries rather than raw logs, expire or re-validate old lessons, and de-duplicate repeated episodes. </details>

Go deeper

Prev: Semantic Memory · Next: Agent Loops · Back to phase: Phase 4