claude-brain 0.30.0 → 0.30.1

package/VERSION

@@ -1 +1 @@
-0.30.0
+0.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-brain",
-  "version": "0.30.0",
+  "version": "0.30.1",
   "description": "Local development assistant bridging Obsidian vaults with Claude Code via MCP",
   "type": "module",
   "main": "src/index.ts",
@@ -13,6 +13,7 @@
     "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/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/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
+}