claude-brain 0.22.2 → 0.22.4

package/VERSION

@@ -1 +1 @@
-0.22.2
+0.22.4

package/package.json

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

package/src/memory/chroma/store.ts

@@ -25,6 +25,7 @@ function sanitizeMetadata(metadata: Record<string, any>): Record<string, string
 }
 
 export interface StoreDecisionInput {
+  id?: string
   project: string
   context: string
   decision: string
@@ -141,7 +142,7 @@ export class ChromaMemoryStore {
       return firstDuplicate.id
     }
 
-    const id = randomUUID()
+    const id = input.id || randomUUID()
     const now = new Date().toISOString()
 
     const metadata: Record<string, any> = {
@@ -225,6 +226,7 @@ export class ChromaMemoryStore {
   }
 
   async storePattern(input: {
+    id?: string
     project: string
     pattern_type: 'solution' | 'anti-pattern' | 'best-practice' | 'common-issue'
     description: string
@@ -233,7 +235,7 @@ export class ChromaMemoryStore {
     context?: string
     source?: string
   }): Promise<string> {
-    const id = randomUUID()
+    const id = input.id || randomUUID()
     const now = new Date().toISOString()
 
     const metadata: Record<string, any> = {
@@ -300,6 +302,7 @@ export class ChromaMemoryStore {
   }
 
   async storeCorrection(input: {
+    id?: string
     project: string
     original: string
     correction: string
@@ -307,7 +310,7 @@ export class ChromaMemoryStore {
     context?: string
     confidence: number
   }): Promise<string> {
-    const id = randomUUID()
+    const id = input.id || randomUUID()
     const now = new Date().toISOString()
 
     const metadata: Record<string, any> = {

package/src/memory/fts5-search.ts

@@ -7,6 +7,7 @@
 import { randomUUID } from 'crypto'
 import type { Database } from 'bun:sqlite'
 import type { Logger } from 'pino'
+import { expandQuery } from '@/retrieval/query/expander'
 
 export type ObservationCategory = 'decision' | 'pattern' | 'correction' | 'insight' | 'preference'
 
@@ -174,8 +175,8 @@ export class FTS5Search {
   /**
    * Store a new observation. Returns the generated ID.
    */
-  store(observation: NewObservation): string {
-    const id = randomUUID()
+  store(observation: NewObservation, providedId?: string): string {
+    const id = providedId || randomUUID()
     const now = new Date().toISOString()
 
     const stmt = this.db.prepare(`
@@ -374,12 +375,13 @@ export class FTS5Search {
     const cleaned = query.replace(/[":*^~(){}[\]]/g, ' ').trim()
     if (!cleaned) return ''
 
-    // Split into words, filter short/stop words
-    const words = cleaned.split(/\s+/).filter(w => w.length >= 2)
-    if (words.length === 0) return ''
+    // Expand query with synonyms (e.g., "database" → also search "storage", "persistence")
+    const expanded = expandQuery(cleaned, { useSynonyms: true, maxExpansions: 8 })
+    const allWords = expanded.combined.split(/\s+/).filter(w => w.length >= 2)
+    const unique = [...new Set(allWords)]
 
-    // Join with OR for broad matching
-    return words.map(w => `"${w}"`).join(' OR ')
+    if (unique.length === 0) return ''
+    return unique.map(w => `"${w}"`).join(' OR ')
   }
 
   /**

package/src/memory/index.ts

@@ -5,6 +5,7 @@
  * Unified memory system manager that combines all components
  */
 
+import { randomUUID } from 'crypto'
 import type { Logger } from 'pino'
 import { MemoryDatabase } from './database'
 import { EmbeddingService } from './embeddings'
@@ -244,6 +245,9 @@ export class MemoryManager {
     reasoning: string,
     options?: { alternatives?: string; tags?: string[] }
   ): Promise<string> {
+    // BUG-001 fix: Generate a single shared ID for all backends
+    const sharedId = randomUUID()
+
     // Phase 26: Always store in FTS5 if available
     let fts5Id: string | undefined
     if (this._fts5) {
@@ -262,7 +266,7 @@ export class MemoryManager {
           reasoning,
           context,
           tags: options?.tags
-        })
+        }, sharedId)
       } catch (error) {
         this.logger.warn({ error }, 'FTS5 store failed, continuing with other backends')
       }
@@ -272,6 +276,7 @@ export class MemoryManager {
     if (this.useChromaDB) {
       try {
         const chromaId = await this.chroma.store.storeDecision({
+          id: sharedId,
           project,
           context,
           decision,
@@ -456,6 +461,9 @@ export class MemoryManager {
     context?: string
     source?: string
   }): Promise<string> {
+    // BUG-001 fix: Generate a single shared ID for all backends
+    const sharedId = randomUUID()
+
     // Phase 26: Dual-write to FTS5
     let fts5Id: string | undefined
     if (this._fts5) {
@@ -467,7 +475,7 @@ export class MemoryManager {
           context: input.context,
           confidence: input.confidence,
           source: input.source
-        })
+        }, sharedId)
       } catch (error) {
         this.logger.warn({ error }, 'FTS5 pattern store failed')
       }
@@ -475,7 +483,7 @@ export class MemoryManager {
 
     if (this.useChromaDB) {
       try {
-        const chromaId = await this.chroma.store.storePattern(input)
+        const chromaId = await this.chroma.store.storePattern({ ...input, id: sharedId })
         return fts5Id || chromaId
       } catch (error) {
         this.logger.warn({ error }, 'ChromaDB pattern store failed')
@@ -500,6 +508,9 @@ export class MemoryManager {
     context?: string
     confidence: number
   }): Promise<string> {
+    // BUG-001 fix: Generate a single shared ID for all backends
+    const sharedId = randomUUID()
+
     // Phase 26: Dual-write to FTS5
     let fts5Id: string | undefined
     if (this._fts5) {
@@ -511,7 +522,7 @@ export class MemoryManager {
           reasoning: input.reasoning,
           context: input.context,
           confidence: input.confidence
-        })
+        }, sharedId)
       } catch (error) {
         this.logger.warn({ error }, 'FTS5 correction store failed')
       }
@@ -519,7 +530,7 @@ export class MemoryManager {
 
     if (this.useChromaDB) {
       try {
-        const chromaId = await this.chroma.store.storeCorrection(input)
+        const chromaId = await this.chroma.store.storeCorrection({ ...input, id: sharedId })
         return fts5Id || chromaId
       } catch (error) {
         this.logger.warn({ error }, 'ChromaDB correction store failed')

package/src/retrieval/query/expander.ts

@@ -59,11 +59,16 @@ const SYNONYMS: Record<string, string[]> = {
   deploy: ['deployment', 'release', 'ship', 'publish'],
   build: ['compile', 'bundle', 'package'],
 
+  // Memory terms
+  memory: ['storage', 'store', 'cache', 'array'],
+
   // Common verbs
   create: ['add', 'new', 'generate', 'make'],
   update: ['modify', 'change', 'edit', 'patch'],
   delete: ['remove', 'destroy', 'drop'],
   get: ['fetch', 'retrieve', 'read', 'query'],
+  choose: ['select', 'pick', 'decide', 'opt', 'chose'],
+  chose: ['choose', 'select', 'pick', 'decide', 'opted'],
 
   // Framework terms
   react: ['reactjs', 'react.js', 'component'],

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

@@ -288,7 +288,7 @@ export class HttpApiServer {
 
   private async handleRecallSimilar(c: any): Promise<Response> {
     try {
-      const query = c.req.query('query') || ''
+      const query = c.req.query('query') || c.req.query('q') || ''
 
       const memoryService = getMemoryService()
 
@@ -583,6 +583,16 @@ export class HttpApiServer {
     }
   }
 
+  /** Normalize project param — extract basename if full path provided */
+  private normalizeProject(raw: string): string {
+    if (!raw) return raw
+    // If it looks like a path (contains /), extract the last segment
+    if (raw.includes('/')) {
+      return raw.split('/').filter(Boolean).pop() || raw
+    }
+    return raw
+  }
+
   // ─── Phase 28: Code Intelligence Endpoints ─────────────────
 
   private async handleCodeIndex(c: any): Promise<Response> {
@@ -669,7 +679,7 @@ export class HttpApiServer {
       }
 
       const query = c.req.query('query') || c.req.query('q') || ''
-      const project = c.req.query('project') || ''
+      const project = this.normalizeProject(c.req.query('project') || '')
       const limit = parseInt(c.req.query('limit') || '20', 10)
 
       if (!query || !project) {
@@ -699,11 +709,11 @@ export class HttpApiServer {
         )
       }
 
-      const project = c.req.query('project') || ''
+      const project = this.normalizeProject(c.req.query('project') || '')
 
       if (!project) {
         return Response.json(
-          { success: false, error: 'project is required' },
+          { success: false, error: 'project query parameter is required (e.g., ?project=my-app)' },
           { status: 400 }
         )
       }
@@ -730,11 +740,11 @@ export class HttpApiServer {
       }
 
       const file = c.req.query('file') || ''
-      const project = c.req.query('project') || ''
+      const project = this.normalizeProject(c.req.query('project') || '')
 
       if (!file || !project) {
         return Response.json(
-          { success: false, error: 'file and project are required' },
+          { success: false, error: 'file and project query parameters are required (e.g., ?file=src/index.ts&project=my-app)' },
           { status: 400 }
         )
       }
@@ -759,11 +769,11 @@ export class HttpApiServer {
         )
       }
 
-      const project = c.req.query('project') || ''
+      const project = this.normalizeProject(c.req.query('project') || '')
 
       if (!project) {
         return Response.json(
-          { success: false, error: 'project is required' },
+          { success: false, error: 'project query parameter is required (e.g., ?project=my-app)' },
           { status: 400 }
         )
       }
@@ -783,7 +793,7 @@ export class HttpApiServer {
 
   private async handleContextQuery(c: any): Promise<Response> {
     try {
-      const query = c.req.query('query') || ''
+      const query = c.req.query('query') || c.req.query('q') || ''
       const type = c.req.query('type') || ''
       const cwd = c.req.query('cwd') || ''
       const limit = parseInt(c.req.query('limit') || '5', 10)
@@ -804,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 }),
         ])

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/server/web-viewer.ts

@@ -30,7 +30,7 @@ export function setupWebViewer(app: Hono): void {
   // Search endpoint — queries FTS5
   app.get('/api/memory/search', async (c) => {
     try {
-      const query = c.req.query('q') || ''
+      const query = c.req.query('query') || c.req.query('q') || ''
       const project = c.req.query('project') || undefined
       const category = c.req.query('category') || undefined
       const limit = parseInt(c.req.query('limit') || '20', 10)

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']