Episode Tracking

Overview

The EpisodeTracker groups related interactions into coherent episodes — bounded units of activity with a beginning, middle, and end. Each episode tracks the user's actions, emotional trajectory, decision points, and outcome. When an episode completes, MetaMemory automatically creates memories from it — including episode summaries, key insights, and success patterns.

Episodes are the bridge between raw interactions and structured memory. Without them, every message is isolated. With them, MetaMemory understands that a sequence of 12 messages was a single debugging session that started with confusion, escalated through frustration, and ended with a breakthrough.

Episode Lifecycle

Every episode follows a three-phase lifecycle:

1. Start — An episode begins when a user initiates a task. The system records the episode type, task goal, domain, complexity, and initial emotional state.
2. Track — As the user takes actions, each step is recorded with its outcome (success, failure, partial) and optional reasoning. The system auto-detects emotional state changes based on computational signals like attempt count and failure patterns.
3. Complete — The episode ends when the task is finished or abandoned. MetaMemory records the outcome, calculates duration, runs final emotional state detection, and automatically creates memories from the episode.

Episode Operations

Starting an Episode

To start an episode, provide the episode type (e.g. debugging, research, learning), an optional task goal, domain, complexity (1-10), and initial emotional state. The system returns an episode ID and records the start time.

Tracking Actions

As the user takes actions, each step is recorded with its description, outcome (success, failure, or partial), and optional reasoning. When you provide an outcome, the system auto-detects emotional state from signals like attempt count and failure patterns. You can also provide the emotional state explicitly to override detection.

Completing an Episode

When the task is finished, mark the episode as complete with the outcome, an optional quality score (0-10), user satisfaction (0-1), and key insights. On completion, MetaMemory automatically creates three types of memories:

• Episode summary — A narrative of the full interaction with process sequence metadata
• Key insights — Each insight as an individual memory, tagged with the final emotional state
• Success pattern — The pattern that worked, tagged with a "breakthrough" emotion if one was detected

Active Episode Lookup

You can query for a user's current incomplete episode. Episodes older than 30 minutes are auto-completed with success: false.

Episode Stats

Aggregated statistics are available per user: total episodes, success count, average duration, average quality score, and breakthrough rate (breakthroughs / total episodes).

Emotional Trajectory Tracking

Each episode maintains an emotional journey — a timestamped sequence of emotional state transitions. The system detects six states: confident, uncertain, confused, frustrated, insight, and breakthrough.

Detection is signal-based, not text-based. The system uses computational signals like model entropy, attempt count, failure patterns, and reasoning loops rather than sentiment analysis on the user's words. Each detected state carries a confidence score and intensity score, both bounded to [0, 1].

When the system detects a breakthrough — success after struggle with high attempt count and a prior frustrated state — it records the timestamp as breakthroughMoment. This enables queries like "what was happening right before the user had a breakthrough?"

Episode Data Model

Each episode stores:

• Temporal boundaries — startTime, endTime, calculated duration in seconds
• Context — episodeType, taskGoal, domain, complexity (1-10 scale)
• Emotional trajectory — initialEmotion, finalEmotion, full emotionalJourney array with timestamps and triggers, optional breakthroughMoment
• Process tracking — actionSequence with outcomes, decisionPoints with rationale, failedAttempts, successPattern
• Outcome — wasSuccessful, qualityScore (0-10), userSatisfaction (0-1), keyInsights
• Hierarchy — Episodes can nest via parentEpisodeId for complex multi-step tasks

Auto-Detection

MetaMemory can handle episode lifecycle automatically. When auto-detect is used, the system checks if the user has an active episode older than 30 minutes and auto-completes it if so. Then it either returns the current active episode or starts a new one based on the provided query type and domain. Use this when you don't want to manage episode boundaries manually.