claude-brain 0.14.2 → 0.14.4

package/src/hooks/session-tracker.ts

@@ -1,275 +1,275 @@
-/**
- * Phase 17: Session Tracker
- * Server-side session tracking that maintains state across hook invocations.
- * Buffers CapturedKnowledge items and generates session summaries on idle/stop.
- */
-
-import type { Logger } from 'pino'
-import type { EpisodeManager } from '@/memory/episodic/manager'
-import type { MemoryManager } from '@/memory'
-import { ExtractiveSummarizer } from '@/memory/episodic/summarizer'
-import type { CapturedKnowledge } from './types'
-import type { HooksConfig } from '@/config/schema'
-
-interface SessionState {
-  sessionId: string
-  project?: string
-  items: CapturedKnowledge[]
-  startedAt: string
-  lastActivityAt: string
-  episodeId?: string
-}
-
-export class HookSessionTracker {
-  private logger: Logger
-  private episodeManager: EpisodeManager | null
-  private memoryManager: MemoryManager | null
-  private summarizer: ExtractiveSummarizer
-  private sessions: Map<string, SessionState> = new Map()
-  private idleTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
-  private idleTimeoutMs: number
-  private minEventsForSummary: number
-
-  constructor(
-    logger: Logger,
-    episodeManager: EpisodeManager | null,
-    config?: HooksConfig['sessions'],
-    memoryManager?: MemoryManager | null
-  ) {
-    this.logger = logger.child({ component: 'hook-session-tracker' })
-    this.episodeManager = episodeManager
-    this.memoryManager = memoryManager ?? null
-    this.summarizer = new ExtractiveSummarizer()
-    this.idleTimeoutMs = (config?.idleTimeoutMinutes ?? 30) * 60 * 1000
-    this.minEventsForSummary = config?.minEventsForSummary ?? 3
-  }
-
-  /**
-   * Track a captured knowledge item within a session.
-   */
-  async track(sessionId: string, knowledge: CapturedKnowledge): Promise<void> {
-    let session = this.sessions.get(sessionId)
-
-    if (!session) {
-      session = {
-        sessionId,
-        project: knowledge.project,
-        items: [],
-        startedAt: new Date().toISOString(),
-        lastActivityAt: new Date().toISOString(),
-      }
-      this.sessions.set(sessionId, session)
-
-      // Start episode if manager available
-      if (this.episodeManager) {
-        try {
-          const episode = await this.episodeManager.startEpisode(knowledge.project)
-          session.episodeId = episode.id
-        } catch (err) {
-          this.logger.warn({ err }, 'Failed to start episode for session')
-        }
-      }
-    }
-
-    session.items.push(knowledge)
-    session.lastActivityAt = new Date().toISOString()
-
-    // Reset idle timer
-    this.resetIdleTimer(sessionId)
-  }
-
-  /**
-   * End a session immediately (triggered by Stop hook event).
-   */
-  async endSession(sessionId: string): Promise<void> {
-    const session = this.sessions.get(sessionId)
-    if (!session) return
-
-    this.clearIdleTimer(sessionId)
-    await this.summarizeAndPersist(session)
-    this.sessions.delete(sessionId)
-  }
-
-  /**
-   * End all active sessions (for server shutdown).
-   */
-  async endAllSessions(): Promise<void> {
-    const sessionIds = Array.from(this.sessions.keys())
-    for (const id of sessionIds) {
-      await this.endSession(id)
-    }
-  }
-
-  /**
-   * Get stats about tracked sessions.
-   */
-  getStats(): { activeSessions: number; totalItems: number } {
-    let totalItems = 0
-    for (const session of this.sessions.values()) {
-      totalItems += session.items.length
-    }
-    return { activeSessions: this.sessions.size, totalItems }
-  }
-
-  private resetIdleTimer(sessionId: string): void {
-    this.clearIdleTimer(sessionId)
-    const timer = setTimeout(() => {
-      this.onIdle(sessionId)
-    }, this.idleTimeoutMs)
-    this.idleTimers.set(sessionId, timer)
-  }
-
-  private clearIdleTimer(sessionId: string): void {
-    const existing = this.idleTimers.get(sessionId)
-    if (existing) {
-      clearTimeout(existing)
-      this.idleTimers.delete(sessionId)
-    }
-  }
-
-  private async onIdle(sessionId: string): Promise<void> {
-    this.logger.debug({ sessionId }, 'Session idle timeout, summarizing')
-    await this.endSession(sessionId)
-  }
-
-  /**
-   * Build a structured summary from session items.
-   * Format: "Did: ...; Decided: ...; Files: ..."
-   */
-  private buildStructuredSummary(session: SessionState): string {
-    const actions: string[] = []
-    const decisions: string[] = []
-    const files = new Set<string>()
-
-    for (const item of session.items) {
-      // Extract file paths from metadata
-      if (item.metadata?.file_path) {
-        files.add(item.metadata.file_path)
-      }
-      if (item.metadata?.files) {
-        for (const f of Array.isArray(item.metadata.files) ? item.metadata.files : [item.metadata.files]) {
-          files.add(f)
-        }
-      }
-
-      if (item.type === 'decision') {
-        decisions.push(item.content.slice(0, 80))
-      } else if (item.type === 'progress') {
-        actions.push(item.content.slice(0, 80))
-      } else if (item.type === 'pattern' || item.type === 'correction') {
-        actions.push(`[${item.type}] ${item.content.slice(0, 60)}`)
-      }
-    }
-
-    const parts: string[] = []
-    if (actions.length > 0) {
-      parts.push(`Did: ${actions.slice(0, 5).join('; ')}`)
-    }
-    if (decisions.length > 0) {
-      parts.push(`Decided: ${decisions.slice(0, 3).join('; ')}`)
-    }
-    if (files.size > 0) {
-      const fileList = [...files].slice(0, 8)
-      parts.push(`Files: ${fileList.join(', ')}`)
-    }
-
-    return parts.join('. ') || `Session with ${session.items.length} events`
-  }
-
-  private async summarizeAndPersist(session: SessionState): Promise<void> {
-    if (session.items.length < this.minEventsForSummary) {
-      this.logger.debug(
-        { sessionId: session.sessionId, items: session.items.length },
-        'Too few items for summary, skipping'
-      )
-      // Still end the episode if started
-      if (session.episodeId && this.episodeManager) {
-        try {
-          await this.episodeManager.endEpisode(session.episodeId)
-        } catch {}
-      }
-      return
-    }
-
-    this.logger.info(
-      { sessionId: session.sessionId, items: session.items.length, project: session.project },
-      'Summarizing session'
-    )
-
-    // Build a synthetic episode for the summarizer
-    const messages = session.items.map((item) => ({
-      role: 'assistant' as const,
-      content: `[${item.type}] ${item.content}`,
-      timestamp: item.timestamp,
-      token_estimate: Math.ceil(item.content.length / 4),
-    }))
-
-    const syntheticEpisode = {
-      id: session.sessionId,
-      project: session.project,
-      status: 'completed' as const,
-      started_at: session.startedAt,
-      ended_at: new Date().toISOString(),
-      messages,
-      related_decisions: session.items
-        .filter(i => i.type === 'decision')
-        .map((_, idx) => `hook-decision-${idx}`),
-      related_patterns: session.items
-        .filter(i => i.type === 'pattern')
-        .map((_, idx) => `hook-pattern-${idx}`),
-      related_corrections: session.items
-        .filter(i => i.type === 'correction')
-        .map((_, idx) => `hook-correction-${idx}`),
-      token_count: messages.reduce((sum, m) => sum + (m.token_estimate || 0), 0),
-      message_count: messages.length,
-    }
-
-    const extractiveSummary = this.summarizer.summarize(syntheticEpisode)
-
-    // Phase 21: Build structured summary alongside extractive
-    const structuredSummary = this.buildStructuredSummary(session)
-
-    // End the episode with summary attached
-    if (session.episodeId && this.episodeManager) {
-      try {
-        // Add messages to episode before ending
-        for (const msg of messages) {
-          await this.episodeManager.addMessage(session.episodeId, msg)
-        }
-        await this.episodeManager.endEpisode(session.episodeId)
-      } catch (err) {
-        this.logger.warn({ err, sessionId: session.sessionId }, 'Failed to end episode')
-      }
-    }
-
-    // Phase 20+21: Store session summary as a searchable decision
-    // Uses structured summary for better auto-context readability
-    if (this.memoryManager && (extractiveSummary.brief || structuredSummary)) {
-      try {
-        const project = session.project || 'general'
-        const technologies = [...new Set(session.items.flatMap(i => i.technologies))]
-        const summaryContent = `Session summary: ${structuredSummary}${extractiveSummary.key_topics.length > 0 ? ` (Topics: ${extractiveSummary.key_topics.join(', ')})` : ''}`
-
-        await this.memoryManager.rememberDecision(
-          project,
-          'Auto-captured session summary',
-          summaryContent,
-          'Session ended — auto-summarized by passive hooks',
-          { tags: ['session-summary', ...technologies] }
-        )
-
-        this.logger.info(
-          { sessionId: session.sessionId, project },
-          'Session summary stored as searchable memory'
-        )
-      } catch (err) {
-        this.logger.warn({ err, sessionId: session.sessionId }, 'Failed to store session summary')
-      }
-    }
-
-    this.logger.info(
-      { sessionId: session.sessionId, summary: structuredSummary },
-      'Session summarized'
-    )
-  }
-}
+/**
+ * Phase 17: Session Tracker
+ * Server-side session tracking that maintains state across hook invocations.
+ * Buffers CapturedKnowledge items and generates session summaries on idle/stop.
+ */
+
+import type { Logger } from 'pino'
+import type { EpisodeManager } from '@/memory/episodic/manager'
+import type { MemoryManager } from '@/memory'
+import { ExtractiveSummarizer } from '@/memory/episodic/summarizer'
+import type { CapturedKnowledge } from './types'
+import type { HooksConfig } from '@/config/schema'
+
+interface SessionState {
+  sessionId: string
+  project?: string
+  items: CapturedKnowledge[]
+  startedAt: string
+  lastActivityAt: string
+  episodeId?: string
+}
+
+export class HookSessionTracker {
+  private logger: Logger
+  private episodeManager: EpisodeManager | null
+  private memoryManager: MemoryManager | null
+  private summarizer: ExtractiveSummarizer
+  private sessions: Map<string, SessionState> = new Map()
+  private idleTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
+  private idleTimeoutMs: number
+  private minEventsForSummary: number
+
+  constructor(
+    logger: Logger,
+    episodeManager: EpisodeManager | null,
+    config?: HooksConfig['sessions'],
+    memoryManager?: MemoryManager | null
+  ) {
+    this.logger = logger.child({ component: 'hook-session-tracker' })
+    this.episodeManager = episodeManager
+    this.memoryManager = memoryManager ?? null
+    this.summarizer = new ExtractiveSummarizer()
+    this.idleTimeoutMs = (config?.idleTimeoutMinutes ?? 30) * 60 * 1000
+    this.minEventsForSummary = config?.minEventsForSummary ?? 3
+  }
+
+  /**
+   * Track a captured knowledge item within a session.
+   */
+  async track(sessionId: string, knowledge: CapturedKnowledge): Promise<void> {
+    let session = this.sessions.get(sessionId)
+
+    if (!session) {
+      session = {
+        sessionId,
+        project: knowledge.project,
+        items: [],
+        startedAt: new Date().toISOString(),
+        lastActivityAt: new Date().toISOString(),
+      }
+      this.sessions.set(sessionId, session)
+
+      // Start episode if manager available
+      if (this.episodeManager) {
+        try {
+          const episode = await this.episodeManager.startEpisode(knowledge.project)
+          session.episodeId = episode.id
+        } catch (err) {
+          this.logger.warn({ err }, 'Failed to start episode for session')
+        }
+      }
+    }
+
+    session.items.push(knowledge)
+    session.lastActivityAt = new Date().toISOString()
+
+    // Reset idle timer
+    this.resetIdleTimer(sessionId)
+  }
+
+  /**
+   * End a session immediately (triggered by Stop hook event).
+   */
+  async endSession(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId)
+    if (!session) return
+
+    this.clearIdleTimer(sessionId)
+    await this.summarizeAndPersist(session)
+    this.sessions.delete(sessionId)
+  }
+
+  /**
+   * End all active sessions (for server shutdown).
+   */
+  async endAllSessions(): Promise<void> {
+    const sessionIds = Array.from(this.sessions.keys())
+    for (const id of sessionIds) {
+      await this.endSession(id)
+    }
+  }
+
+  /**
+   * Get stats about tracked sessions.
+   */
+  getStats(): { activeSessions: number; totalItems: number } {
+    let totalItems = 0
+    for (const session of this.sessions.values()) {
+      totalItems += session.items.length
+    }
+    return { activeSessions: this.sessions.size, totalItems }
+  }
+
+  private resetIdleTimer(sessionId: string): void {
+    this.clearIdleTimer(sessionId)
+    const timer = setTimeout(() => {
+      this.onIdle(sessionId)
+    }, this.idleTimeoutMs)
+    this.idleTimers.set(sessionId, timer)
+  }
+
+  private clearIdleTimer(sessionId: string): void {
+    const existing = this.idleTimers.get(sessionId)
+    if (existing) {
+      clearTimeout(existing)
+      this.idleTimers.delete(sessionId)
+    }
+  }
+
+  private async onIdle(sessionId: string): Promise<void> {
+    this.logger.debug({ sessionId }, 'Session idle timeout, summarizing')
+    await this.endSession(sessionId)
+  }
+
+  /**
+   * Build a structured summary from session items.
+   * Format: "Did: ...; Decided: ...; Files: ..."
+   */
+  private buildStructuredSummary(session: SessionState): string {
+    const actions: string[] = []
+    const decisions: string[] = []
+    const files = new Set<string>()
+
+    for (const item of session.items) {
+      // Extract file paths from metadata
+      if (item.metadata?.file_path) {
+        files.add(item.metadata.file_path)
+      }
+      if (item.metadata?.files) {
+        for (const f of Array.isArray(item.metadata.files) ? item.metadata.files : [item.metadata.files]) {
+          files.add(f)
+        }
+      }
+
+      if (item.type === 'decision') {
+        decisions.push(item.content.slice(0, 80))
+      } else if (item.type === 'progress') {
+        actions.push(item.content.slice(0, 80))
+      } else if (item.type === 'pattern' || item.type === 'correction') {
+        actions.push(`[${item.type}] ${item.content.slice(0, 60)}`)
+      }
+    }
+
+    const parts: string[] = []
+    if (actions.length > 0) {
+      parts.push(`Did: ${actions.slice(0, 5).join('; ')}`)
+    }
+    if (decisions.length > 0) {
+      parts.push(`Decided: ${decisions.slice(0, 3).join('; ')}`)
+    }
+    if (files.size > 0) {
+      const fileList = [...files].slice(0, 8)
+      parts.push(`Files: ${fileList.join(', ')}`)
+    }
+
+    return parts.join('. ') || `Session with ${session.items.length} events`
+  }
+
+  private async summarizeAndPersist(session: SessionState): Promise<void> {
+    if (session.items.length < this.minEventsForSummary) {
+      this.logger.debug(
+        { sessionId: session.sessionId, items: session.items.length },
+        'Too few items for summary, skipping'
+      )
+      // Still end the episode if started
+      if (session.episodeId && this.episodeManager) {
+        try {
+          await this.episodeManager.endEpisode(session.episodeId)
+        } catch {}
+      }
+      return
+    }
+
+    this.logger.info(
+      { sessionId: session.sessionId, items: session.items.length, project: session.project },
+      'Summarizing session'
+    )
+
+    // Build a synthetic episode for the summarizer
+    const messages = session.items.map((item) => ({
+      role: 'assistant' as const,
+      content: `[${item.type}] ${item.content}`,
+      timestamp: item.timestamp,
+      token_estimate: Math.ceil(item.content.length / 4),
+    }))
+
+    const syntheticEpisode = {
+      id: session.sessionId,
+      project: session.project,
+      status: 'completed' as const,
+      started_at: session.startedAt,
+      ended_at: new Date().toISOString(),
+      messages,
+      related_decisions: session.items
+        .filter(i => i.type === 'decision')
+        .map((_, idx) => `hook-decision-${idx}`),
+      related_patterns: session.items
+        .filter(i => i.type === 'pattern')
+        .map((_, idx) => `hook-pattern-${idx}`),
+      related_corrections: session.items
+        .filter(i => i.type === 'correction')
+        .map((_, idx) => `hook-correction-${idx}`),
+      token_count: messages.reduce((sum, m) => sum + (m.token_estimate || 0), 0),
+      message_count: messages.length,
+    }
+
+    const extractiveSummary = this.summarizer.summarize(syntheticEpisode)
+
+    // Phase 21: Build structured summary alongside extractive
+    const structuredSummary = this.buildStructuredSummary(session)
+
+    // End the episode with summary attached
+    if (session.episodeId && this.episodeManager) {
+      try {
+        // Add messages to episode before ending
+        for (const msg of messages) {
+          await this.episodeManager.addMessage(session.episodeId, msg)
+        }
+        await this.episodeManager.endEpisode(session.episodeId)
+      } catch (err) {
+        this.logger.warn({ err, sessionId: session.sessionId }, 'Failed to end episode')
+      }
+    }
+
+    // Phase 20+21: Store session summary as a searchable decision
+    // Uses structured summary for better auto-context readability
+    if (this.memoryManager && (extractiveSummary.brief || structuredSummary)) {
+      try {
+        const project = session.project || 'general'
+        const technologies = [...new Set(session.items.flatMap(i => i.technologies))]
+        const summaryContent = `Session summary: ${structuredSummary}${extractiveSummary.key_topics.length > 0 ? ` (Topics: ${extractiveSummary.key_topics.join(', ')})` : ''}`
+
+        await this.memoryManager.rememberDecision(
+          project,
+          'Auto-captured session summary',
+          summaryContent,
+          'Session ended — auto-summarized by passive hooks',
+          { tags: ['session-summary', ...technologies] }
+        )
+
+        this.logger.info(
+          { sessionId: session.sessionId, project },
+          'Session summary stored as searchable memory'
+        )
+      } catch (err) {
+        this.logger.warn({ err, sessionId: session.sessionId }, 'Failed to store session summary')
+      }
+    }
+
+    this.logger.info(
+      { sessionId: session.sessionId, summary: structuredSummary },
+      'Session summarized'
+    )
+  }
+}

package/src/hooks/types.ts

@@ -1,47 +1,47 @@
-/**
- * Phase 17: Passive Learning via Hooks — Shared Types
- */
-
-/** Claude Code hook stdin JSON format */
-export interface HookInput {
-  session_id: string
-  hook_event_name: 'PostToolUse' | 'Stop' | 'PreToolUse' | 'GitCommit'
-  cwd: string
-  tool_name?: string
-  tool_input?: Record<string, any>
-  tool_response?: {
-    content?: string | Array<{ type: string; text?: string }>
-    [key: string]: any
-  }
-}
-
-/** Knowledge type classifications */
-export type KnowledgeType = 'decision' | 'pattern' | 'correction' | 'progress'
-
-/** A piece of knowledge captured from a hook event */
-export interface CapturedKnowledge {
-  type: KnowledgeType
-  confidence: number
-  content: string
-  project?: string
-  technologies: string[]
-  metadata: Record<string, any>
-  source: 'hook-passive'
-  timestamp: string
-}
-
-/** What to do with captured knowledge before storage */
-export type StoreAction =
-  | { action: 'store_new' }
-  | { action: 'merge'; existingId: string; mergedContent: string }
-  | { action: 'skip'; reason: string }
-
-/** Hook event stats for status reporting */
-export interface HookStats {
-  totalCaptured: number
-  totalSkipped: number
-  totalMerged: number
-  sessionsTracked: number
-  lastCaptureAt?: string
-  queueSize: number
-}
+/**
+ * Phase 17: Passive Learning via Hooks — Shared Types
+ */
+
+/** Claude Code hook stdin JSON format */
+export interface HookInput {
+  session_id: string
+  hook_event_name: 'PostToolUse' | 'Stop' | 'PreToolUse' | 'GitCommit'
+  cwd: string
+  tool_name?: string
+  tool_input?: Record<string, any>
+  tool_response?: {
+    content?: string | Array<{ type: string; text?: string }>
+    [key: string]: any
+  }
+}
+
+/** Knowledge type classifications */
+export type KnowledgeType = 'decision' | 'pattern' | 'correction' | 'progress'
+
+/** A piece of knowledge captured from a hook event */
+export interface CapturedKnowledge {
+  type: KnowledgeType
+  confidence: number
+  content: string
+  project?: string
+  technologies: string[]
+  metadata: Record<string, any>
+  source: 'hook-passive'
+  timestamp: string
+}
+
+/** What to do with captured knowledge before storage */
+export type StoreAction =
+  | { action: 'store_new' }
+  | { action: 'merge'; existingId: string; mergedContent: string }
+  | { action: 'skip'; reason: string }
+
+/** Hook event stats for status reporting */
+export interface HookStats {
+  totalCaptured: number
+  totalSkipped: number
+  totalMerged: number
+  sessionsTracked: number
+  lastCaptureAt?: string
+  queueSize: number
+}

package/src/index.ts

@@ -1,7 +1,7 @@
-#!/usr/bin/env bun
-import { runServe } from './cli/commands/serve'
-
-runServe().catch((error) => {
-  console.error('Fatal error:', error)
-  process.exit(1)
-})
+#!/usr/bin/env bun
+import { runServe } from './cli/commands/serve'
+
+runServe().catch((error) => {
+  console.error('Fatal error:', error)
+  process.exit(1)
+})