Episode Recording

The EpisodeRecorder class captures task outcomes as structured episodes, enabling memory recall and adapter effectiveness tracking.

Interface

interface Episode {
  id: string
  task: string
  taskType: string
  approach: string
  adapter: string
  outcome: 'success' | 'failure' | 'partial'
  tokensUsed: number
  duration: number
  timestamp: Date
  reflections: string[]
}
 
interface EpisodeRecorder {
  record(episode: Omit<Episode, 'id' | 'timestamp'>): Episode
  query(filter: EpisodeFilter): Episode[]
  getById(id: string): Episode | null
  getRecent(count: number): Episode[]
  getByTaskType(taskType: string): Episode[]
  getStats(): EpisodeStats
}
 
interface EpisodeFilter {
  taskType?: string
  adapter?: string
  outcome?: Episode['outcome']
  since?: Date
  limit?: number
}
 
interface EpisodeStats {
  total: number
  successRate: number
  avgTokens: number
  avgDuration: number
  byAdapter: Record<string, { count: number; successRate: number }>
  byTaskType: Record<string, { count: number; successRate: number }>
}

Recording Flow

task complete
  → gather metrics (tokens, duration)
  → determine outcome
  → generate reflections
  → record(episode)
  → persist via SimpleMem bridge

Episode Fields

Field	Type	Description
`task`	`string`	Description of the task performed
`taskType`	`string`	Category (code, test, refactor, docs, etc.)
`approach`	`string`	Strategy used (direct, iterative, research-first)
`adapter`	`string`	Which adapter/model was used
`outcome`	`enum`	`success`, `failure`, or `partial`
`tokensUsed`	`number`	Total tokens consumed
`duration`	`number`	Wall-clock time in ms
`timestamp`	`Date`	When the episode was recorded
`reflections`	`string[]`	Post-task observations and learnings

Episodes are the atomic unit of memory. Every task execution produces one episode. The reflections field captures qualitative insights that quantitative metrics miss.

Querying Episodes

// Get recent successful code tasks
const episodes = recorder.query({
  taskType: 'code',
  outcome: 'success',
  limit: 10
})
 
// Get adapter performance
const stats = recorder.getStats()
// → { total: 47, successRate: 0.83, byAdapter: { ... } }

Storage

Episodes are persisted through the SimpleMem bridge as JSON-structured entries in the memory store. Each episode is indexed by taskType, adapter, and timestamp for efficient retrieval during memory recall.

Session Brain Ralph Universal