claude-brain 0.15.2 → 0.17.0

package/src/routing/router.ts

@@ -1,1322 +1,1441 @@
-/**
- * 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 { BrainEntityExtractor, type BrainExtractedEntities } from './entity-extractor'
-import { ResponseFilter, type BrainResponse, type TierResults } from './response-filter'
-import { SearchEngine } from './search-engine'
-import type { NormalizedResult } from './types'
-import {
-  getMemoryService,
-  getVaultService,
-  getContextService,
-  getPhase12Service,
-  getKnowledgeGraphService,
-  getEpisodeService,
-  getSessionTracker,
-  isServicesInitialized
-} from '@/server/services'
-import { timed } from '@/utils/timing'
-
-/** Default project when none can be detected */
-const DEFAULT_PROJECT = 'general'
-
-/** Phase 19 D4: Minimum similarity for destructive operations */
-const DELETE_MIN_SIMILARITY = 0.5
-const UPDATE_MIN_SIMILARITY = 0.5
-
-export interface BrainInput {
-  message: string
-  project?: string
-}
-
-export class BrainRouter {
-  private classifier: IntentClassifier
-  private entityExtractor: BrainEntityExtractor
-  private responseFilter: ResponseFilter
-  private searchEngine: SearchEngine
-  private logger: Logger
-
-  /** Track the most recently stored decision ID for update/delete operations */
-  private lastStoredId: string | null = null
-  private lastStoredProject: string | null = null
-
-  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' })
-  }
-
-  async route(input: BrainInput): Promise<BrainResponse> {
-    const { message, project: inputProject } = input
-
-    // Classify intent
-    const classification = this.classifier.classify(message)
-    this.logger.debug({ intent: classification.primary, confidence: classification.confidence }, 'Intent classified')
-
-    // Extract entities
-    const entities = await this.entityExtractor.extract(message, inputProject)
-    const project = entities.project || inputProject
-    this.logger.debug({ project, technologies: entities.technologies }, 'Entities extracted')
-
-    // 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)
-
-        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
-      }
-    }
-
-    // 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
-    }
-
-    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()
-    }
-
-    const effectiveProject = 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: effectiveProject, 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: effectiveProject,
-        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: effectiveProject, 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>
-        }))
-      })
-    }
-
-    return this.responseFilter.synthesize(tiers, message, effectiveProject)
-  }
-
-  /**
-   * 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 decision = message
-    const reasoning = entities.reasoning || ''
-    const context = entities.topic || message.slice(0, 200)
-
-    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
-
-    // Invalidate cache for this project
-    this.searchEngine.invalidateCache(effectiveProject)
-
-    // Background: vault write + episode linking (non-critical)
-    setImmediate(() => {
-      this.writeToVault(effectiveProject, decision, reasoning, context, entities.alternatives)
-      this.linkToActiveEpisode(effectiveProject, decisionId, 'decision')
-    })
-
-    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}` : ''}`,
-      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 decision = message
-    const reasoning = entities.reasoning || ''
-    const context = entities.topic || message.slice(0, 200)
-    const alternatives = entities.alternatives
-
-    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
-
-    // Invalidate cache
-    this.searchEngine.invalidateCache(effectiveProject)
-
-    // Background: vault write + episode linking (non-critical)
-    setImmediate(() => {
-      this.writeToVault(effectiveProject, decision, reasoning, context, alternatives)
-      this.linkToActiveEpisode(effectiveProject, decisionId, 'decision')
-    })
-
-    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}`,
-      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
-    this.linkToActiveEpisode(effectiveProject, patternId, 'pattern')
-
-    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
-    this.linkToActiveEpisode(effectiveProject, correctionId, 'correction')
-
-    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 parts: string[] = []
-      const projectLabel = effectiveProject || 'all projects'
-
-      if (decisions.length > 0) {
-        parts.push(`## Decisions (${decisions.length})`)
-        for (const d of decisions.slice(0, 20)) {
-          const rawDecision = d.decision || d.document || d.content || ''
-          const decision = typeof rawDecision === 'string' ? rawDecision : JSON.stringify(rawDecision)
-          const rawDate = d.created_at || d.date || ''
-          const date = rawDate ? ` (${String(rawDate).split('T')[0]})` : ''
-          parts.push(`- ${decision.slice(0, 150)}${date}`)
-        }
-        if (decisions.length > 20) {
-          parts.push(`_...and ${decisions.length - 20} more_`)
-        }
-        parts.push('')
-      }
-
-      if (patterns.length > 0) {
-        parts.push(`## Patterns (${patterns.length})`)
-        for (const p of patterns.slice(0, 10)) {
-          const rawDesc = p.description || p.document || p.content || ''
-          const desc = typeof rawDesc === 'string' ? rawDesc : JSON.stringify(rawDesc)
-          parts.push(`- **${p.pattern_type || 'solution'}**: ${desc.slice(0, 120)}`)
-        }
-        parts.push('')
-      }
-
-      if (corrections.length > 0) {
-        parts.push(`## Corrections (${corrections.length})`)
-        for (const c of corrections.slice(0, 10)) {
-          const rawOrig = c.original || c.document || c.content || ''
-          const orig = typeof rawOrig === 'string' ? rawOrig : JSON.stringify(rawOrig)
-          parts.push(`- ${orig.slice(0, 120)}`)
-        }
-        parts.push('')
-      }
-
-      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
-        }
-      }
-
-      return {
-        action: 'retrieved',
-        summary: `${total} memories for ${projectLabel}`,
-        content: parts.join('\n'),
-        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)
-
-    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
-          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()
-    }
-
-    const effectiveProject = 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: effectiveProject, limit: 5 })
-      searchResults = results
-    } else if (isComplex) {
-      // C7: Try multi-hop chain retrieval
-      const chainResult = await this.searchEngine.chainSearch(query, { project: effectiveProject })
-      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 || effectiveProject || '',
-          date: r.metadata?.created_at || '',
-          metadata: r.metadata || {}
-        }))
-      } else {
-        searchResults = await this.searchEngine.enhancedSearch(query, { project: effectiveProject, limit: 5 })
-      }
-    } else {
-      searchResults = await this.searchEngine.enhancedSearch(query, { project: effectiveProject, 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>
-        }))
-      })
-    }
-
-    // Parallel: patterns + corrections + graph
-    const [patternResults, correctionResults, graphResults] = await Promise.all([
-      this.searchEngine.searchPatterns(query, { project: effectiveProject, limit: 3 }),
-      this.searchEngine.searchCorrections(query, { project: effectiveProject, 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>
-        }))
-      })
-    }
-
-    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>
-        }))
-      })
-    }
-
-    // C11: Add graph results as "Related Concepts"
-    if (graphResults.length > 0) {
-      tiers.push({
-        label: 'Related Concepts',
-        results: graphResults.map(g => ({
-          content: g.content,
-          score: g.score,
-          source: 'Knowledge Graph',
-          metadata: g.metadata as Record<string, unknown>
-        }))
-      })
-    }
-
-    // C10: CrossProject patterns for general/unspecified project queries
-    if (!project || project === 'general') {
-      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
-      }
-    }
-
-    // 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
-      }
-    }
-
-    // Register with episode
-    this.registerEpisodeMessage(message, effectiveProject, 'question')
-
-    return this.responseFilter.synthesize(tiers, message, effectiveProject)
-  }
-
-  /**
-   * 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()
-    }
-
-    const effectiveProject = 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: effectiveProject,
-        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: effectiveProject })
-      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: effectiveProject })
-      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
-    const graphResults = await this.searchEngine.searchGraph(query, 10)
-    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>
-        }))
-      })
-    }
-
-    // Issue 9: Cross-project patterns for exploration queries
-    if (!project || project === 'general') {
-      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: effectiveProject,
-      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>
-        }))
-      })
-    }
-
-    return this.responseFilter.synthesize(tiers, message, effectiveProject, 'analyzed')
-  }
-
-  private async handleComparison(
-    message: string,
-    project: string | undefined,
-    entities: BrainExtractedEntities
-  ): Promise<BrainResponse> {
-    if (!isServicesInitialized()) {
-      return this.servicesNotReady()
-    }
-
-    const effectiveProject = project || DEFAULT_PROJECT
-    const query = entities.topic || message
-    const tiers: TierResults[] = []
-
-    // Search for related decisions
-    const searchResults = await this.searchEngine.enhancedSearch(query, {
-      project: effectiveProject,
-      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, effectiveProject, 'analyzed')
-  }
-
-  // ===== Helpers =====
-
-  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, 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
-  }
-
-  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)
-  }
-  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.
+ *
+ * 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 { BrainEntityExtractor, type BrainExtractedEntities } from './entity-extractor'
+import { ResponseFilter, type BrainResponse, type TierResults } from './response-filter'
+import { SearchEngine } from './search-engine'
+import type { NormalizedResult } from './types'
+import {
+  getMemoryService,
+  getVaultService,
+  getContextService,
+  getPhase12Service,
+  getKnowledgeGraphService,
+  getEpisodeService,
+  getSessionTracker,
+  isServicesInitialized
+} from '@/server/services'
+import { timed } from '@/utils/timing'
+
+/** Default project when none can be detected */
+const DEFAULT_PROJECT = 'general'
+
+/** Phase 19 D4: Minimum similarity for destructive operations */
+const DELETE_MIN_SIMILARITY = 0.5
+const UPDATE_MIN_SIMILARITY = 0.5
+
+export interface BrainInput {
+  message: string
+  project?: string
+}
+
+/** Recently stored decision for recency fast path (Bug 4 fix) */
+interface RecentDecision {
+  content: string
+  project: string
+  storedAt: 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
+
+  /** 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' })
+  }
+
+  async route(input: BrainInput): Promise<BrainResponse> {
+    const { message, project: inputProject } = input
+
+    // Classify intent
+    const classification = this.classifier.classify(message)
+    this.logger.debug({ intent: classification.primary, confidence: classification.confidence }, 'Intent classified')
+
+    // Extract entities
+    const entities = await this.entityExtractor.extract(message, inputProject)
+    const project = entities.project || inputProject
+    this.logger.debug({ project, technologies: entities.technologies }, 'Entities extracted')
+
+    // 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)
+
+        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
+      }
+    }
+
+    // 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>
+        }))
+      })
+    }
+
+    return this.responseFilter.synthesize(tiers, message, displayProject)
+  }
+
+  /**
+   * 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 decision = message
+    const reasoning = entities.reasoning || ''
+    const context = entities.topic || message.slice(0, 200)
+
+    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 (non-critical)
+    setImmediate(() => {
+      this.writeToVault(effectiveProject, decision, reasoning, context, entities.alternatives)
+      this.linkToActiveEpisode(effectiveProject, decisionId, 'decision')
+    })
+
+    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}` : ''}`,
+      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 decision = message
+    const reasoning = entities.reasoning || ''
+    const context = entities.topic || message.slice(0, 200)
+    const alternatives = entities.alternatives
+
+    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 (non-critical)
+    setImmediate(() => {
+      this.writeToVault(effectiveProject, decision, reasoning, context, alternatives)
+      this.linkToActiveEpisode(effectiveProject, decisionId, 'decision')
+    })
+
+    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}`,
+      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
+    this.linkToActiveEpisode(effectiveProject, patternId, 'pattern')
+
+    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
+    this.linkToActiveEpisode(effectiveProject, correctionId, 'correction')
+
+    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 parts: string[] = []
+      const projectLabel = effectiveProject || 'all projects'
+
+      if (decisions.length > 0) {
+        parts.push(`## Decisions (${decisions.length})`)
+        for (const d of decisions.slice(0, 20)) {
+          const rawDecision = d.decision || d.document || d.content || ''
+          const decision = typeof rawDecision === 'string' ? rawDecision : JSON.stringify(rawDecision)
+          const rawDate = d.created_at || d.date || ''
+          const date = rawDate ? ` (${String(rawDate).split('T')[0]})` : ''
+          parts.push(`- ${decision.slice(0, 150)}${date}`)
+        }
+        if (decisions.length > 20) {
+          parts.push(`_...and ${decisions.length - 20} more_`)
+        }
+        parts.push('')
+      }
+
+      if (patterns.length > 0) {
+        parts.push(`## Patterns (${patterns.length})`)
+        for (const p of patterns.slice(0, 10)) {
+          const rawDesc = p.description || p.document || p.content || ''
+          const desc = typeof rawDesc === 'string' ? rawDesc : JSON.stringify(rawDesc)
+          parts.push(`- **${p.pattern_type || 'solution'}**: ${desc.slice(0, 120)}`)
+        }
+        parts.push('')
+      }
+
+      if (corrections.length > 0) {
+        parts.push(`## Corrections (${corrections.length})`)
+        for (const c of corrections.slice(0, 10)) {
+          const rawOrig = c.original || c.document || c.content || ''
+          const orig = typeof rawOrig === 'string' ? rawOrig : JSON.stringify(rawOrig)
+          parts.push(`- ${orig.slice(0, 120)}`)
+        }
+        parts.push('')
+      }
+
+      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
+        }
+      }
+
+      return {
+        action: 'retrieved',
+        summary: `${total} memories for ${projectLabel}`,
+        content: parts.join('\n'),
+        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)
+
+    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
+          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()
+    }
+
+    // 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>
+        }))
+      })
+    }
+
+    // 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>
+        }))
+      })
+    }
+
+    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>
+        }))
+      })
+    }
+
+    // C11: Add graph results as "Related Concepts" (Bug 3: filter low-score, cap to 0.4)
+    const relevantGraphResults = graphResults.filter(g => g.score >= 0.6)
+    if (relevantGraphResults.length > 0) {
+      tiers.push({
+        label: 'Related Concepts',
+        results: relevantGraphResults.map(g => ({
+          content: g.content,
+          score: Math.min(g.score, 0.4),
+          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 as high-score tier
+    const recentMatches = this.findRecentDecisions(query, searchProject)
+    if (recentMatches.length > 0) {
+      tiers.unshift({
+        label: 'Recent Decisions',
+        results: recentMatches.map(d => ({
+          content: d.content,
+          score: 0.95,
+          source: 'Recent Decision',
+          metadata: { storedAt: d.storedAt, project: d.project }
+        }))
+      })
+    }
+
+    // Register with episode
+    this.registerEpisodeMessage(message, displayProject, 'question')
+
+    return this.responseFilter.synthesize(tiers, message, displayProject)
+  }
+
+  /**
+   * 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
+    const graphResults = await this.searchEngine.searchGraph(query, 10)
+    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>
+        }))
+      })
+    }
+
+    // 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>
+        }))
+      })
+    }
+
+    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')
+  }
+
+  // ===== Helpers =====
+
+  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, 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
+   */
+  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 []
+
+    return this.recentDecisions.filter(d => {
+      // Project filter: skip if searching a specific project and it doesn't match
+      if (project && d.project !== project) return false
+      const contentWords = d.content.toLowerCase().split(/\s+/).filter(w => w.length > 2)
+      const overlap = contentWords.filter(w => queryWords.has(w)).length
+      return overlap >= 1
+    })
+  }
+
+  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)
+  }
+  return routerInstance
+}
+
+/** Reset singleton for testing */
+export function _resetBrainRouterForTesting(): void {
+  routerInstance = null
+}