claude-brain 0.5.0 → 0.8.0

package/src/routing/router.ts

@@ -0,0 +1,671 @@
+/**
+ * Brain Router
+ * Phase 16: Core orchestrator for the unified brain() tool
+ *
+ * Routes classified intents to internal service calls and
+ * returns unified BrainResponse objects.
+ */
+
+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 {
+  getMemoryService,
+  getVaultService,
+  getContextService,
+  getPhase12Service,
+  getKnowledgeGraphService,
+  isServicesInitialized
+} from '@/server/services'
+
+export interface BrainInput {
+  message: string
+  project?: string
+}
+
+export class BrainRouter {
+  private classifier: IntentClassifier
+  private entityExtractor: BrainEntityExtractor
+  private responseFilter: ResponseFilter
+  private logger: Logger
+
+  constructor(logger: Logger) {
+    this.classifier = new IntentClassifier()
+    this.entityExtractor = new BrainEntityExtractor()
+    this.responseFilter = new ResponseFilter()
+    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)
+
+        case 'decision_made':
+          return this.handleDecisionMade(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)
+
+        default:
+          return this.handleContextNeeded(message, project, entities)
+      }
+    } 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 * 100)
+        parts.push(`**[${similarity}%]** ${mem.decision?.decision || mem.memory?.content?.slice(0, 100) || ''}`)
+        if (mem.decision?.reasoning) {
+          parts.push(`  _${mem.decision.reasoning}_`)
+        }
+      }
+    }
+
+    // If Phase 12 found nothing, do a direct search fallback
+    if (!phase12Result.recalledMemories?.memories.length) {
+      try {
+        const memory = getMemoryService()
+        const directResults = await memory.searchRaw(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.similarity || 0) * 100)
+            parts.push(`**[${similarity}%]** ${r.decision?.decision || r.content?.slice(0, 100) || ''}`)
+          }
+        }
+      } catch {
+        // Direct search failed, continue without
+      }
+    }
+
+    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
+  ): Promise<BrainResponse> {
+    if (!isServicesInitialized()) {
+      return this.servicesNotReady()
+    }
+
+    const memory = getMemoryService()
+    const query = entities.topic || message
+
+    // Search for relevant memories
+    const tiers: TierResults[] = []
+
+    try {
+      const rawResults = await memory.searchRaw(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) {
+        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
+          }))
+        })
+      }
+    } catch {
+      // Pattern search not available
+    }
+
+    return this.responseFilter.synthesize(tiers, message, project)
+  }
+
+  private async handleDecisionMade(
+    message: string,
+    project: string | undefined,
+    entities: BrainExtractedEntities
+  ): Promise<BrainResponse> {
+    if (!project) {
+      return {
+        action: 'none',
+        summary: 'Cannot store decision without a project',
+        content: 'Please specify which project this decision relates to.',
+        relevantItems: 0
+      }
+    }
+
+    if (!isServicesInitialized()) {
+      return this.servicesNotReady()
+    }
+
+    const memory = getMemoryService()
+    const vault = getVaultService()
+
+    // Extract decision components (use entities or fall back to raw message)
+    const decision = entities.decision || message
+    const reasoning = entities.reasoning || ''
+    const context = entities.topic || message.slice(0, 200)
+    const alternatives = entities.alternatives
+
+    const decisionId = await memory.rememberDecision(
+      project,
+      context,
+      decision,
+      reasoning,
+      {
+        alternatives,
+        tags: entities.technologies.length > 0 ? entities.technologies : ['auto-detected']
+      }
+    )
+
+    // Also write to vault
+    try {
+      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 — memory storage still succeeded
+    }
+
+    return {
+      action: 'stored',
+      summary: `Stored decision: ${decision.slice(0, 60)}`,
+      content: `Decision stored (ID: ${decisionId})\n\n**Project:** ${project}\n**Decision:** ${decision}\n**Reasoning:** ${reasoning}`,
+      relevantItems: 1
+    }
+  }
+
+  private async handlePatternFound(
+    message: string,
+    project: string | undefined,
+    entities: BrainExtractedEntities
+  ): Promise<BrainResponse> {
+    if (!project) {
+      return {
+        action: 'none',
+        summary: 'Cannot store pattern without a project',
+        content: 'Please specify which project this pattern relates to.',
+        relevantItems: 0
+      }
+    }
+
+    if (!isServicesInitialized()) {
+      return this.servicesNotReady()
+    }
+
+    const memory = getMemoryService()
+    const patternType = entities.patternType || 'solution'
+    const description = entities.topic || message
+
+    const patternId = await memory.storePattern({
+      project,
+      pattern_type: patternType,
+      description,
+      confidence: 0.8,
+      context: message.slice(0, 300)
+    })
+
+    return {
+      action: 'stored',
+      summary: `Stored ${patternType}: ${description.slice(0, 60)}`,
+      content: `Pattern stored (ID: ${patternId})\n\n**Type:** ${patternType}\n**Project:** ${project}\n**Description:** ${description}`,
+      relevantItems: 1
+    }
+  }
+
+  private async handleMistakeLearned(
+    message: string,
+    project: string | undefined,
+    entities: BrainExtractedEntities
+  ): Promise<BrainResponse> {
+    if (!project) {
+      return {
+        action: 'none',
+        summary: 'Cannot store correction without a project',
+        content: 'Please specify which project this lesson relates to.',
+        relevantItems: 0
+      }
+    }
+
+    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,
+      original,
+      correction: correction || message,
+      reasoning,
+      context: entities.topic || '',
+      confidence: 0.9
+    })
+
+    return {
+      action: 'stored',
+      summary: `Stored correction: ${original.slice(0, 60)}`,
+      content: `Correction stored (ID: ${correctionId})\n\n**Project:** ${project}\n**Original:** ${original}\n**Correction:** ${correction || '(see original message)'}`,
+      relevantItems: 1
+    }
+  }
+
+  private async handleProgressUpdate(
+    message: string,
+    project: string | undefined,
+    entities: BrainExtractedEntities
+  ): Promise<BrainResponse> {
+    if (!project) {
+      return {
+        action: 'none',
+        summary: 'Cannot update progress without a project',
+        content: 'Please specify which project to update progress for.',
+        relevantItems: 0
+      }
+    }
+
+    if (!isServicesInitialized()) {
+      return this.servicesNotReady()
+    }
+
+    const contextService = getContextService()
+
+    const completedTask = entities.completedTask || message
+    const nextSteps = entities.nextSteps || 'Continue development'
+
+    try {
+      await contextService.progress.addCompletedTask(project, {
+        id: this.generateTaskId(completedTask),
+        title: completedTask,
+        status: 'done',
+        completedAt: new Date()
+      })
+    } catch {
+      // Progress update failed — still report what we found
+    }
+
+    return {
+      action: 'stored',
+      summary: `Progress: ${completedTask.slice(0, 60)}`,
+      content: `Progress updated for ${project}\n\n**Completed:** ${completedTask}\n**Next:** ${nextSteps}`,
+      relevantItems: 1
+    }
+  }
+
+  private async handleQuestion(
+    message: string,
+    project: string | undefined,
+    entities: BrainExtractedEntities,
+    classification: ClassificationResult
+  ): Promise<BrainResponse> {
+    if (!isServicesInitialized()) {
+      return this.servicesNotReady()
+    }
+
+    const memory = getMemoryService()
+    const query = entities.topic || message
+    const tiers: TierResults[] = []
+
+    // 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) {
+      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
+        }))
+      })
+    }
+
+    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
+        }))
+      })
+    }
+
+    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,
+          source: 'Lesson Learned',
+          metadata: c.metadata
+        }))
+      })
+    }
+
+    // If secondary intent is exploration, also try graph search
+    if (classification.secondary.includes('exploration')) {
+      await this.addExplorationResults(query, project, tiers)
+    }
+
+    return this.responseFilter.synthesize(tiers, message, project)
+  }
+
+  private async handleComparison(
+    message: string,
+    project: string | undefined,
+    entities: BrainExtractedEntities
+  ): Promise<BrainResponse> {
+    if (!isServicesInitialized()) {
+      return this.servicesNotReady()
+    }
+
+    const memory = getMemoryService()
+    const query = entities.topic || message
+    const tiers: TierResults[] = []
+
+    // Search for related decisions
+    try {
+      const rawResults = await memory.searchRaw(query, {
+        project,
+        limit: 5,
+        minSimilarity: 0.2
+      })
+
+      if (rawResults.length > 0) {
+        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'
+          }))
+        })
+      }
+    } 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'
+            }))
+          })
+        }
+      }
+    } catch {
+      // Knowledge graph not available
+    }
+
+    return this.responseFilter.synthesize(tiers, message, project, 'analyzed')
+  }
+
+  private async handleExploration(
+    message: string,
+    project: string | undefined,
+    entities: BrainExtractedEntities
+  ): Promise<BrainResponse> {
+    if (!isServicesInitialized()) {
+      return this.servicesNotReady()
+    }
+
+    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
+      })
+
+      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
+    }
+
+    return this.responseFilter.synthesize(tiers, message, project, 'analyzed')
+  }
+
+  // ===== Helpers =====
+
+  private async addExplorationResults(
+    query: string,
+    _project: string | undefined,
+    tiers: TierResults[]
+  ): Promise<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'
+            }))
+          })
+        }
+      }
+    } catch {
+      // Knowledge graph not available
+    }
+  }
+
+  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
+    }
+  }
+
+  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
+}

package/src/server/handlers/call-tool.ts

@@ -47,6 +47,9 @@ import { handleWhatIfAnalysis } from './tools/what-if-analysis'
 import { handleGetRecommendations } from './tools/get-recommendations'
 import { handleFindCrossProjectPatterns } from './tools/find-cross-project-patterns'
 
+// Phase 16 Unified Brain Tool
+import { handleBrain } from './tools/brain'
+
 /**
  * Handle tools/call request
  * Validates that tool exists and routes to the appropriate handler
@@ -164,6 +167,10 @@ export async function handleCallTool(
       case 'find_cross_project_patterns':
         return await handleFindCrossProjectPatterns(args, logger)
 
+      // Phase 16 Unified Brain Tool
+      case 'brain':
+        return await handleBrain(args, logger)
+
       default:
         // This should never happen if validateToolExists works correctly
         throw new McpError(