claude-brain 0.4.0 → 0.5.0

package/src/server/handlers/tools/get-decision-timeline.ts

@@ -24,11 +24,6 @@ export async function handleGetDecisionTimeline(
     const { project_name, topic, time_range, limit } = input
 
     const memory = getMemoryService()
-    const timelineBuilder = new TimelineBuilder(
-      logger,
-      memory.chroma.collections,
-      memory.chroma.embeddings
-    )
 
     // Parse temporal expression if provided
     let startDate: string | undefined
@@ -41,6 +36,97 @@ export async function handleGetDecisionTimeline(
       endDate = parsed.endDate
     }
 
+    if (!memory.isChromaDBEnabled()) {
+      // SQLite fallback: fetch all data and build timeline
+      const [decisions, patterns, corrections] = await Promise.all([
+        memory.fetchAllDecisions(project_name),
+        memory.fetchAllPatterns(project_name),
+        memory.fetchAllCorrections(project_name)
+      ])
+
+      // Combine into timeline entries
+      let entries: Array<{ date: string; type: string; content: string; reasoning?: string }> = []
+
+      for (const d of decisions) {
+        entries.push({
+          date: d.date,
+          type: 'decision',
+          content: d.decision || d.content,
+          reasoning: d.reasoning
+        })
+      }
+      for (const p of patterns) {
+        entries.push({
+          date: p.date,
+          type: 'pattern',
+          content: p.description || p.content
+        })
+      }
+      for (const c of corrections) {
+        entries.push({
+          date: c.date,
+          type: 'correction',
+          content: c.correction || c.content,
+          reasoning: c.reasoning
+        })
+      }
+
+      // Filter by topic (substring match)
+      if (topic) {
+        const topicLower = topic.toLowerCase()
+        entries = entries.filter(e =>
+          e.content.toLowerCase().includes(topicLower) ||
+          (e.reasoning && e.reasoning.toLowerCase().includes(topicLower))
+        )
+      }
+
+      // Filter by date range
+      if (startDate) {
+        entries = entries.filter(e => e.date >= startDate!)
+      }
+      if (endDate) {
+        entries = entries.filter(e => e.date <= endDate!)
+      }
+
+      // Sort chronologically and limit
+      entries.sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime())
+      const limited = entries.slice(0, limit || 20)
+
+      if (limited.length === 0) {
+        return ResponseFormatter.text('No decisions found for the specified criteria.')
+      }
+
+      const parts: string[] = []
+      parts.push(`## Decision Timeline (SQLite)`)
+      if (project_name) parts.push(`**Project:** ${project_name}`)
+      if (topic) parts.push(`**Topic:** ${topic}`)
+      if (limited.length > 0) {
+        parts.push(`**Period:** ${new Date(limited[0].date).toLocaleDateString()} - ${new Date(limited[limited.length - 1].date).toLocaleDateString()}`)
+      }
+      parts.push(`**Total entries:** ${limited.length}`)
+      parts.push('')
+
+      for (const entry of limited) {
+        const date = new Date(entry.date).toLocaleDateString()
+        const icon = entry.type === 'decision' ? '📋' : entry.type === 'pattern' ? '🔄' : '⚠️'
+        parts.push(`### ${icon} ${date} [${entry.type}]`)
+        parts.push(entry.content.slice(0, 200))
+        if (entry.reasoning) {
+          parts.push(`*Reasoning:* ${entry.reasoning.slice(0, 100)}`)
+        }
+        parts.push('')
+      }
+
+      const statsLine = formatMemoryStats({ recalled: limited.length })
+      return ResponseFormatter.text(withMemoryIndicator(parts.join('\n'), limited.length) + '\n\n' + statsLine)
+    }
+
+    const timelineBuilder = new TimelineBuilder(
+      logger,
+      memory.chroma.collections,
+      memory.chroma.embeddings
+    )
+
     const timeline = await timelineBuilder.buildTimeline({
       project: project_name,
       topic,
@@ -50,10 +136,7 @@ export async function handleGetDecisionTimeline(
     })
 
     if (timeline.entries.length === 0) {
-      const chromaNote = !memory.isChromaDBEnabled()
-        ? '\n\nNote: ChromaDB is not connected. Decision timeline requires ChromaDB for semantic search. Start a ChromaDB server or switch to persistent mode.'
-        : ''
-      return ResponseFormatter.text('No decisions found for the specified criteria.' + chromaNote)
+      return ResponseFormatter.text('No decisions found for the specified criteria.')
     }
 
     // Format timeline

package/src/server/handlers/tools/get-episode.ts

@@ -32,7 +32,17 @@ export async function handleGetEpisode(
     const episodeService = getEpisodeService()
     if (!episodeService) {
       return ResponseFormatter.text(
-        'Episodic memory is not enabled. Enable it by setting knowledge.episodic.enabled=true in config.'
+        '## Episodic Memory Not Available\n\n' +
+        'Episodic memory requires ChromaDB to track conversation sessions.\n\n' +
+        '**To enable:**\n' +
+        '- Start a ChromaDB server: `chroma run --path /path/to/data`\n' +
+        '- Set `CHROMA_URL=http://localhost:8000` in your environment\n' +
+        '- Set `knowledge.episodic.enabled=true` in config\n\n' +
+        '**Alternative tools that work without ChromaDB:**\n' +
+        '- `recall_similar` — search past decisions by semantic similarity\n' +
+        '- `get_patterns` — retrieve recognized patterns\n' +
+        '- `get_corrections` — retrieve lessons learned\n' +
+        '- `smart_context` — get full project context with memory recall'
       )
     }
 

package/src/server/handlers/tools/get-recommendations.ts

@@ -23,6 +23,86 @@ export async function handleGetRecommendations(
     const { query, project_name, limit } = input
 
     const memory = getMemoryService()
+
+    if (!memory.isChromaDBEnabled()) {
+      // SQLite fallback: combine searchRaw + searchPatterns + searchCorrections
+      const [rawResults, patternResults, correctionResults] = await Promise.all([
+        memory.searchRaw(query, { project: project_name, limit: limit || 5, minSimilarity: 0.2 }),
+        memory.searchPatterns(query, { project: project_name, limit: limit || 5, minSimilarity: 0.2 }),
+        memory.searchCorrections(query, { project: project_name, limit: limit || 5, minSimilarity: 0.2 })
+      ])
+
+      // Combine and format as recommendations
+      const recommendations: Array<{ type: string; source: string; content: string; reasoning: string; confidence: number }> = []
+
+      // Corrections get highest priority (lessons learned)
+      for (const c of correctionResults) {
+        recommendations.push({
+          type: 'correction',
+          source: 'Past Correction',
+          content: `Original: ${c.metadata?.original || ''}\nCorrection: ${c.metadata?.correction || c.content || ''}`,
+          reasoning: c.metadata?.reasoning || 'Based on previous lesson learned',
+          confidence: c.similarity || c.metadata?.confidence || 0.5
+        })
+      }
+
+      // Patterns
+      for (const p of patternResults) {
+        recommendations.push({
+          type: p.metadata?.pattern_type || 'pattern',
+          source: `Pattern (${p.metadata?.pattern_type || 'general'})`,
+          content: p.metadata?.description || p.content || '',
+          reasoning: p.metadata?.context || 'Based on recognized pattern',
+          confidence: p.similarity || p.metadata?.confidence || 0.5
+        })
+      }
+
+      // Decisions
+      for (const r of rawResults) {
+        recommendations.push({
+          type: 'decision',
+          source: 'Past Decision',
+          content: r.decision?.decision || r.memory?.content?.slice(0, 300) || '',
+          reasoning: r.decision?.reasoning || 'Based on similar past decision',
+          confidence: r.similarity || 0.5
+        })
+      }
+
+      // Sort by confidence, deduplicate, and limit
+      const seen = new Set<string>()
+      const deduped = recommendations.filter(r => {
+        const key = r.content.slice(0, 50)
+        if (seen.has(key)) return false
+        seen.add(key)
+        return true
+      })
+      .sort((a, b) => b.confidence - a.confidence)
+      .slice(0, limit || 5)
+
+      if (deduped.length === 0) {
+        return ResponseFormatter.text(`No recommendations found for: "${query}"`)
+      }
+
+      const parts: string[] = []
+      parts.push(`## Recommendations (SQLite)`)
+      parts.push(`**Query:** ${query}`)
+      if (project_name) parts.push(`**Project:** ${project_name}`)
+      parts.push(`**Found:** ${deduped.length}`)
+      parts.push('')
+
+      for (const rec of deduped) {
+        const confidence = Math.round(rec.confidence * 100)
+        const icon = rec.type === 'correction' ? '⚠️' : rec.type === 'best-practice' ? '✅' : rec.type === 'pattern' ? '🔄' : '📋'
+        parts.push(`### ${icon} ${rec.source} (${confidence}% confidence)`)
+        parts.push(rec.content.slice(0, 300))
+        parts.push(`*${rec.reasoning}*`)
+        parts.push('')
+      }
+
+      const statsLine = formatMemoryStats({ recalled: deduped.length })
+      return ResponseFormatter.text(withMemoryIndicator(parts.join('\n'), deduped.length) + '\n\n' + statsLine)
+    }
+
     const recommender = new Recommender(
       logger,
       memory.chroma.collections,
@@ -35,10 +115,7 @@ export async function handleGetRecommendations(
     })
 
     if (result.recommendations.length === 0) {
-      const chromaNote = !memory.isChromaDBEnabled()
-        ? '\n\nNote: ChromaDB is not connected. Recommendations require ChromaDB for semantic search across patterns, corrections, and decisions. Start a ChromaDB server or switch to persistent mode.'
-        : ''
-      return ResponseFormatter.text(`No recommendations found for: "${query}"` + chromaNote)
+      return ResponseFormatter.text(`No recommendations found for: "${query}"`)
     }
 
     const parts: string[] = []

package/src/server/handlers/tools/list-episodes.ts

@@ -32,7 +32,17 @@ export async function handleListEpisodes(
     const episodeService = getEpisodeService()
     if (!episodeService) {
       return ResponseFormatter.text(
-        'Episodic memory is not enabled. Enable it by setting knowledge.episodic.enabled=true in config.'
+        '## Episodic Memory Not Available\n\n' +
+        'Episodic memory requires ChromaDB to track conversation sessions.\n\n' +
+        '**To enable:**\n' +
+        '- Start a ChromaDB server: `chroma run --path /path/to/data`\n' +
+        '- Set `CHROMA_URL=http://localhost:8000` in your environment\n' +
+        '- Set `knowledge.episodic.enabled=true` in config\n\n' +
+        '**Alternative tools that work without ChromaDB:**\n' +
+        '- `recall_similar` — search past decisions by semantic similarity\n' +
+        '- `get_patterns` — retrieve recognized patterns\n' +
+        '- `get_corrections` — retrieve lessons learned\n' +
+        '- `smart_context` — get full project context with memory recall'
       )
     }
 

package/src/server/handlers/tools/rate-memory.ts

@@ -39,8 +39,14 @@ export async function handleRateMemory(
     // Check if feedback is enabled
     if (!retrieval) {
       return ResponseFormatter.text(
-        'Feedback collection is not enabled. ' +
-        'Enable it by setting RETRIEVAL_FEEDBACK_ENABLED=true or retrieval.feedback.enabled=true in config.'
+        '## Memory Feedback Not Available\n\n' +
+        'Memory rating requires the retrieval feedback system, which depends on ChromaDB.\n\n' +
+        '**To enable:**\n' +
+        '- Start a ChromaDB server: `chroma run --path /path/to/data`\n' +
+        '- Set `CHROMA_URL=http://localhost:8000` in your environment\n' +
+        '- Set `RETRIEVAL_FEEDBACK_ENABLED=true` or `retrieval.feedback.enabled=true` in config\n\n' +
+        '**Note:** Your rating was not lost — the memory system will still function without feedback. ' +
+        'Feedback helps improve retrieval quality over time by learning which memories are most useful.'
       )
     }
 

package/src/server/handlers/tools/search-knowledge-graph.ts

@@ -5,7 +5,7 @@
 
 import type { Logger } from 'pino'
 import type { ToolResponse } from '@/tools/types'
-import { getKnowledgeGraphService, isServicesInitialized } from '@/server/services'
+import { getKnowledgeGraphService, getMemoryService, isServicesInitialized } from '@/server/services'
 import { ToolValidator } from '@/server/utils/validators'
 import { ResponseFormatter } from '@/server/utils/response-formatter'
 import { ErrorHandler } from '@/server/utils/error-handler'
@@ -72,6 +72,19 @@ export async function handleSearchKnowledgeGraph(
       edgeCount: result.edges.length
     }, 'Knowledge graph search complete')
 
+    // If graph is empty and ChromaDB is not connected, add guidance
+    if (result.nodes.length === 0 && result.edges.length === 0) {
+      const memory = getMemoryService()
+      if (!memory.isChromaDBEnabled()) {
+        return ResponseFormatter.text(
+          'Knowledge graph is empty (0 nodes, 0 edges).\n\n' +
+          'Note: ChromaDB is not connected. The knowledge graph is populated from stored decisions. ' +
+          'New decisions stored via SQLite will populate the graph going forward. ' +
+          'To migrate existing decisions into the graph, start a ChromaDB server or configure persistent mode.'
+        )
+      }
+    }
+
     return ResponseFormatter.json(response, 'Knowledge Graph Search Results')
 
   } catch (error) {

package/src/server/handlers/tools/smart-context.ts

@@ -5,7 +5,7 @@
 
 import type { Logger } from 'pino'
 import type { ToolResponse } from '@/tools/types'
-import { getContextService, getPhase12Service, isServicesInitialized } from '@/server/services'
+import { getContextService, getPhase12Service, getMemoryService, isServicesInitialized } from '@/server/services'
 import { ToolValidator } from '@/server/utils/validators'
 import { ResponseFormatter } from '@/server/utils/response-formatter'
 import { withMemoryIndicator, formatMemoryStats } from '@/server/utils/memory-indicator'
@@ -52,6 +52,28 @@ export async function handleSmartContext(
     // Process with Phase 12 for proactive recall
     const phase12Result = await phase12.processMessage(current_task, project_name)
 
+    // If Phase12's gated recall found nothing, do direct search (like recall_similar)
+    if (!phase12Result.recalledMemories || phase12Result.recalledMemories.memories.length === 0) {
+      try {
+        const memory = getMemoryService()
+        const directRecall = await memory.searchRaw(current_task, {
+          project: project_name,
+          limit: 5,
+          minSimilarity: min_similarity || 0.3
+        })
+        if (directRecall.length > 0) {
+          phase12Result.recalledMemories = {
+            query: current_task,
+            memories: directRecall,
+            relevanceScore: directRecall.reduce((sum: number, m: any) => sum + (m.similarity || 0), 0) / directRecall.length,
+            triggeredBy: ['direct-search-fallback']
+          }
+        }
+      } catch (e) {
+        logger.debug({ error: e }, 'Direct recall fallback failed, continuing without')
+      }
+    }
+
     // Format base context
     const formattedContext = contextService.formatter.format(context)
 

package/src/server/handlers/tools/update-progress.ts

@@ -43,6 +43,7 @@ export async function handleUpdateProgress(
 
     const taskId = generateTaskId(completed_task)
 
+    // Step 1: Append completed task to progress file
     await context.progress.addCompletedTask(project_name, {
       id: taskId,
       title: completed_task,
@@ -50,19 +51,8 @@ export async function handleUpdateProgress(
       completedAt: new Date()
     })
 
-    // Calculate and update completion percentage
-    const progressState = await context.progress.getProgress(project_name)
-    const totalTasks = progressState.completedTasks.length + progressState.currentTasks.length
-    const completionPercentage = totalTasks > 0
-      ? Math.round((progressState.completedTasks.length / totalTasks) * 100)
-      : 0
-
-    await context.progress.updateProgress(project_name, {
-      completionPercentage,
-      currentPhase: completionPercentage >= 100 ? 'complete' : 'active'
-    })
-
-    const progressFile = await vault.reader.readMarkdownFile(projectPaths.progress)
+    // Step 2: Read file bypassing cache, update next steps, write content
+    const progressFile = await vault.reader.readMarkdownFile(projectPaths.progress, false)
     const updatedContent = updateNextStepsSection(progressFile.content, next_steps)
 
     await vault.writer.writeMarkdownFile(
@@ -72,11 +62,26 @@ export async function handleUpdateProgress(
       true
     )
 
+    // Step 3: Notes appended if present
     if (notes) {
       const notesEntry = `\n## Notes (${new Date().toLocaleDateString()})\n${notes}\n`
       await vault.writer.appendContent(projectPaths.progress, notesEntry)
     }
 
+    // Step 4: Calculate and update frontmatter LAST (so nothing overwrites it)
+    const progressState = await context.progress.getProgress(project_name)
+    const totalTasks = progressState.completedTasks.length + progressState.currentTasks.length
+    const completionPercentage = totalTasks > 0
+      ? Math.round((progressState.completedTasks.length / totalTasks) * 100)
+      : 0
+
+    await context.progress.updateProgress(project_name, {
+      completionPercentage,
+      currentPhase: completionPercentage >= 100 ? 'complete' : 'active'
+    })
+
+    // Step 5: Invalidate cache so subsequent reads get fresh data
+    vault.reader.invalidateCache(projectPaths.progress)
     context.invalidateContext(project_name)
 
     logger.info({ projectName: project_name, taskId }, 'Progress updated successfully')

package/src/server/handlers/tools/what-if-analysis.ts

@@ -23,6 +23,68 @@ export async function handleWhatIfAnalysis(
     const { change, project_name, max_results } = input
 
     const memory = getMemoryService()
+
+    if (!memory.isChromaDBEnabled()) {
+      // SQLite fallback: use searchRaw for semantic search + knowledge graph if available
+      const results = await memory.searchRaw(change, {
+        project: project_name,
+        limit: max_results || 10,
+        minSimilarity: 0.2
+      })
+
+      const parts: string[] = []
+      parts.push(`## What-If: "${change}" (SQLite)`)
+      parts.push('')
+
+      if (results.length === 0) {
+        parts.push('No related decisions found to assess impact.')
+        return ResponseFormatter.text(parts.join('\n'))
+      }
+
+      // Assess impact based on similarity
+      const affectedDecisions = results.map(r => {
+        const similarity = r.similarity || 0
+        const impact = similarity > 0.7 ? 'high' : similarity > 0.4 ? 'medium' : 'low'
+        return {
+          decision: r.decision?.decision || r.memory?.content?.slice(0, 150) || '',
+          impact,
+          similarity,
+          reason: `${Math.round(similarity * 100)}% similarity — ${r.decision?.reasoning?.slice(0, 100) || 'related context found'}`
+        }
+      })
+
+      parts.push(`Analyzed ${results.length} related decisions.\n`)
+
+      parts.push('### Affected Decisions')
+      for (const d of affectedDecisions) {
+        const icon = d.impact === 'high' ? '🔴' : d.impact === 'medium' ? '🟡' : '🟢'
+        parts.push(`${icon} **[${d.impact}]** ${d.decision}`)
+        parts.push(`  *${d.reason}*`)
+      }
+
+      // Try knowledge graph if available
+      try {
+        const kgService = getKnowledgeGraphService()
+        if (kgService?.graph) {
+          const graphResults = await kgService.graph.search(change, { limit: 5 })
+          if (graphResults && graphResults.length > 0) {
+            const technologies = graphResults
+              .filter((n: any) => n.type === 'technology')
+              .map((n: any) => n.name || n.label)
+            if (technologies.length > 0) {
+              parts.push(`\n### Connected Technologies`)
+              parts.push(technologies.map((t: string) => `- ${t}`).join('\n'))
+            }
+          }
+        }
+      } catch {
+        // Knowledge graph not available, skip
+      }
+
+      const content = parts.join('\n')
+      return ResponseFormatter.text(withMemoryIndicator(content, results.length))
+    }
+
     const kgService = getKnowledgeGraphService()
     const graph = kgService?.graph || null
 
@@ -63,10 +125,7 @@ export async function handleWhatIfAnalysis(
       return ResponseFormatter.text(withMemoryIndicator(content, totalAffected))
     }
 
-    const chromaNote = !memory.isChromaDBEnabled()
-      ? '\n\nNote: ChromaDB is not connected. What-if analysis requires ChromaDB for semantic search across decisions. Start a ChromaDB server or switch to persistent mode.'
-      : ''
-    return ResponseFormatter.text(content + chromaNote)
+    return ResponseFormatter.text(content)
 
   } catch (error) {
     ErrorHandler.logError(logger, error, { tool: 'what_if_analysis' })

package/src/server/services.ts

@@ -112,9 +112,9 @@ export async function initializeServices(config: Config, logger: Logger): Promis
     await phase12.initialize()
     serviceLogger.info('Phase 12 service initialized')
 
-    // Initialize Retrieval Service (Phase 13)
+    // Initialize Retrieval Service (Phase 13) — requires ChromaDB
     let retrieval: RetrievalService | null = null
-    if (config.retrieval?.feedback?.enabled || config.retrieval?.enabled) {
+    if ((config.retrieval?.feedback?.enabled || config.retrieval?.enabled) && memory.isChromaDBEnabled()) {
       retrieval = new RetrievalService(
         logger,
         memory.chroma.collections,
@@ -123,6 +123,8 @@ export async function initializeServices(config: Config, logger: Logger): Promis
       )
       await retrieval.initialize()
       serviceLogger.info('Retrieval service initialized')
+    } else if (config.retrieval?.enabled && !memory.isChromaDBEnabled()) {
+      serviceLogger.warn('Retrieval service requires ChromaDB, skipping initialization')
     }
 
     // Initialize Knowledge Graph Service (Phase 14)
@@ -146,14 +148,16 @@ export async function initializeServices(config: Config, logger: Logger): Promis
 
         knowledgeGraph = { graph, search, builder, linker }
 
-        // Migrate existing decisions if graph is empty
-        if (graph.getNodeCount() === 0) {
+        // Migrate existing decisions if graph is empty (requires ChromaDB)
+        if (graph.getNodeCount() === 0 && memory.isChromaDBEnabled()) {
           serviceLogger.info('Empty graph detected, migrating existing decisions...')
           const migrationResult = await builder.migrateExistingDecisions(memory.chroma.collections)
           serviceLogger.info(
             { processed: migrationResult.processed, errors: migrationResult.errors },
             'Initial graph migration complete'
           )
+        } else if (graph.getNodeCount() === 0) {
+          serviceLogger.info('Empty graph detected, but ChromaDB unavailable — graph will populate as new decisions are stored')
         }
 
         // Hook builder into decision storage for real-time graph population
@@ -171,9 +175,9 @@ export async function initializeServices(config: Config, logger: Logger): Promis
       }
     }
 
-    // Initialize Episode Manager (Phase 14)
+    // Initialize Episode Manager (Phase 14) — requires ChromaDB
     let episodeManager: EpisodeManager | null = null
-    if (config.knowledge?.episodic?.enabled !== false) {
+    if (config.knowledge?.episodic?.enabled !== false && memory.isChromaDBEnabled()) {
       try {
         episodeManager = new EpisodeManager(
           logger,
@@ -187,10 +191,10 @@ export async function initializeServices(config: Config, logger: Logger): Promis
       }
     }
 
-    // Initialize Semantic Cache & Precompute (Phase 15)
+    // Initialize Semantic Cache & Precompute (Phase 15) — requires ChromaDB
     let semanticCache: SemanticCache | null = null
     let precompute: PrecomputeEngine | null = null
-    if (config.advancedIntelligence?.enabled !== false && config.advancedIntelligence?.cache?.enabled !== false) {
+    if (config.advancedIntelligence?.enabled !== false && config.advancedIntelligence?.cache?.enabled !== false && memory.isChromaDBEnabled()) {
       try {
         const cacheConfig = config.advancedIntelligence?.cache || {}
         semanticCache = new SemanticCache(logger, {