claude-brain 0.4.1 → 0.5.1

package/VERSION

@@ -1 +1 @@
-0.4.1
+0.5.1

package/package.json

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

package/src/cli/bin.ts

@@ -26,6 +26,7 @@ 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'],
@@ -55,12 +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 chroma start')}    ${dimText('Start ChromaDB server')}`,
-    `  ${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/')}`,
@@ -74,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()

package/src/cli/commands/chroma.ts

@@ -25,18 +25,111 @@ function getChromaDataPath(): string {
   return paths.chroma
 }
 
-function isChromaCliInstalled(): boolean {
+/**
+ * Find the chroma binary - checks PATH first, then common pip install locations
+ */
+function findChromaBinary(): string | null {
+  const isWindows = process.platform === 'win32'
+  const chromaName = isWindows ? 'chroma.exe' : 'chroma'
+
+  // Try bare 'chroma' first (on PATH)
   try {
     execSync('chroma --version', { stdio: 'pipe', timeout: 5000 })
-    return true
-  } catch {
-    return false
+    return 'chroma'
+  } catch {}
+
+  const { homedir } = require('os')
+  const home = homedir()
+
+  // Platform-specific search paths
+  const candidates: string[] = isWindows
+    ? [
+        // Windows pip install locations
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python39', 'Scripts', chromaName),
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python310', 'Scripts', chromaName),
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python311', 'Scripts', chromaName),
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python312', 'Scripts', chromaName),
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python313', 'Scripts', chromaName),
+        // Windows user pip install (pip install --user)
+        join(home, 'AppData', 'Roaming', 'Python', 'Python39', 'Scripts', chromaName),
+        join(home, 'AppData', 'Roaming', 'Python', 'Python310', 'Scripts', chromaName),
+        join(home, 'AppData', 'Roaming', 'Python', 'Python311', 'Scripts', chromaName),
+        join(home, 'AppData', 'Roaming', 'Python', 'Python312', 'Scripts', chromaName),
+        join(home, 'AppData', 'Roaming', 'Python', 'Python313', 'Scripts', chromaName),
+        // Scoop / Chocolatey / winget
+        join(home, 'scoop', 'shims', chromaName),
+        'C:\\Python39\\Scripts\\' + chromaName,
+        'C:\\Python310\\Scripts\\' + chromaName,
+        'C:\\Python311\\Scripts\\' + chromaName,
+        'C:\\Python312\\Scripts\\' + chromaName,
+        'C:\\Python313\\Scripts\\' + chromaName,
+      ]
+    : [
+        // macOS pip install locations
+        join(home, 'Library', 'Python', '3.9', 'bin', chromaName),
+        join(home, 'Library', 'Python', '3.10', 'bin', chromaName),
+        join(home, 'Library', 'Python', '3.11', 'bin', chromaName),
+        join(home, 'Library', 'Python', '3.12', 'bin', chromaName),
+        join(home, 'Library', 'Python', '3.13', 'bin', chromaName),
+        // Linux pip install locations
+        join(home, '.local', 'bin', chromaName),
+        '/usr/local/bin/' + chromaName,
+        '/opt/homebrew/bin/' + chromaName,
+      ]
+
+  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 (works on all platforms)
+  const pythonCmd = isWindows ? 'python' : 'python3'
+  try {
+    const sitePackages = execSync(`${pythonCmd} -c "import site; print(site.getusersitepackages())"`, {
+      encoding: 'utf-8', stdio: 'pipe', timeout: 5000
+    }).trim()
+
+    let binDir: string
+    if (isWindows) {
+      // Windows: C:\Users\x\AppData\Roaming\Python\Python311\site-packages → Scripts
+      binDir = sitePackages.replace(/[\\\/]site-packages$/, '\\Scripts')
+    } else {
+      // Unix: /Users/x/Library/Python/3.9/lib/python/site-packages → bin
+      binDir = sitePackages.replace(/\/lib\/.*/, '/bin')
+    }
+
+    const chromaPath = join(binDir, chromaName)
+    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('chroma --version', { encoding: 'utf-8', stdio: 'pipe', timeout: 5000 }).trim()
+    return execSync(`"${binary}" --version`, { encoding: 'utf-8', stdio: 'pipe', timeout: 5000 }).trim()
   } catch {
     return 'unknown'
   }
@@ -75,15 +168,17 @@ function getRunningPid(): number | null {
 }
 
 function isChromaReachable(): boolean {
-  try {
-    execSync(`curl -sf http://localhost:${DEFAULT_PORT}/api/v1/heartbeat`, {
-      stdio: 'pipe',
-      timeout: 3000
-    })
-    return true
-  } catch {
-    return false
+  // 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> {
@@ -112,8 +207,9 @@ async function chromaStart(): Promise<void> {
   }
 
   // Check if chroma CLI is installed
-  if (!isChromaCliInstalled()) {
-    console.log(errorText('ChromaDB CLI is not 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')}`)
@@ -126,12 +222,13 @@ async function chromaStart(): Promise<void> {
 
   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('chroma', ['run', '--path', dataPath, '--port', DEFAULT_PORT], {
+  const child = spawn(chromaBinary, ['run', '--path', dataPath, '--port', DEFAULT_PORT], {
     detached: true,
     stdio: ['ignore', 'pipe', 'pipe'],
     env: { ...process.env }
@@ -375,6 +472,75 @@ function printChromaHelp(): void {
   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> {

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.1',
+  serverVersion: '0.5.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.1'),
+  serverVersion: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semver format').default('0.5.1'),
 
   /** Logging level */
   logLevel: LogLevelSchema.default('info'),

package/src/memory/chroma/client.ts

@@ -29,8 +29,12 @@ export class ChromaClientManager {
 
       switch (this.config.mode) {
         case 'persistent':
+          // ChromaDB v3.x no longer supports embedded persistent mode via 'path'.
+          // Fall through to client-server connecting to localhost.
+          this.logger.info('Persistent mode: connecting to ChromaDB server on localhost (v3.x requires a running server)')
           this.client = new ChromaClient({
-            path: this.config.path,
+            host: this.config.host || 'localhost',
+            port: this.config.port || 8000,
             ...authConfig
           })
           break
@@ -88,7 +92,7 @@ export class ChromaClientManager {
       }
 
     } catch (error) {
-      this.logger.error({ error }, 'Failed to initialize ChromaDB client')
+      this.logger.warn({ error }, 'ChromaDB not available, will use SQLite fallback')
       throw error
     }
   }

package/src/memory/chroma/index.ts

@@ -54,7 +54,7 @@ export class ChromaManager {
       this.logger.info('ChromaDB initialized successfully')
 
     } catch (error) {
-      this.logger.error({ error }, 'Failed to initialize ChromaDB')
+      this.logger.warn({ error }, 'ChromaDB unavailable')
       throw error
     }
   }

package/src/memory/chroma/store.ts

@@ -6,6 +6,25 @@ import type { DecisionMetadata, MemoryMetadata } from './schemas'
 import type { EmbeddingProvider } from './embeddings'
 import type { SearchResult } from './search'
 
+/**
+ * Sanitize metadata for ChromaDB v3.x compatibility.
+ * Strips undefined/null values (ChromaDB only accepts string, number, boolean).
+ */
+function sanitizeMetadata(metadata: Record<string, any>): Record<string, string | number | boolean> {
+  const clean: Record<string, string | number | boolean> = {}
+  for (const [key, value] of Object.entries(metadata)) {
+    if (value === undefined || value === null) continue
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      clean[key] = value
+    } else if (Array.isArray(value)) {
+      clean[key] = JSON.stringify(value)
+    } else {
+      clean[key] = String(value)
+    }
+  }
+  return clean
+}
+
 export interface StoreDecisionInput {
   project: string
   context: string
@@ -145,7 +164,7 @@ export class ChromaMemoryStore {
       await collection.add({
         ids: [id],
         documents: [input.decision],
-        metadatas: [metadata as Record<string, any>],
+        metadatas: [sanitizeMetadata(metadata as Record<string, any>)],
         ...(embeddings ? { embeddings } : {})
       })
 
@@ -166,7 +185,7 @@ export class ChromaMemoryStore {
         await memoriesCollection.add({
           ids: [id], // Use same ID for cross-reference
           documents: [memoryContent],
-          metadatas: [memoryMetadata],
+          metadatas: [sanitizeMetadata(memoryMetadata)],
           ...(embeddings ? { embeddings } : {})
         })
 
@@ -230,7 +249,7 @@ export class ChromaMemoryStore {
       await collection.add({
         ids: [id],
         documents: [input.description],
-        metadatas: [metadata],
+        metadatas: [sanitizeMetadata(metadata)],
         ...(embeddings ? { embeddings } : {})
       })
 
@@ -252,7 +271,7 @@ export class ChromaMemoryStore {
         await memoriesCollection.add({
           ids: [id],
           documents: [memoryContent],
-          metadatas: [memoryMetadata],
+          metadatas: [sanitizeMetadata(memoryMetadata)],
           ...(embeddings ? { embeddings } : {})
         })
 
@@ -304,7 +323,7 @@ export class ChromaMemoryStore {
       await collection.add({
         ids: [id],
         documents: [input.correction],
-        metadatas: [metadata],
+        metadatas: [sanitizeMetadata(metadata)],
         ...(embeddings ? { embeddings } : {})
       })
 
@@ -325,7 +344,7 @@ export class ChromaMemoryStore {
         await memoriesCollection.add({
           ids: [id],
           documents: [memoryContent],
-          metadatas: [memoryMetadata],
+          metadatas: [sanitizeMetadata(memoryMetadata)],
           ...(embeddings ? { embeddings } : {})
         })
 
@@ -367,7 +386,7 @@ export class ChromaMemoryStore {
       await collection.add({
         ids: [id],
         documents: [input.content],
-        metadatas: [metadata as Record<string, any>],
+        metadatas: [sanitizeMetadata(metadata as Record<string, any>)],
         ...(embeddings ? { embeddings } : {})
       })
 
@@ -409,7 +428,7 @@ export class ChromaMemoryStore {
       await collection.upsert({
         ids: [id],
         documents: [input.decision],
-        metadatas: [metadata as Record<string, any>],
+        metadatas: [sanitizeMetadata(metadata as Record<string, any>)],
         ...(embeddings ? { embeddings } : {})
       })
 

package/src/memory/index.ts

@@ -381,6 +381,97 @@ export class MemoryManager {
     return this.store.searchCorrections('', { limit: options?.limit || 10 })
   }
 
+  /**
+   * Fetch all decisions with content — routes to ChromaDB or SQLite
+   * Used by analytical tools that need bulk access to decision data
+   */
+  async fetchAllDecisions(project?: string): Promise<any[]> {
+    if (this.useChromaDB) {
+      try {
+        const results = await this.chroma.collections.decisions.get({
+          where: project ? { project } : undefined
+        })
+        if (results && results.ids) {
+          return results.ids.map((id: string, i: number) => ({
+            id,
+            content: results.documents?.[i] || '',
+            date: results.metadatas?.[i]?.created_at || new Date().toISOString(),
+            project: results.metadatas?.[i]?.project || project || 'unknown',
+            context: results.metadatas?.[i]?.context || '',
+            decision: results.metadatas?.[i]?.decision || results.documents?.[i] || '',
+            reasoning: results.metadatas?.[i]?.reasoning || '',
+            alternatives: results.metadatas?.[i]?.alternatives_considered || '',
+            tags: results.metadatas?.[i]?.tags || []
+          }))
+        }
+        return []
+      } catch (error) {
+        this.logger.warn({ error }, 'ChromaDB fetchAllDecisions failed, falling back to SQLite')
+      }
+    }
+    return this.store.getAllDecisionsWithContent(project)
+  }
+
+  /**
+   * Fetch all patterns with content — routes to ChromaDB or SQLite
+   */
+  async fetchAllPatterns(project?: string): Promise<any[]> {
+    if (this.useChromaDB) {
+      try {
+        const results = await this.chroma.collections.patterns.get({
+          where: project ? { project } : undefined
+        })
+        if (results && results.ids) {
+          return results.ids.map((id: string, i: number) => ({
+            id,
+            content: results.documents?.[i] || '',
+            date: results.metadatas?.[i]?.created_at || new Date().toISOString(),
+            project: results.metadatas?.[i]?.project || project || 'unknown',
+            pattern_type: results.metadatas?.[i]?.pattern_type || '',
+            description: results.metadatas?.[i]?.description || results.documents?.[i] || '',
+            example: results.metadatas?.[i]?.example || '',
+            confidence: results.metadatas?.[i]?.confidence || 0,
+            context: results.metadatas?.[i]?.context || ''
+          }))
+        }
+        return []
+      } catch (error) {
+        this.logger.warn({ error }, 'ChromaDB fetchAllPatterns failed, falling back to SQLite')
+      }
+    }
+    return this.store.getAllPatternsWithContent(project)
+  }
+
+  /**
+   * Fetch all corrections with content — routes to ChromaDB or SQLite
+   */
+  async fetchAllCorrections(project?: string): Promise<any[]> {
+    if (this.useChromaDB) {
+      try {
+        const results = await this.chroma.collections.corrections.get({
+          where: project ? { project } : undefined
+        })
+        if (results && results.ids) {
+          return results.ids.map((id: string, i: number) => ({
+            id,
+            content: results.documents?.[i] || '',
+            date: results.metadatas?.[i]?.created_at || new Date().toISOString(),
+            project: results.metadatas?.[i]?.project || project || 'unknown',
+            original: results.metadatas?.[i]?.original || '',
+            correction: results.metadatas?.[i]?.correction || results.documents?.[i] || '',
+            reasoning: results.metadatas?.[i]?.reasoning || '',
+            context: results.metadatas?.[i]?.context || '',
+            confidence: results.metadatas?.[i]?.confidence || 0
+          }))
+        }
+        return []
+      } catch (error) {
+        this.logger.warn({ error }, 'ChromaDB fetchAllCorrections failed, falling back to SQLite')
+      }
+    }
+    return this.store.getAllCorrectionsWithContent(project)
+  }
+
   /**
    * Search patterns by query — routes to ChromaDB or SQLite
    */