claude-brain 0.30.2 → 0.30.3

package/src/routing/router.ts

@@ -1,2193 +1,245 @@
-/**
- * Brain Router
- * Phase 16 + Phase 19: Core orchestrator for the unified brain() tool
- *
- * Routes classified intents to internal service calls and
- * returns unified BrainResponse objects.
- *
- * Phase 19: Uses SearchEngine for all searches (hybrid, cached, temporal).
- * Wires Timeline, Evolution, Trends, ChainRetrieval, Episodes,
- * Recommender, CrossProject patterns, and KnowledgeGraph enrichment.
- */
-
-import type { Logger } from 'pino'
-import { IntentClassifier, type ClassificationResult } from './intent-classifier'
-import type { InferenceRouter } from '@/intelligence/inference-router'
-import { BrainEntityExtractor, type BrainExtractedEntities } from './entity-extractor'
-import { ResponseFilter, type BrainResponse, type TierResults, type FilterableResult, formatCompactResponse, formatDetailResponse, formatTimeline, groupByDay } from './response-filter'
-import { SearchEngine } from './search-engine'
-import type { NormalizedResult } from './types'
-import {
-  getMemoryService,
-  getVaultService,
-  getContextService,
-  getPhase12Service,
-  getEpisodeService,
-  getSessionTracker,
-  getCodeLinker,
-  getCodeQuery,
-  isServicesInitialized
-} from '@/server/services'
-import { timed } from '@/utils/timing'
-import type { ObservationCompressor } from '@/memory/compression'
-
-/** Default project when none can be detected */
-const DEFAULT_PROJECT = 'general'
-
-/** Phase 19 D4: Minimum similarity for destructive operations */
-const DELETE_MIN_SIMILARITY = 0.3
-const UPDATE_MIN_SIMILARITY = 0.3
-
-export interface BrainInput {
-  message: string
-  project?: string
-  action?: 'auto' | 'store' | 'recall' | 'update' | 'delete'
-}
-
-/** Recently stored decision for recency fast path (Bug 4 fix) */
-interface RecentDecision {
-  content: string
-  project: string
-  storedAt: number
-  /** Keyword overlap ratio with query (0-1), computed by findRecentDecisions */
-  overlapScore?: number
-}
-
-/** How long recent decisions stay eligible for fast-path recall (ms) */
-const RECENT_DECISION_WINDOW_MS = 60_000
-
-export class BrainRouter {
-  private classifier: IntentClassifier
-  private entityExtractor: BrainEntityExtractor
-  private responseFilter: ResponseFilter
-  private searchEngine: SearchEngine
-  private logger: Logger
-
-  /** SLM Upgrade: Optional inference router for model-based classification */
-  private inferenceRouter: InferenceRouter | null = null
-
-  /** Phase 30: Optional LLM compressor for long observations */
-  private compressor: ObservationCompressor | null = null
-
-  /** Track the most recently stored decision ID for update/delete operations */
-  private lastStoredId: string | null = null
-  private lastStoredProject: string | null = null
-
-  /** Bug 4: Recently stored decisions for recency fast path */
-  private recentDecisions: RecentDecision[] = []
-
-  constructor(logger: Logger) {
-    this.classifier = new IntentClassifier()
-    this.entityExtractor = new BrainEntityExtractor()
-    this.responseFilter = new ResponseFilter()
-    this.searchEngine = new SearchEngine(logger)
-    this.logger = logger.child({ component: 'brain-router' })
-  }
-
-  /** SLM Upgrade: Set the optional inference router for model-based classification */
-  setInferenceRouter(router: InferenceRouter): void {
-    this.inferenceRouter = router
-    this.entityExtractor.setInferenceRouter(router)
-  }
-
-  /** Phase 30: Set the optional LLM compressor */
-  setCompressor(compressor: ObservationCompressor): void {
-    this.compressor = compressor
-  }
-
-  async route(input: BrainInput): Promise<BrainResponse> {
-    const { message, project: inputProject, action } = input
-
-    // Extract entities (needed for all paths)
-    const entities = await this.entityExtractor.extract(message, inputProject)
-    const project = entities.project || inputProject
-    this.logger.debug({ project, technologies: entities.technologies }, 'Entities extracted')
-
-    // P1: Explicit action override — bypass intent classifier entirely
-    if (action && action !== 'auto') {
-      this.logger.debug({ action }, 'Using explicit action override')
-      try {
-        switch (action) {
-          case 'store':
-            return this.handleStoreThis(message, project, entities)
-          case 'recall':
-            return this.handleContextNeeded(message, project, entities)
-          case 'update':
-            return this.handleUpdateMemory(message, project, entities)
-          case 'delete':
-            return this.handleDeleteMemory(message, project, entities)
-          default:
-            break
-        }
-      } catch (error) {
-        this.logger.error({ error, action }, 'Router action override error')
-        return {
-          action: 'none',
-          summary: `Error processing ${action} request`,
-          content: `Failed to process: ${error instanceof Error ? error.message : 'Unknown error'}`,
-          relevantItems: 0
-        }
-      }
-    }
-
-    // Classify intent (SLM: use inference router if available, falls back to regex)
-    const classification = this.inferenceRouter
-      ? await this.inferenceRouter.classifyIntent(message)
-      : this.classifier.classify(message)
-    this.logger.debug({ intent: classification.primary, confidence: classification.confidence }, 'Intent classified')
-
-    // Route to handler
-    try {
-      switch (classification.primary) {
-        case 'no_action':
-          return this.handleNoAction(message)
-
-        case 'session_start':
-          return this.handleSessionStart(message, project, entities)
-
-        case 'context_needed':
-          return this.handleContextNeeded(message, project, entities, classification)
-
-        case 'decision_made':
-          return this.handleDecisionMade(message, project, entities)
-
-        case 'store_this':
-          return this.handleStoreThis(message, project, entities)
-
-        case 'pattern_found':
-          return this.handlePatternFound(message, project, entities)
-
-        case 'mistake_learned':
-          return this.handleMistakeLearned(message, project, entities)
-
-        case 'progress_update':
-          return this.handleProgressUpdate(message, project, entities)
-
-        case 'question':
-          return this.handleQuestion(message, project, entities, classification)
-
-        case 'comparison':
-          return this.handleComparison(message, project, entities)
-
-        case 'exploration':
-          return this.handleExploration(message, project, entities)
-
-        case 'list_all':
-          return this.handleListAll(message, project, entities)
-
-        case 'update_memory':
-          return this.handleUpdateMemory(message, project, entities)
-
-        case 'delete_memory':
-          return this.handleDeleteMemory(message, project, entities)
-
-        case 'detail_request':
-          return this.handleDetailRequest(message, project, entities)
-
-        case 'timeline':
-          return this.handleTimeline(message, project, entities)
-
-        default:
-          return this.handleContextNeeded(message, project, entities, classification)
-      }
-    } catch (error) {
-      this.logger.error({ error, intent: classification.primary }, 'Router handler error')
-      return {
-        action: 'none',
-        summary: `Error processing request`,
-        content: `Failed to process: ${error instanceof Error ? error.message : 'Unknown error'}`,
-        relevantItems: 0
-      }
-    }
-  }
-
-  // ===== Intent Handlers =====
-
-  private handleNoAction(_message: string): BrainResponse {
-    return {
-      action: 'none',
-      summary: 'No action needed',
-      content: '',
-      relevantItems: 0
-    }
-  }
-
-  private async handleSessionStart(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    if (!project) {
-      return {
-        action: 'none',
-        summary: 'No project detected',
-        content: 'Could not determine project. Please specify which project you are working on.',
-        relevantItems: 0
-      }
-    }
-
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    const contextService = getContextService()
-    const phase12 = getPhase12Service()
-
-    // Get project context
-    const context = await contextService.getContext(project, {
-      includeMemories: false,
-      includeProgress: true,
-      includeStandards: true,
-      maxTokens: 6000,
-      relevanceThreshold: 0.5
-    })
-
-    const formattedContext = contextService.formatter.format(context)
-
-    // Process with Phase 12 for proactive recall
-    const phase12Result = await phase12.processMessage(
-      entities.topic || message,
-      project
-    )
-
-    // Build response
-    const parts: string[] = [formattedContext]
-
-    if (phase12Result.recalledMemories?.memories.length) {
-      parts.push('\n---\n## Relevant Past Decisions\n')
-      for (const mem of phase12Result.recalledMemories.memories) {
-        const similarity = Math.round((mem.similarity || 0) * 100)
-        const decisionText = mem.decision?.decision || mem.memory?.content || ''
-        const safeText = typeof decisionText === 'string' ? decisionText : JSON.stringify(decisionText)
-        parts.push(`**[${similarity}%]** ${safeText.slice(0, 200)}`)
-        if (mem.decision?.reasoning) {
-          const reasoning = typeof mem.decision.reasoning === 'string' ? mem.decision.reasoning : JSON.stringify(mem.decision.reasoning)
-          parts.push(`  _${reasoning}_`)
-        }
-      }
-    }
-
-    // If Phase 12 found nothing, do a direct search fallback via SearchEngine
-    if (!phase12Result.recalledMemories?.memories.length) {
-      try {
-        const directResults = await this.searchEngine.enhancedSearch(entities.topic || message, {
-          project,
-          limit: 5,
-          minSimilarity: 0.3
-        })
-        if (directResults.length > 0) {
-          parts.push('\n---\n## Related Memories\n')
-          for (const r of directResults) {
-            const similarity = Math.round((r.score || 0) * 100)
-            const safeContent = typeof r.content === 'string' ? r.content : JSON.stringify(r.content ?? '')
-            parts.push(`**[${similarity}%]** ${safeContent.slice(0, 200)}`)
-          }
-        }
-      } catch {
-        // Direct search failed, continue without
-      }
-    }
-
-    // Phase 32: Include code file map in session context if code index is available
-    try {
-      const codeQuery = getCodeQuery()
-      if (codeQuery && project) {
-        const fileMap = codeQuery.getFileMap(project, 50)
-        if (fileMap.length > 0) {
-          const formatted = codeQuery.formatFileMap(fileMap)
-          parts.push('\n---\n## Code Structure\n')
-          parts.push(formatted)
-        }
-      }
-    } catch {
-      // Code intelligence not available
-    }
-
-    // C8: Register with episode manager
-    this.registerEpisodeMessage(message, project, 'session_start')
-
-    // C9: Append proactive recommendations
-    try {
-      const recommendations = await this.searchEngine.getRecommendations(
-        entities.topic || message,
-        { project, limit: 3 }
-      )
-      if (recommendations?.recommendations?.length) {
-        parts.push('\n---\n## Proactive Recommendations\n')
-        for (const rec of recommendations.recommendations) {
-          parts.push(`- **${rec.type}**: ${rec.content?.slice(0, 150) || ''}`)
-          if (rec.reasoning) parts.push(`  _${rec.reasoning}_`)
-        }
-      }
-    } catch {
-      // Recommendations not available
-    }
-
-    // Phase 25: Query past session summaries for this project
-    try {
-      let sessionSummaries = await this.searchEngine.plainSearch(
-        'session summary',
-        { project: project || undefined, limit: 5, minSimilarity: 0.3 }
-      )
-
-      // Fallback: if plainSearch returns 0, try enhancedSearch with broader query
-      if (sessionSummaries.length === 0) {
-        sessionSummaries = await this.searchEngine.enhancedSearch(
-          `session summary ${project || ''}`.trim(),
-          { project: project || undefined, limit: 5, minSimilarity: 0.2 }
-        )
-      }
-
-      let summaryItems = sessionSummaries.filter(r =>
-        (r.metadata as Record<string, unknown>)?.tags &&
-        Array.isArray((r.metadata as Record<string, unknown>).tags) &&
-        ((r.metadata as Record<string, unknown>).tags as string[]).includes('session-summary') ||
-        r.content.toLowerCase().startsWith('session summary:') ||
-        r.content.toLowerCase().includes('worked on')
-      )
-
-      // Sort by date descending (most recent first)
-      summaryItems.sort((a, b) => {
-        const dateA = a.date || (a.metadata as Record<string, unknown>)?.created_at as string || ''
-        const dateB = b.date || (b.metadata as Record<string, unknown>)?.created_at as string || ''
-        return dateB.localeCompare(dateA)
-      })
-
-      if (summaryItems.length > 0) {
-        parts.push('\n---\n## Past Sessions\n')
-        for (const s of summaryItems.slice(0, 3)) {
-          const safeContent = typeof s.content === 'string' ? s.content : JSON.stringify(s.content ?? '')
-          parts.push(`- ${safeContent.slice(0, 300)}`)
-        }
-      }
-    } catch {
-      // Non-critical — skip if search fails
-    }
-
-    const totalRecalled = phase12Result.recalledMemories?.memories.length || 0
-    return {
-      action: 'retrieved',
-      summary: `Session context for ${project}${totalRecalled ? ` (${totalRecalled} memories)` : ''}`,
-      content: parts.join('\n'),
-      relevantItems: totalRecalled
-    }
-  }
-
-  private async handleContextNeeded(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities,
-    classification?: ClassificationResult
-  ): Promise<BrainResponse> {
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    // Phase 25: Use undefined for search when no project detected (search all projects)
-    const searchProject = project || undefined
-    const displayProject = project || DEFAULT_PROJECT
-    const query = entities.topic || message
-    const tiers: TierResults[] = []
-    const hasTemporal = classification?.secondary.includes('exploration') ||
-      this.classifier.hasTemporalSignal(message.toLowerCase())
-
-    // Use temporal search if temporal signals detected
-    if (hasTemporal) {
-      const { results } = await this.searchEngine.temporalSearch(query, { project: searchProject, limit: 5 })
-      if (results.length > 0) {
-        tiers.push({
-          label: 'Memories',
-          results: results.map(r => ({
-            content: r.content,
-            score: r.score,
-            source: r.source === 'decision' ? 'Past Decision' : r.source,
-            metadata: r.metadata as Record<string, unknown>
-          }))
-        })
-      }
-    } else {
-      // Standard enhanced search
-      const searchResults = await this.searchEngine.enhancedSearch(query, {
-        project: searchProject,
-        limit: 5,
-        minSimilarity: 0.3
-      })
-      if (searchResults.length > 0) {
-        tiers.push({
-          label: 'Memories',
-          results: searchResults.map(r => ({
-            content: r.content,
-            score: r.score,
-            source: r.source === 'decision' ? 'Past Decision' : r.source,
-            metadata: r.metadata as Record<string, unknown>
-          }))
-        })
-      }
-    }
-
-    // Also search patterns
-    const patternResults = await this.searchEngine.searchPatterns(query, { project: searchProject, limit: 3 })
-    if (patternResults.length > 0) {
-      tiers.push({
-        label: 'Patterns',
-        results: patternResults.map(p => ({
-          content: p.content,
-          score: p.score,
-          source: `Pattern`,
-          metadata: p.metadata as Record<string, unknown>
-        }))
-      })
-    }
-
-    // Phase 32: Code intelligence — query code index for matching symbols/files
-    const codeTier = this.queryCodeIntelligence(query, searchProject)
-    if (codeTier) {
-      tiers.push(codeTier)
-    }
-
-    const response = this.responseFilter.synthesize(tiers, message, displayProject)
-
-    // P0: When no results found and message looks like a plain statement (not a question),
-    // add a hint that the user may have intended to store it
-    if (response.action === 'none' && response.relevantItems === 0) {
-      const isPlainStatement = message.length > 15 &&
-        !message.trim().endsWith('?') &&
-        message.split(/\s+/).length > 3
-      if (isPlainStatement) {
-        response.content += `\n\n**Tip:** If you meant to save this, try:\n- \`brain("Remember: ${message.slice(0, 60)}")\`\n- Or use \`action: "store"\` to force storage: \`brain({ message: "...", action: "store" })\``
-      }
-    }
-
-    return response
-  }
-
-  /**
-   * Handle explicit "store this" requests — always uses the FULL message as the decision text.
-   */
-  private async handleStoreThis(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    const effectiveProject = project || DEFAULT_PROJECT
-
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    const memory = getMemoryService()
-    const reasoning = entities.reasoning || ''
-    const context = entities.topic || message.slice(0, 200)
-
-    // Phase 30: Optional LLM compression
-    const { content: decision, rawContent } = await this.maybeCompress(message, 'store')
-
-    const decisionId = await timed('brain:store', () => memory.rememberDecision(
-      effectiveProject,
-      context,
-      decision,
-      reasoning,
-      {
-        alternatives: entities.alternatives,
-        tags: entities.technologies.length > 0 ? entities.technologies : ['user-stored']
-      }
-    ))
-
-    // Track for potential update/delete
-    this.lastStoredId = decisionId
-    this.lastStoredProject = effectiveProject
-
-    // Bug 4: Track for recency fast path
-    this.trackRecentDecision(decision, effectiveProject)
-
-    // Invalidate cache for this project
-    this.searchEngine.invalidateCache(effectiveProject)
-
-    // Background: vault write + episode linking + code linkage (non-critical)
-    setImmediate(() => {
-      this.writeToVault(effectiveProject, decision, reasoning, context, entities.alternatives)
-      this.linkToActiveEpisode(effectiveProject, decisionId, 'decision')
-      this.linkToCodeFiles(decisionId, decision, effectiveProject)
-    })
-
-    const compressedNote = rawContent ? '\n*(compressed)*' : ''
-    return {
-      action: 'stored',
-      summary: `Stored: ${message.slice(0, 60)}`,
-      content: `Memory stored (ID: ${decisionId})\n\n**Project:** ${effectiveProject}\n**Content:** ${decision}${reasoning ? `\n**Reasoning:** ${reasoning}` : ''}${compressedNote}`,
-      relevantItems: 1
-    }
-  }
-
-  private async handleDecisionMade(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    const effectiveProject = project || DEFAULT_PROJECT
-
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    const memory = getMemoryService()
-    const reasoning = entities.reasoning || ''
-    const context = entities.topic || message.slice(0, 200)
-    const alternatives = entities.alternatives
-
-    // Phase 30: Optional LLM compression
-    const { content: decision, rawContent } = await this.maybeCompress(message, 'decision')
-
-    const decisionId = await timed('brain:store', () => memory.rememberDecision(
-      effectiveProject,
-      context,
-      decision,
-      reasoning,
-      {
-        alternatives,
-        tags: entities.technologies.length > 0 ? entities.technologies : ['auto-detected']
-      }
-    ))
-
-    this.lastStoredId = decisionId
-    this.lastStoredProject = effectiveProject
-
-    // Bug 4: Track for recency fast path
-    this.trackRecentDecision(decision, effectiveProject)
-
-    // Invalidate cache
-    this.searchEngine.invalidateCache(effectiveProject)
-
-    // Background: vault write + episode linking + code linkage (non-critical)
-    setImmediate(() => {
-      this.writeToVault(effectiveProject, decision, reasoning, context, alternatives)
-      this.linkToActiveEpisode(effectiveProject, decisionId, 'decision')
-      this.linkToCodeFiles(decisionId, decision, effectiveProject)
-    })
-
-    const compressedNote = rawContent ? '\n*(compressed)*' : ''
-    return {
-      action: 'stored',
-      summary: `Stored decision: ${message.slice(0, 60)}`,
-      content: `Decision stored (ID: ${decisionId})\n\n**Project:** ${effectiveProject}\n**Decision:** ${decision}\n**Reasoning:** ${reasoning}${compressedNote}`,
-      relevantItems: 1
-    }
-  }
-
-  private async handlePatternFound(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    const effectiveProject = project || DEFAULT_PROJECT
-
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    const memory = getMemoryService()
-    const patternType = entities.patternType || 'solution'
-    const description = message
-
-    const patternId = await memory.storePattern({
-      project: effectiveProject,
-      pattern_type: patternType,
-      description,
-      confidence: 0.8,
-      context: message.slice(0, 300)
-    })
-
-    // Invalidate cache
-    this.searchEngine.invalidateCache(effectiveProject)
-
-    // Link to active episode + code files
-    this.linkToActiveEpisode(effectiveProject, patternId, 'pattern')
-    this.linkToCodeFiles(patternId, description, effectiveProject)
-
-    return {
-      action: 'stored',
-      summary: `Stored ${patternType}: ${description.slice(0, 60)}`,
-      content: `Pattern stored (ID: ${patternId})\n\n**Type:** ${patternType}\n**Project:** ${effectiveProject}\n**Description:** ${description}`,
-      relevantItems: 1
-    }
-  }
-
-  private async handleMistakeLearned(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    const effectiveProject = project || DEFAULT_PROJECT
-
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    const memory = getMemoryService()
-    const original = entities.original || message
-    const correction = entities.correction || ''
-    const reasoning = entities.reasoning || 'Lesson learned from experience'
-
-    const correctionId = await memory.storeCorrection({
-      project: effectiveProject,
-      original,
-      correction: correction || message,
-      reasoning,
-      context: entities.topic || '',
-      confidence: 0.9
-    })
-
-    // Invalidate cache
-    this.searchEngine.invalidateCache(effectiveProject)
-
-    // Link to active episode + code files
-    this.linkToActiveEpisode(effectiveProject, correctionId, 'correction')
-    this.linkToCodeFiles(correctionId, original, effectiveProject)
-
-    return {
-      action: 'stored',
-      summary: `Stored correction: ${original.slice(0, 60)}`,
-      content: `Correction stored (ID: ${correctionId})\n\n**Project:** ${effectiveProject}\n**Original:** ${original}\n**Correction:** ${correction || '(see original message)'}`,
-      relevantItems: 1
-    }
-  }
-
-  private async handleProgressUpdate(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    const effectiveProject = project || DEFAULT_PROJECT
-
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    const contextService = getContextService()
-    const memory = getMemoryService()
-
-    const completedTask = entities.completedTask || message
-    const nextSteps = entities.nextSteps || 'Continue development'
-
-    // Store in session context
-    try {
-      await contextService.progress.addCompletedTask(effectiveProject, {
-        id: this.generateTaskId(completedTask),
-        title: completedTask,
-        status: 'done',
-        completedAt: new Date()
-      })
-    } catch {
-      // Progress update failed
-    }
-
-    // Also store as a searchable memory
-    try {
-      await memory.rememberDecision(
-        effectiveProject,
-        `Progress update`,
-        `Progress: ${completedTask}${nextSteps !== 'Continue development' ? `. Next: ${nextSteps}` : ''}`,
-        'Progress tracking',
-        { tags: ['progress', ...entities.technologies] }
-      )
-
-      // Invalidate cache
-      this.searchEngine.invalidateCache(effectiveProject)
-    } catch {
-      // Memory storage failed
-    }
-
-    // Register with episode
-    this.registerEpisodeMessage(message, effectiveProject, 'progress_update')
-
-    return {
-      action: 'stored',
-      summary: `Progress: ${completedTask.slice(0, 60)}`,
-      content: `Progress updated for ${effectiveProject}\n\n**Completed:** ${completedTask}\n**Next:** ${nextSteps}`,
-      relevantItems: 1
-    }
-  }
-
-  /**
-   * List all decisions for a project
-   */
-  private async handleListAll(
-    _message: string,
-    project: string | undefined,
-    _entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    const memory = getMemoryService()
-    const effectiveProject = project
-
-    try {
-      const decisions = await memory.fetchAllDecisions(effectiveProject)
-      const patterns = await memory.fetchAllPatterns(effectiveProject)
-      const corrections = await memory.fetchAllCorrections(effectiveProject)
-
-      const projectLabel = effectiveProject || 'all projects'
-      const total = decisions.length + patterns.length + corrections.length
-
-      if (total === 0) {
-        return {
-          action: 'none',
-          summary: `No memories found for ${projectLabel}`,
-          content: `No decisions, patterns, or corrections stored yet for ${projectLabel}.`,
-          relevantItems: 0
-        }
-      }
-
-      // Phase 27: Use compact format for list_all
-      const allItems: any[] = [
-        ...decisions.map(d => ({
-          id: d.id || (d as any).decision_id,
-          content: typeof (d.decision || d.document || d.content) === 'string'
-            ? (d.decision || d.document || d.content)
-            : JSON.stringify(d.decision || d.document || d.content || ''),
-          category: 'decision',
-          project: d.project || effectiveProject || 'general',
-          created_at: d.created_at || d.date || '',
-        })),
-        ...patterns.map(p => ({
-          id: p.id,
-          content: typeof (p.description || p.document || p.content) === 'string'
-            ? (p.description || p.document || p.content)
-            : JSON.stringify(p.description || p.document || p.content || ''),
-          category: p.pattern_type || 'pattern',
-          project: p.project || effectiveProject || 'general',
-          created_at: p.created_at || '',
-        })),
-        ...corrections.map(c => ({
-          id: c.id,
-          content: typeof (c.original || c.document || c.content) === 'string'
-            ? (c.original || c.document || c.content)
-            : JSON.stringify(c.original || c.document || c.content || ''),
-          category: 'correction',
-          project: c.project || effectiveProject || 'general',
-          created_at: c.created_at || '',
-        })),
-      ]
-
-      const compactContent = formatCompactResponse(allItems, `all memories for ${projectLabel}`)
-      return {
-        action: 'retrieved',
-        summary: `${total} memories for ${projectLabel}`,
-        content: compactContent,
-        relevantItems: total
-      }
-    } catch (error) {
-      return {
-        action: 'none',
-        summary: 'Error listing memories',
-        content: `Failed to list memories: ${error instanceof Error ? error.message : 'Unknown error'}`,
-        relevantItems: 0
-      }
-    }
-  }
-
-  /**
-   * Phase 19 D4: Update with higher similarity threshold
-   */
-  private async handleUpdateMemory(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    const effectiveProject = project || this.lastStoredProject || DEFAULT_PROJECT
-
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    const memory = getMemoryService()
-    const topic = entities.topic || message
-    const hasSpecificContent = this.hasDescriptiveContent(message)
-
-    if (hasSpecificContent) {
-      try {
-        const results = await memory.searchRaw(topic, {
-          project: effectiveProject,
-          limit: 1,
-          minSimilarity: UPDATE_MIN_SIMILARITY
-        })
-
-        const matchId = results[0]?.memory?.id || results[0]?.decision?.id || results[0]?.id
-        const matchSimilarity = results[0]?.similarity || 0
-
-        if (results.length > 0 && matchId && matchSimilarity >= UPDATE_MIN_SIMILARITY) {
-          const oldId = matchId
-          const newId = await memory.updateDecision(
-            oldId,
-            effectiveProject,
-            `Updated: ${topic.slice(0, 200)}`,
-            message,
-            entities.reasoning || 'Updated via brain tool',
-            { tags: entities.technologies.length > 0 ? entities.technologies : ['updated'] }
-          )
-
-          this.lastStoredId = newId
-          this.lastStoredProject = effectiveProject
-
-          // Invalidate cache
-          this.searchEngine.invalidateCache(effectiveProject)
-
-          const oldContent = results[0].decision?.decision || results[0].memory?.content?.slice(0, 100) || results[0].content?.slice(0, 100) || ''
-          return {
-            action: 'stored',
-            summary: `Updated decision`,
-            content: `Replaced: "${oldContent.slice(0, 80)}"\n\nWith:\n**New content:** ${message}`,
-            relevantItems: 1
-          }
-        } else if (results.length > 0 && matchSimilarity < UPDATE_MIN_SIMILARITY) {
-          // D4: No confident match — store as new instead of updating wrong memory
-          return this.storeAsNew(memory, effectiveProject, message, topic, entities, 'No confident match to update (similarity too low)')
-        }
-      } catch {
-        // Search failed, fall through
-      }
-    }
-
-    // Generic update — use lastStoredId
-    if (this.lastStoredId) {
-      const newId = await memory.updateDecision(
-        this.lastStoredId,
-        effectiveProject,
-        `Updated: ${topic.slice(0, 200)}`,
-        message,
-        entities.reasoning || 'Updated via brain tool',
-        { tags: entities.technologies.length > 0 ? entities.technologies : ['updated'] }
-      )
-
-      this.lastStoredId = newId
-      this.lastStoredProject = effectiveProject
-      this.searchEngine.invalidateCache(effectiveProject)
-
-      return {
-        action: 'stored',
-        summary: `Updated decision`,
-        content: `Previous decision replaced with:\n\n**Project:** ${effectiveProject}\n**New content:** ${message}`,
-        relevantItems: 1
-      }
-    }
-
-    // Fallback: store as new decision
-    return this.storeAsNew(memory, effectiveProject, message, topic, entities, 'No matching decision found to update')
-  }
-
-  /**
-   * Phase 19 D4: Delete with higher similarity threshold
-   */
-  private async handleDeleteMemory(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    const effectiveProject = project || this.lastStoredProject || DEFAULT_PROJECT
-
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    const memory = getMemoryService()
-    const topic = entities.topic || message
-    const hasSpecificContent = this.hasDescriptiveContent(message)
-    const lower = message.toLowerCase()
-
-    // BUG-006 T6: Bulk delete — "delete all memories for project X"
-    if (lower.includes('delete all') || lower.includes('remove all') || lower.includes('clear all')) {
-      const bulkProject = entities.project || project || this.lastStoredProject
-      if (bulkProject) {
-        try {
-          const decisions = await memory.chroma.store.getDecisionsByProject(bulkProject)
-          if (decisions.length === 0) {
-            return {
-              action: 'none',
-              summary: 'No memories found',
-              content: `No memories found for project "${bulkProject}".`,
-              relevantItems: 0
-            }
-          }
-          for (const d of decisions) {
-            await memory.deleteDecision(d.id)
-          }
-          this.searchEngine.invalidateCache(bulkProject)
-          return {
-            action: 'stored',
-            summary: `Bulk deleted ${decisions.length} memories`,
-            content: `Deleted all ${decisions.length} memories for project "${bulkProject}".`,
-            relevantItems: 0
-          }
-        } catch {
-          // Bulk delete failed, fall through to single-item delete
-        }
-      }
-    }
-
-    if (hasSpecificContent) {
-      try {
-        const results = await memory.searchRaw(topic, {
-          project: effectiveProject,
-          limit: 3,
-          minSimilarity: DELETE_MIN_SIMILARITY
-        })
-
-        const matchId = results[0]?.memory?.id || results[0]?.decision?.id || results[0]?.id
-        const matchSimilarity = results[0]?.similarity || 0
-
-        if (results.length > 0 && matchId && matchSimilarity >= DELETE_MIN_SIMILARITY) {
-          const targetId = matchId
-          const content = results[0].decision?.decision || results[0].memory?.content?.slice(0, 100) || results[0].content?.slice(0, 100) || ''
-
-          await memory.deleteDecision(targetId)
-          if (this.lastStoredId === targetId) this.lastStoredId = null
-
-          // Invalidate cache
-          this.searchEngine.invalidateCache(effectiveProject)
-
-          return {
-            action: 'stored',
-            summary: `Deleted memory`,
-            content: `Deleted: "${content.slice(0, 100)}" (ID: ${targetId})`,
-            relevantItems: 0
-          }
-        } else if (results.length > 0 && matchSimilarity < DELETE_MIN_SIMILARITY) {
-          // D4: No confident match — try direct FTS5 content search as fallback
-          const memory = getMemoryService()
-          if (memory.fts5) {
-            const ftsResults = memory.fts5.search(topic, effectiveProject, 3)
-            if (ftsResults.length > 0) {
-              const ftsTarget = ftsResults[0]
-              await memory.deleteDecision(ftsTarget.id)
-              if (this.lastStoredId === ftsTarget.id) this.lastStoredId = null
-              this.searchEngine.invalidateCache(effectiveProject)
-              return {
-                action: 'stored',
-                summary: `Deleted memory`,
-                content: `Deleted: "${ftsTarget.content.slice(0, 100)}" (ID: ${ftsTarget.id})`,
-                relevantItems: 0
-              }
-            }
-          }
-          return {
-            action: 'none',
-            summary: 'No confident match to delete',
-            content: `Found a possible match but similarity (${Math.round(matchSimilarity * 100)}%) is too low for safe deletion. Try being more specific about what to delete.`,
-            relevantItems: 0
-          }
-        }
-      } catch {
-        // Search failed, fall through
-      }
-    }
-
-    // Generic request — use lastStoredId
-    if (this.lastStoredId) {
-      try {
-        await memory.deleteDecision(this.lastStoredId)
-        const deletedId = this.lastStoredId
-        this.lastStoredId = null
-        this.searchEngine.invalidateCache(effectiveProject)
-        return {
-          action: 'stored',
-          summary: `Deleted most recent memory`,
-          content: `Deleted memory (ID: ${deletedId})`,
-          relevantItems: 0
-        }
-      } catch {
-        // Deletion failed
-      }
-    }
-
-    return {
-      action: 'none',
-      summary: 'No matching memory found to delete',
-      content: 'Could not find a memory matching your request. Try being more specific about what to delete.',
-      relevantItems: 0
-    }
-  }
-
-  /**
-   * Phase 19 C7+C10+C11: Enhanced question handler
-   * - Uses SearchEngine for all searches (hybrid, cached)
-   * - Temporal search when temporal signals detected
-   * - ChainRetrieval for complex multi-part questions
-   * - CrossProject patterns for general/unspecified project
-   * - KnowledgeGraph enrichment
-   */
-  private async handleQuestion(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities,
-    classification: ClassificationResult
-  ): Promise<BrainResponse> {
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    // BUG-002: Detect category-based queries and route to fetchAll
-    const categoryIntent = this.detectCategoryIntent(message)
-    if (categoryIntent) {
-      return this.handleCategoryQuery(message, project, categoryIntent)
-    }
-
-    // Phase 25: Use undefined for search (no project filter = search all) when no project detected
-    const searchProject = project || undefined
-    const displayProject = project || DEFAULT_PROJECT
-    const query = entities.topic || message
-    const tiers: TierResults[] = []
-    const hasTemporal = classification.secondary.includes('exploration') ||
-      this.classifier.hasTemporalSignal(message.toLowerCase())
-
-    // C7: Detect multi-part questions for chain retrieval
-    const isComplex = this.isComplexQuestion(message)
-
-    // Main search — temporal or standard
-    let searchResults: NormalizedResult[]
-    if (hasTemporal) {
-      const { results } = await this.searchEngine.temporalSearch(query, { project: searchProject, limit: 5 })
-      searchResults = results
-    } else if (isComplex) {
-      // C7: Try multi-hop chain retrieval
-      const chainResult = await this.searchEngine.chainSearch(query, { project: searchProject })
-      if (chainResult?.allResults?.length) {
-        searchResults = chainResult.allResults.map((r: any) => ({
-          id: r.id || '',
-          content: r.content || '',
-          score: r.similarity || 0,
-          source: 'decision' as const,
-          project: r.metadata?.project || displayProject || '',
-          date: r.metadata?.created_at || '',
-          metadata: r.metadata || {}
-        }))
-      } else {
-        searchResults = await this.searchEngine.enhancedSearch(query, { project: searchProject, limit: 5 })
-      }
-    } else {
-      searchResults = await this.searchEngine.enhancedSearch(query, { project: searchProject, limit: 5 })
-    }
-
-    if (searchResults.length > 0) {
-      tiers.push({
-        label: 'Memories',
-        results: searchResults.map(r => ({
-          content: r.content,
-          score: r.score,
-          source: r.source === 'decision' ? 'Past Decision' : r.source,
-          metadata: {
-            ...(r.metadata as Record<string, unknown>),
-            id: r.id,
-            project: r.project,
-            created_at: r.date
-          }
-        }))
-      })
-    }
-
-    // Phase 32: Code intelligence — synchronous SQLite query, runs alongside async searches
-    const codeTier = this.queryCodeIntelligence(query, searchProject)
-    if (codeTier) {
-      tiers.push(codeTier)
-    }
-
-    // Parallel: patterns + corrections + graph
-    const [patternResults, correctionResults, graphResults] = await Promise.all([
-      this.searchEngine.searchPatterns(query, { project: searchProject, limit: 3 }),
-      this.searchEngine.searchCorrections(query, { project: searchProject, limit: 3 }),
-      // C11: KnowledgeGraph enrichment for all questions
-      this.searchEngine.searchGraph(query, 5)
-    ])
-
-    if (patternResults.length > 0) {
-      tiers.push({
-        label: 'Patterns',
-        results: patternResults.map(p => ({
-          content: p.content,
-          score: p.score,
-          source: `Pattern`,
-          metadata: {
-            ...(p.metadata as Record<string, unknown>),
-            id: p.id,
-            project: p.project,
-            created_at: p.date,
-            category: 'pattern'
-          }
-        }))
-      })
-    }
-
-    if (correctionResults.length > 0) {
-      tiers.push({
-        label: 'Corrections',
-        results: correctionResults.map(c => ({
-          content: c.content,
-          score: c.score,
-          source: 'Lesson Learned',
-          metadata: {
-            ...(c.metadata as Record<string, unknown>),
-            id: c.id,
-            project: c.project,
-            created_at: c.date,
-            category: 'correction'
-          }
-        }))
-      })
-    }
-
-    // C11: Add graph results as "Related Concepts"
-    // When a project filter is active, cap graph results lower (0.25) so they don't
-    // outrank project-scoped ChromaDB results. Without a project filter, cap at 0.4.
-    // BUG-006 T4: Also require keyword overlap with query to prevent noise
-    const graphScoreCap = searchProject ? 0.25 : 0.4
-    const queryWordsForGraph = new Set(query.toLowerCase().split(/\s+/).filter(w => w.length > 2))
-    const relevantGraphResults = graphResults.filter(g => {
-      if (g.score < 0.6) return false
-      // Require at least one query keyword to appear in graph content
-      if (queryWordsForGraph.size > 0) {
-        const contentLower = g.content.toLowerCase()
-        const hasOverlap = [...queryWordsForGraph].some(w => contentLower.includes(w))
-        if (!hasOverlap) return false
-      }
-      return true
-    })
-    if (relevantGraphResults.length > 0) {
-      tiers.push({
-        label: 'Related Concepts',
-        results: relevantGraphResults.map(g => ({
-          content: g.content,
-          score: Math.min(g.score, graphScoreCap),
-          source: 'Knowledge Graph',
-          metadata: g.metadata as Record<string, unknown>
-        }))
-      })
-    }
-
-    // C10: CrossProject patterns for general/unspecified project queries (Bug 2: cap to 0.3)
-    if (!project) {
-      try {
-        const crossProject = await this.searchEngine.findCrossProjectPatterns({
-          query,
-          limit: 3
-        })
-        if (crossProject?.patterns?.length) {
-          tiers.push({
-            label: 'Cross-Project Patterns',
-            results: crossProject.patterns.map((p: any) => ({
-              content: `${p.description || ''} (${p.projects?.join(', ') || 'multiple projects'})`,
-              score: Math.min(p.confidence || 0.5, 0.3),
-              source: 'Cross-Project',
-              metadata: {}
-            }))
-          })
-        }
-      } catch {
-        // Cross-project not available
-      }
-    }
-
-    // Phase 23b Fix 5: Session recall — "what have we discussed" queries session tracker
-    if (this.isSessionRecallQuery(message)) {
-      try {
-        const tracker = getSessionTracker()
-        if (tracker) {
-          const stats = tracker.getStats()
-          if (stats.totalItems > 0) {
-            tiers.push({
-              label: 'Current Session',
-              results: [{
-                content: `Active sessions: ${stats.activeSessions}, items tracked: ${stats.totalItems}`,
-                score: 0.95,
-                source: 'Session Tracker',
-                metadata: {}
-              }]
-            })
-          }
-        }
-      } catch {
-        // Session tracker not available
-      }
-    }
-
-    // Bug 4: Inject recently stored decisions using keyword overlap as score
-    const recentMatches = this.findRecentDecisions(query, searchProject)
-    // Only include results whose overlap score meets the hard floor (0.35)
-    const qualifiedRecent = recentMatches.filter(d => (d.overlapScore || 0) >= 0.35)
-    if (qualifiedRecent.length > 0) {
-      tiers.unshift({
-        label: 'Recent Decisions',
-        results: qualifiedRecent.map(d => ({
-          content: d.content,
-          score: d.overlapScore || 0,
-          source: 'Recent Decision',
-          metadata: { storedAt: d.storedAt, project: d.project }
-        }))
-      })
-    }
-
-    // Register with episode
-    this.registerEpisodeMessage(message, displayProject, 'question')
-
-    // Phase 27: Use compact format for progressive disclosure
-    // Combine all tier results, filter, then format compactly
-    const allResults: import('./response-filter').FilterableResult[] = []
-    for (const tier of tiers) {
-      allResults.push(...tier.results)
-    }
-
-    if (allResults.length === 0) {
-      return {
-        action: 'none',
-        summary: 'No relevant information found',
-        content: `No results found for: "${message.slice(0, 100)}"`,
-        relevantItems: 0
-      }
-    }
-
-    const filtered = this.responseFilter.filter(allResults, message, displayProject)
-    if (filtered.length === 0) {
-      return {
-        action: 'none',
-        summary: 'Results filtered out as noise or irrelevant',
-        content: `No relevant results after filtering for: "${message.slice(0, 100)}"`,
-        relevantItems: 0
-      }
-    }
-
-    // Collect result IDs for detail lookups
-    const resultIds = filtered
-      .map(r => (r.metadata as any)?.id || (r.metadata as any)?.decision_id)
-      .filter(Boolean)
-
-    const compactContent = formatCompactResponse(filtered, message)
-    return {
-      action: 'retrieved',
-      summary: `Found ${filtered.length} result${filtered.length === 1 ? '' : 's'}`,
-      content: compactContent,
-      relevantItems: filtered.length
-    }
-  }
-
-  /**
-   * Phase 19 C6: Enhanced exploration handler
-   * - Timeline for "timeline"/"chronological" queries
-   * - DecisionEvolutionTracker for "how has X changed" queries
-   * - TrendDetector for "trends"/"emerging" queries
-   */
-  private async handleExploration(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    // Phase 25: Use undefined for search when no project detected
-    const searchProject = project || undefined
-    const displayProject = project || DEFAULT_PROJECT
-    const query = entities.topic || message
-    const lower = message.toLowerCase()
-    const tiers: TierResults[] = []
-
-    // C6: Timeline queries
-    if (lower.includes('timeline') || lower.includes('chronological') || lower.includes('history of')) {
-      const timeline = await this.searchEngine.buildTimeline({
-        project: searchProject,
-        topic: query,
-        limit: 20
-      })
-
-      if (timeline?.entries?.length) {
-        tiers.push({
-          label: 'Timeline',
-          results: timeline.entries.map((e: any) => ({
-            content: `**${e.date || ''}** — ${e.content || ''}`,
-            score: 0.8,
-            source: `Timeline (${e.type || 'event'})`,
-            metadata: e.metadata || {}
-          }))
-        })
-      }
-    }
-
-    // C6: Evolution queries
-    if (lower.includes('evolution') || lower.includes('how has') || lower.includes('changed') || lower.includes('evolved')) {
-      const evolution = await this.searchEngine.analyzeEvolution(query, { project: searchProject })
-      if (evolution?.timeline?.length) {
-        const parts = []
-        parts.push(`**Stability:** ${evolution.stability || 'unknown'}`)
-        if (evolution.currentState) parts.push(`**Current:** ${evolution.currentState}`)
-        for (const change of (evolution.changes || []).slice(0, 5)) {
-          parts.push(`- ${change.description || change}`)
-        }
-
-        tiers.push({
-          label: 'Decision Evolution',
-          results: [{
-            content: parts.join('\n'),
-            score: 0.8,
-            source: 'Evolution Analysis',
-            metadata: {}
-          }]
-        })
-      }
-    }
-
-    // C6: Trend queries
-    if (lower.includes('trend') || lower.includes('emerging') || lower.includes('declining')) {
-      const trends = await this.searchEngine.detectTrends({ project: searchProject })
-      if (trends?.topTrends?.length) {
-        tiers.push({
-          label: 'Trends',
-          results: trends.topTrends.slice(0, 5).map((t: any) => ({
-            content: `**${t.term}** — ${t.trend} (${t.occurrences} occurrences, momentum: ${t.momentum || 'unknown'})`,
-            score: t.occurrences > 5 ? 0.9 : 0.7,
-            source: `Trend (${t.trend})`,
-            metadata: {}
-          }))
-        })
-      }
-    }
-
-    // Always include graph exploration — cap scores when project filter is active
-    // BUG-006 T4: Also require keyword overlap with query to prevent noise
-    const explorationGraphCap = searchProject ? 0.25 : 0.5
-    const explorationQueryWords = new Set(query.toLowerCase().split(/\s+/).filter(w => w.length > 2))
-    const graphResults = await this.searchEngine.searchGraph(query, 10)
-    const filteredGraphResults = graphResults.filter(g => {
-      if (explorationQueryWords.size > 0) {
-        const contentLower = g.content.toLowerCase()
-        return [...explorationQueryWords].some(w => contentLower.includes(w))
-      }
-      return true
-    })
-    if (filteredGraphResults.length > 0) {
-      tiers.push({
-        label: 'Knowledge Graph',
-        results: filteredGraphResults.map(g => ({
-          content: g.content,
-          score: Math.min(g.score, explorationGraphCap),
-          source: 'Knowledge Graph',
-          metadata: g.metadata as Record<string, unknown>
-        }))
-      })
-    }
-
-    // Issue 9: Cross-project patterns for exploration queries
-    if (!project) {
-      try {
-        const crossProject = await this.searchEngine.findCrossProjectPatterns({
-          query,
-          limit: 3
-        })
-        if (crossProject?.patterns?.length) {
-          tiers.push({
-            label: 'Cross-Project Patterns',
-            results: crossProject.patterns.map((p: any) => ({
-              content: `${p.description || ''} (${p.projects?.join(', ') || 'multiple projects'})`,
-              score: p.confidence || 0.5,
-              source: 'Cross-Project',
-              metadata: {}
-            }))
-          })
-        }
-      } catch {
-        // Cross-project not available
-      }
-    }
-
-    // Also do a basic memory search as fallback
-    const searchResults = await this.searchEngine.enhancedSearch(query, {
-      project: searchProject,
-      limit: 5,
-      minSimilarity: 0.2
-    })
-    if (searchResults.length > 0) {
-      tiers.push({
-        label: 'Memories',
-        results: searchResults.map(r => ({
-          content: r.content,
-          score: r.score,
-          source: r.source === 'decision' ? 'Past Decision' : r.source,
-          metadata: r.metadata as Record<string, unknown>
-        }))
-      })
-    }
-
-    // Phase 32: Code intelligence for exploration queries
-    const codeTier = this.queryCodeIntelligence(query, searchProject)
-    if (codeTier) {
-      tiers.push(codeTier)
-    }
-
-    return this.responseFilter.synthesize(tiers, message, displayProject, 'analyzed')
-  }
-
-  private async handleComparison(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    // Phase 25: Use undefined for search when no project detected
-    const searchProject = project || undefined
-    const displayProject = project || DEFAULT_PROJECT
-    const query = entities.topic || message
-    const tiers: TierResults[] = []
-
-    // Search for related decisions
-    const searchResults = await this.searchEngine.enhancedSearch(query, {
-      project: searchProject,
-      limit: 5,
-      minSimilarity: 0.2
-    })
-    if (searchResults.length > 0) {
-      tiers.push({
-        label: 'Related Decisions',
-        results: searchResults.map(r => ({
-          content: r.content,
-          score: r.score,
-          source: 'Past Decision',
-          metadata: r.metadata as Record<string, unknown>
-        }))
-      })
-    }
-
-    // Graph search for comparison context
-    const graphResults = await this.searchEngine.searchGraph(query, 5)
-    if (graphResults.length > 0) {
-      tiers.push({
-        label: 'Knowledge Graph',
-        results: graphResults.map(g => ({
-          content: g.content,
-          score: g.score,
-          source: 'Knowledge Graph',
-          metadata: g.metadata as Record<string, unknown>
-        }))
-      })
-    }
-
-    return this.responseFilter.synthesize(tiers, message, displayProject, 'analyzed')
-  }
-
-  /**
-   * Phase 27: Handle detail requests — "details obs_abc123", "expand <id>"
-   * Looks up a single observation by ID and returns full detail view.
-   */
-  private async handleDetailRequest(
-    message: string,
-    project: string | undefined,
-    _entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    // Extract ID from message using regex
-    const idMatch = message.match(/\b(obs_\w+|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{8,})\b/i)
-    if (!idMatch) {
-      return {
-        action: 'none',
-        summary: 'No observation ID provided',
-        content: 'Please provide an observation ID. Use brain("details {ID}") with an ID from search results.',
-        relevantItems: 0
-      }
-    }
-
-    const id = idMatch[1]
-    const observation = await this.lookupById(id)
-
-    if (!observation) {
-      return {
-        action: 'none',
-        summary: `No observation found: ${id}`,
-        content: `No observation found with ID: ${id}`,
-        relevantItems: 0
-      }
-    }
-
-    // Increment access count
-    this.incrementAccess(id)
-
-    return {
-      action: 'retrieved',
-      summary: `Details for ${id.slice(0, 12)}...`,
-      content: formatDetailResponse(observation),
-      relevantItems: 1
-    }
-  }
-
-  /**
-   * Phase 27: Handle timeline requests — "timeline for project", "recent activity"
-   * Fetches observations in a time range and groups by day.
-   */
-  private async handleTimeline(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    const effectiveProject = entities.project || project
-    const displayProject = effectiveProject || DEFAULT_PROJECT
-
-    // Parse time range from message (default: last 7 days)
-    const now = new Date()
-    let start: Date
-    let daysBack = 7
-    const lower = message.toLowerCase()
-    if (lower.includes('yesterday')) {
-      daysBack = 1
-      start = new Date(now.getTime() - 1 * 24 * 60 * 60 * 1000)
-    } else if (lower.includes('today')) {
-      daysBack = 0
-      // Start of today, not "now"
-      start = new Date(now.getFullYear(), now.getMonth(), now.getDate())
-    } else if (lower.includes('last month') || lower.includes('past month')) {
-      daysBack = 30
-      start = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000)
-    } else if (lower.includes('last week') || lower.includes('past week')) {
-      daysBack = 7
-      start = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000)
-    } else if (lower.includes('last 3 days') || lower.includes('past 3 days')) {
-      daysBack = 3
-      start = new Date(now.getTime() - 3 * 24 * 60 * 60 * 1000)
-    } else {
-      start = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000)
-    }
-
-    const observations = await this.fetchRecentObservations(effectiveProject, start, now)
-    if (observations.length === 0) {
-      return {
-        action: 'none',
-        summary: `No activity found for ${displayProject}`,
-        content: `No observations found in the last ${daysBack === 0 ? 'day' : `${daysBack} day(s)`} for ${displayProject}.`,
-        relevantItems: 0
-      }
-    }
-
-    const grouped = groupByDay(observations)
-    const timelineContent = formatTimeline(grouped, displayProject)
-
-    return {
-      action: 'retrieved',
-      summary: `Timeline for ${displayProject} (${observations.length} items)`,
-      content: timelineContent,
-      relevantItems: observations.length
-    }
-  }
-
-  /**
-   * Phase 27: Look up a single observation by ID.
-   * Tries FTS5 first, then falls back to ChromaDB search.
-   */
-  private async lookupById(id: string): Promise<any | null> {
-    const memory = getMemoryService()
-
-    // Try FTS5 first (fast, direct lookup)
-    if (memory.fts5) {
-      const result = memory.fts5.getById(id)
-      if (result) return result
-    }
-
-    // Fallback: search ChromaDB by ID if available
-    if (memory.isChromaDBEnabled()) {
-      try {
-        const collections = memory.chroma.collections
-        // Try decisions collection
-        const decisions = await collections.getDecisions()
-        if (decisions) {
-          try {
-            const result = await decisions.get({ ids: [id] })
-            if (result?.documents?.[0]) {
-              return {
-                id,
-                content: result.documents[0],
-                metadata: result.metadatas?.[0] || {},
-                category: 'decision',
-                project: (result.metadatas?.[0] as any)?.project || '',
-                created_at: (result.metadatas?.[0] as any)?.created_at || '',
-                reasoning: (result.metadatas?.[0] as any)?.reasoning || null,
-                tags: [],
-                confidence: 0.8
-              }
-            }
-          } catch { /* ID not in this collection */ }
-        }
-      } catch {
-        // ChromaDB lookup failed
-      }
-    }
-
-    return null
-  }
-
-  /**
-   * Phase 27: Fetch recent observations in a date range.
-   * Tries FTS5 first, then falls back to ChromaDB temporal search.
-   */
-  private async fetchRecentObservations(
-    project: string | undefined,
-    start: Date,
-    end: Date
-  ): Promise<any[]> {
-    const memory = getMemoryService()
-
-    // Try FTS5 first (efficient SQL-level date filtering)
-    if (memory.fts5 && project) {
-      return memory.fts5.fetchByTimeRange(project, start, end)
-    }
-
-    // Also try FTS5 without project filter
-    if (memory.fts5 && !project) {
-      // FTS5 fetchByTimeRange requires project, use fetchAll with date filtering
-      try {
-        const all = memory.fts5.search('*', undefined, 100)
-        return all.filter(r => {
-          const date = new Date(r.created_at)
-          if (isNaN(date.getTime())) return false
-          return date >= start && date <= end
-        }).sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())
-      } catch {
-        // FTS5 search failed, fall through
-      }
-    }
-
-    // Fallback: use memory fetchAll with date filtering
-    try {
-      const allDecisions = await memory.fetchAllDecisions(project)
-      const allPatterns = await memory.fetchAllPatterns(project)
-      const allCorrections = await memory.fetchAllCorrections(project)
-
-      const allItems = [
-        ...allDecisions.map((d: any) => ({
-          id: d.id || d.decision_id,
-          content: d.decision || d.document || d.content || '',
-          category: 'decision',
-          project: d.project || project || DEFAULT_PROJECT,
-          created_at: d.created_at || d.date || '',
-        })),
-        ...allPatterns.map((p: any) => ({
-          id: p.id,
-          content: p.description || p.document || p.content || '',
-          category: p.pattern_type || 'pattern',
-          project: p.project || project || DEFAULT_PROJECT,
-          created_at: p.created_at || '',
-        })),
-        ...allCorrections.map((c: any) => ({
-          id: c.id,
-          content: c.original || c.document || c.content || '',
-          category: 'correction',
-          project: c.project || project || DEFAULT_PROJECT,
-          created_at: c.created_at || '',
-        })),
-      ]
-
-      return allItems.filter(item => {
-        if (!item.created_at) return true // include items without dates
-        const date = new Date(item.created_at)
-        if (isNaN(date.getTime())) return true
-        return date >= start && date <= end
-      }).sort((a, b) => {
-        const dateA = new Date(a.created_at || 0).getTime()
-        const dateB = new Date(b.created_at || 0).getTime()
-        return dateB - dateA
-      })
-    } catch {
-      return []
-    }
-  }
-
-  /**
-   * Phase 27: Increment access count for an observation.
-   */
-  private incrementAccess(id: string): void {
-    try {
-      const memory = getMemoryService()
-      if (memory.fts5) {
-        memory.fts5.recordAccess(id)
-      }
-    } catch {
-      // Non-critical
-    }
-  }
-
-  // ===== Helpers =====
-
-  /**
-   * Phase 32: Query code intelligence for symbols and files matching a query.
-   * Returns a TierResults if matches found, null otherwise.
-   * Fast operation — direct SQLite queries, no network calls.
-   */
-  private queryCodeIntelligence(query: string, project: string | undefined): TierResults | null {
-    try {
-      const codeQuery = getCodeQuery()
-      if (!codeQuery) return null
-
-      // Extract meaningful keywords from query for code search
-      const keywords = this.extractCodeKeywords(query)
-      if (keywords.length === 0) return null
-
-      const results: FilterableResult[] = []
-
-      for (const keyword of keywords) {
-        // Search symbols across all indexed projects (project may not match code index project name)
-        const symbolResults = codeQuery.findSymbols(keyword, project || '', 5)
-
-        // If no results with project filter, try without (code index may use path-based project names)
-        const symbols = symbolResults.length > 0
-          ? symbolResults
-          : codeQuery.findSymbols(keyword, '', 5)
-
-        for (const sym of symbols.slice(0, 3)) {
-          const location = sym.lineEnd
-            ? `${sym.filePath}:${sym.lineStart}-${sym.lineEnd}`
-            : `${sym.filePath}:${sym.lineStart}`
-          const sigPart = sym.signature ? ` — \`${sym.signature}\`` : ''
-          results.push({
-            content: `**${sym.symbol}** (${sym.type}) at \`${location}\`${sigPart}`,
-            score: sym.confidence * 0.6, // Scale down so memories rank higher
-            source: 'Code Index',
-            metadata: {
-              filePath: sym.filePath,
-              lineStart: sym.lineStart,
-              lineEnd: sym.lineEnd,
-              symbolType: sym.type,
-            }
-          })
-        }
-
-        // Also search files by name/summary
-        const fileResults = codeQuery.findFiles(keyword, project || '')
-        const files = fileResults.length > 0
-          ? fileResults
-          : codeQuery.findFiles(keyword, '')
-
-        for (const file of files.slice(0, 3)) {
-          // Skip if we already have symbol results from this file
-          if (results.some(r => (r.metadata as any)?.filePath === file.filePath)) continue
-          const summaryPart = file.summary ? ` — ${file.summary}` : ''
-          results.push({
-            content: `**${file.filePath}** (${file.language || 'unknown'}, ${file.symbolCount} symbols, ${file.lineCount} lines)${summaryPart}`,
-            score: 0.4, // File matches are lower confidence
-            source: 'Code Index',
-            metadata: {
-              filePath: file.filePath,
-              symbolCount: file.symbolCount,
-            }
-          })
-        }
-      }
-
-      // Deduplicate by filePath
-      const seen = new Set<string>()
-      const deduped = results.filter(r => {
-        const fp = (r.metadata as any)?.filePath
-        if (fp && seen.has(fp)) return false
-        if (fp) seen.add(fp)
-        return true
-      })
-
-      if (deduped.length === 0) return null
-
-      return {
-        label: 'Code Intelligence',
-        results: deduped.slice(0, 5)
-      }
-    } catch (error) {
-      this.logger.debug({ error }, 'Code intelligence query failed (non-fatal)')
-      return null
-    }
-  }
-
-  /**
-   * Extract meaningful keywords from a natural language query for code search.
-   * Filters out stop words and common filler, returns words likely to match code symbols.
-   */
-  private extractCodeKeywords(query: string): string[] {
-    const STOP_WORDS = new Set([
-      'how', 'what', 'where', 'when', 'why', 'who', 'which', 'are', 'is', 'was',
-      'were', 'been', 'being', 'have', 'has', 'had', 'having', 'do', 'does', 'did',
-      'doing', 'will', 'would', 'could', 'should', 'shall', 'can', 'may', 'might',
-      'must', 'the', 'a', 'an', 'and', 'but', 'or', 'nor', 'for', 'yet', 'so',
-      'in', 'on', 'at', 'to', 'from', 'by', 'with', 'about', 'into', 'through',
-      'during', 'before', 'after', 'above', 'below', 'between', 'out', 'off', 'over',
-      'under', 'again', 'further', 'then', 'once', 'here', 'there', 'all', 'each',
-      'every', 'both', 'few', 'more', 'most', 'other', 'some', 'such', 'only', 'own',
-      'same', 'than', 'too', 'very', 'just', 'because', 'not', 'this', 'that', 'these',
-      'those', 'its', 'our', 'their', 'your', 'my', 'me', 'we', 'you', 'they', 'them',
-      'know', 'tell', 'show', 'find', 'get', 'make', 'use', 'using', 'used', 'managing',
-      'managed', 'handle', 'handling', 'handled', 'work', 'working', 'works', 'implement',
-      'implementing', 'implemented', 'doing', 'done', 'project', 'code', 'file', 'function',
-    ])
-
-    const words = query.toLowerCase()
-      .replace(/[^a-z0-9\s-_]/g, ' ')
-      .split(/\s+/)
-      .filter(w => w.length > 2 && !STOP_WORDS.has(w))
-
-    // Also try multi-word phrases (camelCase/kebab-case patterns the user might reference)
-    const phrases: string[] = []
-    for (let i = 0; i < words.length - 1; i++) {
-      // Create camelCase combo: "brain router" → "brainRouter"
-      phrases.push(words[i] + words[i + 1].charAt(0).toUpperCase() + words[i + 1].slice(1))
-    }
-
-    // Return unique keywords, single words first then phrases
-    return [...new Set([...words, ...phrases])].slice(0, 5)
-  }
-
-  /**
-   * Phase 29: Link a stored observation to code files (non-blocking, fire-and-forget).
-   */
-  private linkToCodeFiles(observationId: string, content: string, project: string): void {
-    try {
-      const linker = getCodeLinker()
-      if (linker) {
-        linker.linkObservation(observationId, content, project).catch(err => {
-          this.logger.debug({ err }, 'Code linkage failed (non-fatal)')
-        })
-      }
-    } catch {
-      // Linker not available
-    }
-  }
-
-  private async writeToVault(
-    project: string,
-    decision: string,
-    reasoning: string,
-    context: string,
-    alternatives?: string
-  ): Promise<void> {
-    try {
-      const vault = getVaultService()
-      const projectPaths = vault.getProjectPaths(project)
-      const date = new Date().toISOString().split('T')[0]
-      const entry = `### Decision: ${decision.slice(0, 100)}\n\n**Date:** ${date}\n**Context:** ${context}\n**Decision:** ${decision}\n**Reasoning:** ${reasoning}\n${alternatives ? `**Alternatives:** ${alternatives}\n` : ''}\n---\n\n`
-      await vault.writer.appendContent(projectPaths.decisions, entry, '\n')
-    } catch {
-      // Vault write failed
-    }
-  }
-
-  /**
-   * Store as a new decision (fallback for update when no match found)
-   */
-  private async storeAsNew(
-    memory: any,
-    project: string,
-    message: string,
-    topic: string,
-    entities: BrainExtractedEntities,
-    reason: string
-  ): Promise<BrainResponse> {
-    const decisionId = await memory.rememberDecision(
-      project,
-      topic.slice(0, 200),
-      message,
-      entities.reasoning || '',
-      { tags: entities.technologies.length > 0 ? entities.technologies : ['updated'] }
-    )
-
-    this.lastStoredId = decisionId
-    this.lastStoredProject = project
-    this.searchEngine.invalidateCache(project)
-
-    return {
-      action: 'stored',
-      summary: `Stored as new (${reason})`,
-      content: `Stored as new decision (ID: ${decisionId})\n\n**Project:** ${project}\n**Content:** ${message}`,
-      relevantItems: 1
-    }
-  }
-
-  /**
-   * C8: Register a message with the episode manager
-   */
-  private registerEpisodeMessage(message: string, project?: string, role: string = 'user'): void {
-    try {
-      const episodeManager = getEpisodeService()
-      if (!episodeManager) return
-      episodeManager.processMessage(
-        { role: role as 'user' | 'assistant' | 'system', content: message, timestamp: new Date().toISOString() },
-        project
-      ).catch(() => {})
-    } catch {
-      // Episode manager not available
-    }
-  }
-
-  /**
-   * C8: Link a stored decision/pattern/correction to the active episode
-   */
-  private linkToActiveEpisode(project: string, id: string, type: 'decision' | 'pattern' | 'correction'): void {
-    try {
-      const episodeManager = getEpisodeService()
-      if (!episodeManager) return
-      const activeEpisode = episodeManager.getActiveEpisode(project)
-      if (!activeEpisode) return
-
-      if (type === 'decision') episodeManager.linkDecision(activeEpisode.id, id)
-      else if (type === 'pattern') episodeManager.linkPattern(activeEpisode.id, id)
-      else if (type === 'correction') episodeManager.linkCorrection(activeEpisode.id, id)
-    } catch {
-      // Episode manager not available
-    }
-  }
-
-  /**
-   * Phase 23b: Detect session recall queries ("what have we discussed", "this session", etc.)
-   */
-  private isSessionRecallQuery(message: string): boolean {
-    const lower = message.toLowerCase()
-    const SESSION_RECALL_PHRASES = [
-      'what have we discussed',
-      'what did we discuss',
-      'what have we talked about',
-      'what did we talk about',
-      'this session',
-      'current session',
-      'session so far',
-      'what have we done',
-      'what did we do',
-      'session summary',
-      'summarize this session',
-      'recap this session',
-      'what happened this session',
-      'what have we covered'
-    ]
-    return SESSION_RECALL_PHRASES.some(p => lower.includes(p))
-  }
-
-  /**
-   * C7: Detect complex multi-part questions
-   */
-  private isComplexQuestion(message: string): boolean {
-    // Multiple question marks
-    const questionMarks = (message.match(/\?/g) || []).length
-    if (questionMarks >= 2) return true
-    // Very long question (likely multi-part)
-    if (message.length > 200 && message.includes('?')) return true
-    // Multiple clauses with "and" or "also"
-    if (message.includes(' and ') && message.includes('?') && message.length > 100) return true
-    return false
-  }
-
-  private servicesNotReady(): BrainResponse {
-    return {
-      action: 'none',
-      summary: 'Services not initialized',
-      content: 'Claude Brain services are not ready. The server may still be starting up.',
-      relevantItems: 0
-    }
-  }
-
-  /**
-   * Check if a delete/update message has descriptive content beyond just the command words.
-   */
-  private hasDescriptiveContent(message: string): boolean {
-    const COMMAND_WORDS = [
-      'forget', 'delete', 'remove', 'discard', 'erase', 'undo', 'clear', 'drop',
-      'actually', 'correction', 'update', 'change', 'replace', 'modify', 'revise',
-      'amend', 'override', 'scratch', 'no', 'wait', 'instead',
-      'that', 'this', 'the', 'it', 'about', 'memory', 'decision', 'to', 'a', 'an'
-    ]
-    const words = message.toLowerCase().split(/[\s,;:.!?]+/).filter(w => w.length > 1)
-    const meaningfulWords = words.filter(w => !COMMAND_WORDS.includes(w))
-    return meaningfulWords.length >= 2
-  }
-
-  /**
-   * Bug 4: Track a recently stored decision for recency fast path
-   */
-  private trackRecentDecision(content: string, project: string): void {
-    const now = Date.now()
-    // Prune expired entries
-    this.recentDecisions = this.recentDecisions.filter(
-      d => now - d.storedAt < RECENT_DECISION_WINDOW_MS
-    )
-    this.recentDecisions.push({ content, project, storedAt: now })
-  }
-
-  /**
-   * Bug 4: Find recent decisions matching a query by keyword overlap.
-   * Returns matches with their overlapScore (ratio of query keywords found in content).
-   */
-  private findRecentDecisions(query: string, project?: string): RecentDecision[] {
-    const now = Date.now()
-    // Prune expired
-    this.recentDecisions = this.recentDecisions.filter(
-      d => now - d.storedAt < RECENT_DECISION_WINDOW_MS
-    )
-
-    const queryWords = new Set(
-      query.toLowerCase().split(/\s+/).filter(w => w.length > 2)
-    )
-    if (queryWords.size === 0) return []
-
-    const matches: RecentDecision[] = []
-    for (const d of this.recentDecisions) {
-      // Project filter: skip if searching a specific project and it doesn't match
-      if (project && d.project !== project) continue
-      const contentWords = new Set(d.content.toLowerCase().split(/\s+/).filter(w => w.length > 2))
-      const overlap = [...queryWords].filter(w => contentWords.has(w)).length
-      if (overlap >= 1) {
-        const overlapScore = overlap / queryWords.size
-        matches.push({ ...d, overlapScore })
-      }
-    }
-    return matches
-  }
-
-  /**
-   * Phase 30: Optionally compress content before storing.
-   * Returns the (possibly compressed) content and original if compressed.
-   */
-  private async maybeCompress(content: string, category: string): Promise<{ content: string; rawContent?: string }> {
-    if (!this.compressor) return { content }
-    try {
-      const result = await this.compressor.compress(content, category)
-      if (result.compressed) {
-        return { content: result.summary, rawContent: result.original }
-      }
-    } catch {
-      // Compression failed, use original
-    }
-    return { content }
-  }
-
-  /**
-   * BUG-002: Detect category-based intent from question messages.
-   * Returns the category if the user is asking about a specific type of memory.
-   */
-  private detectCategoryIntent(message: string): 'decision' | 'pattern' | 'correction' | null {
-    const lower = message.toLowerCase()
-
-    // Decision-oriented queries
-    if (
-      lower.includes('what decisions') || lower.includes('my decisions') ||
-      lower.includes('what have i decided') || lower.includes('what did i decide') ||
-      lower.includes('what choices') || lower.includes('decisions i') ||
-      lower.includes('list decisions') || lower.includes('show decisions') ||
-      lower.includes('all decisions') || lower.includes('what did i choose')
-    ) {
-      return 'decision'
-    }
-
-    // Pattern-oriented queries
-    if (
-      lower.includes('what patterns') || lower.includes('my patterns') ||
-      lower.includes('best practices') || lower.includes('conventions') ||
-      lower.includes('list patterns') || lower.includes('show patterns') ||
-      lower.includes('all patterns')
-    ) {
-      return 'pattern'
-    }
-
-    // Correction-oriented queries
-    if (
-      lower.includes('what mistakes') || lower.includes('my mistakes') ||
-      lower.includes('what bugs') || lower.includes('lessons learned') ||
-      lower.includes('what corrections') || lower.includes('my corrections') ||
-      lower.includes('list corrections') || lower.includes('show corrections') ||
-      lower.includes('all corrections') || lower.includes('what have i fixed') ||
-      lower.includes('what did i fix')
-    ) {
-      return 'correction'
-    }
-
-    return null
-  }
-
-  /**
-   * BUG-002: Handle category-scoped queries by fetching all items of that category.
-   */
-  private async handleCategoryQuery(
-    message: string,
-    project: string | undefined,
-    category: 'decision' | 'pattern' | 'correction'
-  ): Promise<BrainResponse> {
-    const memory = getMemoryService()
-    const projectLabel = project || 'all projects'
-
-    let items: any[]
-    switch (category) {
-      case 'decision':
-        items = await memory.fetchAllDecisions(project)
-        break
-      case 'pattern':
-        items = await memory.fetchAllPatterns(project)
-        break
-      case 'correction':
-        items = await memory.fetchAllCorrections(project)
-        break
-    }
-
-    if (items.length === 0) {
-      return {
-        action: 'none',
-        summary: `No ${category}s found`,
-        content: `No ${category}s found for ${projectLabel}.`,
-        relevantItems: 0
-      }
-    }
-
-    // Format as compact items
-    const allItems = items.map(item => ({
-      id: item.id || item.decision_id,
-      content: typeof (item.decision || item.description || item.correction || item.original || item.document || item.content) === 'string'
-        ? (item.decision || item.description || item.correction || item.original || item.document || item.content)
-        : JSON.stringify(item.decision || item.description || item.correction || item.original || item.document || item.content || ''),
-      category,
-      project: item.project || project || 'general',
-      created_at: item.created_at || item.date || '',
-    }))
-
-    const compactContent = formatCompactResponse(allItems, `${category}s for ${projectLabel}`)
-    return {
-      action: 'retrieved',
-      summary: `${items.length} ${category}s for ${projectLabel}`,
-      content: compactContent,
-      relevantItems: items.length
-    }
-  }
-
-  private generateTaskId(title: string): string {
-    return title
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-+|-+$/g, '')
-      .slice(0, 50)
-  }
-}
-
-// Lazy singleton
-let routerInstance: BrainRouter | null = null
-
-export function getBrainRouter(logger: Logger): BrainRouter {
-  if (!routerInstance) {
-    routerInstance = new BrainRouter(logger)
-    // SLM Upgrade: Wire inference router if available
-    try {
-      const { getInferenceRouter } = require('@/server/services')
-      const ir = getInferenceRouter()
-      if (ir) routerInstance.setInferenceRouter(ir)
-    } catch {
-      // Services not initialized yet — will use regex fallback
-    }
-  }
-  return routerInstance
-}
-
-/** Reset singleton for testing */
-export function _resetBrainRouterForTesting(): void {
-  routerInstance = null
-}
+/**
+ * Brain Router
+ * Phase 16 + Phase 19: Core orchestrator for the unified brain() tool
+ *
+ * Routes classified intents to internal service calls and
+ * returns unified BrainResponse objects.
+ *
+ * Task 3.1: Refactored to delegate to domain handler modules.
+ * Intent handlers live in src/routing/handlers/.
+ */
+
+import type { Logger } from 'pino'
+import { IntentClassifier } from './intent-classifier'
+import type { InferenceRouter } from '@/intelligence/inference-router'
+import { BrainEntityExtractor } from './entity-extractor'
+import type { BrainResponse } from './response-filter'
+import { SearchEngine } from './search-engine'
+import type { ObservationCompressor } from '@/memory/compression'
+
+import type { HandlerContext, RecentDecision } from './handlers/types'
+import { RECENT_DECISION_WINDOW_MS } from './handlers/types'
+
+// Domain handlers
+import {
+  handleStoreThis,
+  handleDecisionMade,
+  handlePatternFound,
+  handleMistakeLearned,
+  handleProgressUpdate
+} from './handlers/memory-handler'
+import {
+  handleSessionStart,
+  handleContextNeeded,
+  handleQuestion,
+  handleDetailRequest
+} from './handlers/recall-handler'
+import {
+  handleUpdateMemory,
+  handleDeleteMemory
+} from './handlers/mutation-handler'
+import {
+  handleExploration,
+  handleComparison,
+  handleListAll,
+  handleTimeline
+} from './handlers/exploration-handler'
+
+export interface BrainInput {
+  message: string
+  project?: string
+  action?: 'auto' | 'store' | 'recall' | 'update' | 'delete'
+}
+
+export class BrainRouter {
+  private classifier: IntentClassifier
+  private entityExtractor: BrainEntityExtractor
+  private searchEngine: SearchEngine
+  private logger: Logger
+
+  /** SLM Upgrade: Optional inference router for model-based classification */
+  private inferenceRouter: InferenceRouter | null = null
+
+  /** Phase 30: Optional LLM compressor for long observations */
+  private compressor: ObservationCompressor | null = null
+
+  /** Track the most recently stored decision ID for update/delete operations */
+  private lastStoredId: string | null = null
+  private lastStoredProject: string | null = null
+
+  /** Bug 4: Recently stored decisions for recency fast path */
+  private recentDecisions: RecentDecision[] = []
+
+  constructor(logger: Logger) {
+    this.classifier = new IntentClassifier()
+    this.entityExtractor = new BrainEntityExtractor()
+    this.searchEngine = new SearchEngine(logger)
+    this.logger = logger.child({ component: 'brain-router' })
+  }
+
+  /** SLM Upgrade: Set the optional inference router for model-based classification */
+  setInferenceRouter(router: InferenceRouter): void {
+    this.inferenceRouter = router
+    this.entityExtractor.setInferenceRouter(router)
+  }
+
+  /** Phase 30: Set the optional LLM compressor */
+  setCompressor(compressor: ObservationCompressor): void {
+    this.compressor = compressor
+  }
+
+  /** Build handler context to pass to domain handlers */
+  private buildContext(): HandlerContext {
+    return {
+      logger: this.logger,
+      searchEngine: this.searchEngine,
+      classifier: this.classifier,
+      compressor: this.compressor,
+      lastStoredId: this.lastStoredId,
+      lastStoredProject: this.lastStoredProject,
+      recentDecisions: this.recentDecisions,
+      setLastStored: (id: string, project: string) => {
+        this.lastStoredId = id || null
+        this.lastStoredProject = project || null
+      },
+      trackRecentDecision: (content: string, project: string) => {
+        const now = Date.now()
+        this.recentDecisions = this.recentDecisions.filter(
+          d => now - d.storedAt < RECENT_DECISION_WINDOW_MS
+        )
+        this.recentDecisions.push({ content, project, storedAt: now })
+      }
+    }
+  }
+
+  async route(input: BrainInput): Promise<BrainResponse> {
+    const { message, project: inputProject, action } = input
+
+    // Extract entities (needed for all paths)
+    const entities = await this.entityExtractor.extract(message, inputProject)
+    const project = entities.project || inputProject
+    this.logger.debug({ project, technologies: entities.technologies }, 'Entities extracted')
+
+    const ctx = this.buildContext()
+
+    // P1: Explicit action override — bypass intent classifier entirely
+    if (action && action !== 'auto') {
+      this.logger.debug({ action }, 'Using explicit action override')
+      try {
+        switch (action) {
+          case 'store':
+            return handleStoreThis(ctx, message, project, entities)
+          case 'recall':
+            return handleContextNeeded(ctx, message, project, entities)
+          case 'update':
+            return handleUpdateMemory(ctx, message, project, entities)
+          case 'delete':
+            return handleDeleteMemory(ctx, message, project, entities)
+          default:
+            break
+        }
+      } catch (error) {
+        this.logger.error({ error, action }, 'Router action override error')
+        return {
+          action: 'none',
+          summary: `Error processing ${action} request`,
+          content: `Failed to process: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          relevantItems: 0
+        }
+      }
+    }
+
+    // Classify intent (SLM: use inference router if available, falls back to regex)
+    const classification = this.inferenceRouter
+      ? await this.inferenceRouter.classifyIntent(message)
+      : this.classifier.classify(message)
+    this.logger.debug({ intent: classification.primary, confidence: classification.confidence }, 'Intent classified')
+
+    // Route to handler
+    try {
+      switch (classification.primary) {
+        case 'no_action':
+          return { action: 'none', summary: 'No action needed', content: '', relevantItems: 0 }
+
+        case 'session_start':
+          return handleSessionStart(ctx, message, project, entities)
+
+        case 'context_needed':
+          return handleContextNeeded(ctx, message, project, entities, classification)
+
+        case 'decision_made':
+          return handleDecisionMade(ctx, message, project, entities)
+
+        case 'store_this':
+          return handleStoreThis(ctx, message, project, entities)
+
+        case 'pattern_found':
+          return handlePatternFound(ctx, message, project, entities)
+
+        case 'mistake_learned':
+          return handleMistakeLearned(ctx, message, project, entities)
+
+        case 'progress_update':
+          return handleProgressUpdate(ctx, message, project, entities)
+
+        case 'question':
+          return handleQuestion(ctx, message, project, entities, classification)
+
+        case 'comparison':
+          return handleComparison(ctx, message, project, entities)
+
+        case 'exploration':
+          return handleExploration(ctx, message, project, entities)
+
+        case 'list_all':
+          return handleListAll(ctx, message, project, entities)
+
+        case 'update_memory':
+          return handleUpdateMemory(ctx, message, project, entities)
+
+        case 'delete_memory':
+          return handleDeleteMemory(ctx, message, project, entities)
+
+        case 'detail_request':
+          return handleDetailRequest(ctx, message, project, entities)
+
+        case 'timeline':
+          return handleTimeline(ctx, message, project, entities)
+
+        default:
+          return handleContextNeeded(ctx, message, project, entities, classification)
+      }
+    } catch (error) {
+      this.logger.error({ error, intent: classification.primary }, 'Router handler error')
+      return {
+        action: 'none',
+        summary: `Error processing request`,
+        content: `Failed to process: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        relevantItems: 0
+      }
+    }
+  }
+}
+
+// Lazy singleton
+let routerInstance: BrainRouter | null = null
+
+export function getBrainRouter(logger: Logger): BrainRouter {
+  if (!routerInstance) {
+    routerInstance = new BrainRouter(logger)
+    // SLM Upgrade: Wire inference router if available
+    try {
+      const { getInferenceRouter } = require('@/server/services')
+      const ir = getInferenceRouter()
+      if (ir) routerInstance.setInferenceRouter(ir)
+    } catch {
+      // Services not initialized yet — will use regex fallback
+    }
+  }
+  return routerInstance
+}
+
+/** Reset singleton for testing */
+export function _resetBrainRouterForTesting(): void {
+  routerInstance = null
+}