claude-mem-lite 2.19.0 → 2.20.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.19.0",
+      "version": "2.20.0",
       "source": "./",
       "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/hook.mjs

@@ -723,8 +723,9 @@ async function handleSessionStart() {
     try { getVocabulary(db); } catch (e) { debugCatch(e, 'session-start-vocab'); }
 
     // Auto-update check (24h throttle, 3s timeout, silent on failure)
-    // Fire-and-forget: don't block SessionStart for up to 3s network timeout
-    checkForUpdate().then(updateResult => {
+    // Awaited so process.exit(0) doesn't kill the promise before notification
+    try {
+      const updateResult = await checkForUpdate();
       if (updateResult?.updated) {
         process.stdout.write(`\n🔄 claude-mem-lite: v${updateResult.from} → v${updateResult.to} updated\n`);
       } else if (updateResult?.updateAvailable) {
@@ -733,7 +734,7 @@ async function handleSessionStart() {
           : '';
         process.stdout.write(`\n📦 claude-mem-lite: v${updateResult.to} available (current: v${updateResult.from})${hint}\n`);
       }
-    }).catch(e => debugCatch(e, 'session-start-update'));
+    } catch (e) { debugCatch(e, 'session-start-update'); }
 
   } finally {
     db.close();

package/install.mjs

@@ -51,13 +51,13 @@ function reindexKnownResources(rdb) {
     UPDATE resources SET
       intent_tags = ?, domain_tags = ?,
       capability_summary = ?, trigger_patterns = ?,
-      invocation_name = CASE WHEN ?1 != '' THEN ?1 ELSE invocation_name END,
-      recommendation_mode = CASE WHEN ?2 != '' THEN ?2 ELSE recommendation_mode END,
-      keywords = CASE WHEN ?3 != '' THEN ?3 ELSE keywords END,
-      tech_stack = CASE WHEN ?4 != '' THEN ?4 ELSE tech_stack END,
-      use_cases = CASE WHEN ?5 != '' THEN ?5 ELSE use_cases END,
+      invocation_name = CASE WHEN ? != '' THEN ? ELSE invocation_name END,
+      recommendation_mode = CASE WHEN ? != '' THEN ? ELSE recommendation_mode END,
+      keywords = CASE WHEN ? != '' THEN ? ELSE keywords END,
+      tech_stack = CASE WHEN ? != '' THEN ? ELSE tech_stack END,
+      use_cases = CASE WHEN ? != '' THEN ? ELSE use_cases END,
       updated_at = datetime('now')
-    WHERE type = ?6 AND name = ?7
+    WHERE type = ? AND name = ?
   `);
 
   rdb.transaction(() => {
@@ -68,14 +68,17 @@ function reindexKnownResources(rdb) {
       const name = key.slice(sep + 1);
       const invName = meta.invocation_name || deriveInvocationName(name);
       const recMode = meta.recommendation_mode || '';
+      const kw = meta.keywords || '';
+      const ts = meta.tech_stack || '';
+      const uc = meta.use_cases || '';
       update.run(
         meta.intent_tags, meta.domain_tags,
         meta.capability_summary, meta.trigger_patterns,
-        invName,
-        recMode,
-        meta.keywords || '',
-        meta.tech_stack || '',
-        meta.use_cases || '',
+        invName, invName,
+        recMode, recMode,
+        kw, kw,
+        ts, ts,
+        uc, uc,
         type, name
       );
     }

package/nlp.mjs

@@ -0,0 +1,187 @@
+// nlp.mjs -- FTS5 query building, synonym expansion, CJK tokenization.
+// Extracted from utils.mjs for focused module boundaries.
+
+import { BASE_STOP_WORDS } from './stop-words.mjs';
+import { SYNONYM_MAP, CJK_COMPOUNDS } from './synonyms.mjs';
+
+// Re-export for backward compatibility (consumers import from nlp.mjs or utils.mjs)
+export { SYNONYM_MAP, CJK_COMPOUNDS };
+
+// ─── FTS5 Constants ──────────────────────────────────────────────────────────
+
+const FTS5_KEYWORDS = new Set(['AND', 'OR', 'NOT', 'NEAR']);
+
+// Sort by length descending for greedy matching
+const CJK_SORTED = [...CJK_COMPOUNDS].sort((a, b) => b.length - a.length);
+
+/**
+ * Generate search tokens from CJK text using dictionary-first tokenization.
+ * Compound words are emitted whole; remaining chars use bigram fallback.
+ * "修复了数据库崩溃" → "修复 数据库 崩溃" (3 clean tokens)
+ * vs old bigram: "修复 复了 了数 数据 据库 库崩 崩溃" (7 noisy tokens)
+ * @param {string} text Input text containing CJK characters
+ * @returns {string} Space-separated tokens
+ */
+export function cjkBigrams(text) {
+  if (!text) return '';
+  const runs = text.match(/[\u4e00-\u9fff\u3400-\u4dbf]{2,}/g) || [];
+  const tokens = [];
+  for (const run of runs) {
+    let i = 0;
+    while (i < run.length) {
+      let matched = false;
+      // Greedy dictionary match (longest first)
+      for (const word of CJK_SORTED) {
+        if (i + word.length <= run.length && run.slice(i, i + word.length) === word) {
+          tokens.push(word);
+          i += word.length;
+          matched = true;
+          break;
+        }
+      }
+      if (!matched) {
+        // Fallback: bigram for unknown compound
+        if (i + 1 < run.length) {
+          tokens.push(run[i] + run[i + 1]);
+        }
+        i++;
+      }
+    }
+  }
+  return [...new Set(tokens)].join(' ');
+}
+
+// ─── CJK Synonym Extraction ─────────────────────────────────────────────────
+
+// Extract known CJK words (from SYNONYM_MAP) out of unsegmented CJK text.
+// Greedy longest-match: "数据库的全文搜索" → ["数据库", "搜索"] (skips particles/unknown).
+const _cjkSynonymKeys = [...SYNONYM_MAP.keys()]
+  .filter(k => /[\u4e00-\u9fff\u3400-\u4dbf]/.test(k))
+  .sort((a, b) => b.length - a.length); // longest first
+
+export function extractCjkSynonymTokens(text) {
+  const found = [];
+  let i = 0;
+  while (i < text.length) {
+    let matched = false;
+    for (const key of _cjkSynonymKeys) {
+      if (text.startsWith(key, i)) {
+        found.push(key);
+        i += key.length;
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) i++;
+  }
+  return found;
+}
+
+// ─── FTS5 Token Formatting ──────────────────────────────────────────────────
+
+// Format a term for FTS5: quote if it contains spaces, hyphens, or special chars
+function ftsToken(term) {
+  // Bare tokens are safe if purely alphanumeric or CJK characters
+  if (/^[a-zA-Z0-9\u4e00-\u9fff\u3400-\u4dbf]+$/.test(term)) return term;
+  return `"${term.replace(/"/g, '""')}"`;
+}
+
+export function expandToken(token) {
+  const synonyms = SYNONYM_MAP.get(token.toLowerCase());
+  if (!synonyms || synonyms.size === 0) return ftsToken(token);
+  // FTS5 OR group: (original OR synonym1 OR "multi word synonym")
+  const parts = [ftsToken(token)];
+  for (const syn of synonyms) {
+    parts.push(ftsToken(syn));
+  }
+  return `(${parts.join(' OR ')})`;
+}
+
+// ─── Stop Words ──────────────────────────────────────────────────────────────
+
+export const FTS_STOP_WORDS = new Set([...BASE_STOP_WORDS]);
+
+// ─── FTS5 Query Sanitization ─────────────────────────────────────────────────
+
+/**
+ * Sanitize and expand a user query into a valid FTS5 query string.
+ * Strips special characters, expands synonyms, and joins with AND/space.
+ * @param {string} query Raw user search query
+ * @returns {string|null} FTS5-safe query or null if empty
+ */
+export function sanitizeFtsQuery(query) {
+  if (!query) return null;
+  const cleaned = query
+    .replace(/[{}()[\]^~*:"\\]/g, ' ')
+    .replace(/(^|\s)-/g, '$1')
+    .trim();
+  if (!cleaned) return null;
+  let tokens = cleaned.split(/\s+/).filter(t =>
+    t && !/^-+$/.test(t) && !FTS5_KEYWORDS.has(t.toUpperCase()) && !/^NEAR\/\d+$/i.test(t)
+    // Skip single ASCII-letter tokens — too noisy for FTS5 (CJK single chars handled separately below)
+    && !(t.length === 1 && /^[a-zA-Z]$/.test(t))
+  );
+  // Filter stop words (but keep all if filtering would empty the query)
+  const filtered = tokens.filter(t => !FTS_STOP_WORDS.has(t.toLowerCase()));
+  if (filtered.length > 0) tokens = filtered;
+  // Split unsegmented CJK tokens into known vocabulary words for synonym expansion.
+  // e.g. "数据库的全文搜索" → ["数据库", "搜索"] (both have EN synonyms in SYNONYM_MAP)
+  const expandedTokens = [];
+  let cjkExtracted = false;
+  for (const t of tokens) {
+    if (/[\u4e00-\u9fff\u3400-\u4dbf]/.test(t) && t.length > 2) {
+      const cjkWords = extractCjkSynonymTokens(t);
+      if (cjkWords.length > 0) {
+        expandedTokens.push(...cjkWords);
+        cjkExtracted = true;
+        continue;
+      }
+    }
+    expandedTokens.push(t);
+  }
+  tokens = expandedTokens;
+  if (tokens.length === 0) return null;
+  // Replace single CJK character tokens with bigrams for better phrase matching.
+  // Individual CJK chars ("系","统") are too noisy; bigrams ("系统") capture compound words.
+  // Skip bigrams when CJK synonym extraction already produced meaningful tokens —
+  // bigrams joined with AND would make the query too restrictive.
+  const bigrams = cjkExtracted ? null : cjkBigrams(cleaned);
+  const bigramSet = new Set(bigrams ? bigrams.split(' ').filter(Boolean) : []);
+  const hasBigrams = bigramSet.size > 0;
+  const finalTokens = [];
+  const seen = new Set();
+  const rawTokensSeen = new Set(); // track raw tokens to prevent bigram duplicates
+  for (const t of tokens) {
+    // Skip single CJK characters when we have bigrams — they're subsumed by bigram tokens
+    if (hasBigrams && /^[\u4e00-\u9fff\u3400-\u4dbf]$/.test(t)) continue;
+    const expanded = expandToken(t);
+    if (!seen.has(expanded)) { seen.add(expanded); rawTokensSeen.add(t); finalTokens.push(expanded); }
+  }
+  for (const bg of bigramSet) {
+    if (!seen.has(bg) && !rawTokensSeen.has(bg)) { seen.add(bg); finalTokens.push(bg); }
+  }
+  if (finalTokens.length === 0) return null;
+  // FTS5 requires explicit AND after parenthesized OR groups
+  const hasGroup = finalTokens.some(e => e.startsWith('('));
+  return finalTokens.join(hasGroup ? ' AND ' : ' ');
+}
+
+/**
+ * Relax an AND-joined FTS5 query to OR-joined for fallback search.
+ * Only useful when the original query has multiple tokens (single-token queries
+ * are already as relaxed as possible).
+ * @param {string} ftsQuery Original AND-joined FTS5 query from sanitizeFtsQuery
+ * @returns {string|null} OR-joined query, or null if relaxation wouldn't help
+ */
+export function relaxFtsQueryToOr(ftsQuery) {
+  if (!ftsQuery) return null;
+  // Replace AND joins with OR — handles both explicit " AND " and implicit space joins
+  const orQuery = ftsQuery.replace(/ AND /g, ' OR ');
+  // If no AND was present, tokens are space-joined (implicit AND); convert to OR
+  if (orQuery === ftsQuery && !ftsQuery.includes(' OR ')) {
+    const parts = ftsQuery.split(/\s+/);
+    if (parts.length < 2) return null; // single token — OR won't help
+    return parts.join(' OR ');
+  }
+  return orQuery !== ftsQuery ? orQuery : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {
@@ -46,6 +46,11 @@
     "skip-tools.mjs",
     "tool-schemas.mjs",
     "utils.mjs",
+    "nlp.mjs",
+    "scoring-sql.mjs",
+    "stop-words.mjs",
+    "tier.mjs",
+    "tfidf.mjs",
     "project-utils.mjs",
     "secret-scrub.mjs",
     "format-utils.mjs",

package/scoring-sql.mjs

@@ -0,0 +1,41 @@
+// scoring-sql.mjs — SQL constants for BM25 scoring and temporal decay.
+// Extracted from utils.mjs for focused module boundaries.
+
+// ─── Type-Differentiated Recency Decay ──────────────────────────────────────
+
+/** Recency half-life per observation type (in milliseconds) */
+export const DECAY_HALF_LIFE_BY_TYPE = {
+  decision:  90 * 86400000,  // 90 days — architectural decisions persist
+  discovery: 60 * 86400000,  // 60 days — learned patterns last
+  feature:   30 * 86400000,  // 30 days — feature work is mid-range
+  bugfix:    14 * 86400000,  // 14 days — bugs are usually one-off
+  refactor:  14 * 86400000,  // 14 days — code cleanup
+  change:     7 * 86400000,  //  7 days — routine changes decay fast
+};
+export const DEFAULT_DECAY_HALF_LIFE_MS = 14 * 86400000;
+
+// ─── BM25 Weight Constants ──────────────────────────────────────────────────
+// Single source of truth for FTS5 BM25 weight expressions.
+// Column order must match ensureFTS() calls in schema.mjs.
+
+/** observations_fts BM25 weights: title=10, subtitle=5, narrative=5, text=3, facts=3, concepts=2, lesson_learned=8 */
+export const OBS_BM25 = 'bm25(observations_fts, 10, 5, 5, 3, 3, 2, 8)';
+
+/** session_summaries_fts BM25 weights: request=5, investigated=3, learned=3, completed=3, next_steps=2, notes=1, remaining_items=1 */
+export const SESS_BM25 = 'bm25(session_summaries_fts, 5, 3, 3, 3, 2, 1, 1)';
+
+/** FTS5 columns for observations (must match BM25 weight order) */
+export const OBS_FTS_COLUMNS = ['title', 'subtitle', 'narrative', 'text', 'facts', 'concepts', 'lesson_learned'];
+
+/** SQL CASE for type-differentiated recency decay half-lives (milliseconds) */
+export const TYPE_DECAY_CASE = `(
+  CASE o.type
+    WHEN 'decision'  THEN 7776000000.0
+    WHEN 'discovery' THEN 5184000000.0
+    WHEN 'feature'   THEN 2592000000.0
+    WHEN 'bugfix'    THEN 1209600000.0
+    WHEN 'refactor'  THEN 1209600000.0
+    WHEN 'change'    THEN  604800000.0
+    ELSE 1209600000.0
+  END
+)`;

package/server-internals.mjs

@@ -76,8 +76,6 @@ export function reRankWithContext(db, results, project) {
  */
 export function markSuperseded(db, results) {
   if (!results || results.length === 0) return;
-  const now = Date.now();
-  const updateStmt = db ? db.prepare('UPDATE observations SET superseded_at = ?, superseded_by = ? WHERE id = ? AND superseded_at IS NULL') : null;
   // Build map: file → [result objects], only for obs with files
   const fileMap = new Map();
   for (const r of results) {
@@ -89,7 +87,9 @@ export function markSuperseded(db, results) {
       fileMap.get(f).push(r);
     }
   }
-  // For each file with 2+ observations: mark older lower-importance as superseded
+  // For each file with 2+ observations: mark older lower-importance as superseded (in-memory only)
+  // Note: DB persistence removed — search is a read operation and should not write.
+  // Persistent superseding belongs in mem_maintain/mem_compress write paths.
   for (const [, obsForFile] of fileMap) {
     if (obsForFile.length < 2) continue;
     obsForFile.sort((a, b) => (b.date || '').localeCompare(a.date || ''));
@@ -97,11 +97,6 @@ export function markSuperseded(db, results) {
     for (let i = 1; i < obsForFile.length; i++) {
       if ((obsForFile[i].importance ?? 1) <= (newest.importance ?? 1)) {
         obsForFile[i].superseded = true;
-        if (db) {
-          try {
-            updateStmt.run(now, newest.id, obsForFile[i].id);
-          } catch (e) { debugCatch(e, 'markSuperseded-persist'); }
-        }
       }
     }
   }

package/server.mjs

@@ -729,7 +729,7 @@ server.registerTool(
       // Auto-boost importance for frequently accessed observations
       autoBoostIfNeeded(db, args.ids);
       rows = db.prepare(`SELECT * FROM observations WHERE id IN (${placeholders}) ORDER BY created_at_epoch ASC`).all(...args.ids);
-      allFields = ['id', 'type', 'title', 'subtitle', 'narrative', 'text', 'facts', 'concepts', 'files_read', 'files_modified', 'project', 'created_at', 'memory_session_id', 'prompt_number', 'importance', 'related_ids', 'access_count', 'branch', 'superseded_at', 'superseded_by', 'last_accessed_at'];
+      allFields = ['id', 'type', 'title', 'subtitle', 'narrative', 'text', 'facts', 'concepts', 'lesson_learned', 'search_aliases', 'files_read', 'files_modified', 'project', 'created_at', 'memory_session_id', 'prompt_number', 'importance', 'related_ids', 'access_count', 'branch', 'superseded_at', 'superseded_by', 'last_accessed_at'];
       prefix = '#';
     }
 
@@ -1531,7 +1531,10 @@ server.registerTool(
     const updates = [];
     const params = [];
     for (const [key, col] of [['title','title'],['narrative','narrative'],['type','type'],['importance','importance'],['lesson_learned','lesson_learned'],['concepts','concepts']]) {
-      if (args[key] !== undefined) { updates.push(`${col} = ?`); params.push(args[key]); }
+      if (args[key] !== undefined) {
+        updates.push(`${col} = ?`);
+        params.push(typeof args[key] === 'string' ? scrubSecrets(args[key]) : args[key]);
+      }
     }
     if (updates.length === 0) return { content: [{ type: 'text', text: 'No fields to update' }], isError: true };
 
@@ -1541,9 +1544,11 @@ server.registerTool(
     db.transaction(() => {
       db.prepare(`UPDATE observations SET ${updates.join(', ')} WHERE id = ?`).run(...params);
 
-      // Rebuild FTS text field
-      const row = db.prepare('SELECT title, subtitle, narrative, concepts, facts FROM observations WHERE id = ?').get(args.id);
-      const textField = [row.title, row.subtitle, row.narrative, row.concepts, row.facts].filter(Boolean).join(' ');
+      // Rebuild FTS text field (must include CJK bigrams + search_aliases to match mem_save/hook-llm)
+      const row = db.prepare('SELECT title, subtitle, narrative, concepts, facts, lesson_learned, search_aliases FROM observations WHERE id = ?').get(args.id);
+      const base = [row.title, row.subtitle, row.narrative, row.concepts, row.facts, row.lesson_learned, row.search_aliases].filter(Boolean).join(' ');
+      const bigrams = cjkBigrams((row.title || '') + ' ' + (row.narrative || ''));
+      const textField = bigrams ? base + ' ' + bigrams : base;
       db.prepare('UPDATE observations SET text = ? WHERE id = ?').run(textField, args.id);
 
       // Re-vectorize (non-critical — catch to avoid rollback)
@@ -1589,7 +1594,8 @@ server.registerTool(
     }
 
     const where = wheres.length > 0 ? 'WHERE ' + wheres.join(' AND ') : '';
-    const rows = db.prepare(`SELECT id, project, type, title, subtitle, narrative, concepts, facts, lesson_learned, importance, files_modified, created_at, created_at_epoch FROM observations ${where} ORDER BY created_at_epoch DESC LIMIT 1000`).all(...params);
+    const exportLimit = Math.min(args.limit ?? 200, 1000);
+    const rows = db.prepare(`SELECT id, project, type, title, subtitle, narrative, concepts, facts, lesson_learned, importance, files_modified, created_at, created_at_epoch FROM observations ${where} ORDER BY created_at_epoch DESC LIMIT ?`).all(...params, exportLimit);
 
     if (rows.length === 0) return { content: [{ type: 'text', text: 'No observations found matching the criteria.' }] };
 
@@ -1597,7 +1603,7 @@ server.registerTool(
       ? rows.map(r => JSON.stringify(r)).join('\n')
       : JSON.stringify(rows, null, 2);
 
-    const cap = rows.length >= 1000 ? '\nNote: Results capped at 1000. Use date_from/date_to to export in batches.' : '';
+    const cap = rows.length >= exportLimit ? `\nNote: Results capped at ${exportLimit}. Use date_from/date_to or increase limit (max 1000) to export more.` : '';
     return { content: [{ type: 'text', text: `Exported ${rows.length} observations:${cap}\n${output}` }] };
   })
 );

package/stop-words.mjs

@@ -0,0 +1,16 @@
+// stop-words.mjs — Shared base stop-word set for all NLP/search modules.
+// Single source of truth: consumers extend with domain-specific extras.
+
+/** Common English stop words shared across FTS, TF-IDF, PRF, and registry search. */
+export const BASE_STOP_WORDS = new Set([
+  'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+  'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+  'should', 'may', 'might', 'can', 'shall', 'to', 'of', 'in', 'for',
+  'on', 'with', 'at', 'by', 'from', 'as', 'into', 'about', 'between',
+  'after', 'before', 'above', 'below', 'and', 'or', 'but', 'not', 'no',
+  'this', 'that', 'these', 'those', 'it', 'its', 'my', 'your', 'his',
+  'her', 'our', 'their', 'me', 'him', 'us', 'them', 'i', 'you', 'he',
+  'she', 'we', 'they', 'what', 'which', 'who', 'when', 'where', 'how',
+  'all', 'each', 'every', 'both', 'few', 'more', 'most', 'other', 'some',
+  'such', 'than', 'too', 'very', 'just', 'also', 'then', 'so', 'if',
+]);

package/tfidf.mjs

@@ -0,0 +1,425 @@
+// tfidf.mjs — TF-IDF vector search engine
+// Pure JS implementation, zero external dependencies.
+// Provides tokenization, vocabulary building, vector computation,
+// cosine similarity, vector search, and RRF merging.
+
+import { cjkBigrams } from './utils.mjs';
+import { BASE_STOP_WORDS } from './stop-words.mjs';
+import { createHash } from 'crypto';
+
+export const VOCAB_DIM = 512;
+export const MIN_COSINE_SIMILARITY = 0.05;
+export const VECTOR_SCAN_LIMIT = 500;
+
+const VOCAB_STOP_WORDS = new Set([
+  ...BASE_STOP_WORDS,
+  'now','only','still','here','there','up','out','am',
+]);
+
+// ─── Porter Stemmer ──────────────────────────────────────────────────────────
+// Minimal Porter stemmer (1980) aligned with SQLite FTS5's built-in porter tokenizer.
+
+const step2map = {
+  ational:'ate', tional:'tion', enci:'ence', anci:'ance', izer:'ize',
+  abli:'able', alli:'al', entli:'ent', eli:'e', ousli:'ous', ization:'ize',
+  ation:'ate', ator:'ate', alism:'al', iveness:'ive', fulness:'ful',
+  ousness:'ous', aliti:'al', iviti:'ive', biliti:'ble', logi:'log',
+};
+const step3map = {
+  icate:'ic', ative:'', alize:'al', iciti:'ic', ical:'ic', ful:'', ness:'',
+};
+
+function consonant(word, i) {
+  const c = word[i];
+  if (/[aeiou]/.test(c)) return false;
+  if (c === 'y') return i === 0 || !/[aeiou]/.test(word[i - 1]);
+  return true;
+}
+
+function measure(word) {
+  let m = 0, prev = true; // start assuming consonant context
+  for (let i = 0; i < word.length; i++) {
+    const c = consonant(word, i);
+    if (!c && prev) m++;
+    prev = c;
+  }
+  return m;
+}
+
+function hasVowel(word) {
+  for (let i = 0; i < word.length; i++) if (!consonant(word, i)) return true;
+  return false;
+}
+
+function endsDouble(word) {
+  const l = word.length;
+  return l >= 2 && word[l - 1] === word[l - 2] && consonant(word, l - 1);
+}
+
+function cvc(word) {
+  const l = word.length;
+  return l >= 3 && consonant(word, l - 1) && !consonant(word, l - 2) && consonant(word, l - 3)
+    && !/[wxy]/.test(word[l - 1]);
+}
+
+export function porterStem(w) {
+  if (w.length <= 2) return w;
+  let word = w;
+
+  // Step 1a
+  if (word.endsWith('sses')) word = word.slice(0, -2);
+  else if (word.endsWith('ies')) word = word.slice(0, -2);
+  else if (!word.endsWith('ss') && word.endsWith('s')) word = word.slice(0, -1);
+
+  // Step 1b
+  let step1b2 = false;
+  if (word.endsWith('eed')) {
+    if (measure(word.slice(0, -3)) > 0) word = word.slice(0, -1);
+  } else if (word.endsWith('ed') && hasVowel(word.slice(0, -2))) {
+    word = word.slice(0, -2); step1b2 = true;
+  } else if (word.endsWith('ing') && hasVowel(word.slice(0, -3))) {
+    word = word.slice(0, -3); step1b2 = true;
+  }
+  if (step1b2) {
+    if (word.endsWith('at') || word.endsWith('bl') || word.endsWith('iz')) word += 'e';
+    else if (endsDouble(word) && !/[lsz]/.test(word[word.length - 1])) word = word.slice(0, -1);
+    else if (measure(word) === 1 && cvc(word)) word += 'e';
+  }
+
+  // Step 1c
+  if (word.endsWith('y') && hasVowel(word.slice(0, -1))) {
+    word = word.slice(0, -1) + 'i';
+  }
+
+  // Step 2
+  for (const [suffix, repl] of Object.entries(step2map)) {
+    if (word.endsWith(suffix)) {
+      const stem = word.slice(0, -suffix.length);
+      if (measure(stem) > 0) word = stem + repl;
+      break;
+    }
+  }
+
+  // Step 3
+  for (const [suffix, repl] of Object.entries(step3map)) {
+    if (word.endsWith(suffix)) {
+      const stem = word.slice(0, -suffix.length);
+      if (measure(stem) > 0) word = stem + repl;
+      break;
+    }
+  }
+
+  // Step 4
+  const step4suffixes = ['al','ance','ence','er','ic','able','ible','ant','ement','ment',
+    'ent','ion','ou','ism','ate','iti','ous','ive','ize'];
+  for (const suffix of step4suffixes) {
+    if (word.endsWith(suffix)) {
+      const stem = word.slice(0, -suffix.length);
+      if (measure(stem) > 1) {
+        if (suffix === 'ion' && stem.length > 0 && /[st]$/.test(stem)) word = stem;
+        else if (suffix !== 'ion') word = stem;
+      }
+      break;
+    }
+  }
+
+  // Step 5a
+  if (word.endsWith('e')) {
+    const stem = word.slice(0, -1);
+    if (measure(stem) > 1 || (measure(stem) === 1 && !cvc(stem))) word = stem;
+  }
+
+  // Step 5b
+  if (measure(word) > 1 && endsDouble(word) && word.endsWith('l')) {
+    word = word.slice(0, -1);
+  }
+
+  return word;
+}
+
+function isNoiseTerm(term) {
+  if (VOCAB_STOP_WORDS.has(term)) return true;
+  if (/^\d+$/.test(term)) return true;
+  return false;
+}
+
+// ─── Tokenization ───────────────────────────────────────────────────────────
+
+const CJK_RANGE = /[\u4e00-\u9fff\u3400-\u4dbf]/;
+
+/**
+ * Tokenize text into terms for TF-IDF.
+ * ASCII: lowercase + split + Porter stem (aligned with FTS5's porter tokenizer).
+ * CJK: reuse cjkBigrams() for consistency with FTS5.
+ */
+export function tokenize(text) {
+  if (!text) return [];
+  text = String(text).toLowerCase();
+
+  const tokens = [];
+
+  // Split into ASCII and CJK segments
+  const parts = text.split(/([\u4e00-\u9fff\u3400-\u4dbf]+)/);
+  for (const part of parts) {
+    if (CJK_RANGE.test(part)) {
+      // CJK: use bigrams for consistency with FTS5 indexing
+      const bigrams = cjkBigrams(part);
+      if (bigrams) {
+        for (const t of bigrams.split(/\s+/)) {
+          if (t.length >= 2) tokens.push(t);
+        }
+      }
+    } else {
+      // ASCII: split on non-alphanumeric, then Porter stem
+      for (const t of part.split(/[^a-z0-9]+/)) {
+        if (t.length >= 2) tokens.push(porterStem(t));
+      }
+    }
+  }
+
+  return tokens;
+}
+
+// ─── Vocabulary ─────────────────────────────────────────────────────────────
+
+let _vocabCache = null;
+
+/** Reset vocabulary cache (for testing). */
+export function _resetVocabCache() { _vocabCache = null; }
+
+/**
+ * Build global vocabulary (IDF table) from all active observations.
+ * @param {object} db - better-sqlite3 database
+ * @returns {{ terms: Map<string, {index: number, idf: number}>, version: string, dim: number } | null}
+ */
+export function buildVocabulary(db) {
+  const rows = db.prepare(`
+    SELECT title, narrative, concepts FROM observations
+    WHERE COALESCE(compressed_into, 0) = 0 AND superseded_at IS NULL
+  `).all();
+
+  const N = rows.length;
+  if (N === 0) return null;
+
+  // Count document frequency for each term
+  const df = new Map();
+  for (const row of rows) {
+    const text = [row.title || '', row.narrative || '', row.concepts || ''].join(' ');
+    const docTerms = new Set(tokenize(text));
+    for (const term of docTerms) {
+      df.set(term, (df.get(term) || 0) + 1);
+    }
+  }
+
+  // Compute IDF and sort by IDF (rare discriminative terms first), filter noise + hapax
+  const idf = (freq) => Math.log(1 + N / (1 + freq));
+  const sortedTerms = [...df.entries()]
+    .filter(([term, freq]) => !isNoiseTerm(term) && freq >= 2)
+    .map(([term, freq]) => ({ term, df: freq, idf: idf(freq), ig: freq * idf(freq) }))
+    .sort((a, b) => b.idf - a.idf)
+    .slice(0, VOCAB_DIM);
+
+  // Build terms map with index and IDF
+  const terms = new Map();
+  sortedTerms.forEach((entry, index) => {
+    terms.set(entry.term, { index, idf: entry.idf });
+  });
+
+  // Version hash for staleness detection
+  const termList = sortedTerms.map(e => e.term).join(',');
+  const version = createHash('md5').update(termList).digest('hex').slice(0, 12);
+
+  const vocab = { terms, version, dim: VOCAB_DIM };
+  _vocabCache = vocab;
+  return vocab;
+}
+
+/**
+ * Rebuild vocabulary from corpus AND persist to vocab_state table.
+ * @param {object} db - better-sqlite3 database
+ * @returns {object|null} The new vocabulary
+ */
+export function rebuildVocabulary(db) {
+  const vocab = buildVocabulary(db);
+  if (!vocab) return null;
+
+  const insertStmt = db.prepare(
+    'INSERT INTO vocab_state (term, term_index, idf, version, created_at_epoch) VALUES (?, ?, ?, ?, ?)'
+  );
+  const now = Date.now();
+  db.transaction(() => {
+    db.prepare('DELETE FROM vocab_state').run();
+    for (const [term, entry] of vocab.terms) {
+      insertStmt.run(term, entry.index, entry.idf, vocab.version, now);
+    }
+  })();
+
+  _vocabCache = vocab;
+  return vocab;
+}
+
+/**
+ * Get cached vocabulary, load from DB, or rebuild from corpus.
+ * @param {object} db - better-sqlite3 database
+ * @returns {object|null} vocabulary
+ */
+export function getVocabulary(db) {
+  if (_vocabCache) return _vocabCache;
+
+  // Try loading from persisted vocab_state
+  try {
+    const rows = db.prepare(
+      'SELECT term, term_index, idf, version FROM vocab_state ORDER BY term_index'
+    ).all();
+    if (rows.length > 0) {
+      const terms = new Map();
+      for (const r of rows) {
+        terms.set(r.term, { index: r.term_index, idf: r.idf });
+      }
+      const vocab = { terms, version: rows[0].version, dim: VOCAB_DIM };
+      _vocabCache = vocab;
+      return vocab;
+    }
+  } catch { /* table may not exist in old/test DBs */ }
+
+  // Fallback: compute and persist (first run)
+  return rebuildVocabulary(db);
+}
+
+// ─── Vector Computation ─────────────────────────────────────────────────────
+
+/**
+ * Compute TF-IDF vector for a text string.
+ * @returns {Float32Array | null} L2-normalized vector, or null if empty/no matching terms
+ */
+export function computeVector(text, vocab) {
+  if (!vocab || !text) return null;
+
+  const tokens = tokenize(text);
+  if (tokens.length === 0) return null;
+
+  // Compute term frequency
+  const tf = new Map();
+  for (const t of tokens) {
+    tf.set(t, (tf.get(t) || 0) + 1);
+  }
+
+  // Build TF-IDF vector with sublinear TF: 1 + log(tf)
+  const vec = new Float32Array(vocab.dim);
+  let hasNonZero = false;
+  for (const [term, freq] of tf) {
+    const entry = vocab.terms.get(term);
+    if (entry) {
+      vec[entry.index] = (1 + Math.log(freq)) * entry.idf;
+      hasNonZero = true;
+    }
+  }
+
+  if (!hasNonZero) return null;
+
+  // L2 normalize
+  let norm = 0;
+  for (let i = 0; i < vec.length; i++) norm += vec[i] * vec[i];
+  norm = Math.sqrt(norm);
+  if (norm === 0) return null;
+  for (let i = 0; i < vec.length; i++) vec[i] /= norm;
+
+  return vec;
+}
+
+// ─── Cosine Similarity ──────────────────────────────────────────────────────
+
+/**
+ * Dot product of two L2-normalized Float32Arrays = cosine similarity.
+ */
+export function cosineSimilarity(a, b) {
+  let dot = 0;
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) dot += a[i] * b[i];
+  return dot;
+}
+
+// ─── Vector Search ──────────────────────────────────────────────────────────
+
+/**
+ * Search observation_vectors by cosine similarity.
+ * @param {object} db - better-sqlite3 database
+ * @param {Float32Array} queryVec - query vector
+ * @param {object} opts - { project?, type?, vocabVersion, limit? }
+ * @returns {{ id: number, similarity: number }[]}
+ */
+const VECTOR_TIME_WINDOW_MS = 90 * 24 * 60 * 60 * 1000; // 90 days
+const VECTOR_MIN_RESULTS = 50; // fallback to full scan if time-window yields fewer
+
+export function vectorSearch(db, queryVec, { project, type, vocabVersion, limit = VECTOR_SCAN_LIMIT }) {
+  if (!queryVec) return [];
+
+  const now = Date.now();
+
+  const wheres = [
+    'COALESCE(o.compressed_into, 0) = 0',
+    'o.superseded_at IS NULL',
+    'ov.vocab_version = ?',
+  ];
+  const params = [vocabVersion];
+
+  if (project) { wheres.push('o.project = ?'); params.push(project); }
+  if (type) { wheres.push('o.type = ?'); params.push(type); }
+
+  // Time-window prefilter: try 90 days first, fallback to full if too few results
+  const timeWheres = [...wheres, 'o.created_at_epoch > ?'];
+  const timeParams = [...params, now - VECTOR_TIME_WINDOW_MS, limit];
+
+  let rows = db.prepare(`
+    SELECT ov.observation_id, ov.vector
+    FROM observation_vectors ov
+    JOIN observations o ON ov.observation_id = o.id
+    WHERE ${timeWheres.join(' AND ')}
+    ORDER BY o.created_at_epoch DESC
+    LIMIT ?
+  `).all(...timeParams);
+
+  // Fallback: if time-window yields too few, scan without time constraint
+  if (rows.length < VECTOR_MIN_RESULTS) {
+    params.push(limit);
+    rows = db.prepare(`
+      SELECT ov.observation_id, ov.vector
+      FROM observation_vectors ov
+      JOIN observations o ON ov.observation_id = o.id
+      WHERE ${wheres.join(' AND ')}
+      ORDER BY o.created_at_epoch DESC
+      LIMIT ?
+    `).all(...params);
+  }
+
+  const results = [];
+  for (const row of rows) {
+    const vec = new Float32Array(row.vector.buffer, row.vector.byteOffset, row.vector.byteLength / 4);
+    const sim = cosineSimilarity(queryVec, vec);
+    if (sim > MIN_COSINE_SIMILARITY) results.push({ id: row.observation_id, similarity: sim });
+  }
+  results.sort((a, b) => b.similarity - a.similarity);
+  return results.slice(0, 20);
+}
+
+// ─── RRF Merge ──────────────────────────────────────────────────────────────
+
+/**
+ * Reciprocal Rank Fusion: merge two ranked result lists.
+ * @param {{ id: number }[]} bm25Results - FTS5 results (ranked by position)
+ * @param {{ id: number }[]} vectorResults - Vector results (ranked by position)
+ * @param {number} k - RRF constant (default 60)
+ * @returns {{ id: number, rrfScore: number }[]}
+ */
+export function rrfMerge(bm25Results, vectorResults, k = 60) {
+  const scores = new Map();
+  bm25Results.forEach((r, i) => {
+    scores.set(r.id, (scores.get(r.id) ?? 0) + 1 / (k + i + 1));
+  });
+  vectorResults.forEach((r, i) => {
+    scores.set(r.id, (scores.get(r.id) ?? 0) + 1 / (k + i + 1));
+  });
+  return [...scores.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .map(([id, score]) => ({ id, rrfScore: score }));
+}

package/tier.mjs

@@ -0,0 +1,116 @@
+// tier.mjs — Virtual three-tier memory classification engine
+// Computes tier (working/active/archive) from existing observation fields.
+// No database dependencies — pure functions + SQL expression.
+
+import { DECAY_HALF_LIFE_BY_TYPE } from './utils.mjs';
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const TWO_HOURS_MS = 2 * 3600000;
+
+/** Active window = 2x decay half-life per type (ms) */
+export const ACTIVE_WINDOWS = Object.fromEntries(
+  Object.entries(DECAY_HALF_LIFE_BY_TYPE).map(([type, hl]) => [type, hl * 2])
+);
+const DEFAULT_ACTIVE_WINDOW_MS = DECAY_HALF_LIFE_BY_TYPE.change * 2;
+
+// ─── JavaScript Tier Classification ──────────────────────────────────────────
+
+/**
+ * Compute tier for a single observation row.
+ * @param {object} obs - Row from observations table
+ * @param {object} ctx - { now, currentProject, currentSessionId }
+ * @returns {'working' | 'active' | 'archive'}
+ */
+export function computeTier(obs, ctx) {
+  const { now, currentProject, currentSessionId } = ctx;
+
+  // Rule 1: Archive if compressed or superseded
+  if ((obs.compressed_into ?? 0) !== 0) return 'archive';
+  if (obs.superseded_at !== null && obs.superseded_at !== undefined) return 'archive';
+
+  // Rule 2: Working if same session
+  if (currentSessionId && obs.memory_session_id === currentSessionId) return 'working';
+
+  const twoHoursAgo = now - TWO_HOURS_MS;
+
+  // Rule 3: Working if same project + high importance + recently accessed
+  if (obs.project === currentProject && (obs.importance ?? 1) >= 2 && obs.last_accessed_at >= twoHoursAgo) {
+    return 'working';
+  }
+
+  // Rule 4: Working if same project + recently created
+  if (obs.project === currentProject && obs.created_at_epoch >= twoHoursAgo) {
+    return 'working';
+  }
+
+  // Rule 5: Active if within type-specific window
+  const activeWindow = ACTIVE_WINDOWS[obs.type] ?? DEFAULT_ACTIVE_WINDOW_MS;
+  if (now - obs.created_at_epoch < activeWindow) return 'active';
+
+  // Rule 6: Archive (fallback)
+  return 'archive';
+}
+
+// ─── SQL CASE Expression ────────────────────────────────────────────────────
+
+/**
+ * SQL CASE expression for inline tier computation.
+ * Params: see tierSqlParams().
+ */
+export const TIER_CASE_SQL = `(CASE
+  WHEN COALESCE(compressed_into, 0) != 0 THEN 'archive'
+  WHEN superseded_at IS NOT NULL THEN 'archive'
+  WHEN memory_session_id = ? THEN 'working'
+  WHEN project = ? AND COALESCE(importance, 1) >= 2 AND last_accessed_at >= ? THEN 'working'
+  WHEN project = ? AND created_at_epoch >= ? THEN 'working'
+  WHEN type = 'decision'  AND created_at_epoch >= ? THEN 'active'
+  WHEN type = 'discovery' AND created_at_epoch >= ? THEN 'active'
+  WHEN type = 'feature'   AND created_at_epoch >= ? THEN 'active'
+  WHEN type = 'bugfix'    AND created_at_epoch >= ? THEN 'active'
+  WHEN type = 'refactor'  AND created_at_epoch >= ? THEN 'active'
+  WHEN type = 'change'    AND created_at_epoch >= ? THEN 'active'
+  WHEN created_at_epoch >= ? THEN 'active'
+  ELSE 'archive'
+END)`;
+
+/**
+ * Build params array for TIER_CASE_SQL.
+ * @param {object} ctx - { now, currentProject, currentSessionId }
+ * @returns {any[]}
+ */
+export function tierSqlParams(ctx) {
+  const { now, currentProject, currentSessionId } = ctx;
+  const twoHoursAgo = now - TWO_HOURS_MS;
+  return [
+    currentSessionId ?? '',
+    currentProject ?? '',
+    twoHoursAgo,
+    currentProject ?? '',
+    twoHoursAgo,
+    now - ACTIVE_WINDOWS.decision,
+    now - ACTIVE_WINDOWS.discovery,
+    now - ACTIVE_WINDOWS.feature,
+    now - ACTIVE_WINDOWS.bugfix,
+    now - ACTIVE_WINDOWS.refactor,
+    now - ACTIVE_WINDOWS.change,
+    now - DEFAULT_ACTIVE_WINDOW_MS,
+  ];
+}
+
+// ─── Relative Time Formatting ───────────────────────────────────────────────
+
+/**
+ * Format epoch as relative time string (e.g., "5min ago", "3d ago").
+ * @param {number} epoch - Timestamp in milliseconds
+ * @param {number} now - Current time in milliseconds
+ * @returns {string}
+ */
+export function relativeTime(epoch, now) {
+  const diff = now - epoch;
+  if (diff < 60000) return `${Math.floor(diff / 1000)}s ago`;
+  if (diff < 3600000) return `${Math.floor(diff / 60000)}min ago`;
+  if (diff < 86400000) return `${Math.floor(diff / 3600000)}h ago`;
+  if (diff < 30 * 86400000) return `${Math.floor(diff / 86400000)}d ago`;
+  return `${Math.floor(diff / (30 * 86400000))}mo ago`;
+}

package/tool-schemas.mjs

@@ -111,6 +111,7 @@ export const memExportSchema = {
   date_from: z.string().optional().describe('Start date (ISO 8601 or YYYY-MM-DD)'),
   date_to: z.string().optional().describe('End date (ISO 8601 or YYYY-MM-DD)'),
   include_compressed: coerceBool.optional().describe('Include compressed observations (default: false)'),
+  limit: coerceInt.optional().describe('Max observations to export (default: 200, max: 1000)'),
 };
 
 export const memFtsCheckSchema = {

package/utils.mjs

@@ -294,8 +294,11 @@ export function extractMatchKeywords(text, files) {
 // ─── Git Branch Detection ──────────────────────────────────────────────────
 
 let _cachedBranch;
+let _branchCacheTime = 0;
+const BRANCH_CACHE_TTL = 60000; // 60s TTL for long-running MCP server process
 export function getCurrentBranch() {
-  if (_cachedBranch !== undefined) return _cachedBranch;
+  const now = Date.now();
+  if (_cachedBranch !== undefined && (now - _branchCacheTime) < BRANCH_CACHE_TTL) return _cachedBranch;
   try {
     const result = execSync('git rev-parse --abbrev-ref HEAD', {
       encoding: 'utf8', timeout: 2000, stdio: ['pipe', 'pipe', 'pipe'],
@@ -304,8 +307,9 @@ export function getCurrentBranch() {
   } catch {
     _cachedBranch = null;
   }
+  _branchCacheTime = now;
   return _cachedBranch;
 }
 
 /** Reset cached branch (for testing or after git checkout) */
-export function _resetBranchCache() { _cachedBranch = undefined; }
+export function _resetBranchCache() { _cachedBranch = undefined; _branchCacheTime = 0; }