claude-brain 0.30.2 → 0.30.3

package/src/routing/response-filter.ts

@@ -1,391 +1,399 @@
-/**
- * Brain Response Filter
- * Phase 16 + Phase 19: Filters noise, deduplicates, ranks, and synthesizes results
- *
- * Phase 19 changes:
- * - D2: Lower word overlap threshold 0.85 → 0.75, add ID-based and prefix-based dedup
- * - D3: Split INFRA_NOISE into strong (1 hit = filter) and weak (2+ hits = filter)
- */
-
-export interface FilterableResult {
-  content: string
-  score: number
-  source: string
-  metadata?: Record<string, unknown>
-}
-
-export interface FilteredResult {
-  id?: string
-  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 {
-  // D3: Strong noise — 1 hit is enough to filter (very specific internal terms)
-  private readonly STRONG_NOISE = [
-    'mcp-server', 'model-context-protocol', 'embedding-service', 'vector-database',
-    'mcp tool', 'tool handler', 'precompute engine', 'knowledge graph builder',
-    'semantic cache', 'bun:test'
-  ]
-
-  // D3: Weak noise — need 2+ hits to filter (terms that could appear in legitimate decisions)
-  private readonly WEAK_NOISE = [
-    'chromadb', 'minisearch', 'compromise', 'better-sqlite3',
-    'pino', 'hono', 'zod', 'claude-brain',
-    'phase 12', 'phase 13', 'phase 14', 'phase 15', 'phase 16',
-    'phase 17', 'phase 18', 'phase 19'
-  ]
-
-  /**
-   * 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') {
-      const queryLower = query.toLowerCase()
-      filtered = filtered.filter(r => !this.isInfrastructureNoise(r.content, queryLower))
-    }
-
-    // 2. Remove near-duplicates (Phase 19 D2: improved dedup)
-    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 (preserve id from metadata)
-    return filtered.map(r => ({
-      id: (r.metadata as any)?.id || (r.metadata as any)?.decision_id,
-      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)}%]` : ''
-      // Defensive: ensure content is always a string (prevents [object Object])
-      const contentStr = typeof result.content === 'string'
-        ? result.content
-        : JSON.stringify(result.content ?? '')
-      contentParts.push(`**${result.source}**${scoreStr}\n${contentStr}`)
-      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
-    }
-  }
-
-  /**
-   * D3: Check if content is infrastructure/internal noise
-   * Strong noise: 1 hit filters (unless the term appears in the query)
-   * Weak noise: 2+ hits filters (skipping terms that appear in the query)
-   */
-  private isInfrastructureNoise(content: string, queryLower?: string): boolean {
-    const lower = content.toLowerCase()
-
-    // Strong noise: a single hit is enough (but skip terms the user asked about)
-    for (const term of this.STRONG_NOISE) {
-      if (queryLower && queryLower.includes(term)) continue
-      if (lower.includes(term)) {
-        return true
-      }
-    }
-
-    // Weak noise: need 2+ hits (skip terms the user asked about)
-    let weakHits = 0
-    for (const term of this.WEAK_NOISE) {
-      if (queryLower && queryLower.includes(term)) continue
-      if (lower.includes(term)) {
-        weakHits++
-      }
-    }
-    return weakHits >= 2
-  }
-
-  /**
-   * D2: Improved deduplication
-   * - ID-based dedup (if metadata has an ID)
-   * - Prefix-based dedup (first 100 chars match)
-   * - Word overlap dedup (lowered from 0.85 to 0.75)
-   */
-  private deduplicateResults(results: FilterableResult[]): FilterableResult[] {
-    const kept: FilterableResult[] = []
-    const seenIds = new Set<string>()
-    const seenPrefixes = new Set<string>()
-
-    for (const result of results) {
-      // ID-based dedup
-      const id = (result.metadata as any)?.id || (result.metadata as any)?.decision_id
-      if (id && seenIds.has(id)) continue
-      if (id) seenIds.add(id)
-
-      // Prefix-based dedup (first 100 chars, normalized)
-      const prefix = result.content.slice(0, 100).toLowerCase().replace(/\s+/g, ' ').trim()
-      if (prefix.length > 20 && seenPrefixes.has(prefix)) continue
-      if (prefix.length > 20) seenPrefixes.add(prefix)
-
-      // Word overlap dedup (D2: lowered to 0.75)
-      const isDuplicate = kept.some(existing => {
-        const overlap = this.calculateWordOverlap(existing.content, result.content)
-        return overlap > 0.75
-      })
-
-      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 = Math.max(median * 0.7, 0.45)
-
-    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}%)`
-  }
-}
-
-// =============================================================================
-// Phase 27: Progressive Disclosure — Compact Response Formatters
-// =============================================================================
-
-/**
- * Truncate text to maxLen chars, appending "..." if truncated
- */
-function truncate(text: string, maxLen: number): string {
-  if (!text) return ''
-  if (text.length <= maxLen) return text
-  return text.substring(0, maxLen).trimEnd() + '...'
-}
-
-/**
- * Format a date as a human-readable relative time string
- */
-function formatRelativeTime(dateStr: string | Date | undefined): string {
-  if (!dateStr) return 'unknown'
-  const date = typeof dateStr === 'string' ? new Date(dateStr) : dateStr
-  if (isNaN(date.getTime())) return 'unknown'
-  const now = new Date()
-  const diffMs = now.getTime() - date.getTime()
-  const diffMins = Math.floor(diffMs / 60000)
-  const diffHours = Math.floor(diffMs / 3600000)
-  const diffDays = Math.floor(diffMs / 86400000)
-
-  if (diffMins < 1) return 'just now'
-  if (diffMins < 60) return `${diffMins} minute${diffMins === 1 ? '' : 's'} ago`
-  if (diffHours < 24) return `${diffHours} hour${diffHours === 1 ? '' : 's'} ago`
-  if (diffDays === 1) return 'yesterday'
-  if (diffDays < 7) return `${diffDays} days ago`
-  if (diffDays < 30) return `${Math.floor(diffDays / 7)} week${Math.floor(diffDays / 7) === 1 ? '' : 's'} ago`
-  return `${Math.floor(diffDays / 30)} month${Math.floor(diffDays / 30) === 1 ? '' : 's'} ago`
-}
-
-/**
- * Layer 1: Format a single result as a compact one-liner with metadata
- */
-export function formatCompactResult(result: any, index: number): string {
-  const meta = result.metadata || {}
-  const category = result.category || result.type || meta.category || result.source || 'memory'
-  const summary = truncate(result.content || result.text || result.decision || '', 80)
-  const project = result.project || meta.project || 'general'
-  const timeAgo = formatRelativeTime(
-    result.createdAt || result.created_at || result.timestamp ||
-    result.date || meta.created_at || meta.createdAt || meta.date
-  )
-  const id = result.id || meta.id || meta.decision_id || 'unknown'
-
-  return `${index}. [${category}] ${summary}\n   Project: ${project} | ${timeAgo}\n   ID: ${id}`
-}
-
-/**
- * Layer 1: Full compact response with header, compact items, and footer
- */
-export function formatCompactResponse(results: any[], query: string): string {
-  if (results.length === 0) {
-    return `No memories found for "${query}".`
-  }
-
-  const header = `Found ${results.length} relevant ${results.length === 1 ? 'memory' : 'memories'} for "${query}":`
-  const items = results.map((r, i) => formatCompactResult(r, i + 1)).join('\n\n')
-  const footer = `\nUse brain("details {ID}") for full context.`
-
-  return header + '\n\n' + items + footer
-}
-
-/**
- * Layer 2: Full detail view for a single observation/memory
- */
-export function formatDetailResponse(observation: any): string {
-  const category = observation.category || observation.type || 'Memory'
-  const content = observation.content || observation.text || observation.decision || ''
-  const context = observation.context || observation.metadata?.context || ''
-  const reasoning = observation.reasoning || observation.metadata?.reasoning || ''
-  const tags = observation.tags || observation.metadata?.tags || []
-  const created = observation.createdAt || observation.created_at || observation.timestamp || ''
-
-  const lines: string[] = []
-  lines.push(`${category.charAt(0).toUpperCase() + category.slice(1)}: ${content}`)
-  if (context) lines.push(`\nContext: ${context}`)
-  if (reasoning) lines.push(`Reasoning: ${reasoning}`)
-  if (tags.length > 0) lines.push(`Tags: ${Array.isArray(tags) ? tags.join(', ') : tags}`)
-  if (created) lines.push(`Created: ${created}`)
-
-  return lines.join('\n')
-}
-
-/**
- * Layer 3: Group observations by day for timeline view
- */
-export function groupByDay(observations: any[]): Map<string, any[]> {
-  const groups = new Map<string, any[]>()
-  for (const obs of observations) {
-    const date = new Date(obs.createdAt || obs.created_at || obs.timestamp || Date.now())
-    const dayKey = isNaN(date.getTime())
-      ? 'Unknown'
-      : date.toLocaleDateString('en-US', { month: 'short', day: 'numeric' })
-    if (!groups.has(dayKey)) groups.set(dayKey, [])
-    groups.get(dayKey)!.push(obs)
-  }
-  return groups
-}
-
-/**
- * Layer 3: Format a timeline from day-grouped observations
- */
-export function formatTimeline(grouped: Map<string, any[]>, project?: string): string {
-  if (grouped.size === 0) {
-    return project ? `No activity found for "${project}".` : 'No recent activity found.'
-  }
-
-  const header = project ? `Timeline for ${project}:` : 'Recent timeline:'
-  const sections: string[] = [header, '']
-
-  for (const [day, observations] of grouped) {
-    sections.push(`${day}:`)
-    for (const obs of observations) {
-      const category = obs.category || obs.type || 'memory'
-      const summary = truncate(obs.content || obs.text || obs.decision || '', 60)
-      sections.push(`  - [${category}] ${summary}`)
-    }
-    sections.push('')
-  }
-
-  return sections.join('\n').trim()
-}
+/**
+ * Brain Response Filter
+ * Phase 16 + Phase 19: Filters noise, deduplicates, ranks, and synthesizes results
+ *
+ * Phase 19 changes:
+ * - D2: Lower word overlap threshold 0.85 → 0.75, add ID-based and prefix-based dedup
+ * - D3: Split INFRA_NOISE into strong (1 hit = filter) and weak (2+ hits = filter)
+ */
+
+export interface FilterableResult {
+  content: string
+  score: number
+  source: string
+  metadata?: Record<string, unknown>
+}
+
+export interface FilteredResult {
+  id?: string
+  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 {
+  // D3: Strong noise — 1 hit is enough to filter (very specific internal terms)
+  private readonly STRONG_NOISE = [
+    'mcp-server', 'model-context-protocol', 'embedding-service', 'vector-database',
+    'mcp tool', 'tool handler', 'precompute engine', 'knowledge graph builder',
+    'semantic cache', 'bun:test'
+  ]
+
+  // D3: Weak noise — need 2+ hits to filter (terms that could appear in legitimate decisions)
+  private readonly WEAK_NOISE = [
+    'chromadb', 'minisearch', 'compromise', 'better-sqlite3',
+    'pino', 'claude-brain',
+    'phase 12', 'phase 13', 'phase 14', 'phase 15', 'phase 16',
+    'phase 17', 'phase 18', 'phase 19'
+  ]
+
+  /**
+   * 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') {
+      const queryLower = query.toLowerCase()
+      filtered = filtered.filter(r => !this.isInfrastructureNoise(r.content, queryLower))
+    }
+
+    // 2. Remove near-duplicates (Phase 19 D2: improved dedup)
+    filtered = this.deduplicateResults(filtered)
+
+    // 3. Apply dynamic threshold (at least 70% of median similarity)
+    const preThreshold = filtered
+    filtered = this.applyDynamicThreshold(filtered)
+
+    // Safety valve: if threshold killed everything but we had results, keep the best one
+    if (filtered.length === 0 && preThreshold.length > 0) {
+      const best = preThreshold.reduce((a, b) => a.score > b.score ? a : b)
+      filtered = [best]
+    }
+
+    // 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 (preserve id from metadata)
+    return filtered.map(r => ({
+      id: (r.metadata as Record<string, unknown> | undefined)?.id as string | undefined || (r.metadata as Record<string, unknown> | undefined)?.decision_id as string | undefined,
+      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)}%]` : ''
+      // Defensive: ensure content is always a string (prevents [object Object])
+      const contentStr = typeof result.content === 'string'
+        ? result.content
+        : JSON.stringify(result.content ?? '')
+      contentParts.push(`**${result.source}**${scoreStr}\n${contentStr}`)
+      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
+    }
+  }
+
+  /**
+   * D3: Check if content is infrastructure/internal noise
+   * Strong noise: 1 hit filters (unless the term appears in the query)
+   * Weak noise: 2+ hits filters (skipping terms that appear in the query)
+   */
+  private isInfrastructureNoise(content: string, queryLower?: string): boolean {
+    const lower = content.toLowerCase()
+
+    // Strong noise: a single hit is enough (but skip terms the user asked about)
+    for (const term of this.STRONG_NOISE) {
+      if (queryLower && queryLower.includes(term)) continue
+      if (lower.includes(term)) {
+        return true
+      }
+    }
+
+    // Weak noise: need 2+ hits (skip terms the user asked about)
+    let weakHits = 0
+    for (const term of this.WEAK_NOISE) {
+      if (queryLower && queryLower.includes(term)) continue
+      if (lower.includes(term)) {
+        weakHits++
+      }
+    }
+    return weakHits >= 2
+  }
+
+  /**
+   * D2: Improved deduplication
+   * - ID-based dedup (if metadata has an ID)
+   * - Prefix-based dedup (first 100 chars match)
+   * - Word overlap dedup (lowered from 0.85 to 0.75)
+   */
+  private deduplicateResults(results: FilterableResult[]): FilterableResult[] {
+    const kept: FilterableResult[] = []
+    const seenIds = new Set<string>()
+    const seenPrefixes = new Set<string>()
+
+    for (const result of results) {
+      // ID-based dedup
+      const id = (result.metadata as Record<string, unknown> | undefined)?.id as string | undefined || (result.metadata as Record<string, unknown> | undefined)?.decision_id as string | undefined
+      if (id && seenIds.has(id)) continue
+      if (id) seenIds.add(id)
+
+      // Prefix-based dedup (first 100 chars, normalized)
+      const prefix = result.content.slice(0, 100).toLowerCase().replace(/\s+/g, ' ').trim()
+      if (prefix.length > 20 && seenPrefixes.has(prefix)) continue
+      if (prefix.length > 20) seenPrefixes.add(prefix)
+
+      // Word overlap dedup (D2: lowered to 0.75)
+      const isDuplicate = kept.some(existing => {
+        const overlap = this.calculateWordOverlap(existing.content, result.content)
+        return overlap > 0.75
+      })
+
+      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 = Math.max(median * 0.7, 0.25)
+
+    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}%)`
+  }
+}
+
+// =============================================================================
+// Phase 27: Progressive Disclosure — Compact Response Formatters
+// =============================================================================
+
+/**
+ * Truncate text to maxLen chars, appending "..." if truncated
+ */
+function truncate(text: string, maxLen: number): string {
+  if (!text) return ''
+  if (text.length <= maxLen) return text
+  return text.substring(0, maxLen).trimEnd() + '...'
+}
+
+/**
+ * Format a date as a human-readable relative time string
+ */
+function formatRelativeTime(dateStr: string | Date | undefined): string {
+  if (!dateStr) return 'unknown'
+  const date = typeof dateStr === 'string' ? new Date(dateStr) : dateStr
+  if (isNaN(date.getTime())) return 'unknown'
+  const now = new Date()
+  const diffMs = now.getTime() - date.getTime()
+  const diffMins = Math.floor(diffMs / 60000)
+  const diffHours = Math.floor(diffMs / 3600000)
+  const diffDays = Math.floor(diffMs / 86400000)
+
+  if (diffMins < 1) return 'just now'
+  if (diffMins < 60) return `${diffMins} minute${diffMins === 1 ? '' : 's'} ago`
+  if (diffHours < 24) return `${diffHours} hour${diffHours === 1 ? '' : 's'} ago`
+  if (diffDays === 1) return 'yesterday'
+  if (diffDays < 7) return `${diffDays} days ago`
+  if (diffDays < 30) return `${Math.floor(diffDays / 7)} week${Math.floor(diffDays / 7) === 1 ? '' : 's'} ago`
+  return `${Math.floor(diffDays / 30)} month${Math.floor(diffDays / 30) === 1 ? '' : 's'} ago`
+}
+
+/**
+ * Layer 1: Format a single result as a compact one-liner with metadata
+ */
+export function formatCompactResult(result: Record<string, unknown>, index: number): string {
+  const meta = (result.metadata || {}) as Record<string, unknown>
+  const category = result.category || result.type || meta.category || result.source || 'memory'
+  const summary = truncate(String(result.content || result.text || result.decision || ''), 80)
+  const project = result.project || meta.project || 'general'
+  const timeAgo = formatRelativeTime(
+    (result.createdAt || result.created_at || result.timestamp ||
+    result.date || meta.created_at || meta.createdAt || meta.date) as string | Date | undefined
+  )
+  const id = result.id || meta.id || meta.decision_id || 'unknown'
+
+  return `${index}. [${category}] ${summary}\n   Project: ${project} | ${timeAgo}\n   ID: ${id}`
+}
+
+/**
+ * Layer 1: Full compact response with header, compact items, and footer
+ */
+export function formatCompactResponse(results: Record<string, unknown>[], query: string): string {
+  if (results.length === 0) {
+    return `No memories found for "${query}".`
+  }
+
+  const header = `Found ${results.length} relevant ${results.length === 1 ? 'memory' : 'memories'} for "${query}":`
+  const items = results.map((r, i) => formatCompactResult(r, i + 1)).join('\n\n')
+  const footer = `\nUse brain("details {ID}") for full context.`
+
+  return header + '\n\n' + items + footer
+}
+
+/**
+ * Layer 2: Full detail view for a single observation/memory
+ */
+export function formatDetailResponse(observation: Record<string, unknown>): string {
+  const meta = (observation.metadata || {}) as Record<string, unknown>
+  const category = String(observation.category || observation.type || 'Memory')
+  const content = String(observation.content || observation.text || observation.decision || '')
+  const context = String(observation.context || meta.context || '')
+  const reasoning = String(observation.reasoning || meta.reasoning || '')
+  const tags = (observation.tags || meta.tags || []) as unknown
+  const created = String(observation.createdAt || observation.created_at || observation.timestamp || '')
+
+  const lines: string[] = []
+  lines.push(`${category.charAt(0).toUpperCase() + category.slice(1)}: ${content}`)
+  if (context) lines.push(`\nContext: ${context}`)
+  if (reasoning) lines.push(`Reasoning: ${reasoning}`)
+  if (tags.length > 0) lines.push(`Tags: ${Array.isArray(tags) ? tags.join(', ') : tags}`)
+  if (created) lines.push(`Created: ${created}`)
+
+  return lines.join('\n')
+}
+
+/**
+ * Layer 3: Group observations by day for timeline view
+ */
+export function groupByDay(observations: Record<string, unknown>[]): Map<string, Record<string, unknown>[]> {
+  const groups = new Map<string, Record<string, unknown>[]>()
+  for (const obs of observations) {
+    const date = new Date((obs.createdAt || obs.created_at || obs.timestamp || Date.now()) as string | number)
+    const dayKey = isNaN(date.getTime())
+      ? 'Unknown'
+      : date.toLocaleDateString('en-US', { month: 'short', day: 'numeric' })
+    if (!groups.has(dayKey)) groups.set(dayKey, [])
+    groups.get(dayKey)!.push(obs)
+  }
+  return groups
+}
+
+/**
+ * Layer 3: Format a timeline from day-grouped observations
+ */
+export function formatTimeline(grouped: Map<string, Record<string, unknown>[]>, project?: string): string {
+  if (grouped.size === 0) {
+    return project ? `No activity found for "${project}".` : 'No recent activity found.'
+  }
+
+  const header = project ? `Timeline for ${project}:` : 'Recent timeline:'
+  const sections: string[] = [header, '']
+
+  for (const [day, observations] of grouped) {
+    sections.push(`${day}:`)
+    for (const obs of observations) {
+      const category = obs.category || obs.type || 'memory'
+      const summary = truncate(String(obs.content || obs.text || obs.decision || ''), 60)
+      sections.push(`  - [${category}] ${summary}`)
+    }
+    sections.push('')
+  }
+
+  return sections.join('\n').trim()
+}