claude-brain 0.15.2 → 0.16.0

package/src/memory/context-builder.ts

@@ -1,236 +1,236 @@
-/**
- * Memory Context Builder
- * Phase 3: Memory and Embedding System
- *
- * Formats retrieved memories for Claude Code consumption
- * with token budget management
- */
-
-import type { Logger } from 'pino'
-import type { MemorySearchResult } from './types'
-
-export interface ContextOptions {
-  maxTokens?: number
-  includeMetadata?: boolean
-  format?: 'detailed' | 'concise' | 'summary'
-}
-
-export class MemoryContextBuilder {
-  private logger: Logger
-
-  constructor(logger: Logger) {
-    this.logger = logger.child({ component: 'memory-context-builder' })
-  }
-
-  /**
-   * Build formatted context from search results
-   */
-  buildContext(results: MemorySearchResult[], options: ContextOptions = {}): string {
-    if (results.length === 0) {
-      return 'No relevant memories found.'
-    }
-
-    const format = options.format || 'detailed'
-    const includeMetadata = options.includeMetadata ?? true
-
-    let context = `## Relevant Past Context (${results.length} items)\n\n`
-
-    for (let i = 0; i < results.length; i++) {
-      const result = results[i]!
-      const index = i + 1
-
-      if (format === 'detailed') {
-        context += this.formatDetailed(result, index, includeMetadata)
-      } else if (format === 'concise') {
-        context += this.formatConcise(result, index)
-      } else {
-        context += this.formatSummary(result, index)
-      }
-
-      context += '\n'
-    }
-
-    // Estimate token count (rough: 1 token ~ 4 characters)
-    const estimatedTokens = Math.ceil(context.length / 4)
-
-    if (options.maxTokens && estimatedTokens > options.maxTokens) {
-      this.logger.warn(
-        { estimatedTokens, maxTokens: options.maxTokens },
-        'Context exceeds token budget, truncating'
-      )
-
-      // Truncate context
-      const maxChars = options.maxTokens * 4
-      context = context.slice(0, maxChars) + '\n\n[Context truncated due to length]'
-    }
-
-    return context
-  }
-
-  /**
-   * Format detailed context entry
-   */
-  private formatDetailed(
-    result: MemorySearchResult,
-    index: number,
-    includeMetadata: boolean
-  ): string {
-    let text = `### ${index}. `
-
-    if (result.decision) {
-      text += `Decision (Similarity: ${(result.similarity * 100).toFixed(1)}%)\n\n`
-      text += `**Context:** ${result.decision.context}\n\n`
-      text += `**Decision:** ${result.decision.decision}\n\n`
-      text += `**Reasoning:** ${result.decision.reasoning}\n\n`
-
-      if (result.decision.alternatives) {
-        text += `**Alternatives Considered:** ${result.decision.alternatives}\n\n`
-      }
-
-      if (result.decision.outcome) {
-        text += `**Outcome:** ${result.decision.outcome}\n\n`
-      }
-
-      if (includeMetadata && result.decision.tags) {
-        const tags = Array.isArray(result.decision.tags) 
-          ? result.decision.tags.join(', ')
-          : result.decision.tags
-        text += `**Tags:** ${tags}\n\n`
-      }
-    } else {
-      text += `Memory (Similarity: ${(result.similarity * 100).toFixed(1)}%)\n\n`
-      text += result.memory.content + '\n\n'
-    }
-
-    if (includeMetadata) {
-      text += `*Project: ${result.memory.project}, Created: ${result.memory.createdAt.toLocaleDateString()}*\n\n`
-    }
-
-    return text
-  }
-
-  /**
-   * Format concise context entry
-   */
-  private formatConcise(result: MemorySearchResult, index: number): string {
-    if (result.decision) {
-      const contextPreview = result.decision.context.slice(0, 100)
-      return (
-        `${index}. **${result.decision.decision}** (${(result.similarity * 100).toFixed(0)}% match)\n` +
-        `   Context: ${contextPreview}${result.decision.context.length > 100 ? '...' : ''}\n\n`
-      )
-    } else {
-      const preview = result.memory.content.slice(0, 150)
-      return `${index}. ${preview}${result.memory.content.length > 150 ? '...' : ''} (${(result.similarity * 100).toFixed(0)}% match)\n\n`
-    }
-  }
-
-  /**
-   * Format summary context entry
-   */
-  private formatSummary(result: MemorySearchResult, index: number): string {
-    if (result.decision) {
-      return `${index}. ${result.decision.decision} (${result.memory.project})\n`
-    } else {
-      return `${index}. ${result.memory.content.slice(0, 80)}... (${result.memory.project})\n`
-    }
-  }
-
-  /**
-   * Build context for decision recall
-   */
-  buildDecisionContext(results: MemorySearchResult[]): string {
-    const decisions = results.filter((r) => r.decision)
-
-    if (decisions.length === 0) {
-      return 'No similar past decisions found.'
-    }
-
-    return this.buildContext(decisions, {
-      format: 'detailed',
-      includeMetadata: true,
-      maxTokens: 2000
-    })
-  }
-
-  /**
-   * Build context for recommendations
-   */
-  buildRecommendationContext(results: MemorySearchResult[]): string {
-    if (results.length === 0) {
-      return 'No recommendations available based on past context.'
-    }
-
-    let context = `## Recommendations Based on Past Experience\n\n`
-    context += `Found ${results.length} relevant past experiences:\n\n`
-
-    context += this.buildContext(results, {
-      format: 'concise',
-      includeMetadata: false,
-      maxTokens: 1000
-    })
-
-    return context
-  }
-
-  /**
-   * Build context for a single decision
-   */
-  buildSingleDecisionContext(result: MemorySearchResult): string {
-    if (!result.decision) {
-      return 'No decision data available.'
-    }
-
-    let context = `## Related Decision\n\n`
-    context += `**Context:** ${result.decision.context}\n\n`
-    context += `**Decision Made:** ${result.decision.decision}\n\n`
-    context += `**Reasoning:** ${result.decision.reasoning}\n\n`
-
-    if (result.decision.alternatives) {
-      context += `**Alternatives Considered:** ${result.decision.alternatives}\n\n`
-    }
-
-    if (result.decision.outcome) {
-      context += `**Outcome:** ${result.decision.outcome}\n\n`
-    }
-
-    context += `---\n`
-    context += `*Similarity: ${(result.similarity * 100).toFixed(1)}% | `
-    context += `Project: ${result.memory.project} | `
-    context += `Date: ${result.memory.createdAt.toLocaleDateString()}*\n`
-
-    return context
-  }
-
-  /**
-   * Estimate token count for text
-   */
-  estimateTokens(text: string): number {
-    // Rough estimate: 1 token ~ 4 characters
-    return Math.ceil(text.length / 4)
-  }
-
-  /**
-   * Truncate text to fit within token budget
-   */
-  truncateToTokens(text: string, maxTokens: number): string {
-    const maxChars = maxTokens * 4
-    if (text.length <= maxChars) {
-      return text
-    }
-    return text.slice(0, maxChars - 20) + '\n\n[Truncated]'
-  }
-
-  /**
-   * Combine multiple contexts with a separator
-   */
-  combineContexts(contexts: string[], maxTokens?: number): string {
-    const combined = contexts.join('\n---\n\n')
-
-    if (maxTokens) {
-      return this.truncateToTokens(combined, maxTokens)
-    }
-
-    return combined
-  }
-}
+/**
+ * Memory Context Builder
+ * Phase 3: Memory and Embedding System
+ *
+ * Formats retrieved memories for Claude Code consumption
+ * with token budget management
+ */
+
+import type { Logger } from 'pino'
+import type { MemorySearchResult } from './types'
+
+export interface ContextOptions {
+  maxTokens?: number
+  includeMetadata?: boolean
+  format?: 'detailed' | 'concise' | 'summary'
+}
+
+export class MemoryContextBuilder {
+  private logger: Logger
+
+  constructor(logger: Logger) {
+    this.logger = logger.child({ component: 'memory-context-builder' })
+  }
+
+  /**
+   * Build formatted context from search results
+   */
+  buildContext(results: MemorySearchResult[], options: ContextOptions = {}): string {
+    if (results.length === 0) {
+      return 'No relevant memories found.'
+    }
+
+    const format = options.format || 'detailed'
+    const includeMetadata = options.includeMetadata ?? true
+
+    let context = `## Relevant Past Context (${results.length} items)\n\n`
+
+    for (let i = 0; i < results.length; i++) {
+      const result = results[i]!
+      const index = i + 1
+
+      if (format === 'detailed') {
+        context += this.formatDetailed(result, index, includeMetadata)
+      } else if (format === 'concise') {
+        context += this.formatConcise(result, index)
+      } else {
+        context += this.formatSummary(result, index)
+      }
+
+      context += '\n'
+    }
+
+    // Estimate token count (rough: 1 token ~ 4 characters)
+    const estimatedTokens = Math.ceil(context.length / 4)
+
+    if (options.maxTokens && estimatedTokens > options.maxTokens) {
+      this.logger.warn(
+        { estimatedTokens, maxTokens: options.maxTokens },
+        'Context exceeds token budget, truncating'
+      )
+
+      // Truncate context
+      const maxChars = options.maxTokens * 4
+      context = context.slice(0, maxChars) + '\n\n[Context truncated due to length]'
+    }
+
+    return context
+  }
+
+  /**
+   * Format detailed context entry
+   */
+  private formatDetailed(
+    result: MemorySearchResult,
+    index: number,
+    includeMetadata: boolean
+  ): string {
+    let text = `### ${index}. `
+
+    if (result.decision) {
+      text += `Decision (Similarity: ${(result.similarity * 100).toFixed(1)}%)\n\n`
+      text += `**Context:** ${result.decision.context}\n\n`
+      text += `**Decision:** ${result.decision.decision}\n\n`
+      text += `**Reasoning:** ${result.decision.reasoning}\n\n`
+
+      if (result.decision.alternatives) {
+        text += `**Alternatives Considered:** ${result.decision.alternatives}\n\n`
+      }
+
+      if (result.decision.outcome) {
+        text += `**Outcome:** ${result.decision.outcome}\n\n`
+      }
+
+      if (includeMetadata && result.decision.tags) {
+        const tags = Array.isArray(result.decision.tags) 
+          ? result.decision.tags.join(', ')
+          : result.decision.tags
+        text += `**Tags:** ${tags}\n\n`
+      }
+    } else {
+      text += `Memory (Similarity: ${(result.similarity * 100).toFixed(1)}%)\n\n`
+      text += result.memory.content + '\n\n'
+    }
+
+    if (includeMetadata) {
+      text += `*Project: ${result.memory.project}, Created: ${result.memory.createdAt.toLocaleDateString()}*\n\n`
+    }
+
+    return text
+  }
+
+  /**
+   * Format concise context entry
+   */
+  private formatConcise(result: MemorySearchResult, index: number): string {
+    if (result.decision) {
+      const contextPreview = result.decision.context.slice(0, 100)
+      return (
+        `${index}. **${result.decision.decision}** (${(result.similarity * 100).toFixed(0)}% match)\n` +
+        `   Context: ${contextPreview}${result.decision.context.length > 100 ? '...' : ''}\n\n`
+      )
+    } else {
+      const preview = result.memory.content.slice(0, 150)
+      return `${index}. ${preview}${result.memory.content.length > 150 ? '...' : ''} (${(result.similarity * 100).toFixed(0)}% match)\n\n`
+    }
+  }
+
+  /**
+   * Format summary context entry
+   */
+  private formatSummary(result: MemorySearchResult, index: number): string {
+    if (result.decision) {
+      return `${index}. ${result.decision.decision} (${result.memory.project})\n`
+    } else {
+      return `${index}. ${result.memory.content.slice(0, 80)}... (${result.memory.project})\n`
+    }
+  }
+
+  /**
+   * Build context for decision recall
+   */
+  buildDecisionContext(results: MemorySearchResult[]): string {
+    const decisions = results.filter((r) => r.decision)
+
+    if (decisions.length === 0) {
+      return 'No similar past decisions found.'
+    }
+
+    return this.buildContext(decisions, {
+      format: 'detailed',
+      includeMetadata: true,
+      maxTokens: 2000
+    })
+  }
+
+  /**
+   * Build context for recommendations
+   */
+  buildRecommendationContext(results: MemorySearchResult[]): string {
+    if (results.length === 0) {
+      return 'No recommendations available based on past context.'
+    }
+
+    let context = `## Recommendations Based on Past Experience\n\n`
+    context += `Found ${results.length} relevant past experiences:\n\n`
+
+    context += this.buildContext(results, {
+      format: 'concise',
+      includeMetadata: false,
+      maxTokens: 1000
+    })
+
+    return context
+  }
+
+  /**
+   * Build context for a single decision
+   */
+  buildSingleDecisionContext(result: MemorySearchResult): string {
+    if (!result.decision) {
+      return 'No decision data available.'
+    }
+
+    let context = `## Related Decision\n\n`
+    context += `**Context:** ${result.decision.context}\n\n`
+    context += `**Decision Made:** ${result.decision.decision}\n\n`
+    context += `**Reasoning:** ${result.decision.reasoning}\n\n`
+
+    if (result.decision.alternatives) {
+      context += `**Alternatives Considered:** ${result.decision.alternatives}\n\n`
+    }
+
+    if (result.decision.outcome) {
+      context += `**Outcome:** ${result.decision.outcome}\n\n`
+    }
+
+    context += `---\n`
+    context += `*Similarity: ${(result.similarity * 100).toFixed(1)}% | `
+    context += `Project: ${result.memory.project} | `
+    context += `Date: ${result.memory.createdAt.toLocaleDateString()}*\n`
+
+    return context
+  }
+
+  /**
+   * Estimate token count for text
+   */
+  estimateTokens(text: string): number {
+    // Rough estimate: 1 token ~ 4 characters
+    return Math.ceil(text.length / 4)
+  }
+
+  /**
+   * Truncate text to fit within token budget
+   */
+  truncateToTokens(text: string, maxTokens: number): string {
+    const maxChars = maxTokens * 4
+    if (text.length <= maxChars) {
+      return text
+    }
+    return text.slice(0, maxChars - 20) + '\n\n[Truncated]'
+  }
+
+  /**
+   * Combine multiple contexts with a separator
+   */
+  combineContexts(contexts: string[], maxTokens?: number): string {
+    const combined = contexts.join('\n---\n\n')
+
+    if (maxTokens) {
+      return this.truncateToTokens(combined, maxTokens)
+    }
+
+    return combined
+  }
+}