claude-brain 0.4.0 → 0.5.0

package/VERSION

@@ -1 +1 @@
-0.4.0
+0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-brain",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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

@@ -26,11 +26,13 @@ function printHelp() {
   console.log()
 
   const commands = [
+    ['start', 'Start ChromaDB + MCP server'],
     ['serve', 'Start the MCP server (default)'],
     ['setup', 'Run interactive setup wizard'],
     ['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'],
@@ -54,11 +56,11 @@ function printHelp() {
     `  ${theme.primary('-h'.padEnd(12))} ${dimText('Show help')}`,
     '',
     theme.bold('Examples:'),
-    `  ${dimText('claude-brain')}                 ${dimText('Start MCP server')}`,
-    `  ${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 health')}          ${dimText('Check system health')}`,
+    `  ${dimText('claude-brain start')}            ${dimText('Start ChromaDB + MCP server')}`,
+    `  ${dimText('claude-brain start --chroma-only')} ${dimText('Start only ChromaDB')}`,
+    `  ${dimText('claude-brain setup')}            ${dimText('Configure Claude Brain')}`,
+    `  ${dimText('claude-brain install')}          ${dimText('Register with Claude Code')}`,
+    `  ${dimText('claude-brain health')}           ${dimText('Check system health')}`,
     '',
     theme.bold('Environment:'),
     `  ${theme.primary('CLAUDE_BRAIN_HOME')}   ${dimText('Override home directory (default: ~/.claude-brain/')}`,
@@ -72,6 +74,12 @@ async function main() {
   const command = process.argv[2] || 'serve'
 
   switch (command) {
+    case 'start': {
+      const { runStart } = await import('./commands/start')
+      await runStart()
+      break
+    }
+
     case 'serve': {
       const { runServe } = await import('./commands/serve')
       await runServe()
@@ -102,6 +110,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,537 @@
+/**
+ * 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
+}
+
+/**
+ * Find the chroma binary - checks PATH first, then common pip install locations
+ */
+function findChromaBinary(): string | null {
+  // Try bare 'chroma' first (on PATH)
+  try {
+    execSync('chroma --version', { stdio: 'pipe', timeout: 5000 })
+    return 'chroma'
+  } catch {}
+
+  // Search common pip install locations
+  const { homedir } = require('os')
+  const home = homedir()
+  const candidates = [
+    join(home, 'Library', 'Python', '3.9', 'bin', 'chroma'),
+    join(home, 'Library', 'Python', '3.10', 'bin', 'chroma'),
+    join(home, 'Library', 'Python', '3.11', 'bin', 'chroma'),
+    join(home, 'Library', 'Python', '3.12', 'bin', 'chroma'),
+    join(home, 'Library', 'Python', '3.13', 'bin', 'chroma'),
+    join(home, '.local', 'bin', 'chroma'),
+    '/usr/local/bin/chroma',
+    '/opt/homebrew/bin/chroma',
+  ]
+
+  for (const candidate of candidates) {
+    try {
+      if (existsSync(candidate)) {
+        execSync(`"${candidate}" --version`, { stdio: 'pipe', timeout: 5000 })
+        return candidate
+      }
+    } catch {}
+  }
+
+  // Try finding via python -m site
+  try {
+    const sitePackages = execSync('python3 -c "import site; print(site.getusersitepackages())"', {
+      encoding: 'utf-8', stdio: 'pipe', timeout: 5000
+    }).trim()
+    // User site-packages is like /Users/x/Library/Python/3.9/lib/python/site-packages
+    // The bin is at the same level as lib
+    const binDir = sitePackages.replace(/\/lib\/.*/, '/bin')
+    const chromaPath = join(binDir, 'chroma')
+    if (existsSync(chromaPath)) {
+      execSync(`"${chromaPath}" --version`, { stdio: 'pipe', timeout: 5000 })
+      return chromaPath
+    }
+  } catch {}
+
+  return null
+}
+
+let _cachedChromaBinary: string | null | undefined = undefined
+
+function getChromaBinary(): string | null {
+  if (_cachedChromaBinary === undefined) {
+    _cachedChromaBinary = findChromaBinary()
+  }
+  return _cachedChromaBinary
+}
+
+function isChromaCliInstalled(): boolean {
+  return getChromaBinary() !== null
+}
+
+function getChromaVersion(): string {
+  const binary = getChromaBinary()
+  if (!binary) return 'unknown'
+  try {
+    return execSync(`"${binary}" --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 v2 API first (ChromaDB 1.x server), then v1 (older servers)
+  for (const apiVersion of ['v2', 'v1']) {
+    try {
+      execSync(`curl -sf http://localhost:${DEFAULT_PORT}/api/${apiVersion}/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
+  const chromaBinary = getChromaBinary()
+  if (!chromaBinary) {
+    console.log(errorText('ChromaDB CLI is not installed or not found on PATH.'))
+    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(`Binary: ${chromaBinary}`))
+  console.log(dimText(`Data path: ${dataPath}`))
+  console.log(dimText(`Port: ${DEFAULT_PORT}`))
+  console.log()
+
+  // Start ChromaDB server in background
+  const child = spawn(chromaBinary, ['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()
+}
+
+// ── Auto-start for serve command ──────────────────────────
+
+/**
+ * Ensures ChromaDB is running before the MCP server starts.
+ * Returns true if ChromaDB is reachable after this call, false otherwise.
+ * Designed to be called from serve.ts — does not call process.exit().
+ */
+export async function ensureChromaRunning(options?: { silent?: boolean }): Promise<boolean> {
+  const log = options?.silent ? () => {} : console.error.bind(console)
+
+  // Already running? Great.
+  if (isChromaReachable()) {
+    return true
+  }
+
+  // Already managed by us but not responding? Clean up stale PID.
+  const stalePid = getRunningPid()
+  if (stalePid) {
+    try {
+      process.kill(stalePid, 'SIGTERM')
+      await sleep(1000)
+    } catch {}
+    try { unlinkSync(getPidFilePath()) } catch {}
+  }
+
+  const chromaBinary = getChromaBinary()
+  if (!chromaBinary) {
+    log('[ChromaDB] Not installed — running with SQLite fallback.')
+    log('[ChromaDB] Install with: claude-brain chroma install')
+    return false
+  }
+
+  const dataPath = getChromaDataPath()
+  log(`[ChromaDB] Starting server (port ${DEFAULT_PORT})...`)
+
+  const child = spawn(chromaBinary, ['run', '--path', dataPath, '--port', DEFAULT_PORT], {
+    detached: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env }
+  })
+
+  const pid = child.pid
+  if (!pid) {
+    log('[ChromaDB] Failed to spawn server process.')
+    return false
+  }
+
+  child.unref()
+  writeFileSync(getPidFilePath(), String(pid), 'utf-8')
+
+  // Wait for server to become reachable (up to 15 seconds)
+  for (let i = 0; i < 30; i++) {
+    await sleep(500)
+    if (isChromaReachable()) {
+      log(`[ChromaDB] Server started (PID: ${pid})`)
+      return true
+    }
+    // Check if process died
+    try {
+      process.kill(pid, 0)
+    } catch {
+      break
+    }
+  }
+
+  log('[ChromaDB] Server started but not yet responding — will retry connection during initialization.')
+  return isChromaReachable()
+}
+
+// ── 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/cli/commands/serve.ts

@@ -5,6 +5,7 @@ import { ClaudeBrainMCPServer } from '@/server'
 import { initializeServices, shutdownServices, getVaultService, getMemoryService } from '@/server/services'
 import { createOrchestrator, type Orchestrator } from '@/orchestrator'
 import { ensureHomeDirectory } from '@/cli/auto-setup'
+import { ensureChromaRunning } from '@/cli/commands/chroma'
 
 const BANNER = `
 ╔═══════════════════════════════════════════════════════╗
@@ -42,6 +43,11 @@ export async function runServe() {
     cacheSize: config.cacheSize
   }, 'Configuration loaded')
 
+  // Auto-start ChromaDB if not already running
+  mainLogger.info('Ensuring ChromaDB is available...')
+  const chromaReady = await ensureChromaRunning({ silent: process.env.NODE_ENV === 'production' })
+  mainLogger.info({ chromaReady }, chromaReady ? 'ChromaDB is ready' : 'ChromaDB not available, using SQLite fallback')
+
   mainLogger.info('Initializing services...')
   await initializeServices(config, logger)
   mainLogger.info('Services initialized successfully')

package/src/cli/commands/start.ts

@@ -0,0 +1,42 @@
+/**
+ * Start Command
+ * Starts ChromaDB + MCP server together, or just ChromaDB with --chroma-only
+ *
+ * Usage:
+ *   claude-brain start              Start ChromaDB + MCP server
+ *   claude-brain start --chroma-only  Start only ChromaDB server
+ */
+
+import {
+  heading, successText, warningText, dimText,
+} from '@/cli/ui/index.js'
+import { ensureChromaRunning } from '@/cli/commands/chroma'
+
+export async function runStart(): Promise<void> {
+  const chromaOnly = process.argv.includes('--chroma-only')
+
+  if (chromaOnly) {
+    console.log()
+    console.log(heading('Starting ChromaDB'))
+    console.log()
+
+    const chromaReady = await ensureChromaRunning()
+    console.log()
+
+    if (chromaReady) {
+      console.log(successText('ChromaDB is running and ready.'))
+    } else {
+      console.log(warningText('ChromaDB could not be started. Check installation with: claude-brain chroma status'))
+    }
+    console.log()
+    return
+  }
+
+  // Full start: ChromaDB + MCP server
+  // serve.ts already calls ensureChromaRunning(), so just delegate
+  console.error(dimText('Starting ChromaDB + MCP server...'))
+  console.error()
+
+  const { runServe } = await import('./serve')
+  await runServe()
+}

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.5.0',
   logLevel: 'info',
   logFilePath: './logs/claude-brain.log',
   dbPath: './data/memory.db',