claude-brain 0.22.1 → 0.22.3

package/VERSION

@@ -1 +1 @@
-0.22.1
+0.22.3

package/package.json

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

package/src/cli/commands/status.ts

@@ -39,16 +39,17 @@ export async function runStatus() {
       const { Database } = await import('bun:sqlite')
       const db = new Database(dbPath, { readonly: true })
 
-      // Count observations by category
+      // Count observations by category (dynamic — includes all categories)
       const total = (db.prepare('SELECT COUNT(*) as cnt FROM observations WHERE archived = 0').get() as any)?.cnt ?? 0
-      const decisions = (db.prepare("SELECT COUNT(*) as cnt FROM observations WHERE category = 'decision' AND archived = 0").get() as any)?.cnt ?? 0
-      const patterns = (db.prepare("SELECT COUNT(*) as cnt FROM observations WHERE category = 'pattern' AND archived = 0").get() as any)?.cnt ?? 0
-      const corrections = (db.prepare("SELECT COUNT(*) as cnt FROM observations WHERE category = 'correction' AND archived = 0").get() as any)?.cnt ?? 0
+      const catRows = db.prepare(
+        'SELECT category, COUNT(*) as cnt FROM observations WHERE archived = 0 GROUP BY category'
+      ).all() as any[]
+      const breakdown = catRows.map((r: any) => `${r.cnt} ${r.category}s`).join(', ')
 
       items.push({ label: 'Storage', value: 'SQLite FTS5', status: 'success' })
       items.push({
         label: 'Observations',
-        value: `${total} (${decisions} decisions, ${patterns} patterns, ${corrections} corrections)`,
+        value: `${total}${breakdown ? ` (${breakdown})` : ''}`,
         status: total > 0 ? 'success' : 'warning'
       })
 
@@ -79,7 +80,7 @@ export async function runStatus() {
       const symbols = (codeDb.prepare('SELECT COUNT(*) as cnt FROM code_symbols').get() as any)?.cnt ?? 0
 
       // Last indexed time
-      const latest = (codeDb.prepare('SELECT MAX(indexed_at) as latest FROM code_files').get() as any)?.latest
+      const latest = (codeDb.prepare('SELECT MAX(last_indexed) as latest FROM code_files').get() as any)?.latest
       const lastIndexed = latest ? formatAge(latest) : 'never'
 
       items.push({

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(`
@@ -245,15 +246,21 @@ export class FTS5Search {
   /**
    * Fetch all observations for a project, optionally filtered by category.
    */
-  fetchAll(project: string, category?: ObservationCategory): ObservationResult[] {
+  fetchAll(project?: string, category?: ObservationCategory): ObservationResult[] {
     let sql: string
-    const params: any[] = [project]
+    const params: any[] = []
 
-    if (category) {
+    if (project && category) {
       sql = `SELECT * FROM observations WHERE project = ? AND category = ? AND archived = 0 ORDER BY created_at DESC`
+      params.push(project, category)
+    } else if (project) {
+      sql = `SELECT * FROM observations WHERE project = ? AND archived = 0 ORDER BY created_at DESC`
+      params.push(project)
+    } else if (category) {
+      sql = `SELECT * FROM observations WHERE category = ? AND archived = 0 ORDER BY created_at DESC`
       params.push(category)
     } else {
-      sql = `SELECT * FROM observations WHERE project = ? AND archived = 0 ORDER BY created_at DESC`
+      sql = `SELECT * FROM observations WHERE archived = 0 ORDER BY created_at DESC`
     }
 
     const rows = this.db.prepare(sql).all(...params) as any[]
@@ -337,6 +344,26 @@ export class FTS5Search {
     this.recordAccess(id)
   }
 
+  /**
+   * BUG-002: Search within a specific category, optionally scoped to a project.
+   * Returns results ordered by creation date (most recent first).
+   */
+  searchByCategory(category: ObservationCategory, project?: string, limit: number = 10): ObservationResult[] {
+    let sql: string
+    const params: any[] = []
+
+    if (project) {
+      sql = `SELECT * FROM observations WHERE category = ? AND project = ? AND archived = 0 ORDER BY created_at DESC LIMIT ?`
+      params.push(category, project, limit)
+    } else {
+      sql = `SELECT * FROM observations WHERE category = ? AND archived = 0 ORDER BY created_at DESC LIMIT ?`
+      params.push(category, limit)
+    }
+
+    const rows = this.db.prepare(sql).all(...params) as any[]
+    return rows.map(row => this.rowToResult(row))
+  }
+
   // --- Private helpers ---
 
   /**
@@ -348,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 ')
   }
 
   /**
@@ -362,9 +390,9 @@ export class FTS5Search {
    * Typical range: -20 (excellent) to 0 (poor).
    */
   private normalizeBM25(score: number): number {
-    // Map typical BM25 range to 0.5-0.85
+    // Map BM25 range to 0.2-0.9 (wider range, allows low scores to be filtered)
     const normalized = Math.min(1, Math.max(0, score / 20))
-    return 0.5 + normalized * 0.35
+    return 0.2 + normalized * 0.7
   }
 
   /**

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')
@@ -543,8 +554,8 @@ export class MemoryManager {
       limit?: number
     }
   ): Promise<any[]> {
-    // Phase 26: Try FTS5 first
-    if (this._fts5 && project) {
+    // Phase 26: Try FTS5 first (BUG-002: works with or without project)
+    if (this._fts5) {
       const results = this._fts5.fetchAll(project, 'pattern')
       if (results.length > 0) {
         return results.map(r => ({
@@ -580,8 +591,8 @@ export class MemoryManager {
     project?: string,
     options?: { limit?: number }
   ): Promise<any[]> {
-    // Phase 26: Try FTS5 first
-    if (this._fts5 && project) {
+    // Phase 26: Try FTS5 first (BUG-002: works with or without project)
+    if (this._fts5) {
       const results = this._fts5.fetchAll(project, 'correction')
       if (results.length > 0) {
         return results.map(r => ({
@@ -615,8 +626,8 @@ export class MemoryManager {
    * Used by analytical tools that need bulk access to decision data
    */
   async fetchAllDecisions(project?: string): Promise<any[]> {
-    // Phase 26: Try FTS5 first
-    if (this._fts5 && project) {
+    // Phase 26: Try FTS5 first (BUG-002: works with or without project)
+    if (this._fts5) {
       const results = this._fts5.fetchAll(project, 'decision')
       if (results.length > 0) {
         return results.map(r => ({
@@ -664,8 +675,8 @@ export class MemoryManager {
    * Fetch all patterns with content — routes to FTS5, ChromaDB, or legacy SQLite
    */
   async fetchAllPatterns(project?: string): Promise<any[]> {
-    // Phase 26: Try FTS5 first
-    if (this._fts5 && project) {
+    // Phase 26: Try FTS5 first (BUG-002: works with or without project)
+    if (this._fts5) {
       const results = this._fts5.fetchAll(project, 'pattern')
       if (results.length > 0) {
         return results.map(r => ({
@@ -713,8 +724,8 @@ export class MemoryManager {
    * Fetch all corrections with content — routes to FTS5, ChromaDB, or legacy SQLite
    */
   async fetchAllCorrections(project?: string): Promise<any[]> {
-    // Phase 26: Try FTS5 first
-    if (this._fts5 && project) {
+    // Phase 26: Try FTS5 first (BUG-002: works with or without project)
+    if (this._fts5) {
       const results = this._fts5.fetchAll(project, 'correction')
       if (results.length > 0) {
         return results.map(r => ({
@@ -873,14 +884,47 @@ export class MemoryManager {
     reasoning: string,
     options?: { alternatives?: string; tags?: string[] }
   ): Promise<string> {
-    // Delete old version — fires onDecisionDeletedCallbacks (graph + episode cleanup)
+    // BUG-001: True in-place update using FTS5 (preserves original ID)
+    if (this._fts5) {
+      try {
+        this._fts5.update(oldId, {
+          content: decision,
+          reasoning,
+          context,
+          tags: options?.tags
+        })
+        this.logger.debug({ oldId }, 'Decision updated in-place via FTS5')
+
+        // Also update ChromaDB if available (best-effort)
+        if (this.useChromaDB) {
+          try {
+            await this.chroma.store.deleteDecision(oldId)
+            await this.chroma.store.storeDecision({
+              project,
+              context,
+              decision,
+              reasoning,
+              alternatives: options?.alternatives,
+              tags: options?.tags
+            })
+          } catch {
+            // ChromaDB sync failed, FTS5 is source of truth
+          }
+        }
+
+        return oldId // SAME ID preserved
+      } catch (error) {
+        this.logger.warn({ error, oldId }, 'FTS5 in-place update failed, falling back to delete+store')
+      }
+    }
+
+    // Fallback: delete + store (legacy behavior for non-FTS5 backends)
     try {
       await this.deleteDecision(oldId)
       this.logger.debug({ oldId }, 'Old decision deleted for update')
     } catch (error) {
       this.logger.warn({ error, oldId }, 'Failed to delete old decision during update, storing new version anyway')
     }
-    // Store new version — fires onDecisionStoredCallbacks (graph rebuild)
     const newId = await this.rememberDecision(project, context, decision, reasoning, options)
     this.logger.debug({ oldId, newId }, 'Decision updated: old deleted, new stored')
     return newId

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

@@ -225,7 +225,7 @@ export class ResponseFilter {
       ? (left + right) / 2
       : right
 
-    const threshold = Math.max(median * 0.7, 0.35)
+    const threshold = Math.max(median * 0.7, 0.45)
 
     return results.filter(r => r.score >= threshold)
   }

package/src/routing/router.ts

@@ -33,8 +33,8 @@ import type { ObservationCompressor } from '@/memory/compression'
 const DEFAULT_PROJECT = 'general'
 
 /** Phase 19 D4: Minimum similarity for destructive operations */
-const DELETE_MIN_SIMILARITY = 0.5
-const UPDATE_MIN_SIMILARITY = 0.5
+const DELETE_MIN_SIMILARITY = 0.3
+const UPDATE_MIN_SIMILARITY = 0.3
 
 export interface BrainInput {
   message: string
@@ -879,7 +879,23 @@ export class BrainRouter {
             relevantItems: 0
           }
         } else if (results.length > 0 && matchSimilarity < DELETE_MIN_SIMILARITY) {
-          // D4: No confident match
+          // D4: No confident match — try direct FTS5 content search as fallback
+          const memory = getMemoryService()
+          if (memory.fts5) {
+            const ftsResults = memory.fts5.search(topic, effectiveProject, 3)
+            if (ftsResults.length > 0) {
+              const ftsTarget = ftsResults[0]
+              await memory.deleteDecision(ftsTarget.id)
+              if (this.lastStoredId === ftsTarget.id) this.lastStoredId = null
+              this.searchEngine.invalidateCache(effectiveProject)
+              return {
+                action: 'stored',
+                summary: `Deleted memory`,
+                content: `Deleted: "${ftsTarget.content.slice(0, 100)}" (ID: ${ftsTarget.id})`,
+                relevantItems: 0
+              }
+            }
+          }
           return {
             action: 'none',
             summary: 'No confident match to delete',
@@ -936,6 +952,12 @@ export class BrainRouter {
       return this.servicesNotReady()
     }
 
+    // BUG-002: Detect category-based queries and route to fetchAll
+    const categoryIntent = this.detectCategoryIntent(message)
+    if (categoryIntent) {
+      return this.handleCategoryQuery(message, project, categoryIntent)
+    }
+
     // Phase 25: Use undefined for search (no project filter = search all) when no project detected
     const searchProject = project || undefined
     const displayProject = project || DEFAULT_PROJECT
@@ -1832,6 +1854,102 @@ export class BrainRouter {
     return { content }
   }
 
+  /**
+   * BUG-002: Detect category-based intent from question messages.
+   * Returns the category if the user is asking about a specific type of memory.
+   */
+  private detectCategoryIntent(message: string): 'decision' | 'pattern' | 'correction' | null {
+    const lower = message.toLowerCase()
+
+    // Decision-oriented queries
+    if (
+      lower.includes('what decisions') || lower.includes('my decisions') ||
+      lower.includes('what have i decided') || lower.includes('what did i decide') ||
+      lower.includes('what choices') || lower.includes('decisions i') ||
+      lower.includes('list decisions') || lower.includes('show decisions') ||
+      lower.includes('all decisions') || lower.includes('what did i choose')
+    ) {
+      return 'decision'
+    }
+
+    // Pattern-oriented queries
+    if (
+      lower.includes('what patterns') || lower.includes('my patterns') ||
+      lower.includes('best practices') || lower.includes('conventions') ||
+      lower.includes('list patterns') || lower.includes('show patterns') ||
+      lower.includes('all patterns')
+    ) {
+      return 'pattern'
+    }
+
+    // Correction-oriented queries
+    if (
+      lower.includes('what mistakes') || lower.includes('my mistakes') ||
+      lower.includes('what bugs') || lower.includes('lessons learned') ||
+      lower.includes('what corrections') || lower.includes('my corrections') ||
+      lower.includes('list corrections') || lower.includes('show corrections') ||
+      lower.includes('all corrections') || lower.includes('what have i fixed') ||
+      lower.includes('what did i fix')
+    ) {
+      return 'correction'
+    }
+
+    return null
+  }
+
+  /**
+   * BUG-002: Handle category-scoped queries by fetching all items of that category.
+   */
+  private async handleCategoryQuery(
+    message: string,
+    project: string | undefined,
+    category: 'decision' | 'pattern' | 'correction'
+  ): Promise<BrainResponse> {
+    const memory = getMemoryService()
+    const projectLabel = project || 'all projects'
+
+    let items: any[]
+    switch (category) {
+      case 'decision':
+        items = await memory.fetchAllDecisions(project)
+        break
+      case 'pattern':
+        items = await memory.fetchAllPatterns(project)
+        break
+      case 'correction':
+        items = await memory.fetchAllCorrections(project)
+        break
+    }
+
+    if (items.length === 0) {
+      return {
+        action: 'none',
+        summary: `No ${category}s found`,
+        content: `No ${category}s found for ${projectLabel}.`,
+        relevantItems: 0
+      }
+    }
+
+    // Format as compact items
+    const allItems = items.map(item => ({
+      id: item.id || item.decision_id,
+      content: typeof (item.decision || item.description || item.correction || item.original || item.document || item.content) === 'string'
+        ? (item.decision || item.description || item.correction || item.original || item.document || item.content)
+        : JSON.stringify(item.decision || item.description || item.correction || item.original || item.document || item.content || ''),
+      category,
+      project: item.project || project || 'general',
+      created_at: item.created_at || item.date || '',
+    }))
+
+    const compactContent = formatCompactResponse(allItems, `${category}s for ${projectLabel}`)
+    return {
+      action: 'retrieved',
+      summary: `${items.length} ${category}s for ${projectLabel}`,
+      content: compactContent,
+      relevantItems: items.length
+    }
+  }
+
   private generateTaskId(title: string): string {
     return title
       .toLowerCase()

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> {
@@ -595,7 +605,7 @@ export class HttpApiServer {
       }
 
       const body = await c.req.json()
-      const { projectPath, projectName } = body
+      const { projectPath, projectName, force } = body
 
       if (!projectPath || !projectName) {
         return Response.json(
@@ -604,6 +614,20 @@ export class HttpApiServer {
         )
       }
 
+      // BUG-004: Clear existing index data when force flag is set
+      if (force && this.codeQuery) {
+        try {
+          const db = (this.codeQuery as any).db
+          if (db) {
+            db.run('DELETE FROM code_files WHERE project = ?', projectName)
+            db.run('DELETE FROM code_symbols WHERE project = ?', projectName)
+            this.logger.info({ projectName }, 'Force reindex: cleared existing data')
+          }
+        } catch (error) {
+          this.logger.warn({ error, projectName }, 'Failed to clear index data for force reindex')
+        }
+      }
+
       const result = await this.codeIndexer.indexProject(projectPath, projectName)
       return Response.json({ success: true, data: result })
     } catch (error) {
@@ -654,8 +678,8 @@ export class HttpApiServer {
         )
       }
 
-      const query = c.req.query('query') || ''
-      const project = c.req.query('project') || ''
+      const query = c.req.query('query') || c.req.query('q') || ''
+      const project = this.normalizeProject(c.req.query('project') || '')
       const limit = parseInt(c.req.query('limit') || '20', 10)
 
       if (!query || !project) {
@@ -685,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 }
         )
       }
@@ -716,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 }
         )
       }
@@ -745,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 }
         )
       }
@@ -769,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)

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

@@ -600,7 +600,7 @@ export const TOOLS = {
         },
         project: {
           type: 'string',
-          description: 'Project name (optional — auto-detected from message if omitted)'
+          description: 'Project name (IMPORTANT: pass this to scope memories correctly, e.g. "my-app"). Auto-detected from message if omitted, defaults to "general".'
         }
       },
       required: ['message']