claude-brain 0.5.0 → 0.8.0

package/src/routing/intent-classifier.ts

@@ -0,0 +1,229 @@
+/**
+ * Brain Intent Classifier
+ * Phase 16: Rule-based intent classification for the unified brain() tool
+ *
+ * Priority-ordered — first confident match wins.
+ * No LLM calls, pure pattern matching.
+ */
+
+export type Intent =
+  | 'session_start'
+  | 'context_needed'
+  | 'decision_made'
+  | 'pattern_found'
+  | 'mistake_learned'
+  | 'progress_update'
+  | 'question'
+  | 'comparison'
+  | 'exploration'
+  | 'no_action'
+
+export interface ClassificationResult {
+  primary: Intent
+  confidence: number
+  secondary: Intent[]
+}
+
+// Decision-indicating phrases (from automation/decision-detector.ts)
+const DECISION_PHRASES = [
+  'i recommend', 'you should use', 'the best approach',
+  'i suggest', 'better to use', 'prefer using',
+  'go with', 'decided to', "let's use", 'we will use',
+  'the solution is', 'implement using', 'going with',
+  'switching to', 'adopting', 'we chose', 'the plan is to'
+]
+
+const REASONING_PHRASES = [
+  'because', 'since', 'due to', 'as it', 'which provides',
+  'this allows', 'this ensures', 'given that', 'considering',
+  'the reason is', 'this way'
+]
+
+// Mistake/correction indicators
+const MISTAKE_PHRASES = [
+  'bug was', 'the issue was', 'the problem was', 'mistake was',
+  'should have', "shouldn't have", 'should not have',
+  'lesson learned', "don't use", 'avoid using', 'never use',
+  'the fix is', 'the fix was', 'fixed by', 'solved by',
+  'was wrong', 'was broken', 'was incorrect'
+]
+
+// Progress indicators
+const PROGRESS_PHRASES = [
+  'finished', 'completed', 'done with', 'implemented',
+  'built', 'created', 'added', 'fixed', 'resolved',
+  'shipped', 'deployed', 'merged', 'released'
+]
+
+// Comparison indicators
+const COMPARISON_PHRASES = [
+  ' vs ', ' versus ', 'or should', 'compared to', 'comparing ',
+  'which is better', 'should i use', 'should we use',
+  'what if we switch', 'what if we change', 'what if we replace',
+  'pros and cons', 'tradeoffs', 'trade-offs'
+]
+
+// Pattern indicators
+const PATTERN_PHRASES = [
+  'pattern:', 'best practice:', 'anti-pattern:', 'reusable solution',
+  'reusable approach', 'common issue:', 'this pattern',
+  'recognized pattern', 'document this pattern'
+]
+
+// Exploration indicators
+const EXPLORATION_PHRASES = [
+  'show me', 'timeline', 'trends', 'evolution of',
+  'history of', 'graph', 'how has', 'what happened',
+  'decisions about', 'when did we', 'list episodes'
+]
+
+// Session start indicators
+const SESSION_START_PHRASES = [
+  'starting work', 'beginning work', 'resuming',
+  'picking up', 'getting started', 'opening',
+  'starting on', 'working on', 'beginning on'
+]
+
+// Question indicators
+const QUESTION_WORDS = [
+  'what', 'how', 'when', 'why', 'where', 'which',
+  'who', 'can', 'does', 'is', 'are', 'should', 'could', 'would'
+]
+
+// No-action indicators
+const NO_ACTION_PHRASES = [
+  'ok', 'okay', 'thanks', 'thank you', 'got it',
+  'sure', 'yes', 'no', 'cool', 'nice', 'great',
+  'understood', 'noted', 'alright', 'right'
+]
+
+export class IntentClassifier {
+  /**
+   * Classify the intent of a message
+   */
+  classify(message: string): ClassificationResult {
+    const lower = message.toLowerCase().trim()
+    const secondary: Intent[] = []
+
+    // Check in priority order — first confident match wins
+
+    // 1. no_action: very short messages, greetings, acknowledgments
+    if (this.isNoAction(lower)) {
+      return { primary: 'no_action', confidence: 0.95, secondary: [] }
+    }
+
+    // 2. decision_made: decision phrases + reasoning
+    if (this.isDecisionMade(lower)) {
+      if (this.hasComparisonSignal(lower)) secondary.push('comparison')
+      return { primary: 'decision_made', confidence: 0.85, secondary }
+    }
+
+    // 3. mistake_learned: correction/bug/lesson indicators
+    if (this.isMistakeLearned(lower)) {
+      return { primary: 'mistake_learned', confidence: 0.85, secondary }
+    }
+
+    // 4. progress_update: completed task indicators (NOT questions)
+    if (this.isProgressUpdate(lower, message)) {
+      if (this.hasSessionSignal(lower)) secondary.push('session_start')
+      return { primary: 'progress_update', confidence: 0.85, secondary }
+    }
+
+    // 5. comparison: vs, which is better, etc.
+    if (this.isComparison(lower)) {
+      if (this.isQuestion(lower, message)) secondary.push('question')
+      return { primary: 'comparison', confidence: 0.85, secondary }
+    }
+
+    // 6. pattern_found: explicit pattern documentation
+    if (this.isPatternFound(lower)) {
+      return { primary: 'pattern_found', confidence: 0.80, secondary }
+    }
+
+    // 7. session_start: starting/resuming work
+    if (this.isSessionStart(lower)) {
+      secondary.push('context_needed')
+      return { primary: 'session_start', confidence: 0.90, secondary }
+    }
+
+    // 8. exploration: timeline, trends, graph, history
+    if (this.isExploration(lower)) {
+      if (this.isQuestion(lower, message)) secondary.push('question')
+      return { primary: 'exploration', confidence: 0.75, secondary }
+    }
+
+    // 9. question: starts with question word or ends with ?
+    if (this.isQuestion(lower, message)) {
+      if (this.hasComparisonSignal(lower)) secondary.push('comparison')
+      if (this.hasExplorationSignal(lower)) secondary.push('exploration')
+      return { primary: 'question', confidence: 0.80, secondary }
+    }
+
+    // 10. Default: context_needed
+    return { primary: 'context_needed', confidence: 0.60, secondary }
+  }
+
+  private isNoAction(lower: string): boolean {
+    if (lower.length > 30) return false
+    const words = lower.split(/\s+/)
+    if (words.length > 5) return false
+    return NO_ACTION_PHRASES.some(p => lower === p || lower === p + '.' || lower === p + '!')
+  }
+
+  private isDecisionMade(lower: string): boolean {
+    const hasDecision = DECISION_PHRASES.some(p => lower.includes(p))
+    if (!hasDecision) return false
+    // Higher confidence if reasoning is also present
+    const hasReasoning = REASONING_PHRASES.some(p => lower.includes(p))
+    return hasReasoning || lower.length > 30
+  }
+
+  private isMistakeLearned(lower: string): boolean {
+    return MISTAKE_PHRASES.some(p => lower.includes(p))
+  }
+
+  private isProgressUpdate(lower: string, original: string): boolean {
+    // Must not be a question
+    if (original.trim().endsWith('?')) return false
+    const firstWord = lower.split(/\s+/)[0] || ''
+    if (QUESTION_WORDS.includes(firstWord)) return false
+
+    return PROGRESS_PHRASES.some(p => lower.includes(p))
+  }
+
+  private isComparison(lower: string): boolean {
+    return COMPARISON_PHRASES.some(p => lower.includes(p))
+  }
+
+  private isPatternFound(lower: string): boolean {
+    const hasPattern = PATTERN_PHRASES.some(p => lower.includes(p))
+    return hasPattern && lower.length > 50
+  }
+
+  private isSessionStart(lower: string): boolean {
+    return SESSION_START_PHRASES.some(p => lower.includes(p))
+  }
+
+  private isExploration(lower: string): boolean {
+    return EXPLORATION_PHRASES.some(p => lower.includes(p))
+  }
+
+  private isQuestion(lower: string, original: string): boolean {
+    if (original.trim().endsWith('?')) return true
+    const firstWord = lower.split(/\s+/)[0] || ''
+    return QUESTION_WORDS.includes(firstWord)
+  }
+
+  // Secondary signal checks
+  private hasComparisonSignal(lower: string): boolean {
+    return COMPARISON_PHRASES.some(p => lower.includes(p))
+  }
+
+  private hasExplorationSignal(lower: string): boolean {
+    return EXPLORATION_PHRASES.some(p => lower.includes(p))
+  }
+
+  private hasSessionSignal(lower: string): boolean {
+    return SESSION_START_PHRASES.some(p => lower.includes(p))
+  }
+}

package/src/routing/response-filter.ts

@@ -0,0 +1,221 @@
+/**
+ * Brain Response Filter
+ * Phase 16: Filters noise, deduplicates, ranks, and synthesizes results
+ * from the unified brain() tool
+ */
+
+export interface FilterableResult {
+  content: string
+  score: number
+  source: string
+  metadata?: Record<string, unknown>
+}
+
+export interface FilteredResult {
+  content: string
+  score: number
+  source: string
+  relevanceNote: string
+  metadata?: Record<string, unknown>
+}
+
+export interface BrainResponse {
+  action: 'retrieved' | 'stored' | 'analyzed' | 'none'
+  summary: string
+  content: string
+  relevantItems: number
+}
+
+export interface TierResults {
+  label: string
+  results: FilterableResult[]
+}
+
+export class ResponseFilter {
+  // Infrastructure noise terms — strip from non-claude-brain projects
+  private readonly INFRA_NOISE = [
+    'chromadb', 'chroma', 'minisearch', 'compromise', 'better-sqlite3',
+    'pino', 'hono', 'bun:test', 'zod', 'mcp-server', 'claude-brain',
+    'model-context-protocol', 'embedding-service', 'vector-database',
+    'mcp tool', 'tool handler', 'phase 12', 'phase 13', 'phase 14', 'phase 15',
+    'semantic cache', 'precompute engine', 'knowledge graph builder'
+  ]
+
+  /**
+   * Filter a set of results to remove noise and improve relevance
+   */
+  filter(results: FilterableResult[], query: string, project?: string): FilteredResult[] {
+    let filtered = results
+
+    // 1. Remove infrastructure noise (if project !== 'claude-brain')
+    if (project !== 'claude-brain') {
+      filtered = filtered.filter(r => !this.isInfrastructureNoise(r.content))
+    }
+
+    // 2. Remove near-duplicates (>85% word overlap, keep higher score)
+    filtered = this.deduplicateResults(filtered)
+
+    // 3. Apply dynamic threshold (at least 70% of median similarity)
+    filtered = this.applyDynamicThreshold(filtered)
+
+    // 4. Sort by score descending
+    filtered.sort((a, b) => b.score - a.score)
+
+    // 5. Limit to 5 results
+    filtered = filtered.slice(0, 5)
+
+    // 6. Add one-line relevance explanation per result
+    return filtered.map(r => ({
+      content: r.content,
+      score: r.score,
+      source: r.source,
+      relevanceNote: this.generateRelevanceNote(r, query),
+      metadata: r.metadata
+    }))
+  }
+
+  /**
+   * Synthesize results from multiple tiers into a unified BrainResponse
+   */
+  synthesize(
+    tiers: TierResults[],
+    message: string,
+    project?: string,
+    action: BrainResponse['action'] = 'retrieved'
+  ): BrainResponse {
+    // Combine all results from all tiers
+    const allResults: FilterableResult[] = []
+    for (const tier of tiers) {
+      allResults.push(...tier.results)
+    }
+
+    if (allResults.length === 0) {
+      return {
+        action: 'none',
+        summary: 'No relevant information found',
+        content: `No results found for: "${message.slice(0, 100)}"`,
+        relevantItems: 0
+      }
+    }
+
+    // Filter the combined results
+    const filtered = this.filter(allResults, message, project)
+
+    if (filtered.length === 0) {
+      return {
+        action: 'none',
+        summary: 'Results filtered out as noise or irrelevant',
+        content: `No relevant results after filtering for: "${message.slice(0, 100)}"`,
+        relevantItems: 0
+      }
+    }
+
+    // Format filtered results
+    const contentParts: string[] = []
+    for (const result of filtered) {
+      const scoreStr = result.score > 0 ? ` [${Math.round(result.score * 100)}%]` : ''
+      contentParts.push(`**${result.source}**${scoreStr}\n${result.content}`)
+      if (result.relevanceNote) {
+        contentParts.push(`_${result.relevanceNote}_`)
+      }
+      contentParts.push('')
+    }
+
+    const summary = filtered.length === 1
+      ? `Found 1 relevant result`
+      : `Found ${filtered.length} relevant results`
+
+    return {
+      action,
+      summary,
+      content: contentParts.join('\n'),
+      relevantItems: filtered.length
+    }
+  }
+
+  /**
+   * Check if content is infrastructure/internal noise
+   */
+  private isInfrastructureNoise(content: string): boolean {
+    const lower = content.toLowerCase()
+    let noiseHits = 0
+
+    for (const term of this.INFRA_NOISE) {
+      if (lower.includes(term)) {
+        noiseHits++
+      }
+    }
+
+    // If more than 2 infrastructure terms appear, it's likely noise
+    return noiseHits >= 2
+  }
+
+  /**
+   * Remove near-duplicate results (>85% word overlap)
+   */
+  private deduplicateResults(results: FilterableResult[]): FilterableResult[] {
+    const kept: FilterableResult[] = []
+
+    for (const result of results) {
+      const isDuplicate = kept.some(existing => {
+        const overlap = this.calculateWordOverlap(existing.content, result.content)
+        return overlap > 0.85
+      })
+
+      if (!isDuplicate) {
+        kept.push(result)
+      }
+    }
+
+    return kept
+  }
+
+  /**
+   * Apply dynamic threshold — results must be at least 70% of median score
+   */
+  private applyDynamicThreshold(results: FilterableResult[]): FilterableResult[] {
+    if (results.length <= 1) return results
+
+    // Calculate median score
+    const scores = results.map(r => r.score).sort((a, b) => a - b)
+    const mid = Math.floor(scores.length / 2)
+    const left = scores[mid - 1] ?? 0
+    const right = scores[mid] ?? 0
+    const median = scores.length % 2 === 0
+      ? (left + right) / 2
+      : right
+
+    const threshold = median * 0.7
+
+    return results.filter(r => r.score >= threshold)
+  }
+
+  /**
+   * Calculate word overlap between two strings (0-1)
+   */
+  private calculateWordOverlap(a: string, b: string): number {
+    const wordsA = new Set(a.toLowerCase().split(/\s+/).filter(w => w.length > 2))
+    const wordsB = new Set(b.toLowerCase().split(/\s+/).filter(w => w.length > 2))
+
+    if (wordsA.size === 0 || wordsB.size === 0) return 0
+
+    let intersection = 0
+    for (const word of wordsA) {
+      if (wordsB.has(word)) intersection++
+    }
+
+    const smaller = Math.min(wordsA.size, wordsB.size)
+    return intersection / smaller
+  }
+
+  /**
+   * Generate a one-line relevance explanation
+   */
+  private generateRelevanceNote(result: FilterableResult, _query: string): string {
+    const score = Math.round(result.score * 100)
+    if (score >= 90) return `Highly relevant match (${score}%)`
+    if (score >= 70) return `Good match (${score}%)`
+    if (score >= 50) return `Partial match (${score}%)`
+    return `Low relevance match (${score}%)`
+  }
+}