claude-brain 0.29.2 → 0.30.1

package/VERSION

@@ -1 +1 @@
-0.29.2
+0.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-brain",
-  "version": "0.29.2",
+  "version": "0.30.1",
   "description": "Local development assistant bridging Obsidian vaults with Claude Code via MCP",
   "type": "module",
   "main": "src/index.ts",
@@ -9,9 +9,11 @@
   },
   "files": [
     "src/**/*.ts",
+    "src/intelligence/hf-manifest.json",
     "src/hooks/claude-code-mastery.md",
     "scripts/postinstall.mjs",
     "packs/",
+    "skills/",
     "assets/",
     "package.json",
     "tsconfig.json",

package/skills/persistent-memory/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: persistent-memory
+description: Persistent memory management for Claude sessions using the brain MCP tool. Use when starting a work session, making architectural decisions, learning from mistakes, ending a session, or when user says "remember this", "what do I know about", "recall", "brain", or "session summary". Also use when searching code symbols, files, or dependencies with search_code.
+license: MIT
+metadata:
+  author: claude-brain
+  version: 1.0.0
+  mcp-server: claude-brain
+  category: productivity
+  tags: [memory, persistence, decisions, context, code-intelligence]
+---
+
+# Persistent Memory
+
+Manage persistent memory across Claude sessions using the `brain` and `search_code` MCP tools. Memory persists between conversations — decisions, lessons, and context survive session boundaries.
+
+## Critical Rules
+
+- The `brain` tool auto-classifies intent. Most of the time, just pass a natural language message — don't force an action unless you have a reason.
+- Do NOT store file paths, "read file X" events, or progress like "ran tests" — these are too granular and captured automatically by hooks.
+- DO store the WHY — reasoning behind decisions, user preferences, lessons learned from debugging.
+- Use the `project` parameter to scope memories to the right project. If omitted, it's auto-detected from the message.
+
+## Session Workflow
+
+### Step 1: Session Start — Recall Context
+
+At the beginning of significant work, recall what you know:
+
+```
+brain("What do I know about this project?")
+```
+
+This returns past decisions, preferences, patterns, and lessons. Use it to avoid re-asking questions the user already answered in previous sessions.
+
+Expected output: A summary of stored memories with relevance scores.
+
+### Step 2: During Work — Store Decisions and Lessons
+
+Store when you encounter something worth remembering:
+
+**Decisions:**
+```
+brain("Decided to use JWT over sessions because the app is stateless")
+```
+
+**Mistakes and fixes:**
+```
+brain("The bug was caused by missing CORS credentials — fixed with credentials: include")
+```
+
+**User preferences:**
+```
+brain("User prefers explicit error messages over generic 500s")
+```
+
+**Architecture changes:**
+```
+brain("Changed database from MySQL to Postgres for better JSON support")
+```
+
+### Step 3: Session End — Summarize
+
+Before finishing significant work, store a 2-3 sentence summary:
+
+```
+brain("Session summary: Built auth flow for expense tracker. Chose JWT for stateless architecture. Hit CORS issue on /api/login, fixed with credentials: include.")
+```
+
+## Using search_code
+
+The `search_code` tool searches indexed code — faster than grep for large projects.
+
+**Search symbols (functions, classes, types):**
+```
+search_code({ query: "handleAuth", project: "my-app" })
+```
+
+**Search files by name:**
+```
+search_code({ query: "config", project: "my-app", type: "files" })
+```
+
+**Show dependencies of a file:**
+```
+search_code({ query: "deps", project: "my-app", type: "dependencies", file_path: "src/auth.ts" })
+```
+
+If search returns no results, the project may need indexing. Run `claude-brain reindex` first.
+
+## Advanced Patterns
+
+### Updating Past Memories
+When a previous decision changes:
+```
+brain({ message: "Changed my mind — use Postgres instead of MySQL", action: "update" })
+```
+
+### Getting Full Details
+Search returns compact summaries. For the full stored content:
+```
+brain("details 42")
+```
+where 42 is the memory ID from a previous search result.
+
+### Deleting Outdated Memories
+```
+brain({ message: "delete memory about MySQL choice", action: "delete" })
+```
+
+### Scoping to Projects
+Always pass the project name for multi-project work:
+```
+brain({ message: "Chose Tailwind for styling", project: "expense-tracker" })
+```
+
+## What to Store vs. Skip
+
+### Store These
+- Architectural decisions and their reasoning
+- User preferences for tools, style, workflow
+- Solutions to hard debugging problems
+- Patterns confirmed across multiple sessions
+- Key file paths and project structure insights
+
+### Skip These
+- File read/write events (captured by hooks)
+- "Ran tests" / "built successfully" (too granular)
+- Anything already in CLAUDE.md or the codebase
+- Speculative conclusions from reading a single file
+
+## Troubleshooting
+
+### brain tool returns "no relevant memories"
+**Cause:** No memories stored yet, or query doesn't match stored content.
+**Solution:** Try broader phrasing. Use `brain("list all memories for project X")` to see what's stored.
+
+### search_code returns empty results
+**Cause:** Project not indexed.
+**Solution:** Run `claude-brain reindex` in terminal, then retry.
+
+### Memories scoped to wrong project
+**Cause:** Project name not specified or auto-detected incorrectly.
+**Solution:** Always pass `project` parameter explicitly for multi-project work.
+
+### brain tool seems slow
+**Cause:** Large memory database or complex semantic search.
+**Solution:** Use more specific queries. Scope to a project to narrow search space.

package/skills/persistent-memory/references/tool-reference.md

@@ -0,0 +1,90 @@
+# Tool Reference
+
+Complete parameter reference for the brain and search_code MCP tools.
+
+## brain
+
+Your persistent memory. Tell it decisions, ask it questions, or update/delete past notes.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `message` | string | Yes | What you are doing, decided, learned, or need. Natural language. |
+| `project` | string | No | Project name to scope memories (e.g., "my-app"). Auto-detected if omitted. |
+| `action` | enum | No | Force action: `auto`, `store`, `recall`, `update`, `delete`. Default: `auto`. |
+
+### Intent Classification
+
+When `action` is `auto` (default), the tool classifies your message into one of these intents:
+
+- **session_start** — "What do I know about X?" / beginning of session
+- **decision_made** — "Decided to use X because Y"
+- **store_this** — "Remember that..." / storing information
+- **pattern_found** — "I noticed a pattern where..."
+- **mistake_learned** — "The bug was X, fixed by Y"
+- **question** — "What was the reason for X?"
+- **context_needed** — Requesting stored context
+- **update_memory** — Changing a previous memory
+- **delete_memory** — Removing a memory
+- **detail_request** — "details {ID}" for full content
+- **list_all** — "list all memories" / "show everything"
+- **timeline** — "show history" / "what happened when"
+- **comparison** — "compare X vs Y decisions"
+- **exploration** — Open-ended exploration of stored knowledge
+- **progress_update** — "Completed X, next steps Y"
+
+### Response Format
+
+```json
+{
+  "action": "stored | retrieved | updated | deleted | none",
+  "summary": "Brief description of what happened",
+  "content": "Full response with details",
+  "relevantItems": 5
+}
+```
+
+## search_code
+
+Search indexed code for symbols, files, or dependencies. Faster than grep for indexed projects.
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | string | Yes | — | Symbol name, file name, or search term |
+| `project` | string | Yes | — | Project name (usually directory name) |
+| `type` | enum | No | `symbols` | `symbols`, `files`, or `dependencies` |
+| `file_path` | string | No* | — | Required when type is `dependencies` |
+| `limit` | number | No | 20 | Max results (1-100) |
+
+### Search Types
+
+**symbols** (default): Search functions, classes, types, interfaces by name.
+```
+search_code({ query: "UserService", project: "my-app" })
+```
+
+**files**: Search for files by name pattern.
+```
+search_code({ query: "middleware", project: "my-app", type: "files" })
+```
+
+**dependencies**: Show imports and imported-by for a specific file.
+```
+search_code({ query: "deps", project: "my-app", type: "dependencies", file_path: "src/auth/service.ts" })
+```
+
+### Supported File Types
+
+`.ts .tsx .js .jsx .mjs .cjs .py .go .rs .vue .html .css .json .yaml .yml`
+
+### Indexing
+
+If search returns no results, the project needs indexing:
+```bash
+claude-brain reindex
+```
+
+This parses the codebase using tree-sitter and stores symbols in SQLite for fast lookup.

package/src/cli/commands/models.ts

@@ -16,10 +16,13 @@ import { join } from 'node:path'
 import { homedir } from 'node:os'
 import { parseArgs } from 'citty'
 import { renderLogo, theme, heading, dimText, successText, warningText, errorText, box, summaryPanel } from '@/cli/ui/index.js'
+import { progressBar } from '@/cli/ui/components.js'
 import { getHomePaths, getClaudeBrainHome } from '@/config/home'
 import { getTrainingStats, type TrainingTask } from '@/training/data-store'
 import type { ModelManifest, ModelManifestEntry, ModelTask } from '@/intelligence/model-manager'
 import { shouldRetrain, retrainTask, retrainAll, type RetrainConfig } from '@/training/retrain-pipeline'
+import { downloadFromHuggingFace, type HfManifest } from '@/intelligence/hf-downloader'
+import hfManifestData from '@/intelligence/hf-manifest.json'
 
 const ALL_TASKS: ModelTask[] = ['intent', 'entity', 'query', 'knowledge', 'compress', 'pattern']
 
@@ -38,7 +41,7 @@ export async function runModels() {
     subcommand: { type: 'positional', required: false, description: 'Subcommand: list, status, download, enable, disable, benchmark, stats, retrain' },
     taskArg: { type: 'positional', required: false, description: 'Task name or "all" (for enable/disable/benchmark/retrain)' },
     task: { type: 'string', description: 'Target task (for download --task)' },
-    source: { type: 'string', description: 'Source: local (default) or release' },
+    source: { type: 'string', description: 'Source: local (default) or hf (Hugging Face Hub)' },
     force: { type: 'boolean', description: 'Force retrain even if checks say not needed' },
   })
 
@@ -256,7 +259,7 @@ function loadManifest(): ModelManifest | null {
 
 // ─── download ─────────────────────────────────────────────────────
 
-function downloadModels(taskFilter: string, source: string) {
+async function downloadModels(taskFilter: string, source: string) {
   console.log()
   console.log(renderLogo())
   console.log()
@@ -280,17 +283,9 @@ function downloadModels(taskFilter: string, source: string) {
     console.log(successText(`Created models directory: ${paths.models}`))
   }
 
-  // Release source — not yet implemented
-  if (source === 'release') {
-    console.log(
-      box(
-        'Downloading from release artifacts is not yet available.\n' +
-        'Use --source local to install from ~/slm-training/models/ instead.',
-        'Coming Soon'
-      )
-    )
-    console.log()
-    return
+  // Hugging Face Hub source
+  if (source === 'hf' || source === 'release') {
+    return downloadFromHF(tasks, paths.models)
   }
 
   // Local source — copy from ~/slm-training/models/
@@ -409,6 +404,109 @@ function downloadModels(taskFilter: string, source: string) {
   console.log()
 }
 
+// ─── download from HF ─────────────────────────────────────────────
+
+const isTTY = process.stdout.isTTY === true
+
+async function downloadFromHF(tasks: ModelTask[], modelsDir: string) {
+  const manifest = hfManifestData as HfManifest
+
+  // Compute total download size
+  let totalSize = 0
+  for (const task of tasks) {
+    const entry = manifest.models[task]
+    if (entry) totalSize += entry.size
+  }
+
+  console.log(`  ${dimText('Source:')} Hugging Face Hub (${manifest.hfRepo})`)
+  console.log(`  ${dimText('Target:')} ${modelsDir}`)
+  console.log(`  ${dimText('Models:')} ${tasks.join(', ')}`)
+  console.log(`  ${dimText('Total:')}  ~${formatBytes(totalSize)}`)
+  console.log()
+
+  const results = await downloadFromHuggingFace(manifest, {
+    destDir: modelsDir,
+    tasks,
+    onProgress(task, downloaded, total) {
+      if (isTTY && total > 0) {
+        const pct = (downloaded / total) * 100
+        const bar = progressBar(pct, 25)
+        process.stdout.write(`\r  ${task.padEnd(12)} ${bar}  ${formatBytes(downloaded)} / ${formatBytes(total)}`)
+      }
+    },
+    onComplete(task, bytes) {
+      if (isTTY) process.stdout.write('\r' + ' '.repeat(80) + '\r')
+      console.log(`  ${successText(task.padEnd(12))} ${formatBytes(bytes)} ${dimText('SHA256 verified')}`)
+    },
+    onError(task, error) {
+      if (isTTY) process.stdout.write('\r' + ' '.repeat(80) + '\r')
+      console.log(`  ${errorText(task.padEnd(12))} ${error}`)
+    },
+  })
+
+  console.log()
+
+  const succeeded = results.filter(r => r.success)
+  if (succeeded.length === 0) {
+    console.log(warningText('No models were downloaded.'))
+    console.log()
+    return
+  }
+
+  // Build manifest from downloaded results + existing
+  const manifestPath = join(modelsDir, 'manifest.json')
+  const manifestModels: Partial<Record<ModelTask, ModelManifestEntry>> = {}
+
+  // Preserve existing manifest entries
+  if (existsSync(manifestPath)) {
+    try {
+      const existing: ModelManifest = JSON.parse(readFileSync(manifestPath, 'utf-8'))
+      if (existing.models) Object.assign(manifestModels, existing.models)
+    } catch { /* overwrite corrupt */ }
+  }
+
+  const installedTasks: ModelTask[] = []
+  let totalBytes = 0
+
+  for (const result of succeeded) {
+    const task = result.task as ModelTask
+    const entry = manifest.models[task]
+    if (!entry) continue
+
+    manifestModels[task] = {
+      version: entry.version,
+      file: entry.file,
+      sha256: entry.sha256,
+      params: entry.params,
+      accuracy: entry.accuracy ?? undefined,
+      labels: entry.labels,
+      maxSeqLen: entry.maxSeqLen,
+    }
+    installedTasks.push(task)
+    totalBytes += result.bytes
+  }
+
+  // Write manifest
+  const localManifest: ModelManifest = { models: manifestModels }
+  writeFileSync(manifestPath, JSON.stringify(localManifest, null, 2))
+
+  // Auto-enable models in config
+  const config = loadConfigFile()
+  if (!config.slm) config.slm = {}
+  config.slm.enabled = true
+  if (!config.slm.tasks) config.slm.tasks = {}
+  for (const task of installedTasks) {
+    config.slm.tasks[task] = 'model'
+  }
+  saveConfigFile(config)
+  updateConfigYml(installedTasks, 'model')
+
+  console.log(successText(`Downloaded ${succeeded.length} model${succeeded.length !== 1 ? 's' : ''} (${formatBytes(totalBytes)})`))
+  console.log(successText(`Auto-enabled ${installedTasks.join(', ')} in config`))
+  console.log(dimText(`Manifest written to ${manifestPath}`))
+  console.log()
+}
+
 // ─── enable ───────────────────────────────────────────────────────
 
 function enableTask(taskArg: string) {
@@ -783,7 +881,7 @@ function printModelsHelp() {
   const subcommands = [
     ['list', 'Show installed models and their status'],
     ['status', 'Show inference routing and ONNX runtime status'],
-    ['download', 'Download pre-trained models (--task <task>|all)'],
+    ['download', 'Download models (--source local|hf, --task <task>|all)'],
     ['enable <task|all>', 'Enable model inference for task(s)'],
     ['disable <task|all>', 'Disable model inference for task(s)'],
     ['benchmark <task>', 'Run accuracy benchmark on test data'],
@@ -805,6 +903,9 @@ function printModelsHelp() {
   console.log(theme.bold('Examples:'))
   console.log(`  ${dimText('claude-brain models list')}`)
   console.log(`  ${dimText('claude-brain models status')}`)
+  console.log(`  ${dimText('claude-brain models download --source hf')}`)
+  console.log(`  ${dimText('claude-brain models download --source hf --task intent')}`)
+  console.log(`  ${dimText('claude-brain models download --source local')}`)
   console.log(`  ${dimText('claude-brain models enable all')}`)
   console.log(`  ${dimText('claude-brain models enable intent')}`)
   console.log(`  ${dimText('claude-brain models disable pattern')}`)

package/src/cli/commands/serve.ts

@@ -47,14 +47,21 @@ export async function runServe() {
   return runAsDaemon(httpOnly, pidManager)
 }
 
-/** Check if the daemon at the given port is responsive and initialized */
+/** Check if the daemon at the given port is responsive, initialized, and can serve MCP tools */
 async function isDaemonHealthy(port: number): Promise<boolean> {
   try {
-    const res = await fetch(`http://localhost:${port}/api/health`, {
+    const healthRes = await fetch(`http://localhost:${port}/api/health`, {
       signal: AbortSignal.timeout(2000),
     })
-    const json = await res.json() as any
-    return json.success === true && json.initialized === true
+    const healthJson = await healthRes.json() as any
+    if (healthJson.success !== true || healthJson.initialized !== true) return false
+
+    // Verify MCP proxy endpoints actually work (old versions return 404)
+    const toolsRes = await fetch(`http://localhost:${port}/api/mcp/list-tools`, {
+      signal: AbortSignal.timeout(2000),
+    })
+    const toolsJson = await toolsRes.json() as any
+    return toolsJson.success === true && Array.isArray(toolsJson.data?.tools)
   } catch {
     return false
   }
@@ -93,7 +100,9 @@ async function runAsProxy(daemonPort: number) {
 
   process.on('SIGTERM', () => stopProxy('SIGTERM'))
   process.on('SIGINT', () => stopProxy('SIGINT'))
-  process.on('SIGHUP', () => stopProxy('SIGHUP'))
+  if (process.platform !== 'win32') {
+    process.on('SIGHUP', () => stopProxy('SIGHUP'))
+  }
 
   await proxy.start()
   mainLogger.info('MCP proxy ready — forwarding to daemon')
@@ -382,15 +391,43 @@ async function runAsDaemon(httpOnly: boolean, pidManager: ServerPidManager) {
       } catch (error) {
         mainLogger.debug({ error }, 'No hook queue to drain')
       }
-    } catch (error) {
-      mainLogger.error({ error }, 'Failed to start HTTP API server')
+    } catch (error: any) {
+      // EADDRINUSE: kill the stale process and retry once
+      if (error?.code === 'EADDRINUSE' || String(error).includes('EADDRINUSE')) {
+        mainLogger.warn({ port: config.port }, 'Port in use — killing stale process and retrying')
+        try {
+          const { killProcessOnPort } = await import('@/utils/kill-port')
+          const killed = killProcessOnPort(config.port)
+          if (killed.length > 0) {
+            mainLogger.info({ killed }, 'Killed stale process(es) on port')
+          }
+          await new Promise(r => setTimeout(r, 1000))
+          await httpServer.start()
+          mainLogger.info({ port: config.port }, 'HTTP API server started (after recovery)')
+
+          // Drain hook queue on retry success too
+          try {
+            const { drainQueue } = await import('@/hooks/queue')
+            const drained = await drainQueue(config.port)
+            if (drained > 0) {
+              mainLogger.info({ drained }, 'Drained hook queue')
+            }
+          } catch {}
+        } catch (retryError) {
+          mainLogger.error({ error: retryError }, 'Failed to start HTTP API server after recovery — MCP stdio still works')
+        }
+      } else {
+        mainLogger.error({ error }, 'Failed to start HTTP API server')
+      }
     }
   }, 2000)
 
   // ── Signal handlers ──────────────────────────────────────
   process.on('SIGTERM', () => shutdown('SIGTERM'))
   process.on('SIGINT', () => shutdown('SIGINT'))
-  process.on('SIGHUP', () => shutdown('SIGHUP'))
+  if (process.platform !== 'win32') {
+    process.on('SIGHUP', () => shutdown('SIGHUP'))
+  }
 
   if (httpOnly) {
     // HTTP-only daemon mode: no MCP stdio. Use idle watchdog instead of infinite keepAlive.

package/src/config/schema.ts

@@ -362,6 +362,8 @@ export const ConfigSchema = z.object({
     enabled: z.boolean().default(false),
     /** Directory containing ONNX model files */
     modelsDir: z.string().default('~/.claude-brain/models'),
+    /** Hugging Face repo for downloading pre-trained models */
+    hfRepo: z.string().default('demgun101/claude-brain-models'),
     /** Minimum model confidence to use model prediction (below → regex fallback) */
     confidenceThreshold: z.number().min(0).max(1).default(0.7),
     /** Per-task mode: 'model' uses model only, 'regex' uses regex only, 'both' runs both and logs comparison */

package/src/intelligence/hf-downloader.ts

@@ -0,0 +1,222 @@
+/**
+ * Hugging Face Hub Downloader — streams ONNX models from HF with SHA256 verification.
+ * Atomic writes via temp file + rename. Inline retry with exponential backoff.
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, renameSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ModelTask } from '@/intelligence/model-manager'
+
+export interface HfManifestEntry {
+  file: string
+  metaFile: string
+  sha256: string
+  metaSha256: string
+  size: number
+  version: string
+  params: string
+  accuracy: number | null
+  labels: string[]
+  maxSeqLen: number
+}
+
+export interface HfManifest {
+  hfRepo: string
+  hfBranch: string
+  models: Record<string, HfManifestEntry>
+}
+
+export interface DownloadOptions {
+  /** Target directory to write models into */
+  destDir: string
+  /** Tasks to download (subset of manifest keys) */
+  tasks: ModelTask[]
+  /** HF repo override (default from manifest) */
+  hfRepo?: string
+  /** HF branch override (default from manifest) */
+  hfBranch?: string
+  /** Progress callback: task name, bytes downloaded so far, total bytes */
+  onProgress?: (task: string, downloaded: number, total: number) => void
+  /** Called when a task completes */
+  onComplete?: (task: string, bytes: number) => void
+  /** Called on error */
+  onError?: (task: string, error: string) => void
+}
+
+export interface DownloadResult {
+  task: string
+  success: boolean
+  bytes: number
+  error?: string
+}
+
+const MAX_RETRIES = 3
+const RETRY_DELAYS = [2000, 4000, 8000]
+const DOWNLOAD_TIMEOUT_MS = 300_000 // 5 minutes per file
+
+/**
+ * Build HF resolve URL for a file.
+ * Pattern: https://huggingface.co/{repo}/resolve/{branch}/{filename}
+ */
+function hfUrl(repo: string, branch: string, filename: string): string {
+  return `https://huggingface.co/${repo}/resolve/${branch}/${filename}`
+}
+
+/**
+ * Stream-download a single file with SHA256 verification and atomic write.
+ * Returns the number of bytes written.
+ */
+async function downloadFile(
+  url: string,
+  destPath: string,
+  expectedSha256: string,
+  expectedSize: number,
+  onProgress?: (downloaded: number, total: number) => void,
+): Promise<number> {
+  const tempPath = `${destPath}.download`
+
+  // Clean up any leftover temp file
+  if (existsSync(tempPath)) {
+    unlinkSync(tempPath)
+  }
+
+  const response = await fetch(url, {
+    signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+  })
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+  }
+
+  if (!response.body) {
+    throw new Error('Response body is null')
+  }
+
+  const contentLength = parseInt(response.headers.get('content-length') || '0', 10) || expectedSize
+  const hash = createHash('sha256')
+  const writer = Bun.file(tempPath).writer()
+  let downloaded = 0
+
+  const reader = response.body.getReader()
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+
+      writer.write(value)
+      hash.update(value)
+      downloaded += value.byteLength
+
+      if (onProgress) {
+        onProgress(downloaded, contentLength)
+      }
+    }
+  } finally {
+    await writer.end()
+  }
+
+  // Verify SHA256
+  const actualSha256 = hash.digest('hex')
+  if (actualSha256 !== expectedSha256) {
+    // Clean up bad file
+    if (existsSync(tempPath)) unlinkSync(tempPath)
+    throw new Error(
+      `SHA256 mismatch: expected ${expectedSha256.slice(0, 12)}..., got ${actualSha256.slice(0, 12)}...`
+    )
+  }
+
+  // Atomic rename
+  renameSync(tempPath, destPath)
+  return downloaded
+}
+
+/**
+ * Download a single file with retry logic.
+ */
+async function downloadWithRetry(
+  url: string,
+  destPath: string,
+  expectedSha256: string,
+  expectedSize: number,
+  onProgress?: (downloaded: number, total: number) => void,
+): Promise<number> {
+  let lastError: Error | null = null
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      return await downloadFile(url, destPath, expectedSha256, expectedSize, onProgress)
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err))
+
+      // Clean up temp file on failure
+      const tempPath = `${destPath}.download`
+      if (existsSync(tempPath)) {
+        try { unlinkSync(tempPath) } catch { /* ignore */ }
+      }
+
+      if (attempt < MAX_RETRIES) {
+        await new Promise(resolve => setTimeout(resolve, RETRY_DELAYS[attempt]))
+      }
+    }
+  }
+
+  throw lastError!
+}
+
+/**
+ * Main entry point: download models from Hugging Face Hub.
+ */
+export async function downloadFromHuggingFace(
+  manifest: HfManifest,
+  options: DownloadOptions,
+): Promise<DownloadResult[]> {
+  const repo = options.hfRepo || manifest.hfRepo
+  const branch = options.hfBranch || manifest.hfBranch
+  const results: DownloadResult[] = []
+
+  // Ensure dest directory exists
+  if (!existsSync(options.destDir)) {
+    mkdirSync(options.destDir, { recursive: true })
+  }
+
+  for (const task of options.tasks) {
+    const entry = manifest.models[task]
+    if (!entry) {
+      const err = `No manifest entry for task "${task}"`
+      options.onError?.(task, err)
+      results.push({ task, success: false, bytes: 0, error: err })
+      continue
+    }
+
+    try {
+      // Download ONNX model
+      const modelUrl = hfUrl(repo, branch, entry.file)
+      const modelDest = join(options.destDir, entry.file)
+
+      const bytes = await downloadWithRetry(
+        modelUrl,
+        modelDest,
+        entry.sha256,
+        entry.size,
+        (downloaded, total) => options.onProgress?.(task, downloaded, total),
+      )
+
+      // Download metadata JSON
+      const metaUrl = hfUrl(repo, branch, entry.metaFile)
+      const metaDest = join(options.destDir, entry.metaFile)
+
+      await downloadWithRetry(metaUrl, metaDest, entry.metaSha256, 0)
+
+      options.onComplete?.(task, bytes)
+      results.push({ task, success: true, bytes })
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      options.onError?.(task, msg)
+      results.push({ task, success: false, bytes: 0, error: msg })
+    }
+  }
+
+  return results
+}

package/src/intelligence/hf-manifest.json

@@ -0,0 +1,78 @@
+{
+  "hfRepo": "demgun101/claude-brain-models",
+  "hfBranch": "main",
+  "models": {
+    "intent": {
+      "file": "intent.onnx",
+      "metaFile": "intent.json",
+      "sha256": "f276ec091712f53ceeccfdca70d468d0b5aa6da7ee5c4bd7867a7464a9732dd2",
+      "metaSha256": "d5702fd45e5685187e74810da75e41be9d12d9fd82b7ccd7244a9f0d33076c65",
+      "size": 120073283,
+      "version": "0.1.0",
+      "params": "nanoGPT-intent",
+      "accuracy": 0.9904,
+      "labels": ["session_start", "context_needed", "decision_made", "store_this", "pattern_found", "mistake_learned", "progress_update", "question", "comparison", "exploration", "list_all", "update_memory", "delete_memory", "detail_request", "timeline", "no_action"],
+      "maxSeqLen": 128
+    },
+    "entity": {
+      "file": "entity.onnx",
+      "metaFile": "entity.json",
+      "sha256": "d15706b78112e8dda3caa7e054237106b67200f90a1e6e0e4336526468dea8b5",
+      "metaSha256": "1de0636bc3bd9de23c0ce767a148d6becad7b6add6a0a717449a7ac185296d55",
+      "size": 120058476,
+      "version": "0.1.0",
+      "params": "nanoGPT-entity",
+      "accuracy": 0.9795,
+      "labels": ["O", "B-TECH", "I-TECH", "B-PROJECT", "I-PROJECT", "B-CONCEPT", "I-CONCEPT"],
+      "maxSeqLen": 128
+    },
+    "query": {
+      "file": "query.onnx",
+      "metaFile": "query.json",
+      "sha256": "802446105ad873b4a172dc875c07e245882f48691f72ae0abb0bda5934fa084a",
+      "metaSha256": "32393875ff58a87da83480673868e4ac14c3fd1a59e16836d7c1f2fa02a7f25e",
+      "size": 120057880,
+      "version": "0.1.0",
+      "params": "nanoGPT-query",
+      "accuracy": 0.985,
+      "labels": ["factual", "procedural", "comparative", "temporal", "exploratory", "decision"],
+      "maxSeqLen": 128
+    },
+    "knowledge": {
+      "file": "knowledge.onnx",
+      "metaFile": "knowledge.json",
+      "sha256": "a786eefc5ef5c6f2fc132c6de7f0972891057f5a993c9c2d9264207d36165035",
+      "metaSha256": "6aa77194cbd8c10a2451958ec5a3e43328df97ee8aea46abf53e3e432f3f3c4d",
+      "size": 120056340,
+      "version": "0.1.0",
+      "params": "nanoGPT-knowledge",
+      "accuracy": 0.998,
+      "labels": ["fact", "preference", "constraint", "goal", "definition"],
+      "maxSeqLen": 128
+    },
+    "compress": {
+      "file": "compress.onnx",
+      "metaFile": "compress.json",
+      "sha256": "2d950a0e0a2cdc5dc90b7c44803c5fb81c76d824bd208c64a7104c5845e1c237",
+      "metaSha256": "e91500c665ec47083bb6b3ff8c83d529f263792d83f7f169401267ceb1e8d031",
+      "size": 357902441,
+      "version": "0.1.0",
+      "params": "nanoGPT-compress",
+      "accuracy": null,
+      "labels": [],
+      "maxSeqLen": 256
+    },
+    "pattern": {
+      "file": "pattern.onnx",
+      "metaFile": "pattern.json",
+      "sha256": "3b44371eaef11fb8ccc4c1636d6cfbdcdf62ae8bc6ffc808ff0ff45b24824fde",
+      "metaSha256": "1126f3fa9a115b4d26063e006e7d33b9e82b7740194ac86b5dae9f25d5dfd1a2",
+      "size": 254526620,
+      "version": "0.1.0",
+      "params": "nanoGPT-pattern",
+      "accuracy": 0.8667,
+      "labels": ["solution", "anti-pattern", "best-practice", "common-issue"],
+      "maxSeqLen": 128
+    }
+  }
+}

package/src/server/auto-updater.ts

@@ -8,6 +8,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from '
 import { join, dirname, resolve } from 'node:path'
 import { homedir, platform } from 'node:os'
 import { fileURLToPath } from 'node:url'
+import { killProcessOnPort } from '@/utils/kill-port'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -223,34 +224,8 @@ export class AutoUpdater {
       // No matching processes — that's fine
     }
 
-    // Kill by port 3000
-    try {
-      if (isWindows) {
-        const result = execSync(`netstat -ano | findstr :3000 | findstr LISTENING`, {
-          encoding: 'utf-8', stdio: 'pipe', timeout: 5000,
-        })
-        const pids = new Set(
-          result.split('\n')
-            .map(line => line.trim().split(/\s+/).pop())
-            .filter(p => p && Number(p) !== myPid)
-        )
-        for (const pid of pids) {
-          try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'pipe', timeout: 5000 }) } catch {}
-        }
-      } else {
-        const raw = execSync(`lsof -ti :3000`, {
-          encoding: 'utf-8', stdio: 'pipe', timeout: 5000,
-        }).trim()
-        if (raw) {
-          const pids = raw.split('\n').filter(p => p && Number(p) !== myPid)
-          for (const pid of pids) {
-            try { process.kill(Number(pid), 'SIGKILL') } catch {}
-          }
-        }
-      }
-    } catch {
-      // No process on port — that's fine
-    }
+    // Kill by port 3000 using shared utility
+    killProcessOnPort(3000, myPid)
 
     // Clean up stale PID files
     const pidPath = join(this.dataDir, 'server.pid')

package/src/server/pid-manager.ts

@@ -5,6 +5,7 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { execSync } from 'node:child_process'
 import { join } from 'node:path'
 import { getHomePaths } from '@/config/home'
 
@@ -65,10 +66,32 @@ export class ServerPidManager {
       }
 
       // Signal 0 tests if process exists without killing it
-      process.kill(pid, 0)
+      try {
+        process.kill(pid, 0)
+      } catch (signalError: any) {
+        // On Windows, process.kill(pid, 0) can throw unexpected errors
+        // Fall back to tasklist to verify the PID exists
+        if (process.platform === 'win32' && signalError?.code !== 'ESRCH') {
+          try {
+            const result = execSync(`tasklist /FI "PID eq ${pid}" /NH`, {
+              encoding: 'utf-8', stdio: 'pipe', timeout: 3000,
+            })
+            if (!result.includes(String(pid))) {
+              this.cleanup()
+              return null
+            }
+          } catch {
+            this.cleanup()
+            return null
+          }
+        } else {
+          this.cleanup()
+          return null
+        }
+      }
       return { pid, port }
     } catch {
-      // Process not running or invalid file, clean up stale PID file
+      // Invalid file format, clean up stale PID file
       this.cleanup()
       return null
     }
@@ -97,7 +120,7 @@ export class ServerPidManager {
     }
   }
 
-  /** Register cleanup handlers on SIGINT, SIGTERM, SIGHUP, and process exit. */
+  /** Register cleanup handlers on SIGINT, SIGTERM, SIGHUP (non-Windows), and process exit. */
   registerCleanupHandlers(): void {
     const doCleanup = () => {
       this.cleanup()
@@ -106,6 +129,8 @@ export class ServerPidManager {
     process.on('exit', doCleanup)
     process.on('SIGINT', doCleanup)
     process.on('SIGTERM', doCleanup)
-    process.on('SIGHUP', doCleanup)
+    if (process.platform !== 'win32') {
+      process.on('SIGHUP', doCleanup)
+    }
   }
 }

package/src/utils/index.ts

@@ -52,3 +52,7 @@ export {
   getPhase12Instance,
   resetPhase12Cache
 } from './phase12-helper'
+
+export {
+  killProcessOnPort
+} from './kill-port'

package/src/utils/kill-port.ts

@@ -0,0 +1,53 @@
+/**
+ * Cross-platform utility to kill the process holding a specific port.
+ * Used by serve.ts (EADDRINUSE recovery) and auto-updater.ts (ghost cleanup).
+ */
+
+import { execSync } from 'node:child_process'
+
+const isWindows = process.platform === 'win32'
+
+/**
+ * Kill the process listening on the given port.
+ * Skips the current process (myPid) to avoid self-termination.
+ * Returns the PIDs that were killed, or an empty array if none found.
+ */
+export function killProcessOnPort(port: number, myPid: number = process.pid): number[] {
+  const killed: number[] = []
+
+  try {
+    if (isWindows) {
+      const result = execSync(`netstat -ano | findstr :${port} | findstr LISTENING`, {
+        encoding: 'utf-8', stdio: 'pipe', timeout: 5000,
+      })
+      const pids = new Set(
+        result.split('\n')
+          .map(line => line.trim().split(/\s+/).pop())
+          .filter((p): p is string => !!p && Number(p) !== myPid && !isNaN(Number(p)))
+      )
+      for (const pid of pids) {
+        try {
+          execSync(`taskkill /F /PID ${pid}`, { stdio: 'pipe', timeout: 5000 })
+          killed.push(Number(pid))
+        } catch {}
+      }
+    } else {
+      const raw = execSync(`lsof -ti :${port}`, {
+        encoding: 'utf-8', stdio: 'pipe', timeout: 5000,
+      }).trim()
+      if (raw) {
+        const pids = raw.split('\n').filter(p => p && Number(p) !== myPid)
+        for (const pid of pids) {
+          try {
+            process.kill(Number(pid), 'SIGKILL')
+            killed.push(Number(pid))
+          } catch {}
+        }
+      }
+    }
+  } catch {
+    // No process on port — that's fine
+  }
+
+  return killed
+}