claude-brain 0.5.0 → 0.8.0

package/src/hooks/passive-classifier.ts

@@ -0,0 +1,366 @@
+/**
+ * Phase 17: Passive Classifier
+ * Extracts knowledge from tool outputs using lightweight pattern matching.
+ * No embeddings needed — runs fast enough for hook context (<200ms).
+ */
+
+import type { HookInput, CapturedKnowledge } from './types'
+
+/** Phrases that indicate a decision was made */
+const DECISION_PHRASES = [
+  'i recommend', 'you should use', 'the best approach', 'i suggest',
+  'better to use', 'prefer using', 'go with', 'choose', 'instead of',
+  'the right choice', 'decided to', "let's use", 'we will use',
+  'the solution is', 'implement using', 'going with', 'switching to',
+  'adopting', 'we chose', 'the plan is to'
+]
+
+/** Phrases indicating a correction or lesson */
+const CORRECTION_PHRASES = [
+  'the bug was', 'the issue was', 'the problem was', 'mistake was',
+  'should have', 'should not have', "shouldn't have",
+  'lesson learned', "don't use", 'avoid using', 'never use',
+  'the fix is', 'the fix was', 'fixed by', 'solved by'
+]
+
+/** Package install patterns for bash commands */
+const INSTALL_PATTERNS = [
+  /(?:npm|yarn|pnpm|bun)\s+(?:install|add|i)\s+(.+)/i,
+  /pip\s+install\s+(.+)/i,
+  /cargo\s+add\s+(.+)/i,
+  /go\s+get\s+(.+)/i,
+  /gem\s+install\s+(.+)/i,
+]
+
+/** Git operation patterns */
+const GIT_PATTERNS = [
+  /git\s+commit\s+.*-m\s+["'](.+?)["']/i,
+  /git\s+merge\s+(\S+)/i,
+  /git\s+checkout\s+-b\s+(\S+)/i,
+  /git\s+branch\s+(\S+)/i,
+]
+
+/** Test/build command patterns */
+const BUILD_PATTERNS = [
+  /(?:npm|yarn|pnpm|bun)\s+(?:run\s+)?(?:test|build|lint|typecheck|check)/i,
+  /(?:jest|vitest|pytest|cargo\s+test|go\s+test)/i,
+]
+
+/** Bash commands to skip (low signal) */
+const SKIP_COMMANDS = new Set([
+  'cd', 'ls', 'cat', 'head', 'tail', 'pwd', 'echo', 'clear', 'which', 'whoami',
+  'date', 'env', 'printenv', 'export', 'source', 'alias', 'history',
+])
+
+/** File extension to technology mapping */
+const EXT_TO_TECH: Record<string, string> = {
+  '.ts': 'typescript', '.tsx': 'typescript', '.js': 'javascript', '.jsx': 'javascript',
+  '.py': 'python', '.rs': 'rust', '.go': 'go', '.java': 'java',
+  '.rb': 'ruby', '.php': 'php', '.swift': 'swift', '.kt': 'kotlin',
+  '.vue': 'vue', '.svelte': 'svelte', '.astro': 'astro',
+  '.css': 'css', '.scss': 'sass', '.less': 'less',
+  '.sql': 'sql', '.graphql': 'graphql', '.gql': 'graphql',
+  '.yml': 'yaml', '.yaml': 'yaml', '.toml': 'toml',
+  '.dockerfile': 'docker', '.prisma': 'prisma',
+}
+
+/** Path segments that indicate file role */
+const PATH_ROLE_MAP: Record<string, string> = {
+  'test': 'testing', 'tests': 'testing', '__tests__': 'testing', 'spec': 'testing',
+  'src': 'source', 'lib': 'library', 'utils': 'utility', 'helpers': 'utility',
+  'components': 'component', 'pages': 'page', 'routes': 'routing',
+  'api': 'api', 'server': 'server', 'client': 'client',
+  'config': 'configuration', 'scripts': 'scripting',
+  'hooks': 'hooks', 'middleware': 'middleware', 'types': 'types',
+}
+
+export class PassiveClassifier {
+  /**
+   * Classify a hook event and extract knowledge if found.
+   * Returns null if no knowledge worth capturing.
+   */
+  classify(input: HookInput): CapturedKnowledge | null {
+    const toolName = input.tool_name?.toLowerCase()
+    if (!toolName) return null
+
+    switch (toolName) {
+      case 'edit':
+      case 'write':
+        return this.classifyFileEdit(input)
+      case 'bash':
+        return this.classifyBashCommand(input)
+      default:
+        // Read, Glob, Grep — skip (read-only, low signal)
+        return null
+    }
+  }
+
+  private classifyFileEdit(input: HookInput): CapturedKnowledge | null {
+    const toolInput = input.tool_input
+    if (!toolInput) return null
+
+    const filePath = (toolInput.file_path || toolInput.path || '') as string
+    if (!filePath) return null
+
+    const technologies = this.extractTechFromPath(filePath)
+    const role = this.extractRoleFromPath(filePath)
+
+    // Check if the edit content contains decision language
+    const content = toolInput.new_string || toolInput.content || ''
+    const responseText = this.extractResponseText(input.tool_response)
+
+    // Check for new file creation (Write tool)
+    if (input.tool_name?.toLowerCase() === 'write') {
+      return {
+        type: 'pattern',
+        confidence: 0.7,
+        content: `Created ${role ? role + ' ' : ''}file: ${this.shortenPath(filePath)}${technologies.length ? ` (${technologies.join(', ')})` : ''}`,
+        project: this.extractProjectFromCwd(input.cwd),
+        technologies,
+        metadata: { filePath, role, action: 'create' },
+        source: 'hook-passive',
+        timestamp: new Date().toISOString(),
+      }
+    }
+
+    // For edits, only capture if they look significant
+    if (typeof content === 'string' && content.length > 50) {
+      const decisionInContent = this.detectDecisionLanguage(content)
+      if (decisionInContent) {
+        return {
+          type: 'decision',
+          confidence: 0.75,
+          content: decisionInContent,
+          project: this.extractProjectFromCwd(input.cwd),
+          technologies,
+          metadata: { filePath, role, action: 'edit' },
+          source: 'hook-passive',
+          timestamp: new Date().toISOString(),
+        }
+      }
+    }
+
+    // Check tool response for decision language
+    if (responseText) {
+      const decisionInResponse = this.detectDecisionLanguage(responseText)
+      if (decisionInResponse) {
+        return {
+          type: 'decision',
+          confidence: 0.7,
+          content: decisionInResponse,
+          project: this.extractProjectFromCwd(input.cwd),
+          technologies,
+          metadata: { filePath, role, action: 'edit' },
+          source: 'hook-passive',
+          timestamp: new Date().toISOString(),
+        }
+      }
+    }
+
+    return null
+  }
+
+  private classifyBashCommand(input: HookInput): CapturedKnowledge | null {
+    const command = (input.tool_input?.command || '') as string
+    if (!command || command.length < 3) return null
+
+    // Skip low-signal commands
+    const firstWord = command.trim().split(/\s+/)[0]?.toLowerCase()
+    if (firstWord && SKIP_COMMANDS.has(firstWord)) return null
+
+    // Package installs
+    for (const pattern of INSTALL_PATTERNS) {
+      const match = command.match(pattern)
+      if (match) {
+        const packages = match[1]?.trim()
+        if (packages) {
+          return {
+            type: 'decision',
+            confidence: 0.85,
+            content: `Installed package(s): ${packages}`,
+            project: this.extractProjectFromCwd(input.cwd),
+            technologies: this.extractTechFromPackages(packages),
+            metadata: { command, action: 'install' },
+            source: 'hook-passive',
+            timestamp: new Date().toISOString(),
+          }
+        }
+      }
+    }
+
+    // Git operations
+    for (const pattern of GIT_PATTERNS) {
+      const match = command.match(pattern)
+      if (match) {
+        return {
+          type: 'progress',
+          confidence: 0.8,
+          content: `Git: ${command.trim().slice(0, 200)}`,
+          project: this.extractProjectFromCwd(input.cwd),
+          technologies: ['git'],
+          metadata: { command, action: 'git' },
+          source: 'hook-passive',
+          timestamp: new Date().toISOString(),
+        }
+      }
+    }
+
+    // Test/build runs
+    for (const pattern of BUILD_PATTERNS) {
+      if (pattern.test(command)) {
+        const responseText = this.extractResponseText(input.tool_response)
+        const failed = responseText?.toLowerCase().includes('fail') ||
+                       responseText?.toLowerCase().includes('error')
+
+        if (failed) {
+          return {
+            type: 'correction',
+            confidence: 0.75,
+            content: `Build/test failure: ${command.trim().slice(0, 100)}`,
+            project: this.extractProjectFromCwd(input.cwd),
+            technologies: [],
+            metadata: { command, action: 'build', failed: true },
+            source: 'hook-passive',
+            timestamp: new Date().toISOString(),
+          }
+        }
+
+        return {
+          type: 'progress',
+          confidence: 0.7,
+          content: `Ran: ${command.trim().slice(0, 200)}`,
+          project: this.extractProjectFromCwd(input.cwd),
+          technologies: [],
+          metadata: { command, action: 'build', failed: false },
+          source: 'hook-passive',
+          timestamp: new Date().toISOString(),
+        }
+      }
+    }
+
+    // Check response text for decision/correction language
+    const responseText = this.extractResponseText(input.tool_response)
+    if (responseText) {
+      const correction = this.detectCorrectionLanguage(responseText)
+      if (correction) {
+        return {
+          type: 'correction',
+          confidence: 0.7,
+          content: correction,
+          project: this.extractProjectFromCwd(input.cwd),
+          technologies: [],
+          metadata: { command, action: 'bash' },
+          source: 'hook-passive',
+          timestamp: new Date().toISOString(),
+        }
+      }
+    }
+
+    return null
+  }
+
+  /** Extract technology names from file path based on extension */
+  private extractTechFromPath(filePath: string): string[] {
+    const techs: string[] = []
+    const ext = filePath.match(/\.[a-z]+$/i)?.[0]?.toLowerCase()
+    if (ext && EXT_TO_TECH[ext]) {
+      techs.push(EXT_TO_TECH[ext])
+    }
+
+    // Check for Dockerfile without extension
+    const basename = filePath.split('/').pop()?.toLowerCase() || ''
+    if (basename === 'dockerfile' || basename.startsWith('dockerfile.')) {
+      techs.push('docker')
+    }
+    if (basename === 'docker-compose.yml' || basename === 'docker-compose.yaml') {
+      techs.push('docker')
+    }
+
+    return techs
+  }
+
+  /** Extract file role from path segments */
+  private extractRoleFromPath(filePath: string): string | undefined {
+    const segments = filePath.toLowerCase().split('/')
+    for (const segment of segments) {
+      if (PATH_ROLE_MAP[segment]) return PATH_ROLE_MAP[segment]
+    }
+    return undefined
+  }
+
+  /** Extract technology names from package install strings */
+  private extractTechFromPackages(packages: string): string[] {
+    return packages
+      .split(/\s+/)
+      .filter(p => !p.startsWith('-') && p.length > 1)
+      .map(p => p.replace(/@[^/]+$/, '')) // strip version
+      .slice(0, 10) // limit
+  }
+
+  /** Detect decision language in text, return the relevant sentence */
+  private detectDecisionLanguage(text: string): string | null {
+    const lower = text.toLowerCase()
+    for (const phrase of DECISION_PHRASES) {
+      const idx = lower.indexOf(phrase)
+      if (idx !== -1) {
+        // Extract surrounding context (up to 300 chars)
+        const start = Math.max(0, text.lastIndexOf('\n', idx) + 1)
+        const end = Math.min(text.length, text.indexOf('\n', idx + phrase.length))
+        const sentence = text.slice(start, end === -1 ? Math.min(idx + 300, text.length) : end).trim()
+        if (sentence.length > 10) return sentence
+      }
+    }
+    return null
+  }
+
+  /** Detect correction/lesson language in text */
+  private detectCorrectionLanguage(text: string): string | null {
+    const lower = text.toLowerCase()
+    for (const phrase of CORRECTION_PHRASES) {
+      const idx = lower.indexOf(phrase)
+      if (idx !== -1) {
+        const start = Math.max(0, text.lastIndexOf('\n', idx) + 1)
+        const end = Math.min(text.length, text.indexOf('\n', idx + phrase.length))
+        const sentence = text.slice(start, end === -1 ? Math.min(idx + 300, text.length) : end).trim()
+        if (sentence.length > 10) return sentence
+      }
+    }
+    return null
+  }
+
+  /** Extract project name from cwd (last directory segment) */
+  private extractProjectFromCwd(cwd: string): string | undefined {
+    if (!cwd) return undefined
+    const parts = cwd.split('/').filter(Boolean)
+    const last = parts.pop()
+    if (last && last.length > 1 && last.length < 50) {
+      return last.replace(/\s+/g, '-').toLowerCase()
+    }
+    return undefined
+  }
+
+  /** Shorten a file path for display */
+  private shortenPath(filePath: string): string {
+    const parts = filePath.split('/')
+    if (parts.length <= 3) return filePath
+    return `.../${parts.slice(-3).join('/')}`
+  }
+
+  /** Extract text content from tool_response */
+  private extractResponseText(response: HookInput['tool_response']): string | null {
+    if (!response) return null
+
+    if (typeof response.content === 'string') {
+      return response.content.slice(0, 2000)
+    }
+
+    if (Array.isArray(response.content)) {
+      const texts = response.content
+        .filter(block => block.type === 'text' && block.text)
+        .map(block => block.text!)
+      return texts.join('\n').slice(0, 2000) || null
+    }
+
+    return null
+  }
+}

package/src/hooks/queue.ts

@@ -0,0 +1,122 @@
+/**
+ * Phase 17: File Queue
+ * JSONL-based offline fallback when HTTP API server is unreachable.
+ * Queue file: ~/.claude-brain/data/hook-queue.jsonl
+ */
+
+import { appendFileSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { getHomePaths } from '@/config/home'
+import type { CapturedKnowledge } from './types'
+
+/** Get the queue file path */
+export function getQueuePath(): string {
+  return join(getHomePaths().data, 'hook-queue.jsonl')
+}
+
+/**
+ * Append captured knowledge to the offline queue.
+ * Creates the file and parent directory if needed.
+ */
+export function appendToQueue(items: CapturedKnowledge[]): void {
+  if (items.length === 0) return
+
+  const queuePath = getQueuePath()
+  const dir = dirname(queuePath)
+
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+
+  const lines = items.map(item => JSON.stringify(item)).join('\n') + '\n'
+  appendFileSync(queuePath, lines, 'utf-8')
+}
+
+/**
+ * Read all items from the queue file.
+ * Returns empty array if file doesn't exist.
+ */
+export function readQueue(): CapturedKnowledge[] {
+  const queuePath = getQueuePath()
+
+  if (!existsSync(queuePath)) return []
+
+  try {
+    const content = readFileSync(queuePath, 'utf-8').trim()
+    if (!content) return []
+
+    return content
+      .split('\n')
+      .filter(line => line.trim())
+      .map(line => {
+        try {
+          return JSON.parse(line) as CapturedKnowledge
+        } catch {
+          return null
+        }
+      })
+      .filter((item): item is CapturedKnowledge => item !== null)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Clear the queue file after successful processing.
+ */
+export function clearQueue(): void {
+  const queuePath = getQueuePath()
+  if (existsSync(queuePath)) {
+    writeFileSync(queuePath, '', 'utf-8')
+  }
+}
+
+/**
+ * Drain the queue by POSTing items to the ingest endpoint in batches.
+ * Called on server startup.
+ *
+ * @param port The HTTP API port
+ * @param batchSize Number of items per POST
+ * @returns Number of items drained
+ */
+export async function drainQueue(port: number = 3000, batchSize: number = 10): Promise<number> {
+  const items = readQueue()
+  if (items.length === 0) return 0
+
+  let drained = 0
+  const url = `http://localhost:${port}/api/hooks/ingest`
+
+  for (let i = 0; i < items.length; i += batchSize) {
+    const batch = items.slice(i, i + batchSize)
+    try {
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ knowledge: batch }),
+        signal: AbortSignal.timeout(5000),
+      })
+
+      if (res.ok) {
+        drained += batch.length
+      } else {
+        // Stop draining on first failure
+        break
+      }
+    } catch {
+      // Server not ready yet, stop
+      break
+    }
+  }
+
+  if (drained === items.length) {
+    clearQueue()
+  } else if (drained > 0) {
+    // Partially drained — rewrite queue with remaining items
+    const remaining = items.slice(drained)
+    const queuePath = getQueuePath()
+    const lines = remaining.map(item => JSON.stringify(item)).join('\n') + '\n'
+    writeFileSync(queuePath, lines, 'utf-8')
+  }
+
+  return drained
+}

package/src/hooks/session-tracker.ts

@@ -0,0 +1,199 @@
+/**
+ * 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 { 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 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']
+  ) {
+    this.logger = logger.child({ component: 'hook-session-tracker' })
+    this.episodeManager = episodeManager
+    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)
+  }
+
+  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 summary = this.summarizer.summarize(syntheticEpisode)
+
+    // 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')
+      }
+    }
+
+    this.logger.info(
+      { sessionId: session.sessionId, summary: summary.brief },
+      'Session summarized'
+    )
+  }
+}