claude-brain 0.30.2 → 0.30.3

package/src/routing/handlers/exploration-handler.ts

@@ -0,0 +1,369 @@
+/**
+ * Exploration Handler
+ * Task 3.1: Exploration intents — handleExploration, handleComparison,
+ * handleListAll, handleTimeline, handleCategoryQuery
+ */
+
+import type { HandlerContext, BrainExtractedEntities, BrainResponse, TierResults } from './types'
+import { DEFAULT_PROJECT } from './types'
+import { ResponseFilter, formatCompactResponse, formatTimeline, groupByDay } from '../response-filter'
+import {
+  servicesNotReady,
+  queryCodeIntelligence,
+  fetchRecentObservations
+} from './shared'
+import { getMemoryService, isServicesInitialized } from '@/server/services'
+
+/**
+ * Phase 19 C6: Enhanced exploration handler
+ * - Timeline for "timeline"/"chronological" queries
+ * - DecisionEvolutionTracker for "how has X changed" queries
+ * - TrendDetector for "trends"/"emerging" queries
+ */
+export async function handleExploration(
+  ctx: HandlerContext,
+  message: string,
+  project: string | undefined,
+  entities: BrainExtractedEntities
+): Promise<BrainResponse> {
+  if (!isServicesInitialized()) {
+    return 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 ctx.searchEngine.buildTimeline({
+      project: searchProject,
+      topic: query,
+      limit: 20
+    })
+
+    if (timeline?.entries?.length) {
+      tiers.push({
+        label: 'Timeline',
+        results: timeline.entries.map((e: Record<string, unknown>) => ({
+          content: `**${String(e.date || '')}** — ${String(e.content || '')}`,
+          score: 0.8,
+          source: `Timeline (${String(e.type || 'event')})`,
+          metadata: (e.metadata || {}) as Record<string, unknown>
+        }))
+      })
+    }
+  }
+
+  // C6: Evolution queries
+  if (lower.includes('evolution') || lower.includes('how has') || lower.includes('changed') || lower.includes('evolved')) {
+    const evolution = await ctx.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 ctx.searchEngine.detectTrends({ project: searchProject })
+    if (trends?.topTrends?.length) {
+      tiers.push({
+        label: 'Trends',
+        results: trends.topTrends.slice(0, 5).map((t: Record<string, unknown>) => ({
+          content: `**${String(t.term)}** — ${String(t.trend)} (${t.occurrences} occurrences, momentum: ${String(t.momentum || 'unknown')})`,
+          score: (t.occurrences as number) > 5 ? 0.9 : 0.7,
+          source: `Trend (${String(t.trend)})`,
+          metadata: {}
+        }))
+      })
+    }
+  }
+
+  // Always include graph exploration — cap scores when project filter is active
+  // BUG-006 T4: Also require keyword overlap with query to prevent noise
+  const explorationGraphCap = searchProject ? 0.45 : 0.6
+  const explorationQueryWords = new Set(query.toLowerCase().split(/\s+/).filter(w => w.length > 2))
+  const graphResults = await ctx.searchEngine.searchGraph(query, 10)
+  const filteredGraphResults = graphResults.filter(g => {
+    if (explorationQueryWords.size > 0) {
+      const contentLower = g.content.toLowerCase()
+      return [...explorationQueryWords].some(w => contentLower.includes(w))
+    }
+    return true
+  })
+  if (filteredGraphResults.length > 0) {
+    tiers.push({
+      label: 'Knowledge Graph',
+      results: filteredGraphResults.map(g => ({
+        content: g.content,
+        score: Math.min(g.score, explorationGraphCap),
+        source: 'Knowledge Graph',
+        metadata: g.metadata as Record<string, unknown>
+      }))
+    })
+  }
+
+  // Issue 9: Cross-project patterns for exploration queries
+  if (!project) {
+    try {
+      const crossProject = await ctx.searchEngine.findCrossProjectPatterns({
+        query,
+        limit: 3
+      })
+      if (crossProject?.patterns?.length) {
+        tiers.push({
+          label: 'Cross-Project Patterns',
+          results: crossProject.patterns.map((p: Record<string, unknown>) => ({
+            content: `${String(p.description || '')} (${Array.isArray(p.projects) ? p.projects.join(', ') : 'multiple projects'})`,
+            score: (p.confidence as number) || 0.5,
+            source: 'Cross-Project',
+            metadata: {}
+          }))
+        })
+      }
+    } catch {
+      // Cross-project not available
+    }
+  }
+
+  // Also do a basic memory search as fallback
+  const searchResults = await ctx.searchEngine.enhancedSearch(query, {
+    project: searchProject,
+    limit: 5,
+    minSimilarity: 0.2
+  })
+  if (searchResults.length > 0) {
+    tiers.push({
+      label: 'Memories',
+      results: searchResults.map(r => ({
+        content: r.content,
+        score: r.score,
+        source: r.source === 'decision' ? 'Past Decision' : r.source,
+        metadata: r.metadata as Record<string, unknown>
+      }))
+    })
+  }
+
+  // Phase 32: Code intelligence for exploration queries
+  const codeTier = queryCodeIntelligence(ctx, query, searchProject)
+  if (codeTier) {
+    tiers.push(codeTier)
+  }
+
+  const responseFilter = new ResponseFilter()
+  return responseFilter.synthesize(tiers, message, displayProject, 'analyzed')
+}
+
+export async function handleComparison(
+  ctx: HandlerContext,
+  message: string,
+  project: string | undefined,
+  entities: BrainExtractedEntities
+): Promise<BrainResponse> {
+  if (!isServicesInitialized()) {
+    return 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 ctx.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 ctx.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>
+      }))
+    })
+  }
+
+  const responseFilter = new ResponseFilter()
+  return responseFilter.synthesize(tiers, message, displayProject, 'analyzed')
+}
+
+/**
+ * List all decisions for a project
+ */
+export async function handleListAll(
+  _ctx: HandlerContext,
+  _message: string,
+  project: string | undefined,
+  _entities: BrainExtractedEntities
+): Promise<BrainResponse> {
+  if (!isServicesInitialized()) {
+    return servicesNotReady()
+  }
+
+  const memory = getMemoryService()
+  const effectiveProject = project
+
+  try {
+    const decisions = await memory.fetchAllDecisions(effectiveProject)
+    const patterns = await memory.fetchAllPatterns(effectiveProject)
+    const corrections = await memory.fetchAllCorrections(effectiveProject)
+
+    const projectLabel = effectiveProject || 'all projects'
+    const total = decisions.length + patterns.length + corrections.length
+
+    if (total === 0) {
+      return {
+        action: 'none',
+        summary: `No memories found for ${projectLabel}`,
+        content: `No decisions, patterns, or corrections stored yet for ${projectLabel}.`,
+        relevantItems: 0
+      }
+    }
+
+    // Phase 27: Use compact format for list_all
+    const allItems: Record<string, unknown>[] = [
+      ...decisions.map((d: Record<string, unknown>) => ({
+        id: d.id || d.decision_id,
+        content: typeof (d.decision || d.document || d.content) === 'string'
+          ? (d.decision || d.document || d.content)
+          : JSON.stringify(d.decision || d.document || d.content || ''),
+        category: 'decision',
+        project: d.project || effectiveProject || 'general',
+        created_at: d.created_at || d.date || '',
+      })),
+      ...patterns.map((p: Record<string, unknown>) => ({
+        id: p.id,
+        content: typeof (p.description || p.document || p.content) === 'string'
+          ? (p.description || p.document || p.content)
+          : JSON.stringify(p.description || p.document || p.content || ''),
+        category: p.pattern_type || 'pattern',
+        project: p.project || effectiveProject || 'general',
+        created_at: p.created_at || '',
+      })),
+      ...corrections.map((c: Record<string, unknown>) => ({
+        id: c.id,
+        content: typeof (c.original || c.document || c.content) === 'string'
+          ? (c.original || c.document || c.content)
+          : JSON.stringify(c.original || c.document || c.content || ''),
+        category: 'correction',
+        project: c.project || effectiveProject || 'general',
+        created_at: c.created_at || '',
+      })),
+    ]
+
+    const compactContent = formatCompactResponse(allItems, `all memories for ${projectLabel}`)
+    return {
+      action: 'retrieved',
+      summary: `${total} memories for ${projectLabel}`,
+      content: compactContent,
+      relevantItems: total
+    }
+  } catch (error) {
+    return {
+      action: 'none',
+      summary: 'Error listing memories',
+      content: `Failed to list memories: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      relevantItems: 0
+    }
+  }
+}
+
+/**
+ * Phase 27: Handle timeline requests — "timeline for project", "recent activity"
+ * Fetches observations in a time range and groups by day.
+ */
+export async function handleTimeline(
+  _ctx: HandlerContext,
+  message: string,
+  project: string | undefined,
+  entities: BrainExtractedEntities
+): Promise<BrainResponse> {
+  if (!isServicesInitialized()) {
+    return servicesNotReady()
+  }
+
+  const effectiveProject = entities.project || project
+  const displayProject = effectiveProject || DEFAULT_PROJECT
+
+  // Parse time range from message (default: last 7 days)
+  const now = new Date()
+  let start: Date
+  let daysBack = 7
+  const lower = message.toLowerCase()
+  if (lower.includes('yesterday')) {
+    daysBack = 1
+    start = new Date(now.getTime() - 1 * 24 * 60 * 60 * 1000)
+  } else if (lower.includes('today')) {
+    daysBack = 0
+    // Start of today, not "now"
+    start = new Date(now.getFullYear(), now.getMonth(), now.getDate())
+  } else if (lower.includes('last month') || lower.includes('past month')) {
+    daysBack = 30
+    start = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000)
+  } else if (lower.includes('last week') || lower.includes('past week')) {
+    daysBack = 7
+    start = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000)
+  } else if (lower.includes('last 3 days') || lower.includes('past 3 days')) {
+    daysBack = 3
+    start = new Date(now.getTime() - 3 * 24 * 60 * 60 * 1000)
+  } else {
+    start = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000)
+  }
+
+  const observations = await fetchRecentObservations(effectiveProject, start, now)
+  if (observations.length === 0) {
+    return {
+      action: 'none',
+      summary: `No activity found for ${displayProject}`,
+      content: `No observations found in the last ${daysBack === 0 ? 'day' : `${daysBack} day(s)`} for ${displayProject}.`,
+      relevantItems: 0
+    }
+  }
+
+  const grouped = groupByDay(observations)
+  const timelineContent = formatTimeline(grouped, displayProject)
+
+  return {
+    action: 'retrieved',
+    summary: `Timeline for ${displayProject} (${observations.length} items)`,
+    content: timelineContent,
+    relevantItems: observations.length
+  }
+}

package/src/routing/handlers/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Handler Index
+ * Task 3.1: Re-exports all domain handler functions and shared types
+ */
+
+export type { HandlerContext, RecentDecision, IntentHandler } from './types'
+export { DEFAULT_PROJECT, DELETE_MIN_SIMILARITY, UPDATE_MIN_SIMILARITY, RECENT_DECISION_WINDOW_MS } from './types'
+
+// Memory (store) handlers
+export { handleStoreThis, handleDecisionMade, handlePatternFound, handleMistakeLearned, handleProgressUpdate } from './memory-handler'
+
+// Recall handlers
+export { handleSessionStart, handleContextNeeded, handleQuestion, handleDetailRequest } from './recall-handler'
+
+// Mutation handlers
+export { handleUpdateMemory, handleDeleteMemory } from './mutation-handler'
+
+// Exploration handlers
+export { handleExploration, handleComparison, handleListAll, handleTimeline } from './exploration-handler'

package/src/routing/handlers/memory-handler.ts

@@ -0,0 +1,273 @@
+/**
+ * Memory Handler
+ * Task 3.1: Store intents — handleStoreThis, handleDecisionMade,
+ * handlePatternFound, handleMistakeLearned, handleProgressUpdate
+ */
+
+import type { HandlerContext, BrainExtractedEntities, BrainResponse } from './types'
+import { DEFAULT_PROJECT } from './types'
+import {
+  servicesNotReady,
+  writeToVault,
+  linkToActiveEpisode,
+  linkToCodeFiles,
+  registerEpisodeMessage,
+  generateTaskId,
+  maybeCompress
+} from './shared'
+import {
+  getMemoryService,
+  getContextService,
+  isServicesInitialized
+} from '@/server/services'
+import { timed } from '@/utils/timing'
+
+/**
+ * Handle explicit "store this" requests — always uses the FULL message as the decision text.
+ */
+export async function handleStoreThis(
+  ctx: HandlerContext,
+  message: string,
+  project: string | undefined,
+  entities: BrainExtractedEntities
+): Promise<BrainResponse> {
+  const effectiveProject = project || DEFAULT_PROJECT
+
+  if (!isServicesInitialized()) {
+    return servicesNotReady()
+  }
+
+  const memory = getMemoryService()
+  const reasoning = entities.reasoning || ''
+  const context = entities.topic || message.slice(0, 200)
+
+  // Phase 30: Optional LLM compression
+  const { content: decision, rawContent } = await maybeCompress(ctx, message, 'store')
+
+  const decisionId = await timed('brain:store', () => memory.rememberDecision(
+    effectiveProject,
+    context,
+    decision,
+    reasoning,
+    {
+      alternatives: entities.alternatives,
+      tags: entities.technologies.length > 0 ? entities.technologies : ['user-stored']
+    }
+  ))
+
+  // Track for potential update/delete
+  ctx.setLastStored(decisionId, effectiveProject)
+
+  // Bug 4: Track for recency fast path
+  ctx.trackRecentDecision(decision, effectiveProject)
+
+  // Invalidate cache for this project
+  ctx.searchEngine.invalidateCache(effectiveProject)
+
+  // Background: vault write + episode linking + code linkage (non-critical)
+  setImmediate(() => {
+    writeToVault(effectiveProject, decision, reasoning, context, entities.alternatives)
+    linkToActiveEpisode(effectiveProject, decisionId, 'decision')
+    linkToCodeFiles(ctx, decisionId, decision, effectiveProject)
+  })
+
+  const compressedNote = rawContent ? '\n*(compressed)*' : ''
+  return {
+    action: 'stored',
+    summary: `Stored: ${message.slice(0, 60)}`,
+    content: `Memory stored (ID: ${decisionId})\n\n**Project:** ${effectiveProject}\n**Content:** ${decision}${reasoning ? `\n**Reasoning:** ${reasoning}` : ''}${compressedNote}`,
+    relevantItems: 1
+  }
+}
+
+export async function handleDecisionMade(
+  ctx: HandlerContext,
+  message: string,
+  project: string | undefined,
+  entities: BrainExtractedEntities
+): Promise<BrainResponse> {
+  const effectiveProject = project || DEFAULT_PROJECT
+
+  if (!isServicesInitialized()) {
+    return servicesNotReady()
+  }
+
+  const memory = getMemoryService()
+  const reasoning = entities.reasoning || ''
+  const context = entities.topic || message.slice(0, 200)
+  const alternatives = entities.alternatives
+
+  // Phase 30: Optional LLM compression
+  const { content: decision, rawContent } = await maybeCompress(ctx, message, 'decision')
+
+  const decisionId = await timed('brain:store', () => memory.rememberDecision(
+    effectiveProject,
+    context,
+    decision,
+    reasoning,
+    {
+      alternatives,
+      tags: entities.technologies.length > 0 ? entities.technologies : ['auto-detected']
+    }
+  ))
+
+  ctx.setLastStored(decisionId, effectiveProject)
+
+  // Bug 4: Track for recency fast path
+  ctx.trackRecentDecision(decision, effectiveProject)
+
+  // Invalidate cache
+  ctx.searchEngine.invalidateCache(effectiveProject)
+
+  // Background: vault write + episode linking + code linkage (non-critical)
+  setImmediate(() => {
+    writeToVault(effectiveProject, decision, reasoning, context, alternatives)
+    linkToActiveEpisode(effectiveProject, decisionId, 'decision')
+    linkToCodeFiles(ctx, decisionId, decision, effectiveProject)
+  })
+
+  const compressedNote = rawContent ? '\n*(compressed)*' : ''
+  return {
+    action: 'stored',
+    summary: `Stored decision: ${message.slice(0, 60)}`,
+    content: `Decision stored (ID: ${decisionId})\n\n**Project:** ${effectiveProject}\n**Decision:** ${decision}\n**Reasoning:** ${reasoning}${compressedNote}`,
+    relevantItems: 1
+  }
+}
+
+export async function handlePatternFound(
+  ctx: HandlerContext,
+  message: string,
+  project: string | undefined,
+  entities: BrainExtractedEntities
+): Promise<BrainResponse> {
+  const effectiveProject = project || DEFAULT_PROJECT
+
+  if (!isServicesInitialized()) {
+    return 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
+  ctx.searchEngine.invalidateCache(effectiveProject)
+
+  // Link to active episode + code files
+  linkToActiveEpisode(effectiveProject, patternId, 'pattern')
+  linkToCodeFiles(ctx, patternId, description, effectiveProject)
+
+  return {
+    action: 'stored',
+    summary: `Stored ${patternType}: ${description.slice(0, 60)}`,
+    content: `Pattern stored (ID: ${patternId})\n\n**Type:** ${patternType}\n**Project:** ${effectiveProject}\n**Description:** ${description}`,
+    relevantItems: 1
+  }
+}
+
+export async function handleMistakeLearned(
+  ctx: HandlerContext,
+  message: string,
+  project: string | undefined,
+  entities: BrainExtractedEntities
+): Promise<BrainResponse> {
+  const effectiveProject = project || DEFAULT_PROJECT
+
+  if (!isServicesInitialized()) {
+    return 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
+  ctx.searchEngine.invalidateCache(effectiveProject)
+
+  // Link to active episode + code files
+  linkToActiveEpisode(effectiveProject, correctionId, 'correction')
+  linkToCodeFiles(ctx, correctionId, original, effectiveProject)
+
+  return {
+    action: 'stored',
+    summary: `Stored correction: ${original.slice(0, 60)}`,
+    content: `Correction stored (ID: ${correctionId})\n\n**Project:** ${effectiveProject}\n**Original:** ${original}\n**Correction:** ${correction || '(see original message)'}`,
+    relevantItems: 1
+  }
+}
+
+export async function handleProgressUpdate(
+  ctx: HandlerContext,
+  message: string,
+  project: string | undefined,
+  entities: BrainExtractedEntities
+): Promise<BrainResponse> {
+  const effectiveProject = project || DEFAULT_PROJECT
+
+  if (!isServicesInitialized()) {
+    return 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: 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
+    ctx.searchEngine.invalidateCache(effectiveProject)
+  } catch {
+    // Memory storage failed
+  }
+
+  // Register with episode
+  registerEpisodeMessage(ctx, 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
+  }
+}