claude-brain 0.9.3 → 0.10.0

package/src/routing/router.ts

@@ -1,27 +1,38 @@
 /**
  * Brain Router
- * Phase 16: Core orchestrator for the unified brain() tool
+ * 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,
   isServicesInitialized
 } from '@/server/services'
 
 /** 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
@@ -31,6 +42,7 @@ 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 */
@@ -41,6 +53,7 @@ export class BrainRouter {
     this.classifier = new IntentClassifier()
     this.entityExtractor = new BrainEntityExtractor()
     this.responseFilter = new ResponseFilter()
+    this.searchEngine = new SearchEngine(logger)
     this.logger = logger.child({ component: 'brain-router' })
   }
 
@@ -66,7 +79,7 @@ export class BrainRouter {
           return this.handleSessionStart(message, project, entities)
 
         case 'context_needed':
-          return this.handleContextNeeded(message, project, entities)
+          return this.handleContextNeeded(message, project, entities, classification)
 
         case 'decision_made':
           return this.handleDecisionMade(message, project, entities)
@@ -102,7 +115,7 @@ export class BrainRouter {
           return this.handleDeleteMemory(message, project, entities)
 
         default:
-          return this.handleContextNeeded(message, project, entities)
+          return this.handleContextNeeded(message, project, entities, classification)
       }
     } catch (error) {
       this.logger.error({ error, intent: classification.primary }, 'Router handler error')
@@ -178,11 +191,10 @@ export class BrainRouter {
       }
     }
 
-    // If Phase 12 found nothing, do a direct search fallback
+    // If Phase 12 found nothing, do a direct search fallback via SearchEngine
     if (!phase12Result.recalledMemories?.memories.length) {
       try {
-        const memory = getMemoryService()
-        const directResults = await memory.searchRaw(entities.topic || message, {
+        const directResults = await this.searchEngine.enhancedSearch(entities.topic || message, {
           project,
           limit: 5,
           minSimilarity: 0.3
@@ -190,8 +202,8 @@ export class BrainRouter {
         if (directResults.length > 0) {
           parts.push('\n---\n## Related Memories\n')
           for (const r of directResults) {
-            const similarity = Math.round((r.similarity || 0) * 100)
-            parts.push(`**[${similarity}%]** ${r.decision?.decision || r.content?.slice(0, 100) || ''}`)
+            const similarity = Math.round(r.score * 100)
+            parts.push(`**[${similarity}%]** ${r.content?.slice(0, 200) || ''}`)
           }
         }
       } catch {
@@ -199,6 +211,26 @@ export class BrainRouter {
       }
     }
 
+    // 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',
@@ -211,61 +243,64 @@ export class BrainRouter {
   private async handleContextNeeded(
     message: string,
     project: string | undefined,
-    entities: BrainExtractedEntities
+    entities: BrainExtractedEntities,
+    classification?: ClassificationResult
   ): Promise<BrainResponse> {
     if (!isServicesInitialized()) {
       return this.servicesNotReady()
     }
 
-    const memory = getMemoryService()
     const query = entities.topic || message
-
-    // Search for relevant memories
     const tiers: TierResults[] = []
+    const hasTemporal = classification?.secondary.includes('exploration') ||
+      this.classifier.hasTemporalSignal(message.toLowerCase())
 
-    try {
-      const rawResults = await memory.searchRaw(query, {
+    // Use temporal search if temporal signals detected
+    if (hasTemporal) {
+      const { results } = await this.searchEngine.temporalSearch(query, { project, 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,
         limit: 5,
         minSimilarity: 0.3
       })
-
-      tiers.push({
-        label: 'Memories',
-        results: rawResults.map(r => ({
-          content: r.decision?.decision
-            ? `**${r.decision.decision}**\n${r.decision.reasoning || ''}\n_Context: ${r.decision.context || ''}_`
-            : r.content?.slice(0, 300) || '',
-          score: r.similarity || 0,
-          source: 'Past Decision',
-          metadata: r.metadata
-        }))
-      })
-    } catch {
-      // Search failed, continue
-    }
-
-    // Also search patterns if project is available
-    try {
-      const patternResults = await memory.searchPatterns(query, {
-        project,
-        limit: 3,
-        minSimilarity: 0.3
-      })
-
-      if (patternResults.length > 0) {
+      if (searchResults.length > 0) {
         tiers.push({
-          label: 'Patterns',
-          results: patternResults.map(p => ({
-            content: p.metadata?.description || p.content || '',
-            score: p.similarity || 0,
-            source: `Pattern (${p.metadata?.pattern_type || 'general'})`,
-            metadata: p.metadata
+          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>
           }))
         })
       }
-    } catch {
-      // Pattern search not available
+    }
+
+    // Also search patterns
+    const patternResults = await this.searchEngine.searchPatterns(query, { project, 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, project)
@@ -273,14 +308,12 @@ export class BrainRouter {
 
   /**
    * Handle explicit "store this" requests — always uses the FULL message as the decision text.
-   * This prevents content mangling from entity extraction.
    */
   private async handleStoreThis(
     message: string,
     project: string | undefined,
     entities: BrainExtractedEntities
   ): Promise<BrainResponse> {
-    // Use "general" as fallback when no project is detected
     const effectiveProject = project || DEFAULT_PROJECT
 
     if (!isServicesInitialized()) {
@@ -288,8 +321,6 @@ export class BrainRouter {
     }
 
     const memory = getMemoryService()
-
-    // ALWAYS use the full message as the decision — never the extracted fragment
     const decision = message
     const reasoning = entities.reasoning || ''
     const context = entities.topic || message.slice(0, 200)
@@ -309,9 +340,15 @@ export class BrainRouter {
     this.lastStoredId = decisionId
     this.lastStoredProject = effectiveProject
 
-    // Also write to vault
+    // Invalidate cache for this project
+    this.searchEngine.invalidateCache(effectiveProject)
+
+    // Write to vault
     this.writeToVault(effectiveProject, decision, reasoning, context, entities.alternatives)
 
+    // Link to active episode
+    this.linkToActiveEpisode(effectiveProject, decisionId, 'decision')
+
     return {
       action: 'stored',
       summary: `Stored: ${message.slice(0, 60)}`,
@@ -325,7 +362,6 @@ export class BrainRouter {
     project: string | undefined,
     entities: BrainExtractedEntities
   ): Promise<BrainResponse> {
-    // Use "general" as fallback when no project is detected
     const effectiveProject = project || DEFAULT_PROJECT
 
     if (!isServicesInitialized()) {
@@ -333,9 +369,6 @@ export class BrainRouter {
     }
 
     const memory = getMemoryService()
-
-    // ALWAYS use the full message as the decision text to prevent content mangling.
-    // The extracted entities are used only for structured metadata.
     const decision = message
     const reasoning = entities.reasoning || ''
     const context = entities.topic || message.slice(0, 200)
@@ -352,13 +385,18 @@ export class BrainRouter {
       }
     )
 
-    // Track for potential update/delete
     this.lastStoredId = decisionId
     this.lastStoredProject = effectiveProject
 
-    // Also write to vault
+    // Invalidate cache
+    this.searchEngine.invalidateCache(effectiveProject)
+
+    // Write to vault
     this.writeToVault(effectiveProject, decision, reasoning, context, alternatives)
 
+    // Link to active episode
+    this.linkToActiveEpisode(effectiveProject, decisionId, 'decision')
+
     return {
       action: 'stored',
       summary: `Stored decision: ${message.slice(0, 60)}`,
@@ -380,7 +418,7 @@ export class BrainRouter {
 
     const memory = getMemoryService()
     const patternType = entities.patternType || 'solution'
-    const description = message // Use full message
+    const description = message
 
     const patternId = await memory.storePattern({
       project: effectiveProject,
@@ -390,6 +428,12 @@ export class BrainRouter {
       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)}`,
@@ -410,8 +454,6 @@ export class BrainRouter {
     }
 
     const memory = getMemoryService()
-
-    // Use full message as the original content to prevent mangling
     const original = entities.original || message
     const correction = entities.correction || ''
     const reasoning = entities.reasoning || 'Lesson learned from experience'
@@ -425,6 +467,12 @@ export class BrainRouter {
       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)}`,
@@ -459,10 +507,10 @@ export class BrainRouter {
         completedAt: new Date()
       })
     } catch {
-      // Progress update failed — still report what we found
+      // Progress update failed
     }
 
-    // Also store as a searchable memory in ChromaDB so it appears in search results
+    // Also store as a searchable memory
     try {
       await memory.rememberDecision(
         effectiveProject,
@@ -471,10 +519,16 @@ export class BrainRouter {
         'Progress tracking',
         { tags: ['progress', ...entities.technologies] }
       )
+
+      // Invalidate cache
+      this.searchEngine.invalidateCache(effectiveProject)
     } catch {
-      // Memory storage failed, context-only storage still succeeded
+      // Memory storage failed
     }
 
+    // Register with episode
+    this.registerEpisodeMessage(message, effectiveProject, 'progress_update')
+
     return {
       action: 'stored',
       summary: `Progress: ${completedTask.slice(0, 60)}`,
@@ -496,7 +550,7 @@ export class BrainRouter {
     }
 
     const memory = getMemoryService()
-    const effectiveProject = project // No fallback — list all if no project
+    const effectiveProject = project
 
     try {
       const decisions = await memory.fetchAllDecisions(effectiveProject)
@@ -565,8 +619,7 @@ export class BrainRouter {
   }
 
   /**
-   * Update a previous decision — searches by content to find the right one, then replaces it.
-   * Uses lastStoredId only for generic "actually, X" with no descriptive subject.
+   * Phase 19 D4: Update with higher similarity threshold
    */
   private async handleUpdateMemory(
     message: string,
@@ -583,17 +636,18 @@ export class BrainRouter {
     const topic = entities.topic || message
     const hasSpecificContent = this.hasDescriptiveContent(message)
 
-    // If the message has specific content, search for the matching decision first
     if (hasSpecificContent) {
       try {
         const results = await memory.searchRaw(topic, {
           project: effectiveProject,
           limit: 1,
-          minSimilarity: 0.3
+          minSimilarity: UPDATE_MIN_SIMILARITY
         })
 
-        const matchId = results[0]?.memory?.id || results[0]?.decision?.id
-        if (results.length > 0 && matchId) {
+        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,
@@ -607,20 +661,26 @@ export class BrainRouter {
           this.lastStoredId = newId
           this.lastStoredProject = effectiveProject
 
-          const oldContent = results[0].decision?.decision || results[0].memory?.content?.slice(0, 100) || ''
+          // 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 ("actually, use X instead") — use lastStoredId
+    // Generic update — use lastStoredId
     if (this.lastStoredId) {
       const newId = await memory.updateDecision(
         this.lastStoredId,
@@ -633,6 +693,7 @@ export class BrainRouter {
 
       this.lastStoredId = newId
       this.lastStoredProject = effectiveProject
+      this.searchEngine.invalidateCache(effectiveProject)
 
       return {
         action: 'stored',
@@ -642,29 +703,12 @@ export class BrainRouter {
       }
     }
 
-    // Fallback: just store as a new decision
-    const decisionId = await memory.rememberDecision(
-      effectiveProject,
-      topic.slice(0, 200),
-      message,
-      entities.reasoning || '',
-      { tags: entities.technologies.length > 0 ? entities.technologies : ['updated'] }
-    )
-
-    this.lastStoredId = decisionId
-    this.lastStoredProject = effectiveProject
-
-    return {
-      action: 'stored',
-      summary: `Stored as new (no matching decision found to update)`,
-      content: `Stored as new decision (ID: ${decisionId})\n\n**Project:** ${effectiveProject}\n**Content:** ${message}`,
-      relevantItems: 1
-    }
+    // Fallback: store as new decision
+    return this.storeAsNew(memory, effectiveProject, message, topic, entities, 'No matching decision found to update')
   }
 
   /**
-   * Delete a memory — searches by content to find the right one.
-   * Only uses lastStoredId for very generic requests like "forget that" with no descriptive words.
+   * Phase 19 D4: Delete with higher similarity threshold
    */
   private async handleDeleteMemory(
     message: string,
@@ -679,46 +723,56 @@ export class BrainRouter {
 
     const memory = getMemoryService()
     const topic = entities.topic || message
-
-    // Check if the message has meaningful content to search by
-    // (strip common delete phrases to see if there's a real subject)
     const hasSpecificContent = this.hasDescriptiveContent(message)
 
-    // If the user described what to delete, ALWAYS search by content first
     if (hasSpecificContent) {
       try {
         const results = await memory.searchRaw(topic, {
           project: effectiveProject,
           limit: 3,
-          minSimilarity: 0.3
+          minSimilarity: DELETE_MIN_SIMILARITY
         })
 
-        const matchId = results[0]?.memory?.id || results[0]?.decision?.id
-        if (results.length > 0 && matchId) {
+        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) || ''
+          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 ("forget that", "delete that") — use lastStoredId
+    // 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`,
@@ -738,6 +792,14 @@ export class BrainRouter {
     }
   }
 
+  /**
+   * 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,
@@ -748,51 +810,67 @@ export class BrainRouter {
       return this.servicesNotReady()
     }
 
-    const memory = getMemoryService()
     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, limit: 5 })
+      searchResults = results
+    } else if (isComplex) {
+      // C7: Try multi-hop chain retrieval
+      const chainResult = await this.searchEngine.chainSearch(query, { project })
+      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 || project || '',
+          date: r.metadata?.created_at || '',
+          metadata: r.metadata || {}
+        }))
+      } else {
+        searchResults = await this.searchEngine.enhancedSearch(query, { project, limit: 5 })
+      }
+    } else {
+      searchResults = await this.searchEngine.enhancedSearch(query, { project, limit: 5 })
+    }
 
-    // Parallel search: raw memories + patterns + corrections
-    const [rawResults, patternResults, correctionResults] = await Promise.all([
-      memory.searchRaw(query, {
-        project,
-        limit: 5,
-        minSimilarity: 0.3
-      }).catch(() => [] as any[]),
-      memory.searchPatterns(query, {
-        project,
-        limit: 3,
-        minSimilarity: 0.3
-      }).catch(() => [] as any[]),
-      memory.searchCorrections(query, {
-        project,
-        limit: 3,
-        minSimilarity: 0.3
-      }).catch(() => [] as any[])
-    ])
-
-    if (rawResults.length > 0) {
+    if (searchResults.length > 0) {
       tiers.push({
         label: 'Memories',
-        results: rawResults.map((r: any) => ({
-          content: r.decision?.decision
-            ? `**${r.decision.decision}**\n${r.decision.reasoning || ''}`
-            : r.content?.slice(0, 300) || '',
-          score: r.similarity || 0,
-          source: 'Past Decision',
-          metadata: r.metadata
+        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, limit: 3 }),
+      this.searchEngine.searchCorrections(query, { project, 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: any) => ({
-          content: p.metadata?.description || p.content || '',
-          score: p.similarity || 0,
-          source: `Pattern (${p.metadata?.pattern_type || 'general'})`,
-          metadata: p.metadata
+        results: patternResults.map(p => ({
+          content: p.content,
+          score: p.score,
+          source: `Pattern`,
+          metadata: p.metadata as Record<string, unknown>
         }))
       })
     }
@@ -800,24 +878,64 @@ export class BrainRouter {
     if (correctionResults.length > 0) {
       tiers.push({
         label: 'Corrections',
-        results: correctionResults.map((c: any) => ({
-          content: `Original: ${c.metadata?.original || ''}\nFix: ${c.metadata?.correction || c.content || ''}`,
-          score: c.similarity || 0,
+        results: correctionResults.map(c => ({
+          content: c.content,
+          score: c.score,
           source: 'Lesson Learned',
-          metadata: c.metadata
+          metadata: c.metadata as Record<string, unknown>
         }))
       })
     }
 
-    // If secondary intent is exploration, also try graph search
-    if (classification.secondary.includes('exploration')) {
-      await this.addExplorationResults(query, project, tiers)
+    // 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
+      }
+    }
+
+    // Register with episode
+    this.registerEpisodeMessage(message, project, 'question')
+
     return this.responseFilter.synthesize(tiers, message, project)
   }
 
-  private async handleComparison(
+  /**
+   * 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
@@ -826,58 +944,106 @@ export class BrainRouter {
       return this.servicesNotReady()
     }
 
-    const memory = getMemoryService()
     const query = entities.topic || message
+    const lower = message.toLowerCase()
     const tiers: TierResults[] = []
 
-    // Search for related decisions
-    try {
-      const rawResults = await memory.searchRaw(query, {
+    // C6: Timeline queries
+    if (lower.includes('timeline') || lower.includes('chronological') || lower.includes('history of')) {
+      const timeline = await this.searchEngine.buildTimeline({
         project,
-        limit: 5,
-        minSimilarity: 0.2
+        topic: query,
+        limit: 20
       })
 
-      if (rawResults.length > 0) {
+      if (timeline?.entries?.length) {
         tiers.push({
-          label: 'Related Decisions',
-          results: rawResults.map((r: any) => ({
-            content: r.decision?.decision
-              ? `**${r.decision.decision}**\n${r.decision.reasoning || ''}`
-              : r.content?.slice(0, 300) || '',
-            score: r.similarity || 0,
-            source: 'Past Decision'
+          label: 'Timeline',
+          results: timeline.entries.map((e: any) => ({
+            content: `**${e.date || ''}** — ${e.content || ''}`,
+            score: 0.8,
+            source: `Timeline (${e.type || 'event'})`,
+            metadata: e.metadata || {}
           }))
         })
       }
-    } catch {
-      // Search failed
     }
 
-    // Try what-if analysis if knowledge graph is available
-    try {
-      const kgService = getKnowledgeGraphService()
-      if (kgService?.search) {
-        const graphResults = kgService.search.search({ query, limit: 5 })
-        if (graphResults?.nodes?.length) {
-          tiers.push({
-            label: 'Knowledge Graph',
-            results: graphResults.nodes.map((n: any) => ({
-              content: `**${n.label || n.name}** (${n.type})\n${n.metadata?.description || ''}`,
-              score: n.score || 0.5,
-              source: 'Knowledge Graph'
-            }))
-          })
+    // 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 })
+      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: {}
+          }]
+        })
       }
-    } catch {
-      // Knowledge graph not available
+    }
+
+    // C6: Trend queries
+    if (lower.includes('trend') || lower.includes('emerging') || lower.includes('declining')) {
+      const trends = await this.searchEngine.detectTrends({ project })
+      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>
+        }))
+      })
+    }
+
+    // Also do a basic memory search as fallback
+    const searchResults = await this.searchEngine.enhancedSearch(query, {
+      project,
+      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, project, 'analyzed')
   }
 
-  private async handleExploration(
+  private async handleComparison(
     message: string,
     project: string | undefined,
     entities: BrainExtractedEntities
@@ -889,31 +1055,36 @@ export class BrainRouter {
     const query = entities.topic || message
     const tiers: TierResults[] = []
 
-    await this.addExplorationResults(query, project, tiers)
-
-    // Also do a basic memory search
-    try {
-      const memory = getMemoryService()
-      const rawResults = await memory.searchRaw(query, {
-        project,
-        limit: 5,
-        minSimilarity: 0.2
+    // Search for related decisions
+    const searchResults = await this.searchEngine.enhancedSearch(query, {
+      project,
+      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>
+        }))
       })
+    }
 
-      if (rawResults.length > 0) {
-        tiers.push({
-          label: 'Memories',
-          results: rawResults.map((r: any) => ({
-            content: r.decision?.decision
-              ? `**${r.decision.decision}**\n${r.decision.reasoning || ''}`
-              : r.content?.slice(0, 300) || '',
-            score: r.similarity || 0,
-            source: 'Past Decision'
-          }))
-        })
-      }
-    } catch {
-      // Search failed
+    // 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, project, 'analyzed')
@@ -935,35 +1106,89 @@ export class BrainRouter {
       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 — memory storage still succeeded
+      // Vault write failed
     }
   }
 
-  private async addExplorationResults(
-    query: string,
-    _project: string | undefined,
-    tiers: TierResults[]
-  ): Promise<void> {
+  /**
+   * 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 kgService = getKnowledgeGraphService()
-      if (kgService?.search) {
-        const graphResults = kgService.search.search({ query, limit: 10 })
-        if (graphResults?.nodes?.length) {
-          tiers.push({
-            label: 'Knowledge Graph',
-            results: graphResults.nodes.map((n: any) => ({
-              content: `**${n.label || n.name}** (${n.type})${n.metadata?.description ? `\n${n.metadata.description}` : ''}`,
-              score: n.score || 0.5,
-              source: 'Knowledge Graph'
-            }))
-          })
-        }
-      }
+      const episodeManager = getEpisodeService()
+      if (!episodeManager) return
+      episodeManager.processMessage(
+        { role, content: message, timestamp: new Date().toISOString() },
+        project
+      ).catch(() => {})
     } catch {
-      // Knowledge graph not available
+      // 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
+    }
+  }
+
+  /**
+   * 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',
@@ -975,7 +1200,6 @@ export class BrainRouter {
 
   /**
    * Check if a delete/update message has descriptive content beyond just the command words.
-   * "forget that" → false (generic), "forget the migrations note" → true (specific)
    */
   private hasDescriptiveContent(message: string): boolean {
     const COMMAND_WORDS = [