claude-brain 0.30.2 → 0.30.3

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

@@ -0,0 +1,642 @@
+/**
+ * Recall Handler
+ * Task 3.1: Recall intents — handleSessionStart, handleContextNeeded,
+ * handleQuestion, handleDetailRequest
+ */
+
+import type { HandlerContext, BrainExtractedEntities, BrainResponse, ClassificationResult, TierResults } from './types'
+import { DEFAULT_PROJECT } from './types'
+import type { NormalizedResult } from '../types'
+import { ResponseFilter, type FilterableResult, formatCompactResponse, formatDetailResponse } from '../response-filter'
+import {
+  servicesNotReady,
+  registerEpisodeMessage,
+  queryCodeIntelligence,
+  isSessionRecallQuery,
+  isComplexQuestion,
+  detectCategoryIntent,
+  findRecentDecisions,
+  lookupById,
+  incrementAccess
+} from './shared'
+import {
+  getMemoryService,
+  getContextService,
+  getPhase12Service,
+  getSessionTracker,
+  getCodeQuery,
+  isServicesInitialized
+} from '@/server/services'
+
+export async function handleSessionStart(
+  ctx: HandlerContext,
+  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 servicesNotReady()
+  }
+
+  const contextService = getContextService()
+  const phase12 = getPhase12Service()
+
+  // Get project context
+  const context = await contextService.getContext(project, {
+    includeMemories: false,
+    includeProgress: true,
+    includeStandards: true,
+    maxTokens: 6000,
+    relevanceThreshold: 0.5
+  })
+
+  const formattedContext = contextService.formatter.format(context)
+
+  // Process with Phase 12 for proactive recall
+  const phase12Result = await phase12.processMessage(
+    entities.topic || message,
+    project
+  )
+
+  // Build response
+  const parts: string[] = [formattedContext]
+
+  if (phase12Result.recalledMemories?.memories.length) {
+    parts.push('\n---\n## Relevant Past Decisions\n')
+    for (const mem of phase12Result.recalledMemories.memories) {
+      const similarity = Math.round((mem.similarity || 0) * 100)
+      const decisionText = mem.decision?.decision || mem.memory?.content || ''
+      const safeText = typeof decisionText === 'string' ? decisionText : JSON.stringify(decisionText)
+      parts.push(`**[${similarity}%]** ${safeText.slice(0, 200)}`)
+      if (mem.decision?.reasoning) {
+        const reasoning = typeof mem.decision.reasoning === 'string' ? mem.decision.reasoning : JSON.stringify(mem.decision.reasoning)
+        parts.push(`  _${reasoning}_`)
+      }
+    }
+  }
+
+  // If Phase 12 found nothing, do a direct search fallback via SearchEngine
+  if (!phase12Result.recalledMemories?.memories.length) {
+    try {
+      const directResults = await ctx.searchEngine.enhancedSearch(entities.topic || message, {
+        project,
+        limit: 5,
+        minSimilarity: 0.3
+      })
+      if (directResults.length > 0) {
+        parts.push('\n---\n## Related Memories\n')
+        for (const r of directResults) {
+          const similarity = Math.round((r.score || 0) * 100)
+          const safeContent = typeof r.content === 'string' ? r.content : JSON.stringify(r.content ?? '')
+          parts.push(`**[${similarity}%]** ${safeContent.slice(0, 200)}`)
+        }
+      }
+    } catch {
+      // Direct search failed, continue without
+    }
+  }
+
+  // Phase 32: Include code file map in session context if code index is available
+  try {
+    const codeQuery = getCodeQuery()
+    if (codeQuery && project) {
+      const fileMap = codeQuery.getFileMap(project, 50)
+      if (fileMap.length > 0) {
+        const formatted = codeQuery.formatFileMap(fileMap)
+        parts.push('\n---\n## Code Structure\n')
+        parts.push(formatted)
+      }
+    }
+  } catch {
+    // Code intelligence not available
+  }
+
+  // C8: Register with episode manager
+  registerEpisodeMessage(ctx, message, project, 'session_start')
+
+  // C9: Append proactive recommendations
+  try {
+    const recommendations = await ctx.searchEngine.getRecommendations(
+      entities.topic || message,
+      { project, limit: 3 }
+    )
+    if (recommendations?.recommendations?.length) {
+      parts.push('\n---\n## Proactive Recommendations\n')
+      for (const rec of recommendations.recommendations) {
+        parts.push(`- **${rec.type}**: ${rec.content?.slice(0, 150) || ''}`)
+        if (rec.reasoning) parts.push(`  _${rec.reasoning}_`)
+      }
+    }
+  } catch {
+    // Recommendations not available
+  }
+
+  // Phase 25: Query past session summaries for this project
+  try {
+    let sessionSummaries = await ctx.searchEngine.plainSearch(
+      'session summary',
+      { project: project || undefined, limit: 5, minSimilarity: 0.3 }
+    )
+
+    // Fallback: if plainSearch returns 0, try enhancedSearch with broader query
+    if (sessionSummaries.length === 0) {
+      sessionSummaries = await ctx.searchEngine.enhancedSearch(
+        `session summary ${project || ''}`.trim(),
+        { project: project || undefined, limit: 5, minSimilarity: 0.2 }
+      )
+    }
+
+    let summaryItems = sessionSummaries.filter(r =>
+      (r.metadata as Record<string, unknown>)?.tags &&
+      Array.isArray((r.metadata as Record<string, unknown>).tags) &&
+      ((r.metadata as Record<string, unknown>).tags as string[]).includes('session-summary') ||
+      r.content.toLowerCase().startsWith('session summary:') ||
+      r.content.toLowerCase().includes('worked on')
+    )
+
+    // Sort by date descending (most recent first)
+    summaryItems.sort((a, b) => {
+      const dateA = a.date || (a.metadata as Record<string, unknown>)?.created_at as string || ''
+      const dateB = b.date || (b.metadata as Record<string, unknown>)?.created_at as string || ''
+      return dateB.localeCompare(dateA)
+    })
+
+    if (summaryItems.length > 0) {
+      parts.push('\n---\n## Past Sessions\n')
+      for (const s of summaryItems.slice(0, 3)) {
+        const safeContent = typeof s.content === 'string' ? s.content : JSON.stringify(s.content ?? '')
+        parts.push(`- ${safeContent.slice(0, 300)}`)
+      }
+    }
+  } catch {
+    // Non-critical — skip if search fails
+  }
+
+  const totalRecalled = phase12Result.recalledMemories?.memories.length || 0
+  return {
+    action: 'retrieved',
+    summary: `Session context for ${project}${totalRecalled ? ` (${totalRecalled} memories)` : ''}`,
+    content: parts.join('\n'),
+    relevantItems: totalRecalled
+  }
+}
+
+export async function handleContextNeeded(
+  ctx: HandlerContext,
+  message: string,
+  project: string | undefined,
+  entities: BrainExtractedEntities,
+  classification?: ClassificationResult
+): Promise<BrainResponse> {
+  if (!isServicesInitialized()) {
+    return servicesNotReady()
+  }
+
+  // Phase 25: Use undefined for search when no project detected (search all projects)
+  const searchProject = project || undefined
+  const displayProject = project || DEFAULT_PROJECT
+  const query = entities.topic || message
+  const tiers: TierResults[] = []
+  const hasTemporal = classification?.secondary.includes('exploration') ||
+    ctx.classifier.hasTemporalSignal(message.toLowerCase())
+
+  // Use temporal search if temporal signals detected
+  if (hasTemporal) {
+    const { results } = await ctx.searchEngine.temporalSearch(query, { project: searchProject, limit: 5 })
+    if (results.length > 0) {
+      tiers.push({
+        label: 'Memories',
+        results: results.map(r => ({
+          content: r.content,
+          score: r.score,
+          source: r.source === 'decision' ? 'Past Decision' : r.source,
+          metadata: r.metadata as Record<string, unknown>
+        }))
+      })
+    }
+  } else {
+    // Standard enhanced search
+    const searchResults = await ctx.searchEngine.enhancedSearch(query, {
+      project: searchProject,
+      limit: 5,
+      minSimilarity: 0.3
+    })
+    if (searchResults.length > 0) {
+      tiers.push({
+        label: 'Memories',
+        results: searchResults.map(r => ({
+          content: r.content,
+          score: r.score,
+          source: r.source === 'decision' ? 'Past Decision' : r.source,
+          metadata: r.metadata as Record<string, unknown>
+        }))
+      })
+    }
+  }
+
+  // Also search patterns
+  const patternResults = await ctx.searchEngine.searchPatterns(query, { project: searchProject, limit: 3 })
+  if (patternResults.length > 0) {
+    tiers.push({
+      label: 'Patterns',
+      results: patternResults.map(p => ({
+        content: p.content,
+        score: p.score,
+        source: `Pattern`,
+        metadata: p.metadata as Record<string, unknown>
+      }))
+    })
+  }
+
+  // Phase 32: Code intelligence — query code index for matching symbols/files
+  const codeTier = queryCodeIntelligence(ctx, query, searchProject)
+  if (codeTier) {
+    tiers.push(codeTier)
+  }
+
+  const responseFilter = new ResponseFilter()
+  const response = responseFilter.synthesize(tiers, message, displayProject)
+
+  // P0: When no results found and message looks like a plain statement (not a question),
+  // add a hint that the user may have intended to store it
+  if (response.action === 'none' && response.relevantItems === 0) {
+    const isPlainStatement = message.length > 15 &&
+      !message.trim().endsWith('?') &&
+      message.split(/\s+/).length > 3
+    if (isPlainStatement) {
+      response.content += `\n\n**Tip:** If you meant to save this, try:\n- \`brain("Remember: ${message.slice(0, 60)}")\`\n- Or use \`action: "store"\` to force storage: \`brain({ message: "...", action: "store" })\``
+    }
+  }
+
+  return response
+}
+
+/**
+ * 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
+ */
+export async function handleQuestion(
+  ctx: HandlerContext,
+  message: string,
+  project: string | undefined,
+  entities: BrainExtractedEntities,
+  classification: ClassificationResult
+): Promise<BrainResponse> {
+  if (!isServicesInitialized()) {
+    return servicesNotReady()
+  }
+
+  // BUG-002: Detect category-based queries and route to fetchAll
+  const categoryIntent = detectCategoryIntent(message)
+  if (categoryIntent) {
+    return handleCategoryQuery(message, project, categoryIntent)
+  }
+
+  // Phase 25: Use undefined for search (no project filter = search all) when no project detected
+  const searchProject = project || undefined
+  const displayProject = project || DEFAULT_PROJECT
+  const query = entities.topic || message
+  const tiers: TierResults[] = []
+  const hasTemporal = classification.secondary.includes('exploration') ||
+    ctx.classifier.hasTemporalSignal(message.toLowerCase())
+
+  // C7: Detect multi-part questions for chain retrieval
+  const complex = isComplexQuestion(message)
+
+  // Main search — temporal or standard
+  let searchResults: NormalizedResult[]
+  if (hasTemporal) {
+    const { results } = await ctx.searchEngine.temporalSearch(query, { project: searchProject, limit: 5 })
+    searchResults = results
+  } else if (complex) {
+    // C7: Try multi-hop chain retrieval
+    const chainResult = await ctx.searchEngine.chainSearch(query, { project: searchProject })
+    if (chainResult?.allResults?.length) {
+      searchResults = chainResult.allResults.map((r: Record<string, unknown>) => {
+        const meta = (r.metadata || {}) as Record<string, unknown>
+        return {
+          id: String(r.id || ''),
+          content: String(r.content || ''),
+          score: (r.similarity as number) || 0,
+          source: 'decision' as const,
+          project: String(meta.project || displayProject || ''),
+          date: String(meta.created_at || ''),
+          metadata: meta
+        }
+      })
+    } else {
+      searchResults = await ctx.searchEngine.enhancedSearch(query, { project: searchProject, limit: 5 })
+    }
+  } else {
+    searchResults = await ctx.searchEngine.enhancedSearch(query, { project: searchProject, limit: 5 })
+  }
+
+  if (searchResults.length > 0) {
+    tiers.push({
+      label: 'Memories',
+      results: searchResults.map(r => ({
+        content: r.content,
+        score: r.score,
+        source: r.source === 'decision' ? 'Past Decision' : r.source,
+        metadata: {
+          ...(r.metadata as Record<string, unknown>),
+          id: r.id,
+          project: r.project,
+          created_at: r.date
+        }
+      }))
+    })
+  }
+
+  // Phase 32: Code intelligence — synchronous SQLite query, runs alongside async searches
+  const codeTier = queryCodeIntelligence(ctx, query, searchProject)
+  if (codeTier) {
+    tiers.push(codeTier)
+  }
+
+  // Parallel: patterns + corrections + graph
+  const [patternResults, correctionResults, graphResults] = await Promise.all([
+    ctx.searchEngine.searchPatterns(query, { project: searchProject, limit: 3 }),
+    ctx.searchEngine.searchCorrections(query, { project: searchProject, limit: 3 }),
+    // C11: KnowledgeGraph enrichment for all questions
+    ctx.searchEngine.searchGraph(query, 5)
+  ])
+
+  if (patternResults.length > 0) {
+    tiers.push({
+      label: 'Patterns',
+      results: patternResults.map(p => ({
+        content: p.content,
+        score: p.score,
+        source: `Pattern`,
+        metadata: {
+          ...(p.metadata as Record<string, unknown>),
+          id: p.id,
+          project: p.project,
+          created_at: p.date,
+          category: 'pattern'
+        }
+      }))
+    })
+  }
+
+  if (correctionResults.length > 0) {
+    tiers.push({
+      label: 'Corrections',
+      results: correctionResults.map(c => ({
+        content: c.content,
+        score: c.score,
+        source: 'Lesson Learned',
+        metadata: {
+          ...(c.metadata as Record<string, unknown>),
+          id: c.id,
+          project: c.project,
+          created_at: c.date,
+          category: 'correction'
+        }
+      }))
+    })
+  }
+
+  // C11: Add graph results as "Related Concepts"
+  // When a project filter is active, cap graph results at 0.45 so they can compete
+  // fairly with project-scoped ChromaDB results. Without a project filter, cap at 0.6.
+  // BUG-006 T4: Also require keyword overlap with query to prevent noise
+  const graphScoreCap = searchProject ? 0.45 : 0.6
+  const queryWordsForGraph = new Set(query.toLowerCase().split(/\s+/).filter(w => w.length > 2))
+  const relevantGraphResults = graphResults.filter(g => {
+    if (g.score < 0.6) return false
+    // Require at least one query keyword to appear in graph content
+    if (queryWordsForGraph.size > 0) {
+      const contentLower = g.content.toLowerCase()
+      const hasOverlap = [...queryWordsForGraph].some(w => contentLower.includes(w))
+      if (!hasOverlap) return false
+    }
+    return true
+  })
+  if (relevantGraphResults.length > 0) {
+    tiers.push({
+      label: 'Related Concepts',
+      results: relevantGraphResults.map(g => ({
+        content: g.content,
+        score: Math.min(g.score, graphScoreCap),
+        source: 'Knowledge Graph',
+        metadata: g.metadata as Record<string, unknown>
+      }))
+    })
+  }
+
+  // C10: CrossProject patterns for general/unspecified project queries (Bug 2: cap to 0.3)
+  if (!project) {
+    try {
+      const crossProject = await 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: Math.min((p.confidence as number) || 0.5, 0.3),
+            source: 'Cross-Project',
+            metadata: {}
+          }))
+        })
+      }
+    } catch {
+      // Cross-project not available
+    }
+  }
+
+  // Phase 23b Fix 5: Session recall — "what have we discussed" queries session tracker
+  if (isSessionRecallQuery(message)) {
+    try {
+      const tracker = getSessionTracker()
+      if (tracker) {
+        const stats = tracker.getStats()
+        if (stats.totalItems > 0) {
+          tiers.push({
+            label: 'Current Session',
+            results: [{
+              content: `Active sessions: ${stats.activeSessions}, items tracked: ${stats.totalItems}`,
+              score: 0.95,
+              source: 'Session Tracker',
+              metadata: {}
+            }]
+          })
+        }
+      }
+    } catch {
+      // Session tracker not available
+    }
+  }
+
+  // Bug 4: Inject recently stored decisions using keyword overlap as score
+  const recentMatches = findRecentDecisions(ctx, query, searchProject)
+  // Only include results whose overlap score meets the hard floor (0.35)
+  const qualifiedRecent = recentMatches.filter(d => (d.overlapScore || 0) >= 0.35)
+  if (qualifiedRecent.length > 0) {
+    tiers.unshift({
+      label: 'Recent Decisions',
+      results: qualifiedRecent.map(d => ({
+        content: d.content,
+        score: d.overlapScore || 0,
+        source: 'Recent Decision',
+        metadata: { storedAt: d.storedAt, project: d.project }
+      }))
+    })
+  }
+
+  // Register with episode
+  registerEpisodeMessage(ctx, message, displayProject, 'question')
+
+  // Phase 27: Use compact format for progressive disclosure
+  // Combine all tier results, filter, then format compactly
+  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
+    }
+  }
+
+  const responseFilter = new ResponseFilter()
+  const filtered = responseFilter.filter(allResults, message, displayProject)
+  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
+    }
+  }
+
+  const compactContent = formatCompactResponse(filtered, message)
+  return {
+    action: 'retrieved',
+    summary: `Found ${filtered.length} result${filtered.length === 1 ? '' : 's'}`,
+    content: compactContent,
+    relevantItems: filtered.length
+  }
+}
+
+/**
+ * Phase 27: Handle detail requests — "details obs_abc123", "expand <id>"
+ * Looks up a single observation by ID and returns full detail view.
+ */
+export async function handleDetailRequest(
+  _ctx: HandlerContext,
+  message: string,
+  _project: string | undefined,
+  _entities: BrainExtractedEntities
+): Promise<BrainResponse> {
+  if (!isServicesInitialized()) {
+    return servicesNotReady()
+  }
+
+  // Extract ID from message using regex
+  const idMatch = message.match(/\b(obs_\w+|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{8,})\b/i)
+  if (!idMatch) {
+    return {
+      action: 'none',
+      summary: 'No observation ID provided',
+      content: 'Please provide an observation ID. Use brain("details {ID}") with an ID from search results.',
+      relevantItems: 0
+    }
+  }
+
+  const id = idMatch[1]!
+  const observation = await lookupById(id)
+
+  if (!observation) {
+    return {
+      action: 'none',
+      summary: `No observation found: ${id}`,
+      content: `No observation found with ID: ${id}`,
+      relevantItems: 0
+    }
+  }
+
+  // Increment access count
+  incrementAccess(id)
+
+  return {
+    action: 'retrieved',
+    summary: `Details for ${id.slice(0, 12)}...`,
+    content: formatDetailResponse(observation),
+    relevantItems: 1
+  }
+}
+
+/**
+ * BUG-002: Handle category-scoped queries by fetching all items of that category.
+ */
+async function handleCategoryQuery(
+  _message: string,
+  project: string | undefined,
+  category: 'decision' | 'pattern' | 'correction'
+): Promise<BrainResponse> {
+  const memory = getMemoryService()
+  const projectLabel = project || 'all projects'
+
+  let items: Record<string, unknown>[]
+  switch (category) {
+    case 'decision':
+      items = await memory.fetchAllDecisions(project) as Record<string, unknown>[]
+      break
+    case 'pattern':
+      items = await memory.fetchAllPatterns(project) as Record<string, unknown>[]
+      break
+    case 'correction':
+      items = await memory.fetchAllCorrections(project) as Record<string, unknown>[]
+      break
+  }
+
+  if (items.length === 0) {
+    return {
+      action: 'none',
+      summary: `No ${category}s found`,
+      content: `No ${category}s found for ${projectLabel}.`,
+      relevantItems: 0
+    }
+  }
+
+  // Format as compact items
+  const allItems = items.map(item => ({
+    id: item.id || item.decision_id,
+    content: typeof (item.decision || item.description || item.correction || item.original || item.document || item.content) === 'string'
+      ? (item.decision || item.description || item.correction || item.original || item.document || item.content)
+      : JSON.stringify(item.decision || item.description || item.correction || item.original || item.document || item.content || ''),
+    category,
+    project: item.project || project || 'general',
+    created_at: item.created_at || item.date || '',
+  }))
+
+  const compactContent = formatCompactResponse(allItems, `${category}s for ${projectLabel}`)
+  return {
+    action: 'retrieved',
+    summary: `${items.length} ${category}s for ${projectLabel}`,
+    content: compactContent,
+    relevantItems: items.length
+  }
+}