Episode Tracking

Overview

The EpisodeTracker groups related interactions into coherent episodes, bounded units of activity with a beginning, middle, and end. Episodes preserve the temporal and emotional context that makes episodic recall effective.

Episode Lifecycle

Every episode follows a three-phase lifecycle:

• Create: open a new episode with an optional description and participants
• Update: add memories, update emotional state, record milestones
• Close: finalize the episode, triggering automatic memory creation from the episode summary

Creating an Episode

import { EpisodeTracker } from 'metamemory';

const tracker = new EpisodeTracker(engine);

const episode = await tracker.create({
  description: 'Debugging production Redis connection pool exhaustion',
  userId: 'agent-1',
  participants: ['agent-1', 'agent-2'],
});

Adding Memories to an Episode

await tracker.addMemory(episode.id, {
  content: 'Identified that max pool size was set to 5, needs to be 20+',
  emotions: [{ label: 'insight', intensity: 0.8 }],
});

await tracker.addMemory(episode.id, {
  content: 'Increased pool size to 25 and deployed. Issue resolved.',
  emotions: [{ label: 'satisfaction', intensity: 0.9 }],
});

Emotional Arc Tracking

The tracker automatically records the emotional trajectory across the episode. When the episode is closed, this trajectory is encoded into the 132d emotional embedding for future retrieval:

const arc = await tracker.getEmotionalArc(episode.id);
// [
//   { label: 'frustration', intensity: 0.7, timestamp: ... },
//   { label: 'insight', intensity: 0.8, timestamp: ... },
//   { label: 'satisfaction', intensity: 0.9, timestamp: ... },
// ]

Closing an Episode

When you close an episode, the tracker automatically creates a consolidated memory summarizing the episode, complete with the full emotional trajectory:

await tracker.close(episode.id);
// Creates a summary memory with:
// - Consolidated content from all episode memories
// - Full emotional trajectory embedding
// - Temporal metadata (start, end, duration)