Episodic Memory

Episodic memory stores experiences from past runs, enabling agents to learn from history and improve over time.

Purpose

Episodic memory captures:

Lessons learned from past runs
Successful strategies
Problems encountered
Contextual patterns

How Learning Works


┌─────────────────────────────────────────────────────────────────────┐
│  Run Completes                                                       │
│       │                                                              │
│       ▼                                                              │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                   Lesson Extraction                          │    │
│  │                                                              │    │
│  │  LLM analyzes the run:                                       │    │
│  │  • What worked well?                                         │    │
│  │  • What problems were encountered?                           │    │
│  │  • What should be remembered for similar situations?         │    │
│  └─────────────────────────────────────────────────────────────┘    │
│       │                                                              │
│       ▼                                                              │
│  Lessons Stored in Episodic Memory                                  │
│       │                                                              │
│  ═════════════════════════════════════════════════════════════════  │
│       │                                                              │
│  Similar Context in Future Run                                       │
│       │                                                              │
│       ▼                                                              │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                   Lesson Retrieval                           │    │
│  │                                                              │    │
│  │  Relevant lessons injected into system prompt                │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Episode Structure


{
  "id": "episode_123",
  "agent_id": "agent_456",
  "run_id": "run_789",
 
  "context": {
    "type": "offboarding",
    "department": "engineering",
    "risk_level": "high"
  },
 
  "lesson": "Engineering departures often have secondary email accounts in monitoring systems (PagerDuty, Datadog) that need to be revoked",
 
  "applicability": ["engineering", "developer", "infrastructure"],
  "importance": 0.85,
 
  "outcome": "success",
  "created_at": "2026-01-15T14:35:00Z"
}

Lesson Retrieval

When a new run starts, relevant lessons are retrieved:


{
  "tool": "memory_search",
  "input": {
    "level": "episodic",
    "context": {
      "type": "offboarding",
      "department": "infrastructure"
    },
    "limit": 5
  },
  "output": {
    "lessons": [
      {
        "lesson": "Check for personal SSH keys in production servers",
        "importance": 0.9,
        "relevance_score": 0.95
      },
      {
        "lesson": "Engineering departures often have secondary email accounts...",
        "importance": 0.85,
        "relevance_score": 0.88
      }
    ]
  }
}

Injection into Prompts

Retrieved lessons are added to the system prompt:


[Original System Prompt]

---
Based on past experience with similar situations:
• Check for personal SSH keys in production servers
• Engineering departures often have secondary email accounts in monitoring systems (PagerDuty, Datadog)
---

Managing Episodes

Viewing Episodes


query GetAgentEpisodes($agentId: ID!) {
  agentEpisodes(agentId: $agentId, limit: 50) {
    id
    context
    lesson
    importance
    outcome
    createdAt
  }
}

Curating Episodes

Remove or downweight unhelpful lessons:


mutation UpdateEpisode($id: ID!, $input: UpdateEpisodeInput!) {
  updateEpisode(id: $id, input: {
    importance: 0.3  # Reduce importance
  }) {
    id
    importance
  }
}

Deleting Episodes


mutation DeleteEpisode($id: ID!) {
  deleteEpisode(id: $id) {
    success
  }
}

Importance Scoring

Lessons are scored by importance (0.0 - 1.0):

Score	Meaning	Retrieval
0.9 - 1.0	Critical	Always include
0.7 - 0.9	High	Include when relevant
0.5 - 0.7	Medium	Include if space allows
0.3 - 0.5	Low	Rarely include
0.0 - 0.3	Minimal	Effectively ignored

Best Practices

Let the System Learn

Don’t disable automatic lesson extraction—it improves agent performance over time.

Review Periodically

Curate episodic memory:

Remove outdated lessons
Adjust importance scores
Merge duplicate lessons

Context Matters

Lessons are retrieved by context similarity. Ensure context tags are accurate for better retrieval.

Outcome Tracking

Track whether lessons led to better outcomes to refine importance scoring.