claude-brain 0.28.2 → 0.29.0

package/VERSION

@@ -1 +1 @@
-0.28.2
+0.29.0

package/package.json

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

package/src/cli/commands/serve.ts

@@ -18,23 +18,89 @@ export async function runServe() {
   // Auto-initialize home directory on first run
   ensureHomeDirectory()
 
-  // --http-only: run HTTP server + services but no MCP stdio transport.
-  // Used by auto-start background process (stdin is /dev/null, no Claude Code attached).
   const httpOnly = process.argv.includes('--http-only')
-
-  // Determine instance role:
-  // - httpOnly → always primary (background HTTP daemon)
-  // - otherwise → secondary if primary is already running (Claude Code MCP session)
   const pidManager = new ServerPidManager()
-  const existingPid = pidManager.getRunningPid()
-  const isSecondaryInstance = !httpOnly && !!existingPid
+  const existingInstance = pidManager.getRunningInstance()
+
+  // ── Decision tree ──────────────────────────────────────────
+  // httpOnly + existing daemon → exit (duplicate daemon)
+  // httpOnly + no daemon      → start as daemon (full services + HTTP + idle watchdog)
+  // !httpOnly + healthy daemon → run as proxy (thin MCP bridge, no services)
+  // !httpOnly + no daemon      → start as daemon + MCP stdio (become daemon)
+
+  if (httpOnly && existingInstance) {
+    console.error(`[claude-brain] Primary instance already running (PID ${existingInstance.pid}). Exiting.`)
+    process.exit(0)
+  }
 
-  if (!isSecondaryInstance) {
-    // Primary instance: write PID file and register cleanup
-    pidManager.writePidFile()
-    pidManager.registerCleanupHandlers()
+  if (!httpOnly && existingInstance) {
+    // Check if existing daemon is healthy before committing to proxy mode
+    const healthy = await isDaemonHealthy(existingInstance.port)
+    if (healthy) {
+      return runAsProxy(existingInstance.port)
+    }
+    // Daemon not healthy — clean up stale PID and start as daemon
+    pidManager.cleanup()
   }
 
+  // ── Start as daemon ────────────────────────────────────────
+  return runAsDaemon(httpOnly, pidManager)
+}
+
+/** Check if the daemon at the given port is responsive and initialized */
+async function isDaemonHealthy(port: number): Promise<boolean> {
+  try {
+    const res = 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
+  } catch {
+    return false
+  }
+}
+
+/** Run as thin MCP proxy — forward all MCP calls to daemon via HTTP */
+async function runAsProxy(daemonPort: number) {
+  const config = await loadConfig()
+  const logger = createLogger(config.logLevel, config.logFilePath)
+  const mainLogger = createComponentLogger(logger, 'proxy')
+
+  mainLogger.info({ daemonPort }, 'Starting as MCP proxy → daemon')
+
+  const { McpProxyServer } = await import('@/server/mcp-proxy')
+
+  let isStopping = false
+  const proxy = new McpProxyServer({
+    daemonUrl: `http://localhost:${daemonPort}`,
+    serverName: config.serverName,
+    serverVersion: config.serverVersion,
+    onStdinClose: () => {
+      if (isStopping) return
+      isStopping = true
+      mainLogger.info('stdin closed — proxy exiting')
+      proxy.stop().finally(() => process.exit(0))
+    },
+  })
+
+  const stopProxy = async (signal: string) => {
+    if (isStopping) return
+    isStopping = true
+    mainLogger.info({ signal }, 'Proxy shutting down')
+    await proxy.stop()
+    process.exit(0)
+  }
+
+  process.on('SIGTERM', () => stopProxy('SIGTERM'))
+  process.on('SIGINT', () => stopProxy('SIGINT'))
+  process.on('SIGHUP', () => stopProxy('SIGHUP'))
+
+  await proxy.start()
+  mainLogger.info('MCP proxy ready — forwarding to daemon')
+}
+
+/** Run as full daemon with services, HTTP, and optionally MCP stdio */
+async function runAsDaemon(httpOnly: boolean, pidManager: ServerPidManager) {
   // Auto-install Claude Code hooks (idempotent, non-fatal)
   try {
     const { installHooks } = await import('@/hooks/installer')
@@ -46,7 +112,7 @@ export async function runServe() {
     console.error(`[claude-brain] Hook auto-install skipped: ${error instanceof Error ? error.message : 'unknown error'}`)
   }
 
-  // Auto-install shell auto-start if not already present (handles bun blocking postinstall)
+  // Auto-install shell auto-start if not already present
   try {
     const { isAutoStartInstalled, installAutoStart } = await import('@/cli/auto-start')
     if (!isAutoStartInstalled()) {
@@ -59,7 +125,7 @@ export async function runServe() {
     // Non-fatal — auto-start is a convenience feature
   }
 
-  // Auto-install CLAUDE.md if not present (handles bun blocking postinstall)
+  // Auto-install CLAUDE.md if not present
   try {
     const { existsSync, readFileSync, writeFileSync, mkdirSync } = await import('node:fs')
     const { join, resolve, dirname } = await import('node:path')
@@ -143,6 +209,7 @@ export async function runServe() {
         mainLogger.error({ error: error.message }, 'MCP server error')
       },
       onRequest: (toolName, requestId) => {
+        pidManager.touchActivity()
         mainLogger.debug({ toolName, requestId }, 'Tool request received')
       },
       onResponse: (toolName, requestId, durationMs) => {
@@ -167,165 +234,193 @@ export async function runServe() {
     await shutdownServices()
   })
 
-  // ── Primary instance only: HTTP server + background services ──
-  // Secondary instances (when auto-start already running) only start MCP stdio
-  if (!isSecondaryInstance) {
-    // Clean up PID file during graceful shutdown
-    cleanup.register(async () => {
-      pidManager.cleanup()
-    })
+  // ── Idempotent shutdown guard ────────────────────────────
+  let isShuttingDown = false
+  const shutdown = async (signal: string) => {
+    if (isShuttingDown) return
+    isShuttingDown = true
+    mainLogger.info({ signal }, 'Shutting down...')
+    await cleanup.cleanup()
+    process.exit(0)
+  }
 
-    // Start HTTP API server alongside MCP server
-    const { HttpApiServer } = await import('@/server/http-api')
-    const httpServer = new HttpApiServer(config, logger)
+  // ── Primary daemon: HTTP server + background services ────
+  // Write PID file and register cleanup
+  pidManager.writePidFile(config.port)
+  pidManager.registerCleanupHandlers()
 
-    cleanup.register(async () => {
-      await httpServer.stop()
-    })
+  cleanup.register(async () => {
+    pidManager.cleanup()
+  })
 
-    // Phase 21: Use session tracker from services (promoted from local creation)
-    {
-      const { getSessionTracker } = await import('@/server/services')
-      const sessionTracker = getSessionTracker()
-      if (sessionTracker) {
-        httpServer.setSessionTracker(sessionTracker)
-        mainLogger.info('Session tracker wired to HTTP server')
-      }
-    }
+  // Start HTTP API server
+  const { HttpApiServer } = await import('@/server/http-api')
+  const httpServer = new HttpApiServer(config, logger)
 
-    // Phase 28: Wire code intelligence to HTTP server
-    {
-      const { getCodeIndexer, getCodeQuery } = await import('@/server/services')
-      const codeIndexer = getCodeIndexer()
-      const codeQuery = getCodeQuery()
-      if (codeIndexer && codeQuery) {
-        httpServer.setCodeIntelligence(codeIndexer, codeQuery)
-        mainLogger.info('Code intelligence wired to HTTP server')
-      }
+  // Wire activity tracker to PID manager for idle watchdog
+  httpServer.setActivityTracker(() => pidManager.touchActivity())
+
+  cleanup.register(async () => {
+    await httpServer.stop()
+  })
+
+  // Phase 21: Use session tracker from services
+  {
+    const { getSessionTracker } = await import('@/server/services')
+    const sessionTracker = getSessionTracker()
+    if (sessionTracker) {
+      httpServer.setSessionTracker(sessionTracker)
+      mainLogger.info('Session tracker wired to HTTP server')
     }
+  }
 
-    // Phase 29: Wire code linker to HTTP server
-    {
-      const { getCodeLinker } = await import('@/server/services')
-      const codeLinker = getCodeLinker()
-      if (codeLinker) {
-        httpServer.setCodeLinker(codeLinker)
-        mainLogger.info('Code linker wired to HTTP server')
-      }
+  // Phase 28: Wire code intelligence to HTTP server
+  {
+    const { getCodeIndexer, getCodeQuery } = await import('@/server/services')
+    const codeIndexer = getCodeIndexer()
+    const codeQuery = getCodeQuery()
+    if (codeIndexer && codeQuery) {
+      httpServer.setCodeIntelligence(codeIndexer, codeQuery)
+      mainLogger.info('Code intelligence wired to HTTP server')
     }
+  }
 
-    // Phase 30: Activity log pruning on startup + periodic cleanup
-    {
-      const memory = getMemoryService()
-      if (memory?.isInitialized()) {
-        try {
-          const { startPeriodicPruning } = await import('@/memory/pruning')
-          const db = memory.database.getDb()
-          const stopPruning = startPeriodicPruning(db, logger, 30)
-          cleanup.register(async () => {
-            stopPruning()
-            mainLogger.info('Activity log pruning stopped')
-          })
-          mainLogger.info('Activity log pruning initialized')
-        } catch (error) {
-          mainLogger.warn({ error }, 'Failed to initialize activity log pruning')
-        }
-      }
+  // Phase 29: Wire code linker to HTTP server
+  {
+    const { getCodeLinker } = await import('@/server/services')
+    const codeLinker = getCodeLinker()
+    if (codeLinker) {
+      httpServer.setCodeLinker(codeLinker)
+      mainLogger.info('Code linker wired to HTTP server')
     }
+  }
 
-    // Phase 30: Optional LLM compression
-    if (config.compression?.enabled) {
+  // Phase 30: Activity log pruning on startup + periodic cleanup
+  {
+    const memory = getMemoryService()
+    if (memory?.isInitialized()) {
       try {
-        const { ObservationCompressor } = await import('@/memory/compression')
-        const { getBrainRouter } = await import('@/routing/router')
-        const compressor = new ObservationCompressor(config.compression, logger)
-        const router = getBrainRouter(logger)
-        router.setCompressor(compressor)
-        mainLogger.info({ provider: config.compression.provider, model: config.compression.model }, 'LLM compression enabled')
+        const { startPeriodicPruning } = await import('@/memory/pruning')
+        const db = memory.database.getDb()
+        const stopPruning = startPeriodicPruning(db, logger, 30)
+        cleanup.register(async () => {
+          stopPruning()
+          mainLogger.info('Activity log pruning stopped')
+        })
+        mainLogger.info('Activity log pruning initialized')
       } catch (error) {
-        mainLogger.warn({ error }, 'Failed to initialize LLM compression')
+        mainLogger.warn({ error }, 'Failed to initialize activity log pruning')
       }
     }
+  }
 
-    // Phase 31: Auto-update checker
-    let autoUpdater: InstanceType<typeof import('@/server/auto-updater').AutoUpdater> | null = null
-    if (config.autoUpdate?.enabled !== false) {
-      try {
-        const { AutoUpdater } = await import('@/server/auto-updater')
-        autoUpdater = new AutoUpdater(
-          {
-            enabled: config.autoUpdate?.enabled ?? true,
-            checkIntervalHours: config.autoUpdate?.checkIntervalHours ?? 24,
-            autoRestart: config.autoUpdate?.autoRestart ?? true,
-          },
-          mainLogger
-        )
-
-        // Check for updates on startup (non-blocking)
-        autoUpdater.check().then(result => {
-          if (result.updateAvailable && result.latestVersion) {
-            mainLogger.info(
-              { current: result.currentVersion, latest: result.latestVersion },
-              'Update available! Run: claude-brain update'
-            )
-          }
-        }).catch(() => {})
-
-        // Schedule periodic checks
-        autoUpdater.schedulePeriodicCheck()
+  // Phase 30: Optional LLM compression
+  if (config.compression?.enabled) {
+    try {
+      const { ObservationCompressor } = await import('@/memory/compression')
+      const { getBrainRouter } = await import('@/routing/router')
+      const compressor = new ObservationCompressor(config.compression, logger)
+      const router = getBrainRouter(logger)
+      router.setCompressor(compressor)
+      mainLogger.info({ provider: config.compression.provider, model: config.compression.model }, 'LLM compression enabled')
+    } catch (error) {
+      mainLogger.warn({ error }, 'Failed to initialize LLM compression')
+    }
+  }
 
-        cleanup.register(async () => {
-          autoUpdater?.stopPeriodicCheck()
-          mainLogger.info('Auto-updater stopped')
-        })
+  // Phase 31: Auto-update checker
+  let autoUpdater: InstanceType<typeof import('@/server/auto-updater').AutoUpdater> | null = null
+  if (config.autoUpdate?.enabled !== false) {
+    try {
+      const { AutoUpdater } = await import('@/server/auto-updater')
+      autoUpdater = new AutoUpdater(
+        {
+          enabled: config.autoUpdate?.enabled ?? true,
+          checkIntervalHours: config.autoUpdate?.checkIntervalHours ?? 24,
+          autoRestart: config.autoUpdate?.autoRestart ?? true,
+        },
+        mainLogger
+      )
+
+      // Check for updates on startup (non-blocking)
+      autoUpdater.check().then(result => {
+        if (result.updateAvailable && result.latestVersion) {
+          mainLogger.info(
+            { current: result.currentVersion, latest: result.latestVersion },
+            'Update available! Run: claude-brain update'
+          )
+        }
+      }).catch(() => {})
 
-        mainLogger.info('Auto-updater initialized')
-      } catch (error) {
-        mainLogger.warn({ error }, 'Failed to initialize auto-updater')
-      }
+      // Schedule periodic checks
+      autoUpdater.schedulePeriodicCheck()
+
+      cleanup.register(async () => {
+        autoUpdater?.stopPeriodicCheck()
+        mainLogger.info('Auto-updater stopped')
+      })
+
+      mainLogger.info('Auto-updater initialized')
+    } catch (error) {
+      mainLogger.warn({ error }, 'Failed to initialize auto-updater')
     }
+  }
+
+  // Start HTTP server after MCP server is ready
+  setTimeout(async () => {
+    try {
+      await httpServer.start()
+      mainLogger.info({ port: config.port }, 'HTTP API server started')
 
-    // Start HTTP server after MCP server is ready
-    setTimeout(async () => {
+      // Drain hook queue after HTTP server is ready
       try {
-        await httpServer.start()
-        mainLogger.info({ port: config.port }, 'HTTP API server started')
-
-        // Drain hook queue after HTTP server is ready
-        try {
-          const { drainQueue } = await import('@/hooks/queue')
-          const drained = await drainQueue(config.port)
-          if (drained > 0) {
-            mainLogger.info({ drained }, 'Drained hook queue')
-          }
-        } catch (error) {
-          mainLogger.debug({ error }, 'No hook queue to drain')
+        const { drainQueue } = await import('@/hooks/queue')
+        const drained = await drainQueue(config.port)
+        if (drained > 0) {
+          mainLogger.info({ drained }, 'Drained hook queue')
         }
       } catch (error) {
-        mainLogger.error({ error }, 'Failed to start HTTP API server')
+        mainLogger.debug({ error }, 'No hook queue to drain')
       }
-    }, 2000)
-  } else {
-    mainLogger.info({ existingPid }, 'Secondary instance — HTTP server already running, starting MCP stdio only')
-  }
-
-  const shutdown = async (signal: string) => {
-    mainLogger.info({ signal }, 'Shutting down...')
-    await cleanup.cleanup()
-    process.exit(0)
-  }
+    } catch (error) {
+      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 (httpOnly) {
-    // HTTP-only mode: no MCP stdio. Keep process alive for HTTP server.
+    // HTTP-only daemon mode: no MCP stdio. Use idle watchdog instead of infinite keepAlive.
     mainLogger.info('HTTP-only mode — MCP stdio disabled (background daemon)')
-    // Keep the event loop alive with a long interval
-    const keepAlive = setInterval(() => {}, 60_000 * 60)
-    cleanup.register(async () => { clearInterval(keepAlive) })
+
+    const idleTimeoutMs = (config.daemon?.idleTimeoutMinutes ?? 30) * 60 * 1000
+    if (idleTimeoutMs > 0) {
+      const watchdog = setInterval(() => {
+        const idleMs = pidManager.getIdleMs()
+        if (idleMs >= idleTimeoutMs) {
+          mainLogger.info({ idleMs, idleTimeoutMs }, 'Idle timeout reached — shutting down daemon')
+          clearInterval(watchdog)
+          shutdown('idle-timeout')
+        }
+      }, 60_000)
+      cleanup.register(async () => clearInterval(watchdog))
+      mainLogger.info({ idleTimeoutMinutes: config.daemon?.idleTimeoutMinutes ?? 30 }, 'Idle watchdog started')
+    } else {
+      // idleTimeoutMinutes=0 means never self-terminate (old behavior)
+      const keepAlive = setInterval(() => {}, 60_000 * 60)
+      cleanup.register(async () => clearInterval(keepAlive))
+      mainLogger.info('Idle watchdog disabled (idleTimeoutMinutes=0)')
+    }
   } else {
+    // MCP stdio mode: start MCP server and detect stdin closure
     await mcpServer.start()
     mainLogger.info('Claude Brain MCP server ready and listening for connections')
+
+    // Detect stdin close — Claude Code disconnected
+    process.stdin.on('end', () => shutdown('stdin-end'))
+    process.stdin.on('close', () => shutdown('stdin-close'))
   }
 }

package/src/config/loader.ts

@@ -148,7 +148,7 @@ export async function loadConfig(basePath: string = process.cwd()): Promise<Conf
   const fileConfig = loadFromFile(basePath)
   const envConfig = loadFromEnv()
 
-  const merged = mergeConfigs(defaultConfig as Partial<Config>, fileConfig, envConfig)
+  const merged = mergeConfigs(defaultConfig as Partial<Config>, envConfig, fileConfig)
 
   const result = ConfigSchema.safeParse(merged)
 
@@ -163,9 +163,14 @@ export async function loadConfig(basePath: string = process.cwd()): Promise<Conf
   const data = result.data
   data.logFilePath = resolveHomePath(data.logFilePath)
   data.dbPath = resolveHomePath(data.dbPath)
-  if (data.knowledge?.graph?.persistPath) {
-    data.knowledge.graph.persistPath = resolveHomePath(data.knowledge.graph.persistPath)
-  }
+
+  // Always resolve knowledge graph path to absolute
+  // Zod .default({}) on nested objects means graph/persistPath may not exist
+  if (!data.knowledge) data.knowledge = {} as any
+  if (!data.knowledge.graph) data.knowledge.graph = {} as any
+  data.knowledge.graph.persistPath = resolveHomePath(
+    data.knowledge.graph.persistPath || './data/knowledge-graph.json'
+  )
 
   // Phase 30: Auto-detect vaultPath if not configured
   if (!data.vaultPath) {

package/src/config/schema.ts

@@ -290,7 +290,7 @@ export const ConfigSchema = z.object({
   serverVersion: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semver format').default(pkg.version),
 
   /** Logging level */
-  logLevel: LogLevelSchema.default('info'),
+  logLevel: LogLevelSchema.default('warn'),
 
   /** Path to log file */
   logFilePath: z.string().default('./logs/claude-brain.log'),
@@ -386,6 +386,12 @@ export const ConfigSchema = z.object({
     }).default({} as any),
   }).default({} as any),
 
+  /** Daemon process configuration */
+  daemon: z.object({
+    /** Minutes of inactivity before daemon self-terminates (0 = never) */
+    idleTimeoutMinutes: z.number().int().min(0).default(30),
+  }).default({} as any),
+
   /** Phase 30: Optional LLM compression for observations */
   compression: z.object({
     /** Enable LLM-based compression of long observations */

package/src/server/http-api.ts

@@ -27,6 +27,7 @@ export class HttpApiServer {
   private codeIndexer?: CodeIndexer
   private codeQuery?: CodeQuery
   private codeLinker?: MemoryCodeLinker
+  private activityTracker?: () => void
   private hookStats: HookStats = {
     totalCaptured: 0,
     totalSkipped: 0,
@@ -44,8 +45,16 @@ export class HttpApiServer {
     this.setupRoutes()
   }
 
+  /** Set activity tracker callback — called on every HTTP request for idle watchdog */
+  setActivityTracker(fn: () => void): void {
+    this.activityTracker = fn
+  }
+
   private setupMiddleware(): void {
     this.app.use('*', async (c, next) => {
+      // Touch activity tracker on every request (idle watchdog)
+      this.activityTracker?.()
+
       c.header('Access-Control-Allow-Origin', '*')
       c.header('Access-Control-Allow-Methods', 'GET, POST, PATCH, DELETE, OPTIONS')
       c.header('Access-Control-Allow-Headers', 'Content-Type, Authorization')
@@ -137,6 +146,10 @@ export class HttpApiServer {
     // Phase 23b: Expose brain://context/auto via HTTP for testability
     this.app.get('/api/context/auto', () => this.handleContextAuto())
 
+    // MCP proxy endpoints — allow thin proxy clients to forward tool calls via HTTP
+    this.app.get('/api/mcp/list-tools', () => this.handleMcpListTools())
+    this.app.post('/api/mcp/call-tool', (c) => this.handleMcpCallTool(c))
+
     // Phase 6A: SLM feedback & model status endpoints
     this.app.get('/api/models/status', () => this.handleModelsStatus())
     this.app.get('/api/models/feedback', (c) => this.handleModelsFeedback(c))
@@ -1129,6 +1142,46 @@ export class HttpApiServer {
     }
   }
 
+  // ─── MCP Proxy Endpoints ────────────────────────────────
+
+  private async handleMcpListTools(): Promise<Response> {
+    try {
+      const { handleListTools } = await import('@/server/handlers/list-tools')
+      const result = await handleListTools()
+      return Response.json({ success: true, data: result })
+    } catch (error) {
+      this.logger.error({ error }, 'Failed to list MCP tools')
+      return Response.json(
+        { success: false, error: 'Failed to list tools' },
+        { status: 500 }
+      )
+    }
+  }
+
+  private async handleMcpCallTool(c: any): Promise<Response> {
+    try {
+      const body = await c.req.json()
+      const { name, args } = body
+
+      if (!name) {
+        return Response.json(
+          { success: false, error: 'name is required' },
+          { status: 400 }
+        )
+      }
+
+      const { handleCallTool } = await import('@/server/handlers/call-tool')
+      const result = await handleCallTool(name, args || {}, this.logger)
+      return Response.json({ success: true, data: result })
+    } catch (error: any) {
+      this.logger.error({ error }, 'Failed to call MCP tool')
+      return Response.json(
+        { success: false, error: error?.message || 'Failed to call tool' },
+        { status: 500 }
+      )
+    }
+  }
+
   async start(): Promise<void> {
     const port = this.config.port || 3000
 

package/src/server/mcp-proxy.ts

@@ -0,0 +1,84 @@
+/**
+ * Thin MCP Proxy — speaks MCP over stdio, forwards everything via HTTP to the daemon.
+ * ~5MB footprint per Claude Code session. Dies when stdin closes.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourcesRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+
+interface McpProxyOptions {
+  daemonUrl: string
+  serverName: string
+  serverVersion: string
+  onStdinClose: () => void
+}
+
+export class McpProxyServer {
+  private server: Server
+  private daemonUrl: string
+  private onStdinClose: () => void
+
+  constructor(opts: McpProxyOptions) {
+    this.daemonUrl = opts.daemonUrl
+    this.onStdinClose = opts.onStdinClose
+
+    this.server = new Server(
+      { name: opts.serverName, version: opts.serverVersion },
+      { capabilities: { tools: {} } }
+    )
+
+    this.setupHandlers()
+  }
+
+  private setupHandlers(): void {
+    // Forward list-tools to daemon
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      const res = await fetch(`${this.daemonUrl}/api/mcp/list-tools`)
+      const json = await res.json() as any
+      if (!json.success) throw new Error(json.error || 'list-tools failed')
+      return json.data
+    })
+
+    // Forward call-tool to daemon
+    this.server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
+      const res = await fetch(`${this.daemonUrl}/api/mcp/call-tool`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          name: request.params.name,
+          args: request.params.arguments || {},
+        }),
+      })
+      const json = await res.json() as any
+      if (!json.success) throw new Error(json.error || 'call-tool failed')
+      return json.data
+    })
+
+    // Prompts/Resources — return empty lists (daemon has these but proxy doesn't need them)
+    this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [] }))
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: [] }))
+
+    this.server.onerror = (error) => {
+      console.error('[mcp-proxy] Server error:', error)
+    }
+  }
+
+  async start(): Promise<void> {
+    const transport = new StdioServerTransport()
+    await this.server.connect(transport)
+
+    // Detect stdin close — Claude Code disconnected
+    process.stdin.on('end', () => this.onStdinClose())
+    process.stdin.on('close', () => this.onStdinClose())
+  }
+
+  async stop(): Promise<void> {
+    await this.server.close()
+  }
+}

package/src/server/pid-manager.ts

@@ -1,6 +1,7 @@
 /**
  * PID file manager for the Claude Brain server.
  * Ensures only one server instance runs at a time.
+ * Tracks daemon port and activity for idle watchdog.
  */
 
 import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
@@ -9,37 +10,82 @@ import { getHomePaths } from '@/config/home'
 
 const PID_FILENAME = 'server.pid'
 
+interface PidFileContent {
+  pid: number
+  port: number
+}
+
 export class ServerPidManager {
   private pidFilePath: string
+  private lastActivityTs: number = Date.now()
 
   constructor() {
     const paths = getHomePaths()
     this.pidFilePath = join(paths.data, PID_FILENAME)
   }
 
-  /** Check if another server instance is already running. Returns the PID if alive, null otherwise. */
-  getRunningPid(): number | null {
+  /** Record activity — call on every HTTP request or MCP tool call */
+  touchActivity(): void {
+    this.lastActivityTs = Date.now()
+  }
+
+  /** Milliseconds since last activity */
+  getIdleMs(): number {
+    return Date.now() - this.lastActivityTs
+  }
+
+  /**
+   * Get running daemon instance info (PID + port).
+   * Returns null if no daemon is running.
+   * Backward-compatible with old plain-number PID files.
+   */
+  getRunningInstance(): { pid: number; port: number } | null {
     if (!existsSync(this.pidFilePath)) return null
 
     try {
-      const pid = parseInt(readFileSync(this.pidFilePath, 'utf-8').trim(), 10)
+      const raw = readFileSync(this.pidFilePath, 'utf-8').trim()
+
+      let pid: number
+      let port: number
+
+      // Try JSON format first (new)
+      if (raw.startsWith('{')) {
+        const parsed: PidFileContent = JSON.parse(raw)
+        pid = parsed.pid
+        port = parsed.port
+      } else {
+        // Backward compat: old plain-number format
+        pid = parseInt(raw, 10)
+        port = 3000 // default port assumption for old format
+      }
+
       if (isNaN(pid)) {
         this.cleanup()
         return null
       }
+
       // Signal 0 tests if process exists without killing it
       process.kill(pid, 0)
-      return pid
+      return { pid, port }
     } catch {
-      // Process not running, clean up stale PID file
+      // Process not running or invalid file, clean up stale PID file
       this.cleanup()
       return null
     }
   }
 
-  /** Write the current process PID to the PID file. */
-  writePidFile(): void {
-    writeFileSync(this.pidFilePath, String(process.pid), 'utf-8')
+  /** Check if another server instance is already running. Returns the PID if alive, null otherwise. */
+  getRunningPid(): number | null {
+    return this.getRunningInstance()?.pid ?? null
+  }
+
+  /** Write the current process PID and port to the PID file. */
+  writePidFile(port?: number): void {
+    const content: PidFileContent = {
+      pid: process.pid,
+      port: port ?? 3000,
+    }
+    writeFileSync(this.pidFilePath, JSON.stringify(content), 'utf-8')
   }
 
   /** Remove the PID file. Safe to call multiple times. */
@@ -51,7 +97,7 @@ export class ServerPidManager {
     }
   }
 
-  /** Register cleanup handlers on SIGINT, SIGTERM, and process exit. */
+  /** Register cleanup handlers on SIGINT, SIGTERM, SIGHUP, and process exit. */
   registerCleanupHandlers(): void {
     const doCleanup = () => {
       this.cleanup()
@@ -60,5 +106,6 @@ export class ServerPidManager {
     process.on('exit', doCleanup)
     process.on('SIGINT', doCleanup)
     process.on('SIGTERM', doCleanup)
+    process.on('SIGHUP', doCleanup)
   }
 }

package/src/server/services.ts

@@ -178,7 +178,9 @@ export async function initializeServices(config: Config, logger: Logger): Promis
     if (config.knowledge?.graph?.enabled !== false) {
       try {
         const graph = new InMemoryKnowledgeGraph(logger)
-        const graphPersistPath = config.knowledge?.graph?.persistPath || './data/knowledge-graph.json'
+        // Use absolute path from getHomePaths() if persistPath not configured
+        const { getHomePaths: getHomePathsKG } = await import('@/config/home')
+        const graphPersistPath = config.knowledge?.graph?.persistPath || getHomePathsKG().knowledgeGraph
 
         // Load existing graph from disk
         await graph.load(graphPersistPath)
@@ -656,7 +658,9 @@ export async function shutdownServices(): Promise<void> {
   // Save and stop knowledge graph
   if (services.knowledgeGraph) {
     services.knowledgeGraph.graph.stopAutoSave()
-    const persistPath = services.config.knowledge?.graph?.persistPath || './data/knowledge-graph.json'
+    // Use absolute path from getHomePaths() if persistPath not configured
+    const { getHomePaths } = await import('@/config/home')
+    const persistPath = services.config.knowledge?.graph?.persistPath || getHomePaths().knowledgeGraph
     try {
       await services.knowledgeGraph.graph.save(persistPath)
       serviceLogger.info('Knowledge graph saved on shutdown')

package/src/utils/error-handler.ts

@@ -29,6 +29,10 @@ export class GlobalErrorHandler {
     process.on('SIGINT', () => {
       this.handleShutdown('SIGINT')
     })
+
+    process.on('SIGHUP', () => {
+      this.handleShutdown('SIGHUP')
+    })
   }
 
   private handleUncaughtException(error: Error): void {