claude-brain 0.4.0 → 0.4.1

package/VERSION

@@ -1 +1 @@
-0.4.0
+0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-brain",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Local development assistant bridging Obsidian vaults with Claude Code via MCP",
   "type": "module",
   "main": "src/index.ts",

package/src/cli/auto-setup.ts

@@ -8,6 +8,14 @@ function getDefaultEnv(vaultPath: string): string {
 VAULT_PATH=${vaultPath}
 LOG_LEVEL=info
 NODE_ENV=production
+
+# ChromaDB Configuration
+# Start ChromaDB server: claude-brain chroma start
+# Install ChromaDB: claude-brain chroma install
+CHROMA_MODE=client-server
+CHROMA_HOST=localhost
+CHROMA_PORT=8000
+CHROMA_EMBEDDING_PROVIDER=transformers
 `
 }
 

package/src/cli/bin.ts

@@ -31,6 +31,7 @@ function printHelp() {
     ['install', 'Register as MCP server in Claude Code'],
     ['uninstall', 'Remove MCP server from Claude Code'],
     ['update', 'Update package and refresh CLAUDE.md'],
+    ['chroma', 'Manage ChromaDB server (start/stop/status)'],
     ['health', 'Run health checks'],
     ['diagnose', 'Run diagnostics'],
     ['version', 'Show version'],
@@ -58,6 +59,7 @@ function printHelp() {
     `  ${dimText('claude-brain setup')}           ${dimText('Configure Claude Brain')}`,
     `  ${dimText('claude-brain install')}         ${dimText('Register with Claude Code')}`,
     `  ${dimText('claude-brain update')}          ${dimText('Update to latest version')}`,
+    `  ${dimText('claude-brain chroma start')}    ${dimText('Start ChromaDB server')}`,
     `  ${dimText('claude-brain health')}          ${dimText('Check system health')}`,
     '',
     theme.bold('Environment:'),
@@ -102,6 +104,12 @@ async function main() {
       break
     }
 
+    case 'chroma': {
+      const { runChroma } = await import('./commands/chroma')
+      await runChroma()
+      break
+    }
+
     case 'health': {
       const { runHealthCheck } = await import('@/health')
       await runHealthCheck()

package/src/cli/commands/chroma.ts

@@ -0,0 +1,407 @@
+/**
+ * ChromaDB Management Command
+ * Start, stop, and manage the ChromaDB server for Claude Brain
+ */
+
+import { spawn, execSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { getHomePaths } from '@/config/home'
+import {
+  theme, heading, successText, errorText, warningText, dimText,
+  infoPanel,
+} from '@/cli/ui/index.js'
+
+const PID_FILENAME = 'chroma.pid'
+const DEFAULT_PORT = '8000'
+
+function getPidFilePath(): string {
+  const paths = getHomePaths()
+  return join(paths.data, PID_FILENAME)
+}
+
+function getChromaDataPath(): string {
+  const paths = getHomePaths()
+  return paths.chroma
+}
+
+function isChromaCliInstalled(): boolean {
+  try {
+    execSync('chroma --version', { stdio: 'pipe', timeout: 5000 })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function getChromaVersion(): string {
+  try {
+    return execSync('chroma --version', { encoding: 'utf-8', stdio: 'pipe', timeout: 5000 }).trim()
+  } catch {
+    return 'unknown'
+  }
+}
+
+function isPythonInstalled(): { installed: boolean; cmd: string } {
+  for (const cmd of ['python3', 'python']) {
+    try {
+      execSync(`${cmd} --version`, { stdio: 'pipe', timeout: 5000 })
+      return { installed: true, cmd }
+    } catch {
+      // try next
+    }
+  }
+  return { installed: false, cmd: 'python3' }
+}
+
+function getRunningPid(): number | null {
+  const pidPath = getPidFilePath()
+  if (!existsSync(pidPath)) return null
+
+  try {
+    const pid = parseInt(readFileSync(pidPath, 'utf-8').trim(), 10)
+    if (isNaN(pid)) {
+      unlinkSync(pidPath)
+      return null
+    }
+    // Signal 0 tests if process exists without killing it
+    process.kill(pid, 0)
+    return pid
+  } catch {
+    // Process not running, clean up stale PID file
+    try { unlinkSync(pidPath) } catch {}
+    return null
+  }
+}
+
+function isChromaReachable(): boolean {
+  try {
+    execSync(`curl -sf http://localhost:${DEFAULT_PORT}/api/v1/heartbeat`, {
+      stdio: 'pipe',
+      timeout: 3000
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+// ── Subcommands ───────────────────────────────────────────
+
+async function chromaStart(): Promise<void> {
+  console.log()
+  console.log(heading('Starting ChromaDB Server'))
+  console.log()
+
+  // Check if already running
+  const existingPid = getRunningPid()
+  if (existingPid) {
+    console.log(warningText(`ChromaDB is already running (PID: ${existingPid})`))
+    console.log()
+    return
+  }
+
+  if (isChromaReachable()) {
+    console.log(warningText('A ChromaDB server is already running on port ' + DEFAULT_PORT))
+    console.log()
+    return
+  }
+
+  // Check if chroma CLI is installed
+  if (!isChromaCliInstalled()) {
+    console.log(errorText('ChromaDB CLI is not installed.'))
+    console.log()
+    console.log(dimText('Install it with:'))
+    console.log(`  ${theme.primary('pip install chromadb')}`)
+    console.log()
+    console.log(dimText('Or run:'))
+    console.log(`  ${theme.primary('claude-brain chroma install')}`)
+    console.log()
+    process.exit(1)
+  }
+
+  const dataPath = getChromaDataPath()
+
+  console.log(dimText(`Data path: ${dataPath}`))
+  console.log(dimText(`Port: ${DEFAULT_PORT}`))
+  console.log()
+
+  // Start ChromaDB server in background
+  const child = spawn('chroma', ['run', '--path', dataPath, '--port', DEFAULT_PORT], {
+    detached: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env }
+  })
+
+  const pid = child.pid
+  if (!pid) {
+    console.log(errorText('Failed to start ChromaDB server — no PID returned.'))
+    console.log()
+    process.exit(1)
+  }
+
+  // Detach the child process so it runs independently
+  child.unref()
+
+  // Save PID file
+  writeFileSync(getPidFilePath(), String(pid), 'utf-8')
+
+  // Capture early output for error detection
+  let startupOutput = ''
+  child.stderr?.on('data', (chunk: Buffer) => {
+    startupOutput += chunk.toString()
+  })
+  child.stdout?.on('data', (chunk: Buffer) => {
+    startupOutput += chunk.toString()
+  })
+
+  // Wait up to 15 seconds for server to become reachable
+  let ready = false
+  for (let i = 0; i < 30; i++) {
+    await sleep(500)
+    if (isChromaReachable()) {
+      ready = true
+      break
+    }
+    // Check if process exited early
+    try {
+      process.kill(pid, 0)
+    } catch {
+      break
+    }
+  }
+
+  if (ready) {
+    console.log(successText(`ChromaDB server started (PID: ${pid})`))
+    console.log()
+    console.log(dimText('The server is running in the background.'))
+    console.log(dimText('Stop it with: ') + theme.primary('claude-brain chroma stop'))
+  } else {
+    // Check if process is still alive
+    let alive = false
+    try {
+      process.kill(pid, 0)
+      alive = true
+    } catch {}
+
+    if (alive) {
+      console.log(warningText('ChromaDB server started but not yet responding.'))
+      console.log(dimText(`PID: ${pid} — it may still be initializing.`))
+      console.log(dimText('Check with: ') + theme.primary('claude-brain chroma status'))
+    } else {
+      console.log(errorText('ChromaDB server failed to start.'))
+      if (startupOutput) {
+        console.log(dimText('Output:'))
+        console.log(dimText(startupOutput.slice(0, 500)))
+      }
+      try { unlinkSync(getPidFilePath()) } catch {}
+      process.exit(1)
+    }
+  }
+  console.log()
+}
+
+async function chromaStop(): Promise<void> {
+  console.log()
+  console.log(heading('Stopping ChromaDB Server'))
+  console.log()
+
+  const pid = getRunningPid()
+  if (!pid) {
+    if (isChromaReachable()) {
+      console.log(warningText('A ChromaDB server is running on port ' + DEFAULT_PORT + ' but was not started by claude-brain.'))
+      console.log(dimText('Kill it manually if needed.'))
+    } else {
+      console.log(dimText('No ChromaDB server is currently running.'))
+    }
+    console.log()
+    return
+  }
+
+  try {
+    process.kill(pid, 'SIGTERM')
+
+    // Wait up to 5 seconds for graceful shutdown
+    for (let i = 0; i < 10; i++) {
+      await sleep(500)
+      try {
+        process.kill(pid, 0)
+      } catch {
+        // Process exited
+        break
+      }
+    }
+
+    // Force kill if still running
+    try {
+      process.kill(pid, 0)
+      // Still alive, force kill
+      process.kill(pid, 'SIGKILL')
+    } catch {
+      // Already dead, good
+    }
+
+    try { unlinkSync(getPidFilePath()) } catch {}
+
+    console.log(successText(`ChromaDB server stopped (PID: ${pid})`))
+  } catch (error) {
+    console.log(errorText(`Failed to stop ChromaDB: ${error instanceof Error ? error.message : String(error)}`))
+    try { unlinkSync(getPidFilePath()) } catch {}
+  }
+  console.log()
+}
+
+async function chromaStatus(): Promise<void> {
+  console.log()
+
+  const pid = getRunningPid()
+  const reachable = isChromaReachable()
+  const installed = isChromaCliInstalled()
+  const version = installed ? getChromaVersion() : 'N/A'
+  const dataPath = getChromaDataPath()
+  const dataExists = existsSync(dataPath)
+
+  const items: Record<string, string> = {
+    'Installed': installed ? `Yes (${version})` : 'No',
+    'Server': reachable ? `Running (port ${DEFAULT_PORT})` : 'Not running',
+    'Managed PID': pid ? String(pid) : 'None',
+    'Data Path': dataPath,
+    'Data Exists': dataExists ? 'Yes' : 'No',
+  }
+
+  console.log(infoPanel('ChromaDB Status', items))
+
+  if (!installed) {
+    console.log()
+    console.log(warningText('ChromaDB is not installed.'))
+    console.log(dimText('Install with: ') + theme.primary('claude-brain chroma install'))
+  } else if (!reachable) {
+    console.log()
+    console.log(dimText('Start the server with: ') + theme.primary('claude-brain chroma start'))
+  }
+  console.log()
+}
+
+async function chromaInstall(): Promise<void> {
+  console.log()
+  console.log(heading('Installing ChromaDB'))
+  console.log()
+
+  if (isChromaCliInstalled()) {
+    const version = getChromaVersion()
+    console.log(successText(`ChromaDB is already installed (${version}).`))
+    console.log()
+    return
+  }
+
+  const python = isPythonInstalled()
+  if (!python.installed) {
+    console.log(errorText('Python 3 is required to install ChromaDB.'))
+    console.log()
+    console.log(dimText('Install Python 3 first:'))
+    console.log(`  ${theme.primary('macOS:')}   brew install python3`)
+    console.log(`  ${theme.primary('Ubuntu:')}  sudo apt install python3 python3-pip`)
+    console.log(`  ${theme.primary('Windows:')} https://python.org/downloads`)
+    console.log()
+    process.exit(1)
+  }
+
+  console.log(dimText(`Found ${python.cmd}. Installing chromadb via pip...`))
+  console.log()
+
+  const pipCommands = python.cmd === 'python3'
+    ? ['pip3 install chromadb', 'python3 -m pip install chromadb']
+    : ['pip install chromadb', 'python -m pip install chromadb']
+
+  let installed = false
+  for (const cmd of pipCommands) {
+    try {
+      execSync(cmd, { stdio: 'inherit', timeout: 300_000 })
+      installed = true
+      break
+    } catch {
+      // Try next command
+    }
+  }
+
+  console.log()
+  if (installed) {
+    console.log(successText('ChromaDB installed successfully!'))
+    console.log()
+    console.log(dimText('Start the server with: ') + theme.primary('claude-brain chroma start'))
+  } else {
+    console.log(errorText('Failed to install ChromaDB.'))
+    console.log(dimText('Try installing manually:'))
+    console.log(`  ${theme.primary('pip install chromadb')}`)
+    process.exit(1)
+  }
+  console.log()
+}
+
+// ── Help ──────────────────────────────────────────────────
+
+function printChromaHelp(): void {
+  console.log()
+  console.log(heading('ChromaDB Management'))
+  console.log()
+  console.log(dimText('ChromaDB provides vector storage for semantic search,'))
+  console.log(dimText('knowledge graph, and advanced intelligence features.'))
+  console.log()
+
+  const commands = [
+    ['start', 'Start ChromaDB server in background'],
+    ['stop', 'Stop the running ChromaDB server'],
+    ['status', 'Show ChromaDB server status'],
+    ['install', 'Install ChromaDB (requires Python 3)'],
+  ]
+
+  const cmdLines = commands
+    .map(([cmd, desc]) => `  ${theme.primary(cmd!.padEnd(12))} ${dimText(desc!)}`)
+    .join('\n')
+
+  console.log(theme.bold('Commands:'))
+  console.log(cmdLines)
+  console.log()
+
+  console.log(theme.bold('Usage:'))
+  console.log(`  ${dimText('claude-brain chroma install')}   ${dimText('Install ChromaDB')}`)
+  console.log(`  ${dimText('claude-brain chroma start')}     ${dimText('Start the server')}`)
+  console.log(`  ${dimText('claude-brain chroma status')}    ${dimText('Check if running')}`)
+  console.log(`  ${dimText('claude-brain chroma stop')}      ${dimText('Stop the server')}`)
+  console.log()
+}
+
+// ── Entry Point ───────────────────────────────────────────
+
+export async function runChroma(): Promise<void> {
+  const subcommand = process.argv[3] || 'help'
+
+  switch (subcommand) {
+    case 'start':
+      await chromaStart()
+      break
+    case 'stop':
+      await chromaStop()
+      break
+    case 'status':
+      await chromaStatus()
+      break
+    case 'install':
+      await chromaInstall()
+      break
+    case 'help':
+    case '--help':
+    case '-h':
+      printChromaHelp()
+      break
+    default:
+      console.log()
+      console.log(errorText(`Unknown subcommand: ${subcommand}`))
+      printChromaHelp()
+      process.exit(1)
+  }
+}

package/src/config/defaults.ts

@@ -3,7 +3,7 @@ import type { PartialConfig } from './schema'
 /** Default configuration values for Claude Brain */
 export const defaultConfig: PartialConfig = {
   serverName: 'claude-brain',
-  serverVersion: '0.4.0',
+  serverVersion: '0.4.1',
   logLevel: 'info',
   logFilePath: './logs/claude-brain.log',
   dbPath: './data/memory.db',

package/src/config/schema.ts

@@ -196,7 +196,7 @@ export const ConfigSchema = z.object({
   serverName: z.string().default('claude-brain'),
 
   /** Server version in semver format */
-  serverVersion: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semver format').default('0.4.0'),
+  serverVersion: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semver format').default('0.4.1'),
 
   /** Logging level */
   logLevel: LogLevelSchema.default('info'),

package/src/memory/chroma/client.ts

@@ -36,12 +36,12 @@ export class ChromaClientManager {
           break
 
         case 'client-server':
-          if (!this.config.host || !this.config.port) {
-            throw new Error('Host and port required for client-server mode')
+          if (!this.config.host) {
+            throw new Error('Host required for client-server mode')
           }
           this.client = new ChromaClient({
             host: this.config.host,
-            port: this.config.port,
+            port: this.config.port || 8000,
             ...authConfig
           })
           break

package/src/memory/chroma/config.ts

@@ -45,6 +45,10 @@ export function getChromaConfigFromEnv(): Partial<ChromaConfig> {
     config.mode = process.env.CHROMA_MODE as any
   }
 
+  if (process.env.CHROMA_PORT) {
+    config.port = parseInt(process.env.CHROMA_PORT, 10)
+  }
+
   if (process.env.CHROMA_EMBEDDING_PROVIDER) {
     config.embeddingProvider = process.env.CHROMA_EMBEDDING_PROVIDER as any
   }

package/src/server/handlers/tools/analyze-decision-evolution.ts

@@ -23,6 +23,16 @@ export async function handleAnalyzeDecisionEvolution(
     const { topic, project_name, limit } = input
 
     const memory = getMemoryService()
+
+    if (!memory.isChromaDBEnabled()) {
+      return ResponseFormatter.text(
+        `No decisions found for topic: "${topic}"\n\n` +
+        'Note: ChromaDB is not connected. Decision evolution analysis requires ChromaDB for semantic search. ' +
+        'Decisions stored via SQLite fallback are available through recall_similar. ' +
+        'To enable evolution tracking, start a ChromaDB server or configure persistent mode.'
+      )
+    }
+
     const tracker = new DecisionEvolutionTracker(
       logger,
       memory.chroma.collections,
@@ -35,10 +45,7 @@ export async function handleAnalyzeDecisionEvolution(
     })
 
     if (analysis.totalDecisions === 0) {
-      const chromaNote = !memory.isChromaDBEnabled()
-        ? '\n\nNote: ChromaDB is not connected. Decision evolution analysis requires ChromaDB for semantic search. Start a ChromaDB server or switch to persistent mode.'
-        : ''
-      return ResponseFormatter.text(`No decisions found for topic: "${topic}"` + chromaNote)
+      return ResponseFormatter.text(`No decisions found for topic: "${topic}"`)
     }
 
     const parts: string[] = []

package/src/server/handlers/tools/detect-trends.ts

@@ -23,6 +23,16 @@ export async function handleDetectTrends(
     const { project_name, period_days, min_occurrences, limit } = input
 
     const memory = getMemoryService()
+
+    if (!memory.isChromaDBEnabled()) {
+      return ResponseFormatter.text(
+        'No decisions found for trend analysis.\n\n' +
+        'Note: ChromaDB is not connected. Trend detection requires ChromaDB for semantic search across decisions. ' +
+        'Decisions stored via SQLite fallback are available through recall_similar and get_patterns. ' +
+        'To enable trend detection, start a ChromaDB server or configure persistent mode.'
+      )
+    }
+
     const detector = new TrendDetector(logger, memory.chroma.collections)
 
     const analysis = await detector.detectTrends({
@@ -33,10 +43,7 @@ export async function handleDetectTrends(
     })
 
     if (analysis.totalDecisionsAnalyzed === 0) {
-      const chromaNote = !memory.isChromaDBEnabled()
-        ? '\n\nNote: ChromaDB is not connected. Trend detection requires ChromaDB for semantic search across decisions. Start a ChromaDB server or switch to persistent mode.'
-        : ''
-      return ResponseFormatter.text('No decisions found for trend analysis.' + chromaNote)
+      return ResponseFormatter.text('No decisions found for trend analysis.')
     }
 
     const parts: string[] = []

package/src/server/handlers/tools/find-cross-project-patterns.ts

@@ -23,6 +23,16 @@ export async function handleFindCrossProjectPatterns(
     const { min_projects, limit, query } = input
 
     const memory = getMemoryService()
+
+    if (!memory.isChromaDBEnabled()) {
+      return ResponseFormatter.text(
+        'No cross-project patterns found.\n\n' +
+        'Note: ChromaDB is not connected. Cross-project pattern analysis requires ChromaDB for semantic search across decisions. ' +
+        'Decisions stored via SQLite fallback are available through recall_similar and get_patterns. ' +
+        'To enable cross-project analysis, start a ChromaDB server or configure persistent mode.'
+      )
+    }
+
     const generalizer = new PatternGeneralizer(
       logger,
       memory.chroma.collections,

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

@@ -24,6 +24,16 @@ export async function handleGetDecisionTimeline(
     const { project_name, topic, time_range, limit } = input
 
     const memory = getMemoryService()
+
+    if (!memory.isChromaDBEnabled()) {
+      return ResponseFormatter.text(
+        'No decisions found for the specified criteria.\n\n' +
+        'Note: ChromaDB is not connected. Decision timeline requires ChromaDB for semantic search. ' +
+        'Decisions stored via SQLite fallback are available through recall_similar. ' +
+        'To enable timeline view, start a ChromaDB server or configure persistent mode.'
+      )
+    }
+
     const timelineBuilder = new TimelineBuilder(
       logger,
       memory.chroma.collections,
@@ -50,10 +60,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-recommendations.ts

@@ -23,6 +23,16 @@ export async function handleGetRecommendations(
     const { query, project_name, limit } = input
 
     const memory = getMemoryService()
+
+    if (!memory.isChromaDBEnabled()) {
+      return ResponseFormatter.text(
+        `No recommendations found for: "${query}"\n\n` +
+        'Note: ChromaDB is not connected. Recommendations require ChromaDB for semantic search across patterns, corrections, and decisions. ' +
+        'Decisions stored via SQLite fallback are available through recall_similar, get_patterns, and get_corrections. ' +
+        'To enable recommendations, start a ChromaDB server or configure persistent mode.'
+      )
+    }
+
     const recommender = new Recommender(
       logger,
       memory.chroma.collections,
@@ -35,10 +45,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/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/what-if-analysis.ts

@@ -23,6 +23,17 @@ export async function handleWhatIfAnalysis(
     const { change, project_name, max_results } = input
 
     const memory = getMemoryService()
+
+    if (!memory.isChromaDBEnabled()) {
+      return ResponseFormatter.text(
+        `## What-If: "${change}"\n\n` +
+        'Unable to perform what-if analysis.\n\n' +
+        'Note: ChromaDB is not connected. What-if analysis requires ChromaDB for semantic search across decisions. ' +
+        'Decisions stored via SQLite fallback are available through recall_similar. ' +
+        'To enable what-if analysis, start a ChromaDB server or configure persistent mode.'
+      )
+    }
+
     const kgService = getKnowledgeGraphService()
     const graph = kgService?.graph || null
 
@@ -63,10 +74,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, {

package/src/setup/wizard.ts

@@ -1,6 +1,7 @@
 import prompts from 'prompts'
 import fs from 'fs/promises'
 import { existsSync } from 'fs'
+import { execSync } from 'child_process'
 import path from 'path'
 import os from 'os'
 import { fileURLToPath } from 'url'
@@ -21,6 +22,7 @@ export interface SetupAnswers {
   vaultPath: string
   logLevel: string
   enableFileWatch: boolean
+  enableChromaDB: boolean
   createSampleProject: boolean
   installClaudeMd: boolean
 }
@@ -34,7 +36,7 @@ export class SetupWizard {
 
   async run(): Promise<SetupAnswers> {
     // Step 1: Detect Vaults
-    console.log(stepIndicator(1, 5, 'Detecting Obsidian Vaults'))
+    console.log(stepIndicator(1, 6, 'Detecting Obsidian Vaults'))
     await transition()
 
     const suggestedPaths = await withSpinner('Scanning for Obsidian vaults', () =>
@@ -49,7 +51,7 @@ export class SetupWizard {
     console.log()
 
     // Step 2: Vault Configuration
-    console.log(stepIndicator(2, 5, 'Vault Configuration'))
+    console.log(stepIndicator(2, 6, 'Vault Configuration'))
     await transition()
 
     const vaultAnswers = await prompts([
@@ -86,7 +88,7 @@ export class SetupWizard {
     const finalVaultPath = vaultAnswers.vaultPath || vaultAnswers.vaultPathChoice
 
     // Step 3: Logging
-    console.log(stepIndicator(3, 5, 'Logging Configuration'))
+    console.log(stepIndicator(3, 6, 'Logging Configuration'))
     await transition()
 
     const loggingAnswers = await prompts({
@@ -103,7 +105,7 @@ export class SetupWizard {
     })
 
     // Step 4: Features
-    console.log(stepIndicator(4, 5, 'Feature Selection'))
+    console.log(stepIndicator(4, 6, 'Feature Selection'))
     await transition()
 
     const featureAnswers = await prompts([
@@ -127,14 +129,40 @@ export class SetupWizard {
       }
     ])
 
-    // Step 5: Review
-    console.log(stepIndicator(5, 5, 'Review Configuration'))
+    // Step 5: ChromaDB
+    console.log(stepIndicator(5, 6, 'ChromaDB (Vector Database)'))
+    await transition()
+
+    console.log(dimText('ChromaDB enables semantic search, knowledge graph,'))
+    console.log(dimText('and advanced intelligence features. Requires Python 3.'))
+    console.log()
+
+    const chromaInstalled = this.isChromaInstalled()
+    if (chromaInstalled) {
+      console.log(successText('ChromaDB CLI detected'))
+    } else {
+      console.log(warningText('ChromaDB CLI not found — you can install it later'))
+    }
+    console.log()
+
+    const chromaAnswers = await prompts({
+      type: 'confirm',
+      name: 'enableChromaDB',
+      message: chromaInstalled
+        ? 'Enable ChromaDB for advanced features?'
+        : 'Enable ChromaDB? (install later: pip install chromadb)',
+      initial: chromaInstalled
+    })
+
+    // Step 6: Review
+    console.log(stepIndicator(6, 6, 'Review Configuration'))
     await transition()
 
     const answers: SetupAnswers = {
       vaultPath: finalVaultPath,
       logLevel: loggingAnswers.logLevel ?? 'warn',
       enableFileWatch: featureAnswers.enableFileWatch ?? true,
+      enableChromaDB: chromaAnswers.enableChromaDB ?? false,
       createSampleProject: featureAnswers.createSampleProject ?? true,
       installClaudeMd: featureAnswers.installClaudeMd ?? true,
     }
@@ -143,6 +171,7 @@ export class SetupWizard {
       { label: 'Vault Path', value: answers.vaultPath, status: 'success' },
       { label: 'Log Level', value: answers.logLevel, status: 'info' },
       { label: 'File Watching', value: answers.enableFileWatch ? 'Enabled' : 'Disabled', status: answers.enableFileWatch ? 'success' : 'warning' },
+      { label: 'ChromaDB', value: answers.enableChromaDB ? 'Enabled' : 'Disabled', status: answers.enableChromaDB ? 'success' : 'warning' },
       { label: 'Sample Project', value: answers.createSampleProject ? 'Yes' : 'No', status: 'info' },
       { label: 'Install CLAUDE.md', value: answers.installClaudeMd ? 'Yes' : 'No', status: 'info' },
     ]))
@@ -191,11 +220,31 @@ export class SetupWizard {
     return locations
   }
 
+  private isChromaInstalled(): boolean {
+    try {
+      execSync('chroma --version', { stdio: 'pipe', timeout: 5000 })
+      return true
+    } catch {
+      return false
+    }
+  }
+
   async applyConfiguration(answers: SetupAnswers): Promise<void> {
     console.log('\n' + heading('Applying configuration...') + '\n')
 
     const homePaths = getHomePaths()
 
+    const chromaEnvLines = answers.enableChromaDB
+      ? [
+          '',
+          '# ChromaDB Configuration',
+          'CHROMA_MODE=client-server',
+          'CHROMA_HOST=localhost',
+          'CHROMA_PORT=8000',
+          'CHROMA_EMBEDDING_PROVIDER=transformers',
+        ].join('\n')
+      : ''
+
     const envContent = `# Claude Brain Configuration
 VAULT_PATH=${answers.vaultPath}
 LOG_LEVEL=${answers.logLevel}
@@ -203,6 +252,7 @@ ENABLE_FILE_WATCH=${answers.enableFileWatch}
 DB_PATH=./data/memory.db
 LOG_FILE_PATH=./logs/claude-brain.log
 SERVER_NAME=claude-brain
+${chromaEnvLines}
 `
 
     await withSpinner('Writing .env configuration', async () => {
@@ -211,6 +261,7 @@ SERVER_NAME=claude-brain
 
     await withSpinner('Creating data and log directories', async () => {
       await fs.mkdir(homePaths.data, { recursive: true })
+      await fs.mkdir(homePaths.chroma, { recursive: true })
       await fs.mkdir(homePaths.logs, { recursive: true })
     })
 
@@ -229,16 +280,35 @@ SERVER_NAME=claude-brain
       }
     }
 
-    console.log()
-    console.log(box([
+    const nextSteps: string[] = [
       heading('Setup complete!'),
       '',
       dimText('Next steps:'),
       `  ${theme.primary('1.')} ${theme.bold('claude-brain install')}`,
       `     ${dimText('Register as MCP server')}`,
-      `  ${theme.primary('2.')} ${theme.bold('claude-brain health')}`,
-      `     ${dimText('Verify everything works')}`,
-    ].join('\n'), 'Done'))
+    ]
+
+    if (answers.enableChromaDB) {
+      nextSteps.push(
+        `  ${theme.primary('2.')} ${theme.bold('claude-brain chroma install')}`,
+        `     ${dimText('Install ChromaDB (if not already installed)')}`,
+        `  ${theme.primary('3.')} ${theme.bold('claude-brain chroma start')}`,
+        `     ${dimText('Start the ChromaDB server')}`,
+        `  ${theme.primary('4.')} ${theme.bold('claude-brain health')}`,
+        `     ${dimText('Verify everything works')}`,
+      )
+    } else {
+      nextSteps.push(
+        `  ${theme.primary('2.')} ${theme.bold('claude-brain health')}`,
+        `     ${dimText('Verify everything works')}`,
+        '',
+        dimText('Optional: Enable ChromaDB later for advanced features:'),
+        `  ${dimText('claude-brain chroma install && claude-brain chroma start')}`,
+      )
+    }
+
+    console.log()
+    console.log(box(nextSteps.join('\n'), 'Done'))
     console.log()
   }