claude-mem-lite 3.16.3 → 3.17.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.16.3",
+      "version": "3.17.0",
       "source": "./",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.16.3",
+  "version": "3.17.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/deep-search.mjs

@@ -34,6 +34,7 @@
 import { searchObservationsHybrid } from './search-engine.mjs';
 import { sanitizeFtsQuery } from './utils.mjs';
 import { RRF_K } from './tfidf.mjs';
+import { rrfAccumulate } from './lib/rrf.mjs';
 import { llmRerankOrder, defaultRerankLLM } from './rerank.mjs';
 
 // original + up to 3 rewrites (keyword / concept-expansion / HyDE).
@@ -350,28 +351,12 @@ export async function rewriteQuery(query, { llm = defaultLLM, retries = 1, cache
  *   match the hybrid path's convention) plus an rrfScore field.
  */
 export function rrfFuseN(rankedLists, k = RRF_K) {
-  const scores = new Map();
-  for (const list of rankedLists) {
-    if (!Array.isArray(list)) continue;
-    list.forEach((r, i) => {
-      if (!r || r.id === undefined || r.id === null) return;
-      const add = 1 / (k + i + 1);
-      const prev = scores.get(r.id);
-      if (prev) {
-        prev.score += add;
-        // Keep the row from the variant that ranked this id HIGHEST (lowest
-        // index). searchObservationsHybrid emits query-dependent fields per
-        // variant (notably the FTS snippet), so first-seen would often show the
-        // weaker original/keyword variant's context; the best-ranked appearance
-        // carries the most relevant snippet/match context (F10).
-        if (i < prev.bestRank) { prev.row = r; prev.bestRank = i; }
-      } else {
-        scores.set(r.id, { row: r, score: add, bestRank: i });
-      }
-    });
-  }
-  return [...scores.values()]
-    .sort((a, b) => b.score - a.score)
+  // Thin N-list adapter over the shared RRF core (lib/rrf.mjs). Emits full source
+  // rows with score = -rrfScore (negative = better, matching the hybrid path's
+  // convention) plus an rrfScore field. rrfAccumulate already keeps each id's
+  // best-ranked row, so query-dependent fields (notably the FTS snippet) come from
+  // the strongest variant rather than first-seen (F10).
+  return rrfAccumulate(rankedLists, k)
     .map(({ row, score }) => ({ ...row, score: -score, rrfScore: score }));
 }
 

package/hook-context.mjs

@@ -244,7 +244,10 @@ export function cleanupClaudeMdLegacyBlock() {
 
   if (normalized === content) { dropMarker(); return; }
 
-  const tmp = claudeMdPath + '.mem-tmp';
+  // Per-pid temp suffix so two concurrent first-run SessionStarts in the same
+  // project (e.g. two terminals) can't rename each other's half-written temp
+  // onto the user's tracked CLAUDE.md. Matches the idiom in hook-shared.mjs.
+  const tmp = claudeMdPath + `.mem-tmp-${process.pid}`;
   try {
     writeFileSync(tmp, normalized);
     renameSync(tmp, claudeMdPath);

package/hook-llm.mjs

@@ -740,9 +740,15 @@ ${actionList}`;
           (parsed.type === 'bugfix' || parsed.type === 'decision') &&
           !process.env.CLAUDE_MEM_NO_LESSON_RETRY) {
         retryAttempted = true;
+        // The first callLLM released its slot in the finally above; this lesson
+        // retry is a SECOND LLM call and must re-acquire the semaphore or it
+        // bypasses LLM_SEM_MAX — a burst of bugfix/decision episodes would otherwise
+        // spawn unbounded concurrent Haiku calls. Under contention we skip the retry
+        // rather than exceed the limit (the lesson is an optional enhancement).
+        const retrySlot = await acquireLLMSlot();
         try {
           const retryPrompt = buildLessonRetryPrompt(episode, parsed);
-          const retryRaw = await callLLM(retryPrompt, 10000);
+          const retryRaw = retrySlot ? await callLLM(retryPrompt, 10000) : null;
           if (retryRaw) {
             const retry = parseJsonFromLLM(retryRaw);
             const retryLesson = typeof retry?.lesson === 'string' ? retry.lesson.trim() : '';
@@ -754,6 +760,7 @@ ${actionList}`;
             }
           }
         } catch (e) { debugCatch(e, 'lesson-retry'); }
+        finally { if (retrySlot) releaseLLMSlot(); }
       }
       // v2.57.x B2: persist retry outcome counters. The retry path costs
       // 1 extra Haiku call per bugfix/decision episode; if recovered/attempts

package/hook-memory.mjs

@@ -222,7 +222,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     // Count original search terms (AND-separated groups), not expanded synonym tokens.
     const queryTokenCount = ftsQuery.includes(' AND ')
       ? ftsQuery.split(' AND ').length
-      : ftsQuery.split(/\s+/).filter(t => t && !t.startsWith('(') || !t.endsWith(')')).length;
+      : ftsQuery.split(/\s+/).filter(t => t && !t.startsWith('(') && !t.endsWith(')')).length;
     // CJK-dominant queries bypass the token-count gate: a single CJK word becomes
     // 2-N overlapping bigrams (优化召回率 → 优化/召回/回率), inflating
     // queryTokenCount past the gate, so the AND-too-strict query never gets the OR
@@ -385,7 +385,11 @@ export function recallForFile(db, filePath, project) {
     `).all(project, cutoff, filePath, likePattern, MAX_FILE_RECALL);
     const now = Date.now();
     const updateStmt = db.prepare('UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id = ?');
-    for (const r of rows) updateStmt.run(now, r.id);
+    // Per-row try/catch for FTS trigger safety — mirror the injection-bump loop
+    // (searchRelevantMemories) and project_non_obvious.md. Without it, one
+    // SQLITE_CORRUPT_VTAB on the access_count UPDATE trigger throws to the outer
+    // catch and discards the ENTIRE file-recall result set.
+    for (const r of rows) { try { updateStmt.run(now, r.id); } catch {} }
     return rows;
   } catch (e) {
     debugCatch(e, 'recallForFile');

package/hook-semaphore.mjs

@@ -33,8 +33,15 @@ export async function acquireLLMSlot() {
         if (fd !== undefined) closeSync(fd);
       }
     } catch {
-      // Slot file already exists for this PID — stale cleanup should have removed it;
-      // retry and let O_CREAT|O_EXCL succeed on next iteration (avoid non-atomic fallback)
+      // Our own pid-named slot file already exists: a leftover from a prior acquire
+      // that never released (crash between acquire and releaseLLMSlot, or PID reuse).
+      // We are inside acquire and therefore do NOT currently hold a slot, so it is
+      // always stale — remove it and retry. The await is essential: a bare `continue`
+      // here re-hits the same EEXIST every iteration, a synchronous tight loop that
+      // pins a core until the 30s deadline (the age-based cleanup below is unreachable
+      // on this path — it only runs after a successful create).
+      try { unlinkSync(slotFile); } catch {}
+      await sleepMs(50 + Math.random() * 100);
       continue;
     }
 

package/lib/maintain-core.mjs

@@ -13,7 +13,7 @@
 //   { projectFilter: 'AND project = ?' | '', baseParams: [project?] , staleAge, opCap }
 
 import { COMPRESSED_PENDING_PURGE, computeMinHash, estimateJaccardFromMinHash, jaccardSimilarity } from '../utils.mjs';
-import { rebuildVocabulary, computeVector, _resetVocabCache } from '../tfidf.mjs';
+import { rebuildVocabulary, computeVector, _resetVocabCache, vectorsEnabled } from '../tfidf.mjs';
 import { DEDUP_JACCARD_THRESHOLD, MINHASH_PRE_THRESHOLD as MINHASH_PRE_THRESHOLD_SRC, FUZZY_DEDUP_THRESHOLD, FUZZY_BODY_THRESHOLD, MINHASH_PREFILTER } from './dedup-constants.mjs';
 
 export const STALE_AGE_MS = 30 * 86400000;
@@ -326,6 +326,7 @@ export function maintenanceStats(db, { projectFilter, baseParams, staleAge }) {
 
 /** Rebuild the TF-IDF vocabulary + every active observation vector (own transaction). */
 export function rebuildVectors(db) {
+  if (!vectorsEnabled()) return { ok: false, reason: 'vector arm disabled (set CLAUDE_MEM_VECTORS=1 to re-enable)', updated: 0, total: 0 };
   _resetVocabCache();
   const vocab = rebuildVocabulary(db);
   if (!vocab) return { ok: false, reason: 'no observations to build vocabulary from' };

package/lib/observation-write.mjs

@@ -8,7 +8,7 @@
 // Statement-only: callers own the transaction boundary (both wrap the row + files
 // + vector writes in one db.transaction so a failure can't leave a partial row).
 
-import { getVocabulary, computeVector } from '../tfidf.mjs';
+import { getVocabulary, computeVector, vectorsEnabled } from '../tfidf.mjs';
 import { debugCatch, cjkBigrams } from '../utils.mjs';
 
 // Canonical column order — must mirror the observations schema (schema.mjs).
@@ -56,6 +56,7 @@ export function insertObservationFiles(db, obsId, files) {
  * observation over a missing vector).
  */
 export function insertObservationVector(db, obsId, vecText) {
+  if (!vectorsEnabled()) return;  // Phase-1: vector arm disabled by default (audit 2026-06-27)
   try {
     const vocab = getVocabulary(db);
     if (!vocab) return;

package/lib/rrf.mjs

@@ -0,0 +1,42 @@
+// lib/rrf.mjs — Reciprocal Rank Fusion core (single source of truth, D#42).
+//
+// Both tfidf.rrfMerge (2-list, minimal { id, rrfScore } output) and
+// deep-search.rrfFuseN (N-list, full-row output with best-rank row selection)
+// are thin shape-adapters over rrfAccumulate below. Keeping the scoring math in
+// one dependency-free place prevents the two from silently drifting (different k
+// or formula — the prior state where each had its own hand-written loop). Callers
+// pass their own RRF_K default; 60 is the canonical value.
+
+/**
+ * Core Reciprocal Rank Fusion accumulator. For each id, sums 1/(k + rank + 1)
+ * across every ranked list it appears in, and keeps the source row from the list
+ * where the id ranked highest (lowest index) — query-dependent fields like an FTS
+ * snippet then come from the best-ranked appearance. Callers that only need the id
+ * ignore the row.
+ *
+ * @param {Array<Array<{id:any}>>} rankedLists one entry per ranked list; each list
+ *   is ordered best-first. Non-array entries and rows with null/undefined id are skipped.
+ * @param {number} [k=60] RRF constant.
+ * @returns {Array<{ id:any, row:object, score:number }>} descending by fused score;
+ *   ties preserve first-list-first insertion order (stable sort).
+ */
+export function rrfAccumulate(rankedLists, k = 60) {
+  const scores = new Map();
+  for (const list of rankedLists) {
+    if (!Array.isArray(list)) continue;
+    list.forEach((r, i) => {
+      if (!r || r.id === undefined || r.id === null) return;
+      const add = 1 / (k + i + 1);
+      const prev = scores.get(r.id);
+      if (prev) {
+        prev.score += add;
+        if (i < prev.bestRank) { prev.row = r; prev.bestRank = i; }
+      } else {
+        scores.set(r.id, { row: r, score: add, bestRank: i });
+      }
+    });
+  }
+  return [...scores.values()]
+    .sort((a, b) => b.score - a.score)
+    .map(({ row, score }) => ({ id: row.id, row, score }));
+}

package/mem-cli.mjs

@@ -15,6 +15,7 @@ import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { computeFunnel, formatFunnel, computeSweep, formatSweep, DEFAULT_SWEEP_FLOORS, DEFAULT_SWEEP_MARGINS } from './registry-recommend.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
+import { buildNotLowSignalSql } from './lib/low-signal-patterns.mjs';
 import {
   cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
@@ -1098,6 +1099,18 @@ async function cmdStats(db, args) {
       AND created_at_epoch < ? ${projectFilter}
   `).get(thirtyDaysAgo, ...baseParams);
   const noiseRatio = obsTotal.c > 0 ? lowVal.c / obsTotal.c : 0;
+  // Low-signal-title population: template / tool-log titles (Modified, Worked on,
+  // Error while working, Error:, node/npm/npx …) that the retrieval layer already
+  // filters out by default. The imp=1 "Low-value" metric above structurally can't
+  // see these — they often carry inflated importance and recent access — so the
+  // health gauge under-reports real noise without this line. Same LOW_SIGNAL
+  // pattern source as the read-side filter (lib/low-signal-patterns.mjs).
+  const lowSignalTitle = db.prepare(`
+    SELECT COUNT(*) as c FROM observations
+    WHERE NOT ${buildNotLowSignalSql()}
+      AND COALESCE(compressed_into, 0) = 0 ${projectFilter}
+  `).get(...baseParams);
+  const lowSignalRatio = obsTotal.c > 0 ? lowSignalTitle.c / obsTotal.c : 0;
   const compressedCount = db.prepare(
     `SELECT COUNT(*) as c FROM observations WHERE compressed_into IS NOT NULL ${projectFilter}`
   ).get(...baseParams);
@@ -1143,6 +1156,8 @@ async function cmdStats(db, args) {
         avg_importance: Number((avgImp.v ?? 1).toFixed(2)),
         low_value_count: lowVal.c,
         noise_ratio: Number(noiseRatio.toFixed(4)),
+        low_signal_titles: lowSignalTitle.c,
+        low_signal_ratio: Number(lowSignalRatio.toFixed(4)),
         compressed: compressedCount.c,
         superseded_only: supersededOnlyCount.c,
         hook_errors_24h: hookErrors24h,
@@ -1179,6 +1194,7 @@ async function cmdStats(db, args) {
   out(`  Est. tokens: ${tokenEst.t ?? 0}`);
   out(`  Avg importance: ${(avgImp.v ?? 1).toFixed(2)}`);
   out(`  Low-value (imp=1, never accessed, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`);
+  out(`  Low-signal titles (Modified/Error/Worked on…): ${lowSignalTitle.c} (${(lowSignalRatio * 100).toFixed(1)}%)`);
   out(`  Compressed: ${compressedCount.c}`);
   out(`  Hook errors (last 24h): ${hookErrors24h}${hookErrors24h > 0 ? `  ← tail ${join(DB_DIR, 'runtime/hook-errors')}` : ''}`);
   // Tier-1 firing counters for ① file-intel + ② reread-guard (recorded by
@@ -1188,7 +1204,7 @@ async function cmdStats(db, args) {
   const rrN = featAgg.reread_warn?.count ?? 0;
   const metricsOn = process.env.CLAUDE_MEM_METRICS === '1';
   out(`  Feature injections (7d): 📄 file-intel ${fiN} · 🔁 reread-warn ${rrN}${(!metricsOn && fiN + rrN === 0) ? '  (set CLAUDE_MEM_METRICS=1 to record)' : ''}`);
-  if (noiseRatio > 0.6) out('  ⚠️ High noise ratio — consider running mem compress');
+  if (noiseRatio > 0.6 || lowSignalRatio > 0.3) out('  ⚠️ High noise ratio — consider running mem maintain / compress');
   out('');
   // Tier counts only live (uncompressed, non-superseded) observations — surface the
   // full decomposition so live + compressed + superseded = Total adds up cleanly.
@@ -1902,7 +1918,23 @@ function cmdMaintain(db, args) {
     }
 
     if (ops.includes('purge_stale')) {
-      const retainDays = parseInt(flags['retain-days'], 10) || 30;
+      // --retain-days: default 30 when absent; reject negative / 0 / NaN / out-of-range.
+      // A negative value made retainCutoff a FUTURE timestamp → purged the entire
+      // pending-purge backlog regardless of age; 0/garbage silently became 30 and
+      // masked typos. Parity with the mem_maintain MCP zod bound [7, 365].
+      let retainDays = 30;
+      if (flags['retain-days'] !== undefined) {
+        // Number + isInteger (not parseInt) so "7.5"/"30x" are rejected rather than
+        // silently truncated to 7/30 — parity with the mem_maintain zod .int() bound.
+        const parsed = Number(flags['retain-days']);
+        if (!Number.isInteger(parsed) || parsed < 7 || parsed > 365) {
+          // fail() only sets exitCode + writes stderr; it does NOT throw, so we
+          // MUST return or execution falls through to the DELETE with the bad value.
+          fail(`[mem] --retain-days must be an integer in [7, 365] (got "${flags['retain-days']}")`);
+          return;
+        }
+        retainDays = parsed;
+      }
       const retainCutoff = Date.now() - retainDays * 86400000;
       // T2-P0-A (CLI parity): purge_stale is the only DELETE in this code path — require
       // --confirm so a mis-typed `maintain execute --ops purge_stale` can't wipe rows silently.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.16.3",
+  "version": "3.17.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -81,6 +81,7 @@
     "lib/recall-core.mjs",
     "lib/timeline-core.mjs",
     "lib/search-core.mjs",
+    "lib/rrf.mjs",
     "lib/compress-core.mjs",
     "lib/maintain-core.mjs",
     "lib/dedup-constants.mjs",

package/search-engine.mjs

@@ -11,7 +11,7 @@ import {
   notLowSignalTitleClause, LOW_SIGNAL_TITLE,
   relaxFtsQueryToOr, debugLog, debugCatch, estimateTokens,
 } from './utils.mjs';
-import { getVocabulary, computeVector, vectorSearch, rrfMerge } from './tfidf.mjs';
+import { getVocabulary, computeVector, vectorSearch, rrfMerge, vectorsEnabled } from './tfidf.mjs';
 import { extractPRFTerms, expandQueryByConcepts } from './search-scoring.mjs';
 
 // Scoring expressions — full adds project boost + access bonus; simple is for
@@ -395,6 +395,7 @@ export function searchObservationsHybrid(db, ctx) {
 
   // Vector search + RRF hybrid merge
   try {
+    if (!vectorsEnabled()) return results;  // Phase-1: vector arm disabled → BM25-only path (audit 2026-06-27)
     const vocab = getVocabulary(db);
     if (!vocab) return results;
     const queryText = ftsQuery.replace(/['"()]/g, ' ');

package/server.mjs

@@ -12,6 +12,7 @@ import { reRankWithContext, markSuperseded, autoBoostIfNeeded, runIdleCleanup, b
 import { searchObservationsHybrid } from './search-engine.mjs';
 import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady } from './deep-search.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
+import { buildNotLowSignalSql } from './lib/low-signal-patterns.mjs';
 import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentTimeline, fetchTimelineWindow } from './lib/timeline-core.mjs';
 import { buildSearchFtsQuery, parseDateBounds, coreRunSearchPipeline } from './lib/search-core.mjs';
 import {
@@ -864,6 +865,15 @@ server.registerTool(
     `).get(thirtyDaysAgo, ...baseParams);
 
     const noiseRatio = obsTotal.c > 0 ? lowVal.c / obsTotal.c : 0;
+    // Low-signal-title population (template / tool-log titles the read-side filter
+    // already excludes). The imp=1 "Low-value" metric can't see these, so the
+    // gauge under-reports real noise without it. See lib/low-signal-patterns.mjs.
+    const lowSignalTitle = db.prepare(`
+      SELECT COUNT(*) as c FROM observations
+      WHERE NOT ${buildNotLowSignalSql()}
+        AND COALESCE(compressed_into, 0) = 0 ${projectFilter}
+    `).get(...baseParams);
+    const lowSignalRatio = obsTotal.c > 0 ? lowSignalTitle.c / obsTotal.c : 0;
     const compressedCount = db.prepare(`
       SELECT COUNT(*) as c FROM observations WHERE compressed_into IS NOT NULL ${projectFilter}
     `).get(...baseParams);
@@ -900,8 +910,9 @@ server.registerTool(
       `  Est. tokens: ${tokenEst.t ?? 0}`,
       `  Avg importance: ${(avgImp.v ?? 1).toFixed(2)}`,
       `  Low-value (imp=1, never accessed, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`,
+      `  Low-signal titles (Modified/Error/Worked on…): ${lowSignalTitle.c} (${(lowSignalRatio * 100).toFixed(1)}%)`,
       `  Compressed: ${compressedCount.c}`,
-      ...(noiseRatio > 0.6 ? ['  ⚠️ High noise ratio — consider running mem_compress'] : []),
+      ...((noiseRatio > 0.6 || lowSignalRatio > 0.3) ? ['  ⚠️ High noise ratio — consider running mem_compress / maintain'] : []),
       '',
       // Tier counts only live (uncompressed, non-superseded) observations — surface
       // the full decomposition so live + compressed + superseded = Total adds up cleanly.

package/source-files.mjs

@@ -114,6 +114,9 @@ export const SOURCE_FILES = [
   // `timeline`/`search` and mem_timeline/mem_search on auto-update.
   'lib/timeline-core.mjs',
   'lib/search-core.mjs',
+  // Reciprocal Rank Fusion core (D#42 single source-of-truth); transitively
+  // reached via tfidf.mjs (rrfMerge) and deep-search.mjs (rrfFuseN).
+  'lib/rrf.mjs',
   // Shared "compress old low-value observations into weekly summaries" core.
   // Statically imported by mem-cli.mjs (cmdCompress), server.mjs (mem_compress),
   // and hook.mjs (handleAutoCompress) — same single-source-of-truth pattern as

package/tfidf.mjs

@@ -6,6 +6,7 @@
 import { cjkBigrams } from './utils.mjs';
 import { BASE_STOP_WORDS } from './stop-words.mjs';
 import { createHash } from 'crypto';
+import { rrfAccumulate } from './lib/rrf.mjs';
 
 export const VOCAB_DIM = 512;
 export const MIN_COSINE_SIMILARITY = 0.05;
@@ -15,6 +16,21 @@ export const VECTOR_SCAN_LIMIT = 500;
 // dominate. 60 is the de-facto RRF default and balances the two retrievers here.
 export const RRF_K = 60;
 
+// Phase-1 disable of the TF-IDF vector arm (memory-quality audit 2026-06-27).
+// The arm reads ~0 benchmark lift (ci-gate hybrid_over_bm25 = 0), pays a
+// computeVector on every observation write, only scans the most-recent
+// VECTOR_SCAN_LIMIT rows (misses older memories), and drifted unnoticed for
+// months. Default OFF. To re-enable: set CLAUDE_MEM_VECTORS=1 AND run
+// `claude-mem-lite maintain execute --ops rebuild_vectors` to repopulate vectors for
+// observations created while disabled — re-enabling WITHOUT a rebuild leaves a
+// partially-populated index (the primary + enrich/compress/optimize write paths all
+// stopped writing while off) → silently degraded hybrid recall until the next
+// rebuild. Tables + code are retained pending Phase-2 removal. Read at call time (not
+// import) so tests + the benchmark A/B can toggle it via env.
+export function vectorsEnabled() {
+  return process.env.CLAUDE_MEM_VECTORS === '1';
+}
+
 const VOCAB_STOP_WORDS = new Set([
   ...BASE_STOP_WORDS,
   'now','only','still','here','there','up','out','am',
@@ -275,6 +291,14 @@ export function rebuildVocabulary(db, opts) {
  * @returns {object|null} vocabulary
  */
 export function getVocabulary(db) {
+  // Phase-1 choke point: when the vector arm is disabled there is no vocabulary to
+  // serve. Returning null here makes EVERY vector write/read path skip via its
+  // existing `if (vocab)` guard — including the enrich (hook-llm), compress
+  // (compress-core) and optimize (hook-optimize) write paths that don't go through
+  // insertObservationVector — so no path can be "missed" and observation_vectors
+  // stays uniformly stale (not half-populated) while disabled. computeVector is
+  // null-safe, so even a caller that skips its guard no-ops rather than crashes.
+  if (!vectorsEnabled()) return null;
   if (_vocabCache) return _vocabCache;
 
   // Try loading from persisted vocab_state
@@ -423,14 +447,9 @@ export function vectorSearch(db, queryVec, { project, type, vocabVersion, limit
  * @returns {{ id: number, rrfScore: number }[]}
  */
 export function rrfMerge(bm25Results, vectorResults, k = RRF_K) {
-  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 }));
+  // Thin 2-list adapter over the shared RRF core (lib/rrf.mjs). Emits the minimal
+  // { id, rrfScore } shape this module's callers (search-engine.mjs) expect; the
+  // accumulator's best-rank row tracking is irrelevant here and ignored.
+  return rrfAccumulate([bm25Results, vectorResults], k)
+    .map(({ id, score }) => ({ id, rrfScore: score }));
 }