claude-brain 0.30.2 → 0.30.3

package/src/memory/episodic/manager.ts

@@ -1,351 +1,347 @@
-/**
- * Episode Manager
- * Manages episode lifecycle with ChromaDB persistence
- */
-
-import { randomUUID } from 'crypto'
-import type { Logger } from 'pino'
-import type { CollectionManager } from '../chroma/collection-manager'
-import type { EmbeddingProvider } from '../chroma/embeddings'
-import type { Episode, EpisodeMessage } from './types'
-import { SessionDetector, type DetectorOptions } from './detector'
-import { ExtractiveSummarizer } from './summarizer'
-
-export class EpisodeManager {
-  private logger: Logger
-  private collections: CollectionManager
-  private embeddings?: EmbeddingProvider
-  private detector: SessionDetector
-  private summarizer: ExtractiveSummarizer
-  private activeEpisodes: Map<string, Episode> = new Map() // project → episode
-
-  constructor(
-    logger: Logger,
-    collections: CollectionManager,
-    embeddings?: EmbeddingProvider,
-    detectorOptions?: DetectorOptions
-  ) {
-    this.logger = logger.child({ component: 'episode-manager' })
-    this.collections = collections
-    this.embeddings = embeddings
-    this.detector = new SessionDetector(detectorOptions)
-    this.summarizer = new ExtractiveSummarizer()
-  }
-
-  async startEpisode(project?: string): Promise<Episode> {
-    const now = new Date().toISOString()
-    const episode: Episode = {
-      id: randomUUID(),
-      project,
-      status: 'active',
-      started_at: now,
-      messages: [],
-      related_decisions: [],
-      related_patterns: [],
-      related_corrections: [],
-      token_count: 0,
-      message_count: 0
-    }
-
-    const key = project || '__global__'
-    this.activeEpisodes.set(key, episode)
-    this.logger.info({ episodeId: episode.id, project }, 'Episode started')
-    return episode
-  }
-
-  async endEpisode(episodeId: string): Promise<Episode | null> {
-    // Find the episode
-    let episode: Episode | null = null
-    let key: string | null = null
-
-    for (const [k, ep] of this.activeEpisodes) {
-      if (ep.id === episodeId) {
-        episode = ep
-        key = k
-        break
-      }
-    }
-
-    if (!episode || !key) {
-      this.logger.warn({ episodeId }, 'Episode not found in active episodes')
-      return null
-    }
-
-    episode.status = 'completed'
-    episode.ended_at = new Date().toISOString()
-
-    // Generate summary
-    if (episode.messages.length > 0) {
-      episode.summary = this.summarizer.summarize(episode)
-    }
-
-    // Persist to ChromaDB
-    await this.persistEpisode(episode)
-
-    this.activeEpisodes.delete(key)
-    this.logger.info({ episodeId, messageCount: episode.message_count }, 'Episode ended')
-    return episode
-  }
-
-  async addMessage(episodeId: string, message: EpisodeMessage): Promise<void> {
-    for (const episode of this.activeEpisodes.values()) {
-      if (episode.id === episodeId) {
-        episode.messages.push(message)
-        episode.message_count++
-        episode.token_count += message.token_estimate || Math.ceil(message.content.length / 4)
-        return
-      }
-    }
-
-    this.logger.warn({ episodeId }, 'Episode not found for adding message')
-  }
-
-  async processMessage(
-    message: EpisodeMessage,
-    project?: string
-  ): Promise<{ episode: Episode; classification: string }> {
-    const key = project || '__global__'
-    const activeEpisode = this.activeEpisodes.get(key)
-
-    const lastActivity = activeEpisode
-      ? (activeEpisode.messages.length > 0
-        ? activeEpisode.messages[activeEpisode.messages.length - 1]?.timestamp
-        : activeEpisode.started_at)
-      : undefined
-
-    const recentMessages = activeEpisode
-      ? activeEpisode.messages.slice(-5)
-      : undefined
-
-    const classification = this.detector.classifyMessage(message, lastActivity, recentMessages)
-
-    if (classification === 'new_session') {
-      // End current episode if exists
-      if (activeEpisode) {
-        await this.endEpisode(activeEpisode.id)
-      }
-      // Start new episode
-      const episode = await this.startEpisode(project)
-      await this.addMessage(episode.id, message)
-      return { episode, classification }
-    }
-
-    // continuation or topic_shift: add to current episode
-    if (activeEpisode) {
-      await this.addMessage(activeEpisode.id, message)
-      return { episode: activeEpisode, classification }
-    }
-
-    // No active episode, start new one
-    const episode = await this.startEpisode(project)
-    await this.addMessage(episode.id, message)
-    return { episode, classification: 'new_session' }
-  }
-
-  getActiveEpisode(project?: string): Episode | undefined {
-    const key = project || '__global__'
-    return this.activeEpisodes.get(key)
-  }
-
-  async getRecentEpisodes(project?: string, limit: number = 10): Promise<Episode[]> {
-    try {
-      const collection = await this.collections.getEpisodes()
-
-      const where: any = {}
-      if (project) {
-        where.project = { $eq: project }
-      }
-
-      const results = await collection.get({
-        where: Object.keys(where).length > 0 ? where : undefined,
-        include: ['documents', 'metadatas'],
-        limit
-      })
-
-      return results.ids.map((id, i) => {
-        const metadata = results.metadatas?.[i] as Record<string, any>
-        return this.metadataToEpisode(id, metadata, results.documents?.[i] as string)
-      }).sort((a, b) => b.started_at.localeCompare(a.started_at))
-
-    } catch (error) {
-      this.logger.error({ error }, 'Failed to get recent episodes')
-      return []
-    }
-  }
-
-  async searchEpisodes(query: string, project?: string, limit: number = 5): Promise<Episode[]> {
-    try {
-      const collection = await this.collections.getEpisodes()
-
-      const where: any = project ? { project: { $eq: project } } : undefined
-
-      let results: any
-
-      if (this.embeddings) {
-        const embedding = await this.embeddings.generate(query)
-        results = await collection.query({
-          queryEmbeddings: [embedding],
-          nResults: limit,
-          where,
-          include: ['documents', 'metadatas', 'distances']
-        })
-      } else {
-        results = await collection.query({
-          queryTexts: [query],
-          nResults: limit,
-          where,
-          include: ['documents', 'metadatas', 'distances']
-        })
-      }
-
-      if (!results.ids || results.ids[0]?.length === 0) return []
-
-      return results.ids[0].map((id: string, i: number) => {
-        const metadata = results.metadatas?.[0]?.[i] as Record<string, any>
-        return this.metadataToEpisode(id, metadata, results.documents?.[0]?.[i] as string)
-      })
-
-    } catch (error) {
-      this.logger.error({ error, query }, 'Failed to search episodes')
-      return []
-    }
-  }
-
-  async getEpisode(episodeId: string): Promise<Episode | null> {
-    // Check active episodes first
-    for (const episode of this.activeEpisodes.values()) {
-      if (episode.id === episodeId) return episode
-    }
-
-    // Check ChromaDB
-    try {
-      const collection = await this.collections.getEpisodes()
-      const result = await collection.get({
-        ids: [episodeId],
-        include: ['documents', 'metadatas']
-      })
-
-      if (result.ids.length === 0) return null
-
-      const metadata = result.metadatas?.[0] as Record<string, any>
-      return this.metadataToEpisode(episodeId, metadata, result.documents?.[0] as string)
-    } catch (error) {
-      this.logger.error({ error, episodeId }, 'Failed to get episode')
-      return null
-    }
-  }
-
-  linkDecision(episodeId: string, decisionId: string): void {
-    for (const episode of this.activeEpisodes.values()) {
-      if (episode.id === episodeId) {
-        if (!episode.related_decisions.includes(decisionId)) {
-          episode.related_decisions.push(decisionId)
-        }
-        return
-      }
-    }
-  }
-
-  linkPattern(episodeId: string, patternId: string): void {
-    for (const episode of this.activeEpisodes.values()) {
-      if (episode.id === episodeId) {
-        if (!episode.related_patterns.includes(patternId)) {
-          episode.related_patterns.push(patternId)
-        }
-        return
-      }
-    }
-  }
-
-  linkCorrection(episodeId: string, correctionId: string): void {
-    for (const episode of this.activeEpisodes.values()) {
-      if (episode.id === episodeId) {
-        if (!episode.related_corrections.includes(correctionId)) {
-          episode.related_corrections.push(correctionId)
-        }
-        return
-      }
-    }
-  }
-
-  /**
-   * Remove a decision reference from all active episodes.
-   * Called when a decision is deleted to prevent stale references.
-   */
-  unlinkDecision(decisionId: string): void {
-    for (const episode of this.activeEpisodes.values()) {
-      const idx = episode.related_decisions.indexOf(decisionId)
-      if (idx !== -1) {
-        episode.related_decisions.splice(idx, 1)
-        this.logger.debug(
-          { episodeId: episode.id, decisionId },
-          'Decision unlinked from episode'
-        )
-      }
-    }
-  }
-
-  private async persistEpisode(episode: Episode): Promise<void> {
-    try {
-      const collection = await this.collections.getEpisodes()
-
-      const summaryText = episode.summary
-        ? `${episode.summary.brief}\n\nTopics: ${episode.summary.key_topics.join(', ')}\n\n${episode.summary.detailed}`
-        : `Episode with ${episode.message_count} messages`
-
-      const metadata: Record<string, any> = {
-        episode_id: episode.id,
-        project: episode.project || '',
-        status: episode.status,
-        started_at: episode.started_at,
-        ended_at: episode.ended_at || '',
-        message_count: episode.message_count,
-        token_count: episode.token_count,
-        key_topics: episode.summary?.key_topics.join(',') || '',
-        brief_summary: episode.summary?.brief || '',
-        related_decisions: episode.related_decisions.join(','),
-        related_patterns: episode.related_patterns.join(','),
-        related_corrections: episode.related_corrections.join(',')
-      }
-
-      const embeddings = this.embeddings
-        ? [await this.embeddings.generate(summaryText)]
-        : undefined
-
-      await collection.add({
-        ids: [episode.id],
-        documents: [summaryText],
-        metadatas: [metadata],
-        ...(embeddings ? { embeddings } : {})
-      })
-
-      this.logger.debug({ episodeId: episode.id }, 'Episode persisted to ChromaDB')
-    } catch (error) {
-      this.logger.error({ error, episodeId: episode.id }, 'Failed to persist episode')
-    }
-  }
-
-  private metadataToEpisode(id: string, metadata: Record<string, any>, document?: string): Episode {
-    return {
-      id,
-      project: metadata.project || undefined,
-      status: metadata.status || 'completed',
-      started_at: metadata.started_at || '',
-      ended_at: metadata.ended_at || undefined,
-      messages: [],
-      summary: metadata.brief_summary ? {
-        brief: metadata.brief_summary,
-        detailed: document || metadata.brief_summary,
-        key_topics: (metadata.key_topics || '').split(',').filter(Boolean),
-        decisions_made: [],
-        unresolved_questions: [],
-        entity_count: 0
-      } : undefined,
-      related_decisions: (metadata.related_decisions || '').split(',').filter(Boolean),
-      related_patterns: (metadata.related_patterns || '').split(',').filter(Boolean),
-      related_corrections: (metadata.related_corrections || '').split(',').filter(Boolean),
-      token_count: metadata.token_count || 0,
-      message_count: metadata.message_count || 0
-    }
-  }
-}
+/**
+ * Episode Manager
+ * Manages episode lifecycle with ChromaDB persistence
+ */
+
+import { randomUUID } from 'crypto'
+import type { Where } from 'chromadb'
+import type { Logger } from 'pino'
+import type { CollectionManager } from '../chroma/collection-manager'
+import type { EmbeddingProvider } from '../chroma/embeddings'
+import type { Episode, EpisodeMessage } from './types'
+import { SessionDetector, type DetectorOptions } from './detector'
+import { ExtractiveSummarizer } from './summarizer'
+
+export class EpisodeManager {
+  private logger: Logger
+  private collections: CollectionManager
+  private embeddings?: EmbeddingProvider
+  private detector: SessionDetector
+  private summarizer: ExtractiveSummarizer
+  private activeEpisodes: Map<string, Episode> = new Map() // project → episode
+
+  constructor(
+    logger: Logger,
+    collections: CollectionManager,
+    embeddings?: EmbeddingProvider,
+    detectorOptions?: DetectorOptions
+  ) {
+    this.logger = logger.child({ component: 'episode-manager' })
+    this.collections = collections
+    this.embeddings = embeddings
+    this.detector = new SessionDetector(detectorOptions)
+    this.summarizer = new ExtractiveSummarizer()
+  }
+
+  async startEpisode(project?: string): Promise<Episode> {
+    const now = new Date().toISOString()
+    const episode: Episode = {
+      id: randomUUID(),
+      project,
+      status: 'active',
+      started_at: now,
+      messages: [],
+      related_decisions: [],
+      related_patterns: [],
+      related_corrections: [],
+      token_count: 0,
+      message_count: 0
+    }
+
+    const key = project || '__global__'
+    this.activeEpisodes.set(key, episode)
+    this.logger.info({ episodeId: episode.id, project }, 'Episode started')
+    return episode
+  }
+
+  async endEpisode(episodeId: string): Promise<Episode | null> {
+    // Find the episode
+    let episode: Episode | null = null
+    let key: string | null = null
+
+    for (const [k, ep] of this.activeEpisodes) {
+      if (ep.id === episodeId) {
+        episode = ep
+        key = k
+        break
+      }
+    }
+
+    if (!episode || !key) {
+      this.logger.warn({ episodeId }, 'Episode not found in active episodes')
+      return null
+    }
+
+    episode.status = 'completed'
+    episode.ended_at = new Date().toISOString()
+
+    // Generate summary
+    if (episode.messages.length > 0) {
+      episode.summary = this.summarizer.summarize(episode)
+    }
+
+    // Persist to ChromaDB
+    await this.persistEpisode(episode)
+
+    this.activeEpisodes.delete(key)
+    this.logger.info({ episodeId, messageCount: episode.message_count }, 'Episode ended')
+    return episode
+  }
+
+  async addMessage(episodeId: string, message: EpisodeMessage): Promise<void> {
+    for (const episode of this.activeEpisodes.values()) {
+      if (episode.id === episodeId) {
+        episode.messages.push(message)
+        episode.message_count++
+        episode.token_count += message.token_estimate || Math.ceil(message.content.length / 4)
+        return
+      }
+    }
+
+    this.logger.warn({ episodeId }, 'Episode not found for adding message')
+  }
+
+  async processMessage(
+    message: EpisodeMessage,
+    project?: string
+  ): Promise<{ episode: Episode; classification: string }> {
+    const key = project || '__global__'
+    const activeEpisode = this.activeEpisodes.get(key)
+
+    const lastActivity = activeEpisode
+      ? (activeEpisode.messages.length > 0
+        ? activeEpisode.messages[activeEpisode.messages.length - 1]?.timestamp
+        : activeEpisode.started_at)
+      : undefined
+
+    const recentMessages = activeEpisode
+      ? activeEpisode.messages.slice(-5)
+      : undefined
+
+    const classification = this.detector.classifyMessage(message, lastActivity, recentMessages)
+
+    if (classification === 'new_session') {
+      // End current episode if exists
+      if (activeEpisode) {
+        await this.endEpisode(activeEpisode.id)
+      }
+      // Start new episode
+      const episode = await this.startEpisode(project)
+      await this.addMessage(episode.id, message)
+      return { episode, classification }
+    }
+
+    // continuation or topic_shift: add to current episode
+    if (activeEpisode) {
+      await this.addMessage(activeEpisode.id, message)
+      return { episode: activeEpisode, classification }
+    }
+
+    // No active episode, start new one
+    const episode = await this.startEpisode(project)
+    await this.addMessage(episode.id, message)
+    return { episode, classification: 'new_session' }
+  }
+
+  getActiveEpisode(project?: string): Episode | undefined {
+    const key = project || '__global__'
+    return this.activeEpisodes.get(key)
+  }
+
+  async getRecentEpisodes(project?: string, limit: number = 10): Promise<Episode[]> {
+    try {
+      const collection = await this.collections.getEpisodes()
+
+      const where: Where | undefined = project
+        ? { project: { $eq: project } } as Where
+        : undefined
+
+      const results = await collection.get({
+        where,
+        include: ['documents', 'metadatas'],
+        limit
+      })
+
+      return results.ids.map((id, i) => {
+        const metadata = results.metadatas?.[i] as Record<string, unknown>
+        return this.metadataToEpisode(id, metadata, results.documents?.[i] as string)
+      }).sort((a, b) => b.started_at.localeCompare(a.started_at))
+
+    } catch (error) {
+      this.logger.error({ error }, 'Failed to get recent episodes')
+      return []
+    }
+  }
+
+  async searchEpisodes(query: string, project?: string, limit: number = 5): Promise<Episode[]> {
+    try {
+      const collection = await this.collections.getEpisodes()
+
+      const where: Where | undefined = project ? { project: { $eq: project } } as Where : undefined
+
+      const results = this.embeddings
+        ? await collection.query({
+            queryEmbeddings: [await this.embeddings.generate(query)],
+            nResults: limit,
+            where,
+            include: ['documents', 'metadatas', 'distances']
+          })
+        : await collection.query({
+            queryTexts: [query],
+            nResults: limit,
+            where,
+            include: ['documents', 'metadatas', 'distances']
+          })
+
+      const resultIds = results.ids?.[0]
+      if (!resultIds || resultIds.length === 0) return []
+
+      return resultIds.map((id: string, i: number) => {
+        const metadata = results.metadatas?.[0]?.[i] as Record<string, unknown>
+        return this.metadataToEpisode(id, metadata, results.documents?.[0]?.[i] as string)
+      })
+
+    } catch (error) {
+      this.logger.error({ error, query }, 'Failed to search episodes')
+      return []
+    }
+  }
+
+  async getEpisode(episodeId: string): Promise<Episode | null> {
+    // Check active episodes first
+    for (const episode of this.activeEpisodes.values()) {
+      if (episode.id === episodeId) return episode
+    }
+
+    // Check ChromaDB
+    try {
+      const collection = await this.collections.getEpisodes()
+      const result = await collection.get({
+        ids: [episodeId],
+        include: ['documents', 'metadatas']
+      })
+
+      if (result.ids.length === 0) return null
+
+      const metadata = result.metadatas?.[0] as Record<string, unknown>
+      return this.metadataToEpisode(episodeId, metadata, result.documents?.[0] as string)
+    } catch (error) {
+      this.logger.error({ error, episodeId }, 'Failed to get episode')
+      return null
+    }
+  }
+
+  linkDecision(episodeId: string, decisionId: string): void {
+    for (const episode of this.activeEpisodes.values()) {
+      if (episode.id === episodeId) {
+        if (!episode.related_decisions.includes(decisionId)) {
+          episode.related_decisions.push(decisionId)
+        }
+        return
+      }
+    }
+  }
+
+  linkPattern(episodeId: string, patternId: string): void {
+    for (const episode of this.activeEpisodes.values()) {
+      if (episode.id === episodeId) {
+        if (!episode.related_patterns.includes(patternId)) {
+          episode.related_patterns.push(patternId)
+        }
+        return
+      }
+    }
+  }
+
+  linkCorrection(episodeId: string, correctionId: string): void {
+    for (const episode of this.activeEpisodes.values()) {
+      if (episode.id === episodeId) {
+        if (!episode.related_corrections.includes(correctionId)) {
+          episode.related_corrections.push(correctionId)
+        }
+        return
+      }
+    }
+  }
+
+  /**
+   * Remove a decision reference from all active episodes.
+   * Called when a decision is deleted to prevent stale references.
+   */
+  unlinkDecision(decisionId: string): void {
+    for (const episode of this.activeEpisodes.values()) {
+      const idx = episode.related_decisions.indexOf(decisionId)
+      if (idx !== -1) {
+        episode.related_decisions.splice(idx, 1)
+        this.logger.debug(
+          { episodeId: episode.id, decisionId },
+          'Decision unlinked from episode'
+        )
+      }
+    }
+  }
+
+  private async persistEpisode(episode: Episode): Promise<void> {
+    try {
+      const collection = await this.collections.getEpisodes()
+
+      const summaryText = episode.summary
+        ? `${episode.summary.brief}\n\nTopics: ${episode.summary.key_topics.join(', ')}\n\n${episode.summary.detailed}`
+        : `Episode with ${episode.message_count} messages`
+
+      const metadata: Record<string, string | number | boolean> = {
+        episode_id: episode.id,
+        project: episode.project || '',
+        status: episode.status,
+        started_at: episode.started_at,
+        ended_at: episode.ended_at || '',
+        message_count: episode.message_count,
+        token_count: episode.token_count,
+        key_topics: episode.summary?.key_topics.join(',') || '',
+        brief_summary: episode.summary?.brief || '',
+        related_decisions: episode.related_decisions.join(','),
+        related_patterns: episode.related_patterns.join(','),
+        related_corrections: episode.related_corrections.join(',')
+      }
+
+      const embeddings = this.embeddings
+        ? [await this.embeddings.generate(summaryText)]
+        : undefined
+
+      await collection.add({
+        ids: [episode.id],
+        documents: [summaryText],
+        metadatas: [metadata],
+        ...(embeddings ? { embeddings } : {})
+      })
+
+      this.logger.debug({ episodeId: episode.id }, 'Episode persisted to ChromaDB')
+    } catch (error) {
+      this.logger.error({ error, episodeId: episode.id }, 'Failed to persist episode')
+    }
+  }
+
+  private metadataToEpisode(id: string, metadata: Record<string, unknown>, document?: string): Episode {
+    return {
+      id,
+      project: (metadata.project as string) || undefined,
+      status: (metadata.status === 'active' ? 'active' : 'completed'),
+      started_at: (metadata.started_at as string) || '',
+      ended_at: (metadata.ended_at as string) || undefined,
+      messages: [],
+      summary: metadata.brief_summary ? {
+        brief: metadata.brief_summary as string,
+        detailed: document || (metadata.brief_summary as string),
+        key_topics: String(metadata.key_topics || '').split(',').filter(Boolean),
+        decisions_made: [],
+        unresolved_questions: [],
+        entity_count: 0
+      } : undefined,
+      related_decisions: String(metadata.related_decisions || '').split(',').filter(Boolean),
+      related_patterns: String(metadata.related_patterns || '').split(',').filter(Boolean),
+      related_corrections: String(metadata.related_corrections || '').split(',').filter(Boolean),
+      token_count: (metadata.token_count as number) || 0,
+      message_count: (metadata.message_count as number) || 0
+    }
+  }
+}