claude-brain 0.22.3 → 0.23.0

package/VERSION

@@ -1 +1 @@
-0.22.3
+0.22.4

package/package.json

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

@@ -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 { ServerPidManager } from '@/server/pid-manager'
 
 const BANNER = `
 ╔═══════════════════════════════════════════════════════╗
@@ -17,6 +18,18 @@ export async function runServe() {
   // Auto-initialize home directory on first run
   ensureHomeDirectory()
 
+  // Singleton check: prevent multiple server instances
+  const pidManager = new ServerPidManager()
+  const existingPid = pidManager.getRunningPid()
+  if (existingPid) {
+    console.error(`[claude-brain] Server already running (PID: ${existingPid}). Exiting.`)
+    process.exit(0)
+  }
+
+  // Write PID file and register cleanup handlers
+  pidManager.writePidFile()
+  pidManager.registerCleanupHandlers()
+
   // Auto-install Claude Code hooks (idempotent, non-fatal)
   try {
     const { installHooks } = await import('@/hooks/installer')
@@ -118,6 +131,11 @@ export async function runServe() {
     await shutdownServices()
   })
 
+  // Clean up PID file during graceful shutdown
+  cleanup.register(async () => {
+    pidManager.cleanup()
+  })
+
   // Start HTTP API server alongside MCP server
   const { HttpApiServer } = await import('@/server/http-api')
   const httpServer = new HttpApiServer(config, logger)

package/src/hooks/passive-classifier.ts

@@ -211,7 +211,7 @@ export class PassiveClassifier {
         const packages = match[1]?.trim()
         if (packages) {
           return {
-            type: 'decision',
+            type: 'progress',
             confidence: 0.85,
             content: `Installed package(s): ${packages}`,
             project: this.extractProjectFromCwd(input.cwd),

package/src/memory/fts5-search.ts

@@ -8,6 +8,8 @@ import { randomUUID } from 'crypto'
 import type { Database } from 'bun:sqlite'
 import type { Logger } from 'pino'
 import { expandQuery } from '@/retrieval/query/expander'
+import { embeddingToBuffer, bufferToEmbedding, cosineSimilarity } from './embedding-utils'
+import type { EmbeddingService } from './embeddings'
 
 export type ObservationCategory = 'decision' | 'pattern' | 'correction' | 'insight' | 'preference'
 
@@ -364,6 +366,153 @@ export class FTS5Search {
     return rows.map(row => this.rowToResult(row))
   }
 
+  // --- Embedding-based semantic search ---
+
+  /**
+   * Store an embedding for an observation.
+   * Called after storing an observation to enable semantic search.
+   */
+  storeEmbedding(observationId: string, embedding: number[]): void {
+    const buffer = embeddingToBuffer(embedding)
+    const now = new Date().toISOString()
+
+    try {
+      this.db.prepare(`
+        INSERT OR REPLACE INTO observation_embeddings (observation_id, embedding, created_at)
+        VALUES (?, ?, ?)
+      `).run(observationId, buffer, now)
+    } catch (error) {
+      this.logger.warn({ error, observationId }, 'Failed to store embedding')
+    }
+  }
+
+  /**
+   * Delete an embedding for an observation.
+   */
+  deleteEmbedding(observationId: string): void {
+    try {
+      this.db.prepare('DELETE FROM observation_embeddings WHERE observation_id = ?').run(observationId)
+    } catch (error) {
+      this.logger.warn({ error, observationId }, 'Failed to delete embedding')
+    }
+  }
+
+  /**
+   * Semantic search using stored embeddings.
+   * Generates a query embedding, then computes cosine similarity against all
+   * stored observation embeddings. Returns top matches above threshold.
+   */
+  async semanticSearch(
+    queryEmbedding: number[],
+    project?: string,
+    limit: number = 10,
+    minSimilarity: number = 0.3
+  ): Promise<ScoredResult[]> {
+    try {
+      // Load all embeddings with their observation IDs
+      let sql: string
+      const params: any[] = []
+
+      if (project) {
+        sql = `
+          SELECT oe.observation_id, oe.embedding, o.*
+          FROM observation_embeddings oe
+          JOIN observations o ON oe.observation_id = o.id
+          WHERE o.archived = 0 AND o.project = ?
+        `
+        params.push(project)
+      } else {
+        sql = `
+          SELECT oe.observation_id, oe.embedding, o.*
+          FROM observation_embeddings oe
+          JOIN observations o ON oe.observation_id = o.id
+          WHERE o.archived = 0
+        `
+      }
+
+      const rows = this.db.prepare(sql).all(...params) as any[]
+
+      if (rows.length === 0) {
+        this.logger.debug('No embeddings found for semantic search')
+        return []
+      }
+
+      // Compute cosine similarity for each stored embedding
+      const scored: { row: any; similarity: number }[] = []
+      for (const row of rows) {
+        try {
+          const storedEmbedding = bufferToEmbedding(row.embedding)
+          const similarity = cosineSimilarity(queryEmbedding, storedEmbedding)
+          if (similarity >= minSimilarity) {
+            scored.push({ row, similarity })
+          }
+        } catch {
+          // Skip invalid embeddings
+        }
+      }
+
+      // Sort by similarity descending and take top results
+      scored.sort((a, b) => b.similarity - a.similarity)
+      const topResults = scored.slice(0, limit)
+
+      return topResults.map(({ row, similarity }) => ({
+        ...this.rowToResult(row),
+        score: similarity
+      }))
+    } catch (error) {
+      this.logger.warn({ error }, 'Semantic search failed')
+      return []
+    }
+  }
+
+  /**
+   * Check if there are any stored embeddings.
+   */
+  hasEmbeddings(): boolean {
+    try {
+      const row = this.db.prepare('SELECT COUNT(*) as count FROM observation_embeddings').get() as any
+      return (row?.count || 0) > 0
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Backfill embeddings for observations that don't have them yet.
+   * Used for migrating existing data.
+   */
+  async backfillEmbeddings(embeddingService: EmbeddingService, batchSize: number = 50): Promise<number> {
+    try {
+      const rows = this.db.prepare(`
+        SELECT o.id, o.content, o.reasoning, o.context
+        FROM observations o
+        LEFT JOIN observation_embeddings oe ON o.id = oe.observation_id
+        WHERE oe.observation_id IS NULL AND o.archived = 0
+        LIMIT ?
+      `).all(batchSize) as any[]
+
+      if (rows.length === 0) return 0
+
+      let count = 0
+      for (const row of rows) {
+        try {
+          const text = [row.content, row.reasoning, row.context].filter(Boolean).join(' ')
+          const embedding = await embeddingService.generateEmbedding(text)
+          this.storeEmbedding(row.id, embedding)
+          count++
+        } catch {
+          // Skip failures, continue with next
+        }
+      }
+
+      this.logger.info({ backfilled: count, total: rows.length }, 'Embedding backfill complete')
+      return count
+    } catch (error) {
+      this.logger.warn({ error }, 'Embedding backfill failed')
+      return 0
+    }
+  }
+
   // --- Private helpers ---
 
   /**

package/src/memory/index.ts

@@ -113,6 +113,17 @@ export class MemoryManager {
         addFTS5Tables(db)
         this._fts5 = new FTS5Search(db, this.logger)
         this.logger.info('FTS5 search initialized')
+
+        // Phase 26b: Backfill embeddings for existing observations (async, non-blocking)
+        if (this.embeddings.isReady()) {
+          this.backfillEmbeddings().then(count => {
+            if (count > 0) {
+              this.logger.info({ count }, 'Backfilled embeddings for existing observations')
+            }
+          }).catch(() => {
+            // Non-critical, log handled in backfillEmbeddings
+          })
+        }
       } catch (error) {
         this.logger.warn({ error }, 'Failed to initialize FTS5, continuing without it')
       }
@@ -169,6 +180,30 @@ export class MemoryManager {
     return this.initialized
   }
 
+  /**
+   * Generate and store an embedding for an observation (fire-and-forget).
+   * Runs asynchronously to avoid blocking the store operation.
+   */
+  private storeObservationEmbedding(observationId: string, text: string): void {
+    if (!this._fts5 || !this.embeddings.isReady()) return
+
+    // Fire-and-forget: don't block the store operation
+    this.embeddings.generateEmbedding(text).then(embedding => {
+      this._fts5?.storeEmbedding(observationId, embedding)
+    }).catch(error => {
+      this.logger.debug({ error, observationId }, 'Failed to store observation embedding')
+    })
+  }
+
+  /**
+   * Backfill embeddings for existing observations that don't have them.
+   * Call this after initialization to migrate existing data.
+   */
+  async backfillEmbeddings(batchSize: number = 50): Promise<number> {
+    if (!this._fts5 || !this.embeddings.isReady()) return 0
+    return this._fts5.backfillEmbeddings(this.embeddings, batchSize)
+  }
+
   close(): void {
     if (this.useChromaDB) {
       this.chroma.close()
@@ -267,6 +302,9 @@ export class MemoryManager {
           context,
           tags: options?.tags
         }, sharedId)
+
+        // Store embedding for semantic search
+        this.storeObservationEmbedding(fts5Id, [decision, reasoning, context].filter(Boolean).join(' '))
       } catch (error) {
         this.logger.warn({ error }, 'FTS5 store failed, continuing with other backends')
       }
@@ -314,7 +352,7 @@ export class MemoryManager {
   }
 
   /**
-   * Get raw search results - uses FTS5 as primary, ChromaDB as enrichment
+   * Get raw search results - uses FTS5 as primary, embeddings as semantic fallback
    * Use this for internal operations that need raw results
    */
   async searchRaw(
@@ -322,52 +360,52 @@ export class MemoryManager {
     options?: { project?: string; limit?: number; minSimilarity?: number }
   ): Promise<any[]> {
     const limit = options?.limit || 5
+    const LOW_CONFIDENCE_THRESHOLD = 0.4
 
     // Phase 26: Try FTS5 first (always available)
     if (this._fts5) {
       const ftsResults = this._fts5.searchWithConfidence(query, options?.project, limit)
 
-      if (ftsResults.length > 0) {
-        // Transform FTS5 results to match expected MemorySearchResult structure
-        const results = ftsResults.map(r => ({
-          id: r.id,
-          content: r.content,
-          memory: {
-            id: r.id,
-            project: r.project,
-            content: r.content,
-            createdAt: new Date(r.created_at),
-            metadata: {
-              project: r.project,
-              category: r.category,
-              context: r.context || '',
-              reasoning: r.reasoning || '',
-              tags: r.tags,
-              created_at: r.created_at
+      // Check if FTS5 returned good results
+      const hasGoodResults = ftsResults.length > 0 &&
+        ftsResults.some(r => r.score >= LOW_CONFIDENCE_THRESHOLD)
+
+      if (hasGoodResults) {
+        return this.transformFtsResults(ftsResults)
+      }
+
+      // Phase 26b: FTS5 returned nothing or low-confidence — try semantic search
+      if (this.embeddings.isReady() && this._fts5.hasEmbeddings()) {
+        try {
+          const queryEmbedding = await this.embeddings.generateEmbedding(query)
+          const semanticResults = await this._fts5.semanticSearch(
+            queryEmbedding,
+            options?.project,
+            limit,
+            options?.minSimilarity || 0.3
+          )
+
+          if (semanticResults.length > 0) {
+            this.logger.debug(
+              { query, ftsCount: ftsResults.length, semanticCount: semanticResults.length },
+              'Semantic search found results where FTS5 did not'
+            )
+
+            // If we had some low-confidence FTS5 results, merge with semantic results
+            if (ftsResults.length > 0) {
+              return this.mergeSearchResults(ftsResults, semanticResults, limit)
             }
-          },
-          similarity: r.score,
-          decision: r.category === 'decision' ? {
-            id: r.id,
-            project: r.project,
-            context: r.context || '',
-            decision: r.content,
-            reasoning: r.reasoning || '',
-            alternatives: '',
-            tags: r.tags,
-            createdAt: new Date(r.created_at)
-          } : undefined,
-          metadata: {
-            project: r.project,
-            category: r.category,
-            context: r.context || '',
-            reasoning: r.reasoning || '',
-            tags: r.tags,
-            created_at: r.created_at
+
+            return this.transformFtsResults(semanticResults)
           }
-        }))
+        } catch (error) {
+          this.logger.warn({ error }, 'Semantic search fallback failed')
+        }
+      }
 
-        return results
+      // Return whatever FTS5 found (even if low confidence)
+      if (ftsResults.length > 0) {
+        return this.transformFtsResults(ftsResults)
       }
     }
 
@@ -417,6 +455,82 @@ export class MemoryManager {
     })
   }
 
+  /**
+   * Transform FTS5/semantic ScoredResults to the expected MemorySearchResult structure
+   */
+  private transformFtsResults(results: import('./fts5-search').ScoredResult[]): any[] {
+    return results.map(r => ({
+      id: r.id,
+      content: r.content,
+      memory: {
+        id: r.id,
+        project: r.project,
+        content: r.content,
+        createdAt: new Date(r.created_at),
+        metadata: {
+          project: r.project,
+          category: r.category,
+          context: r.context || '',
+          reasoning: r.reasoning || '',
+          tags: r.tags,
+          created_at: r.created_at
+        }
+      },
+      similarity: r.score,
+      decision: r.category === 'decision' ? {
+        id: r.id,
+        project: r.project,
+        context: r.context || '',
+        decision: r.content,
+        reasoning: r.reasoning || '',
+        alternatives: '',
+        tags: r.tags,
+        createdAt: new Date(r.created_at)
+      } : undefined,
+      metadata: {
+        project: r.project,
+        category: r.category,
+        context: r.context || '',
+        reasoning: r.reasoning || '',
+        tags: r.tags,
+        created_at: r.created_at
+      }
+    }))
+  }
+
+  /**
+   * Merge FTS5 and semantic search results, deduplicating by ID.
+   * Semantic results get a small boost since they matched conceptually.
+   */
+  private mergeSearchResults(
+    ftsResults: import('./fts5-search').ScoredResult[],
+    semanticResults: import('./fts5-search').ScoredResult[],
+    limit: number
+  ): any[] {
+    const seen = new Set<string>()
+    const merged: import('./fts5-search').ScoredResult[] = []
+
+    // Add semantic results first (they matched conceptually when FTS5 didn't)
+    for (const r of semanticResults) {
+      if (!seen.has(r.id)) {
+        seen.add(r.id)
+        merged.push(r)
+      }
+    }
+
+    // Then add FTS5 results that aren't already included
+    for (const r of ftsResults) {
+      if (!seen.has(r.id)) {
+        seen.add(r.id)
+        merged.push(r)
+      }
+    }
+
+    // Sort by score descending and limit
+    merged.sort((a, b) => b.score - a.score)
+    return this.transformFtsResults(merged.slice(0, limit))
+  }
+
   async recallSimilar(
     query: string,
     options?: { project?: string; limit?: number; minSimilarity?: number }
@@ -476,6 +590,9 @@ export class MemoryManager {
           confidence: input.confidence,
           source: input.source
         }, sharedId)
+
+        // Store embedding for semantic search
+        this.storeObservationEmbedding(fts5Id, [input.description, input.context].filter(Boolean).join(' '))
       } catch (error) {
         this.logger.warn({ error }, 'FTS5 pattern store failed')
       }
@@ -523,6 +640,9 @@ export class MemoryManager {
           context: input.context,
           confidence: input.confidence
         }, sharedId)
+
+        // Store embedding for semantic search
+        this.storeObservationEmbedding(fts5Id, [input.correction, input.reasoning, input.context].filter(Boolean).join(' '))
       } catch (error) {
         this.logger.warn({ error }, 'FTS5 correction store failed')
       }
@@ -846,13 +966,14 @@ export class MemoryManager {
   }
 
   /**
-   * Delete a decision by ID — removes from FTS5 + ChromaDB/SQLite
+   * Delete a decision by ID — removes from FTS5 + embeddings + ChromaDB/SQLite
    */
   async deleteDecision(id: string): Promise<void> {
-    // Phase 26: Delete from FTS5
+    // Phase 26: Delete from FTS5 and embeddings
     if (this._fts5) {
       try {
         this._fts5.delete(id)
+        this._fts5.deleteEmbedding(id)
       } catch (error) {
         this.logger.warn({ error, id }, 'FTS5 delete failed')
       }

package/src/memory/migrations/add-fts5.ts

@@ -95,4 +95,14 @@ export function addFTS5Tables(db: Database): void {
       PRIMARY KEY (source_id, target_id)
     )
   `)
+
+  // Observation embeddings table for semantic search (Phase 26b)
+  db.run(`
+    CREATE TABLE IF NOT EXISTS observation_embeddings (
+      observation_id TEXT PRIMARY KEY,
+      embedding BLOB NOT NULL,
+      created_at TEXT NOT NULL,
+      FOREIGN KEY (observation_id) REFERENCES observations(id) ON DELETE CASCADE
+    )
+  `)
 }

package/src/routing/intent-classifier.ts

@@ -69,6 +69,8 @@ const STORE_PHRASES = [
   'i learned that',
   // Phase 25: Session summary storage
   'session summary:', 'session summary ',
+  // Explicit prefix signal for preference storage
+  'preference:', 'my preference:',
 ]
 
 const REASONING_PHRASES = [
@@ -88,6 +90,8 @@ const MISTAKE_PHRASES = [
   'turns out that',
   // BUG-006: "Mistake:" prefix (colon form, e.g. "Mistake: I was using...")
   'mistake:',
+  // Explicit prefix signals for category classification
+  'lesson:', 'lesson learned:',
 ]
 
 // Progress indicators
@@ -404,7 +408,9 @@ export class IntentClassifier {
 
   private isPatternFound(lower: string): boolean {
     const hasPattern = PATTERN_PHRASES.some(p => lower.includes(p))
-    return hasPattern && lower.length > 50
+    // Explicit prefix signals (e.g. "Pattern: ...") need shorter minimum length
+    const hasExplicitPrefix = lower.startsWith('pattern:') || lower.startsWith('best practice:') || lower.startsWith('anti-pattern:')
+    return hasPattern && (hasExplicitPrefix ? lower.length > 20 : lower.length > 50)
   }
 
   /**

package/src/routing/response-filter.ts

@@ -15,6 +15,7 @@ export interface FilterableResult {
 }
 
 export interface FilteredResult {
+  id?: string
   content: string
   score: number
   source: string
@@ -74,8 +75,9 @@ export class ResponseFilter {
     // 5. Limit to 5 results
     filtered = filtered.slice(0, 5)
 
-    // 6. Add one-line relevance explanation per result
+    // 6. Add one-line relevance explanation per result (preserve id from metadata)
     return filtered.map(r => ({
+      id: (r.metadata as any)?.id || (r.metadata as any)?.decision_id,
       content: r.content,
       score: r.score,
       source: r.source,

package/src/routing/router.ts

@@ -39,6 +39,7 @@ const UPDATE_MIN_SIMILARITY = 0.3
 export interface BrainInput {
   message: string
   project?: string
+  action?: 'auto' | 'store' | 'recall' | 'update' | 'delete'
 }
 
 /** Recently stored decision for recency fast path (Bug 4 fix) */
@@ -84,17 +85,44 @@ export class BrainRouter {
   }
 
   async route(input: BrainInput): Promise<BrainResponse> {
-    const { message, project: inputProject } = input
+    const { message, project: inputProject, action } = input
 
-    // Classify intent
-    const classification = this.classifier.classify(message)
-    this.logger.debug({ intent: classification.primary, confidence: classification.confidence }, 'Intent classified')
-
-    // Extract entities
+    // Extract entities (needed for all paths)
     const entities = await this.entityExtractor.extract(message, inputProject)
     const project = entities.project || inputProject
     this.logger.debug({ project, technologies: entities.technologies }, 'Entities extracted')
 
+    // P1: Explicit action override — bypass intent classifier entirely
+    if (action && action !== 'auto') {
+      this.logger.debug({ action }, 'Using explicit action override')
+      try {
+        switch (action) {
+          case 'store':
+            return this.handleStoreThis(message, project, entities)
+          case 'recall':
+            return this.handleContextNeeded(message, project, entities)
+          case 'update':
+            return this.handleUpdateMemory(message, project, entities)
+          case 'delete':
+            return this.handleDeleteMemory(message, project, entities)
+          default:
+            break
+        }
+      } catch (error) {
+        this.logger.error({ error, action }, 'Router action override error')
+        return {
+          action: 'none',
+          summary: `Error processing ${action} request`,
+          content: `Failed to process: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          relevantItems: 0
+        }
+      }
+    }
+
+    // Classify intent
+    const classification = this.classifier.classify(message)
+    this.logger.debug({ intent: classification.primary, confidence: classification.confidence }, 'Intent classified')
+
     // Route to handler
     try {
       switch (classification.primary) {
@@ -383,7 +411,20 @@ export class BrainRouter {
       })
     }
 
-    return this.responseFilter.synthesize(tiers, message, displayProject)
+    const response = this.responseFilter.synthesize(tiers, message, displayProject)
+
+    // P0: When no results found and message looks like a plain statement (not a question),
+    // add a hint that the user may have intended to store it
+    if (response.action === 'none' && response.relevantItems === 0) {
+      const isPlainStatement = message.length > 15 &&
+        !message.trim().endsWith('?') &&
+        message.split(/\s+/).length > 3
+      if (isPlainStatement) {
+        response.content += `\n\n**Tip:** If you meant to save this, try:\n- \`brain("Remember: ${message.slice(0, 60)}")\`\n- Or use \`action: "store"\` to force storage: \`brain({ message: "...", action: "store" })\``
+      }
+    }
+
+    return response
   }
 
   /**

package/src/server/handlers/tools/brain.ts

@@ -22,19 +22,20 @@ export async function handleBrain(
 ): Promise<ToolResponse> {
   try {
     const input = ToolValidator.validate(args, BrainSchema)
-    const { message, project } = input
+    const { message, project, action } = input
 
     logger.debug(
       {
         messageLength: message.length,
         project,
+        action,
         messagePreview: message.slice(0, 80)
       },
       'Brain tool called'
     )
 
     const router = getBrainRouter(logger)
-    const response = await router.route({ message, project })
+    const response = await router.route({ message, project, action })
 
     logger.info(
       {

package/src/server/handlers/tools/schemas.ts

@@ -137,7 +137,8 @@ export const GetPhase12StatusSchema = z.object({})
 
 export const BrainSchema = z.object({
   message: z.string().min(1, 'message is required'),
-  project: z.string().optional()
+  project: z.string().optional(),
+  action: z.enum(['auto', 'store', 'recall', 'update', 'delete']).optional()
 })
 
 // ============================================================================

package/src/server/http-api.ts

@@ -814,7 +814,7 @@ export class HttpApiServer {
           memoryService.recallSimilar(projectName || 'recent work', {
             project: projectName,
             limit: 5,
-            minSimilarity: 0.2,
+            minSimilarity: 0.65,
           }),
           memoryService.getPatterns(projectName, { limit: 5 }),
         ])
@@ -1065,8 +1065,17 @@ export class HttpApiServer {
         port,
         url: `http://localhost:${port}`,
       }, 'HTTP API server started successfully')
-    } catch (error) {
-      this.logger.error({ error }, 'Failed to start HTTP API server')
+    } catch (error: any) {
+      const code = error?.code || error?.message || ''
+      if (String(code).includes('EADDRINUSE') || String(error?.message).includes('EADDRINUSE')) {
+        this.logger.error(
+          { port },
+          `Port ${port} is already in use. Another claude-brain instance may be running. ` +
+          `Kill existing instances with: pkill -f "claude-brain serve"`
+        )
+      } else {
+        this.logger.error({ error }, 'Failed to start HTTP API server')
+      }
       throw error
     }
   }

package/src/server/pid-manager.ts

@@ -0,0 +1,64 @@
+/**
+ * PID file manager for the Claude Brain server.
+ * Ensures only one server instance runs at a time.
+ */
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { getHomePaths } from '@/config/home'
+
+const PID_FILENAME = 'server.pid'
+
+export class ServerPidManager {
+  private pidFilePath: string
+
+  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 {
+    if (!existsSync(this.pidFilePath)) return null
+
+    try {
+      const pid = parseInt(readFileSync(this.pidFilePath, 'utf-8').trim(), 10)
+      if (isNaN(pid)) {
+        this.cleanup()
+        return null
+      }
+      // Signal 0 tests if process exists without killing it
+      process.kill(pid, 0)
+      return pid
+    } catch {
+      // Process not running, clean up stale PID file
+      this.cleanup()
+      return null
+    }
+  }
+
+  /** Write the current process PID to the PID file. */
+  writePidFile(): void {
+    writeFileSync(this.pidFilePath, String(process.pid), 'utf-8')
+  }
+
+  /** Remove the PID file. Safe to call multiple times. */
+  cleanup(): void {
+    try {
+      unlinkSync(this.pidFilePath)
+    } catch {
+      // Already removed or doesn't exist
+    }
+  }
+
+  /** Register cleanup handlers on SIGINT, SIGTERM, and process exit. */
+  registerCleanupHandlers(): void {
+    const doCleanup = () => {
+      this.cleanup()
+    }
+
+    process.on('exit', doCleanup)
+    process.on('SIGINT', doCleanup)
+    process.on('SIGTERM', doCleanup)
+  }
+}

package/src/server/utils/memory-indicator.ts

@@ -16,13 +16,14 @@ const ANSI = {
 
 /**
  * Memory indicator banner shown when Claude Brain provides helpful data
+ * Note: No ANSI codes — MCP tool responses should be plain text/markdown
  */
-export const MEMORY_HELPED_BANNER = `${ANSI.brightRed}${ANSI.bold}🧠 MEMORY ASSISTED${ANSI.reset}`
+export const MEMORY_HELPED_BANNER = '🧠 MEMORY ASSISTED'
 
 /**
  * Alternative shorter indicator
  */
-export const MEMORY_HELPED_SHORT = `${ANSI.brightRed}[memory-assisted]${ANSI.reset}`
+export const MEMORY_HELPED_SHORT = '[memory-assisted]'
 
 /**
  * Wrap content with the memory helped indicator
@@ -63,7 +64,7 @@ export function formatMemoryStats(stats: {
 
   if (parts.length === 0) return ''
 
-  return `${ANSI.red}📊 Retrieved: ${parts.join(', ')}${ANSI.reset}`
+  return `📊 Retrieved: ${parts.join(', ')}`
 }
 
 /**

package/src/tools/schemas.ts

@@ -601,6 +601,11 @@ export const TOOLS = {
         project: {
           type: 'string',
           description: 'Project name (IMPORTANT: pass this to scope memories correctly, e.g. "my-app"). Auto-detected from message if omitted, defaults to "general".'
+        },
+        action: {
+          type: 'string',
+          enum: ['auto', 'store', 'recall', 'update', 'delete'],
+          description: 'Force a specific action instead of auto-detecting intent. "store" = always save, "recall" = always search, "update" = modify last stored, "delete" = remove. Default: auto (use intent classifier).'
         }
       },
       required: ['message']