claude-mem-lite 2.90.1 → 2.92.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.90.1",
+      "version": "2.92.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": "2.90.1",
+  "version": "2.92.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/hook-llm.mjs

@@ -12,6 +12,7 @@ import {
 import { acquireLLMSlot, releaseLLMSlot } from './hook-semaphore.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { getVocabulary, computeVector } from './tfidf.mjs';
+import { insertObservationRow, insertObservationFiles, insertObservationVector } from './lib/observation-write.mjs';
 import { DEDUP_JACCARD_THRESHOLD, AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import {
   RUNTIME_DIR, DEDUP_WINDOW_MS, RELATED_OBS_WINDOW_MS,
@@ -209,48 +210,23 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
       search_aliases: obs.searchAliases || null,
     });
 
-    // Atomic: observation INSERT + observation_files + vector in one transaction
+    // Atomic: observation INSERT + observation_files + vector in one transaction.
+    // Column list single-sourced in lib/observation-write (shared with manual mem_save).
     const savedId = db.transaction(() => {
-      const result = db.prepare(`
-        INSERT INTO observations (memory_session_id, project, text, type, title, subtitle, narrative, concepts, facts, files_read, files_modified, importance, minhash_sig, lesson_learned, search_aliases, branch, created_at, created_at_epoch)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(
-        sessionId, project,
-        safe.text, obs.type, safe.title, safe.subtitle,
-        safe.narrative,
-        safe.concepts,
-        safe.facts,
-        JSON.stringify(obs.filesRead || []),
-        JSON.stringify(obs.files || []),
-        obs.importance ?? 1,
-        minhashSig,
-        safe.lesson_learned,
-        safe.search_aliases,
-        getCurrentBranch(),
-        now.toISOString(), now.getTime()
-      );
-      const id = Number(result.lastInsertRowid);
-
-      // Populate observation_files junction table
-      if (id && obs.files && obs.files.length > 0) {
-        const insertFile = db.prepare('INSERT OR IGNORE INTO observation_files (obs_id, filename) VALUES (?, ?)');
-        for (const f of obs.files) {
-          if (typeof f === 'string' && f.length > 0) insertFile.run(id, f);
-        }
-      }
+      const id = insertObservationRow(db, {
+        memory_session_id: sessionId, project, text: safe.text, type: obs.type,
+        title: safe.title, subtitle: safe.subtitle, narrative: safe.narrative,
+        concepts: safe.concepts, facts: safe.facts,
+        files_read: JSON.stringify(obs.filesRead || []),
+        files_modified: JSON.stringify(obs.files || []),
+        importance: obs.importance ?? 1, minhash_sig: minhashSig,
+        lesson_learned: safe.lesson_learned, search_aliases: safe.search_aliases,
+        branch: getCurrentBranch(), created_at: now.toISOString(), created_at_epoch: now.getTime(),
+      });
 
-      // Write TF-IDF vector (non-critical — catch inside transaction to avoid rollback)
-      try {
-        const vocab = getVocabulary(db);
-        if (vocab) {
-          const vecText = [obs.title || '', obs.narrative || '', (Array.isArray(obs.concepts) ? obs.concepts.join(' ') : '')].filter(Boolean).join(' ');
-          const vec = computeVector(vecText, vocab);
-          if (vec) {
-            db.prepare('INSERT OR REPLACE INTO observation_vectors (observation_id, vector, vocab_version, created_at_epoch) VALUES (?, ?, ?, ?)')
-              .run(id, Buffer.from(vec.buffer), vocab.version, Date.now());
-          }
-        }
-      } catch (e) { debugCatch(e, 'saveObservation-vector'); }
+      insertObservationFiles(db, id, obs.files);
+      const vecText = [obs.title || '', obs.narrative || '', (Array.isArray(obs.concepts) ? obs.concepts.join(' ') : '')].filter(Boolean).join(' ');
+      insertObservationVector(db, id, vecText);
 
       return id;
     })();

package/lib/citation-tracker.mjs

@@ -492,6 +492,18 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
            decay_seen_count = decay_seen_count + 1
      WHERE id = ?
   `);
+  // Suppressed (non-adopting) projects never demote, so uncited_streak would grow
+  // UNBOUNDED — and citeFactorClause penalizes -0.25*streak (floor 0.4), pinning every
+  // memory at the ranking floor with no recovery path. Cap at UNCITED_STREAK_THRESHOLD-1
+  // to hold the [0, threshold-1] steady state the scoring header asserts (in an adopting
+  // project the streak resets to 0 on demote, so the STORED value never exceeds 2).
+  const updateStreakCapped = db.prepare(`
+    UPDATE observations
+       SET uncited_streak = MIN(uncited_streak + 1, ?),
+           last_decided_session_id = ?,
+           decay_seen_count = decay_seen_count + 1
+     WHERE id = ?
+  `);
   const updateDemote = db.prepare(`
     UPDATE observations
        SET importance = MAX(?, importance - 1),
@@ -520,6 +532,9 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
         if (nextStreak >= UNCITED_STREAK_THRESHOLD && !suppressDemotion) {
           updateDemote.run(IMPORTANCE_FLOOR, sessionId, Date.now(), id);
           demoted++;
+        } else if (suppressDemotion) {
+          // Never-demoting project: cap the streak so cite_factor can't sink to floor.
+          updateStreakCapped.run(UNCITED_STREAK_THRESHOLD - 1, sessionId, id);
         } else {
           updateStreakOnly.run(sessionId, id);
         }

package/lib/maintain-core.mjs

@@ -29,15 +29,28 @@ export const MINHASH_PRE_THRESHOLD = MINHASH_PRE_THRESHOLD_SRC;
 export const PINNED_INJ_THRESHOLD = 8;
 
 /** Delete broken observations (no title AND no narrative). Returns rows deleted. */
+// Before hard-deleting observations, un-hide any rows merged INTO them. A child has
+// compressed_into = <keeperId>; deleting that keeper (compressed_into has no FK) would
+// leave the child dangling behind a now-missing parent — hidden from every
+// COALESCE(compressed_into,0)=0 view and unrecoverable. Recovery = resurface the child
+// as live (NULL) rather than lose it silently. Shared by both hard-delete paths.
+function recoverChildrenOf(db, ids) {
+  if (!ids.length) return 0;
+  const ph = ids.map(() => '?').join(',');
+  return db.prepare(`UPDATE observations SET compressed_into = NULL WHERE compressed_into IN (${ph})`).run(...ids).changes;
+}
+
 export function cleanupBroken(db, { projectFilter, baseParams, opCap = OP_CAP }) {
-  return db.prepare(`
-    DELETE FROM observations WHERE id IN (
-      SELECT id FROM observations
-      WHERE COALESCE(compressed_into, 0) = 0
-        AND (title IS NULL OR title = '') AND (narrative IS NULL OR narrative = '')
-        ${projectFilter} LIMIT ${opCap}
-    )
-  `).run(...baseParams).changes;
+  const doomed = db.prepare(`
+    SELECT id FROM observations
+    WHERE COALESCE(compressed_into, 0) = 0
+      AND (title IS NULL OR title = '') AND (narrative IS NULL OR narrative = '')
+      ${projectFilter} LIMIT ${opCap}
+  `).all(...baseParams).map(r => r.id);
+  if (!doomed.length) return 0;
+  recoverChildrenOf(db, doomed); // empty-content row could still be a cluster keeper
+  const ph = doomed.map(() => '?').join(',');
+  return db.prepare(`DELETE FROM observations WHERE id IN (${ph})`).run(...doomed).changes;
 }
 
 /**
@@ -115,12 +128,54 @@ export function demotePinned(db, { projectFilter, baseParams, opCap = OP_CAP })
  * number of rows merged. Callers parse their own input (CLI string / MCP array).
  */
 export function mergeDuplicates(db, groups) {
-  let merged = 0;
-  const mergeStmt = db.prepare('UPDATE observations SET compressed_into = ? WHERE id = ? AND COALESCE(compressed_into, 0) = 0');
+  // Resolve the WHOLE batch before writing so transitive merges can't orphan rows.
+  // A row is hidden from every view by `compressed_into != 0`, so pointing it at a
+  // keeper that is itself hidden buries it behind a hidden parent. Naively applying
+  // groups one update at a time loses data in three ways the old 1-line self-merge
+  // guard missed:
+  //   - chain  [[A,B],[B,C]] -> C.compressed_into=B, but B is now hidden into A;
+  //     if B is later purgeStale-deleted, C's keeper vanishes and C is unrecoverable.
+  //   - mutual [[A,B],[B,A]] -> BOTH hidden, the cluster loses its live representative.
+  //   - already-compressed keeper [E,F] when E was merged in a prior call -> F buried
+  //     behind hidden E.
+  // mem_maintain's "dedup" auto-suggests pairs that can form these chains (server.mjs),
+  // so this is reachable in normal use, not just typos. Fix: build the redirect map,
+  // collapse each removeId to a single live keeper (cycles -> smallest id as canonical),
+  // and only write removeId -> keeper when that keeper is currently live. Shared core,
+  // so CLI + MCP both inherit it.
+  const redirect = new Map(); // removeId -> keepId (first writer wins, deterministic)
   for (const group of groups) {
     if (!group || group.length < 2) continue;
     const [keepId, ...removeIds] = group;
-    for (const removeId of removeIds) merged += mergeStmt.run(keepId, removeId).changes;
+    for (const removeId of removeIds) {
+      if (removeId === keepId) continue;            // self-merge typo: no-op
+      if (!redirect.has(removeId)) redirect.set(removeId, keepId);
+    }
+  }
+  if (redirect.size === 0) return 0;
+
+  // Follow the redirect chain to the ultimate keeper. A cycle (mutual merge) collapses
+  // to the smallest id among the cycle members so every member agrees on one survivor.
+  const resolveKeeper = (start) => {
+    const seen = [];
+    let cur = start;
+    while (redirect.has(cur)) {
+      const at = seen.indexOf(cur);
+      if (at !== -1) return Math.min(...seen.slice(at)); // cycle -> canonical = min member
+      seen.push(cur);
+      cur = redirect.get(cur);
+    }
+    return cur; // an id with no outgoing redirect is a keeper
+  };
+
+  const isLive = db.prepare('SELECT 1 FROM observations WHERE id = ? AND COALESCE(compressed_into, 0) = 0');
+  const mergeStmt = db.prepare('UPDATE observations SET compressed_into = ? WHERE id = ? AND COALESCE(compressed_into, 0) = 0');
+  let merged = 0;
+  for (const removeId of redirect.keys()) {
+    const keeper = resolveKeeper(removeId);
+    if (keeper === removeId) continue;              // cycle canonical: this row survives
+    if (!isLive.get(keeper)) continue;              // keeper not live -> skip, never orphan
+    merged += mergeStmt.run(keeper, removeId).changes;
   }
   return merged;
 }
@@ -136,13 +191,17 @@ export function purgeStalePreview(db, { projectFilter, baseParams }, retainCutof
 
 /** Delete pending-purge observations older than the retain cutoff. Returns rows deleted. */
 export function purgeStale(db, { projectFilter, baseParams, opCap = OP_CAP }, retainCutoff) {
-  return db.prepare(`
-    DELETE FROM observations WHERE id IN (
-      SELECT id FROM observations
-      WHERE compressed_into = ${COMPRESSED_PENDING_PURGE} AND created_at_epoch < ?
-        ${projectFilter} LIMIT ${opCap}
-    )
-  `).run(retainCutoff, ...baseParams).changes;
+  const doomed = db.prepare(`
+    SELECT id FROM observations
+    WHERE compressed_into = ${COMPRESSED_PENDING_PURGE} AND created_at_epoch < ?
+      ${projectFilter} LIMIT ${opCap}
+  `).all(retainCutoff, ...baseParams).map(r => r.id);
+  if (!doomed.length) return 0;
+  // A keeper that absorbed dups can later be marked idle (compressed_into=PENDING_PURGE)
+  // and reach here; deleting it would orphan its children. Recover them first.
+  recoverChildrenOf(db, doomed);
+  const ph = doomed.map(() => '?').join(',');
+  return db.prepare(`DELETE FROM observations WHERE id IN (${ph})`).run(...doomed).changes;
 }
 
 /**

package/lib/observation-write.mjs

@@ -0,0 +1,67 @@
+// Single source of truth for the observations-table write surface. Two ingest
+// paths previously hand-wrote divergent INSERTs — lib/save-observation.mjs (manual
+// mem_save, 16 cols, omitted subtitle/search_aliases) and hook-llm.mjs (LLM
+// auto-ingest, 18 cols) — the exact column-drift hazard the compress/maintain
+// single-source cores were extracted to eliminate (see #8614). Add a column HERE
+// and both ingest paths pick it up; neither can silently fall out of sync again.
+//
+// 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 { debugCatch } from '../utils.mjs';
+
+// Canonical column order — must mirror the observations schema (schema.mjs).
+const OBS_COLUMNS = [
+  'memory_session_id', 'project', 'text', 'type', 'title', 'subtitle',
+  'narrative', 'concepts', 'facts', 'files_read', 'files_modified',
+  'importance', 'minhash_sig', 'lesson_learned', 'search_aliases', 'branch',
+  'created_at', 'created_at_epoch',
+];
+// Defaults for columns a caller omits. NULL-default columns (subtitle,
+// search_aliases) match the schema DEFAULT, so omitting == the old short INSERT.
+// concepts/facts/files_read default to the empty literals the manual path used.
+const OBS_DEFAULTS = {
+  subtitle: null, narrative: '', concepts: '', facts: '',
+  files_read: '[]', files_modified: '[]', search_aliases: null, importance: 1,
+};
+
+/**
+ * Insert one observations row from a {column: value} map and return its id.
+ * Omitted columns fall back to OBS_DEFAULTS (or NULL). The column list lives only
+ * here, so a schema column can never drift between the two ingest paths again.
+ */
+export function insertObservationRow(db, fields) {
+  const values = OBS_COLUMNS.map(c =>
+    Object.prototype.hasOwnProperty.call(fields, c) ? fields[c]
+      : (c in OBS_DEFAULTS ? OBS_DEFAULTS[c] : null)
+  );
+  const placeholders = OBS_COLUMNS.map(() => '?').join(', ');
+  const result = db
+    .prepare(`INSERT INTO observations (${OBS_COLUMNS.join(', ')}) VALUES (${placeholders})`)
+    .run(...values);
+  return Number(result.lastInsertRowid);
+}
+
+/** Populate the observation_files junction (skips non-string / empty entries). */
+export function insertObservationFiles(db, obsId, files) {
+  if (!obsId || !Array.isArray(files) || files.length === 0) return;
+  const stmt = db.prepare('INSERT OR IGNORE INTO observation_files (obs_id, filename) VALUES (?, ?)');
+  for (const f of files) if (typeof f === 'string' && f.length > 0) stmt.run(obsId, f);
+}
+
+/**
+ * Best-effort TF-IDF vector write. Non-critical: vocab may be uninitialized on a
+ * fresh DB, so failures are swallowed (caller's transaction must NOT roll back the
+ * observation over a missing vector).
+ */
+export function insertObservationVector(db, obsId, vecText) {
+  try {
+    const vocab = getVocabulary(db);
+    if (!vocab) return;
+    const vec = computeVector(vecText, vocab);
+    if (!vec) return;
+    db.prepare('INSERT OR REPLACE INTO observation_vectors (observation_id, vector, vocab_version, created_at_epoch) VALUES (?, ?, ?, ?)')
+      .run(obsId, Buffer.from(vec.buffer), vocab.version, Date.now());
+  } catch (e) { debugCatch(e, 'insertObservationVector'); }
+}

package/lib/save-observation.mjs

@@ -11,9 +11,9 @@
 //   - argument parsing (CLI flags vs MCP Zod schema)
 //   - result rendering (CLI stdout vs MCP content array)
 
-import { jaccardSimilarity, scrubSecrets, computeMinHash, cjkBigrams, getCurrentBranch, debugCatch } from '../utils.mjs';
-import { getVocabulary, computeVector } from '../tfidf.mjs';
+import { jaccardSimilarity, scrubSecrets, computeMinHash, cjkBigrams, getCurrentBranch } from '../utils.mjs';
 import { DEDUP_JACCARD_THRESHOLD } from './dedup-constants.mjs';
+import { insertObservationRow, insertObservationFiles, insertObservationVector } from './observation-write.mjs';
 
 const DEDUP_WINDOW_MS = 5 * 60 * 1000;
 const DEDUP_RECENT_LIMIT = 50;
@@ -40,6 +40,13 @@ export function saveObservation(db, params) {
   const project = params.project;
   const type = params.type || 'discovery';
   const content = params.content;
+  // Defensive single-source guard: never persist an empty/whitespace-only row.
+  // CLI's `!text` check and MCP's `z.string().min(1)` both let whitespace-only
+  // content through ("   " is length>=1 and truthy), creating junk observations
+  // with blank title/text. Reject here so both call sites are covered at once.
+  if (typeof content !== 'string' || content.trim().length === 0) {
+    throw new Error('mem_save: content is empty or whitespace-only');
+  }
   const rawTitle = params.title || content.slice(0, 100);
   const importance = params.importance ?? 2;
   const files = Array.isArray(params.files)
@@ -92,31 +99,17 @@ export function saveObservation(db, params) {
   // (TF-IDF). Vector write is best-effort — vocab may be uninitialized on a
   // fresh DB; failure must not roll back the observation.
   const saveTx = db.transaction(() => {
-    const result = db.prepare(`
-      INSERT INTO observations (memory_session_id, project, text, type, title, narrative, concepts, facts, files_read, files_modified, importance, minhash_sig, lesson_learned, branch, created_at, created_at_epoch)
-      VALUES (?, ?, ?, ?, ?, ?, '', '', '[]', ?, ?, ?, ?, ?, ?, ?)
-    `).run(
-      sessionId, project, textField, type, safeTitle, safeContent,
-      JSON.stringify(files), importance, minhashSig, safeLesson, getCurrentBranch(),
-      now.toISOString(), now.getTime()
-    );
-    const savedId = Number(result.lastInsertRowid);
-
-    if (savedId && files.length > 0) {
-      const insertFile = db.prepare('INSERT OR IGNORE INTO observation_files (obs_id, filename) VALUES (?, ?)');
-      for (const f of files) insertFile.run(savedId, f);
-    }
+    // Manual-save shape: narrative=content, concepts/facts/files_read empty, no
+    // subtitle/search_aliases (defaults). Column list single-sourced in lib/observation-write.
+    const savedId = insertObservationRow(db, {
+      memory_session_id: sessionId, project, text: textField, type, title: safeTitle,
+      narrative: safeContent, files_modified: JSON.stringify(files), importance,
+      minhash_sig: minhashSig, lesson_learned: safeLesson, branch: getCurrentBranch(),
+      created_at: now.toISOString(), created_at_epoch: now.getTime(),
+    });
 
-    try {
-      const vocab = getVocabulary(db);
-      if (vocab) {
-        const vec = computeVector(safeTitle + ' ' + safeContent, vocab);
-        if (vec) {
-          db.prepare('INSERT OR REPLACE INTO observation_vectors (observation_id, vector, vocab_version, created_at_epoch) VALUES (?, ?, ?, ?)')
-            .run(savedId, Buffer.from(vec.buffer), vocab.version, Date.now());
-        }
-      }
-    } catch (e) { debugCatch(e, 'save-observation-vector'); }
+    insertObservationFiles(db, savedId, files);
+    insertObservationVector(db, savedId, safeTitle + ' ' + safeContent);
 
     return savedId;
   });

package/mem-cli.mjs

@@ -11,7 +11,7 @@ import { resolveProject } from './project-utils.mjs';
 import { computeTier, TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
 import { getVocabulary, computeVector, _resetVocabCache } from './tfidf.mjs';
 import { autoBoostIfNeeded, reRankWithContext, markSuperseded } from './server-internals.mjs';
-import { searchObservationsHybrid, findFtsAnchor } from './search-engine.mjs';
+import { searchObservationsHybrid, findFtsAnchor, countSearchTotal } from './search-engine.mjs';
 import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
@@ -313,9 +313,24 @@ function cmdSearch(db, args) {
 
   // Trim to limit with offset. The engine always received perSourceOffset=0 and
   // over-fetched (see above), so the merged+reranked `results` start at row 0 and
-  // the offset is applied exactly ONCE here — for every mode. `total` is the full
-  // match count (capped at perSourceLimit), enabling the "N of M" display.
-  const total = results.length;
+  // the offset is applied exactly ONCE here — for every mode.
+  //
+  // `total` must be the TRUE population, independent of --limit/--offset (else the
+  // over-fetched candidate count grew with the page and broke the "N of M" /
+  // pagination contract). countSearchTotal mirrors each source's MATCH+filters;
+  // clamp to >= results.length so it never understates the rows actually shown
+  // (vector/concept augmentation can add obs rows beyond the FTS count).
+  const trueTotal = countSearchTotal(db, {
+    effectiveSource,
+    ftsQuery,
+    obsFtsQuery: orFallbackFired ? (relaxFtsQueryToOr(ftsQuery) || ftsQuery) : ftsQuery,
+    args: { project: project || null, obs_type: type || null, importance: minImportance || null, branch: branch || null },
+    project: project || null,
+    epochFrom: dateFrom,
+    epochTo: dateTo,
+    includeNoise,
+  });
+  const total = Math.max(trueTotal, results.length);
   const paged = results.slice(offset, offset + limit);
 
   if (paged.length === 0) {
@@ -924,7 +939,7 @@ function cmdTimeline(db, args) {
 function cmdSave(db, args) {
   const { positional, flags } = parseArgs(args);
   const text = positional.join(' ');
-  if (!text) {
+  if (!text.trim()) {
     fail('[mem] Usage: claude-mem-lite save "<text>" [--type T] [--title T] [--importance N] [--project P] [--files f1,f2] [--lesson T] [--closes-deferred 1,D#42]');
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.90.1",
+  "version": "2.92.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",
@@ -67,6 +67,7 @@
     "lib/binding-probe.mjs",
     "lib/mem-override.mjs",
     "lib/save-observation.mjs",
+    "lib/observation-write.mjs",
     "lib/compress-core.mjs",
     "lib/maintain-core.mjs",
     "lib/dedup-constants.mjs",
@@ -136,7 +137,7 @@
     "zod": "^4.3.6"
   },
   "overrides": {
-    "hono": ">=4.12.16",
+    "hono": ">=4.12.21",
     "fast-uri": ">=3.1.2",
     "ip-address": ">=10.1.1"
   },

package/registry.mjs

@@ -339,135 +339,3 @@ export function upsertResource(db, r) {
     return row?.id || 0;
   })();
 }
-
-/**
- * Get all active resources.
- * @param {Database} db Registry database
- * @returns {object[]} Array of resource objects
- */
-export function getActiveResources(db) {
-  return db.prepare('SELECT * FROM resources WHERE status = ? ORDER BY name').all('active');
-}
-
-/**
- * Get a resource by type and name.
- * @param {Database} db Registry database
- * @param {string} type 'skill' or 'agent'
- * @param {string} name Resource name
- * @returns {object|undefined} Resource or undefined
- */
-export function getResourceByName(db, type, name) {
-  return db.prepare('SELECT * FROM resources WHERE type = ? AND name = ?').get(type, name);
-}
-
-/**
- * Get a resource by ID.
- * @param {Database} db Registry database
- * @param {number} id Resource ID
- * @returns {object|undefined} Resource or undefined
- */
-export function getResourceById(db, id) {
-  return db.prepare('SELECT * FROM resources WHERE id = ?').get(id);
-}
-
-/**
- * Atomically increment a stats field on a resource.
- * @param {Database} db Registry database
- * @param {number} id Resource ID
- * @param {'recommend_count'|'adopt_count'|'success_count'} field Stats field
- */
-export function updateResourceStats(db, id, field) {
-  const allowed = new Set(['recommend_count', 'adopt_count', 'success_count']);
-  if (!allowed.has(field)) throw new Error(`Invalid stats field: ${field}`);
-  // String interpolation required: SQLite cannot parameterize column names.
-  // Safety: field is validated against allowlist above.
-  db.prepare(`UPDATE resources SET ${field} = ${field} + 1, updated_at = datetime('now') WHERE id = ?`).run(id);
-}
-
-/**
- * Atomically increment weighted_adopt_sum by a continuous score value.
- * @param {Database} db Registry database
- * @param {number} id Resource ID
- * @param {number} score Adoption confidence score (0.0-1.0)
- */
-export function incrementWeightedAdopt(db, id, score) {
-  db.prepare(`UPDATE resources SET weighted_adopt_sum = COALESCE(weighted_adopt_sum, 0) + ?, updated_at = datetime('now') WHERE id = ?`).run(score, id);
-}
-
-/**
- * Record a dispatch invocation.
- * @param {Database} db Registry database
- * @param {object} record Invocation record
- * @returns {number} Invocation ID
- */
-export function recordInvocation(db, record) {
-  const result = db.prepare(`
-    INSERT INTO invocations (resource_id, session_id, trigger, tier, recommended, adopted, outcome, score)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(
-    record.resource_id, record.session_id || null,
-    record.trigger || null, record.tier || null,
-    record.recommended ?? 1, record.adopted ?? 0,
-    record.outcome || null, record.score ?? null
-  );
-  return Number(result.lastInsertRowid);
-}
-
-/**
- * Get success rates for resources over a time period.
- * @param {Database} db Registry database
- * @param {number} [days=30] Lookback period
- * @returns {object[]} Array of {resource_id, total, adopted, avg_score}
- */
-export function getResourceSuccessRates(db, days = 30) {
-  const since = new Date(Date.now() - days * 86400000).toISOString();
-  return db.prepare(`
-    SELECT resource_id,
-      COUNT(*) as total,
-      SUM(adopted) as adopted,
-      AVG(CASE WHEN score IS NOT NULL THEN score END) as avg_score
-    FROM invocations
-    WHERE created_at > ?
-    GROUP BY resource_id
-  `).all(since);
-}
-
-/**
- * Get invocations for a specific session (for feedback collection).
- * @param {Database} db Registry database
- * @param {string} sessionId Session identifier
- * @returns {object[]} Array of invocation records
- */
-export function getSessionInvocations(db, sessionId) {
-  return db.prepare(`
-    SELECT i.*, r.name as resource_name, r.type as resource_type,
-           r.invocation_name as invocation_name
-    FROM invocations i
-    JOIN resources r ON r.id = i.resource_id
-    WHERE i.session_id = ?
-    ORDER BY i.created_at
-  `).all(sessionId);
-}
-
-/**
- * Update invocation outcome (for feedback).
- * @param {Database} db Registry database
- * @param {number} id Invocation ID
- * @param {object} update Fields to update
- */
-export function updateInvocation(db, id, update) {
-  const allowed = new Set(['adopted', 'outcome', 'score', 'rejection_reason']);
-  const sets = [];
-  const vals = [];
-  for (const [key, val] of Object.entries(update)) {
-    if (val === undefined) continue;
-    if (!allowed.has(key)) throw new Error(`Invalid invocation field: ${key}`);
-    sets.push(`${key} = ?`);
-    vals.push(val);
-  }
-  if (sets.length === 0) return;
-  vals.push(id);
-  // String interpolation required: SQLite cannot parameterize column names.
-  // Safety: column names are validated against allowlist above.
-  db.prepare(`UPDATE invocations SET ${sets.join(', ')} WHERE id = ?`).run(...vals);
-}

package/search-engine.mjs

@@ -72,6 +72,110 @@ export function buildObsFtsParams({ now, projectBoost, ftsQuery, args, epochFrom
   return params;
 }
 
+// --- True match-count helpers (limit/offset-invariant search totals) ----------
+// The search path over-fetches per source — perSourceLimit = max(limit*3,
+// offset+limit+10) — and historically reported `total = results.length`. That made
+// "Found N of M" and the JSON `total` field grow with --limit/--offset, breaking
+// the documented pagination contract (a query's population must not change when you
+// page through it). These COUNT(*) helpers mirror each source's MATCH + filters
+// exactly, so `total` reflects the real population independent of paging. Shared by
+// CLI and MCP per the paired-path single-source-of-truth rule (#8217).
+//
+// Known approximation: post-SQL filters that DROP rows after the query (CJK
+// precision gate on prompts, --tier on obs) are not reflected here, so those niche
+// queries may overcount. Callers clamp total to >= page size, so it never
+// understates the rows actually shown.
+export function countObsFtsMatches(db, { ftsQuery, args = {}, epochFrom = null, epochTo = null, includeNoise = false }) {
+  if (!ftsQuery) return 0;
+  const lowSignalClause = includeNoise ? '' : `AND ${notLowSignalTitleClause('o')}`;
+  try {
+    const row = db.prepare(`
+      SELECT COUNT(*) as c
+      FROM observations_fts
+      JOIN observations o ON observations_fts.rowid = o.id
+      WHERE observations_fts MATCH ?
+        AND COALESCE(o.compressed_into, 0) = 0
+        AND o.superseded_at IS NULL
+        AND (? IS NULL OR o.project = ?)
+        AND (? IS NULL OR o.type = ?)
+        AND (? IS NULL OR o.created_at_epoch >= ?)
+        AND (? IS NULL OR o.created_at_epoch <= ?)
+        AND (? IS NULL OR COALESCE(o.importance, 1) >= ?)
+        AND (? IS NULL OR o.branch = ?)
+        ${lowSignalClause}
+    `).get(
+      ftsQuery,
+      args.project ?? null, args.project ?? null,
+      args.obs_type ?? null, args.obs_type ?? null,
+      epochFrom, epochFrom,
+      epochTo, epochTo,
+      args.importance ?? null, args.importance ?? null,
+      args.branch ?? null, args.branch ?? null,
+    );
+    return row?.c ?? 0;
+  } catch { return 0; }
+}
+
+export function countSessionFtsMatches(db, { ftsQuery, project = null, epochFrom = null, epochTo = null }) {
+  if (!ftsQuery) return 0;
+  try {
+    const wheres = ['session_summaries_fts MATCH ?'];
+    const params = [ftsQuery];
+    if (project) { wheres.push('s.project = ?'); params.push(project); }
+    if (epochFrom) { wheres.push('s.created_at_epoch >= ?'); params.push(epochFrom); }
+    if (epochTo) { wheres.push('s.created_at_epoch <= ?'); params.push(epochTo); }
+    const row = db.prepare(`
+      SELECT COUNT(*) as c
+      FROM session_summaries_fts
+      JOIN session_summaries s ON session_summaries_fts.rowid = s.id
+      WHERE ${wheres.join(' AND ')}
+    `).get(...params);
+    return row?.c ?? 0;
+  } catch { return 0; }
+}
+
+export function countPromptFtsMatches(db, { ftsQuery, project = null, epochFrom = null, epochTo = null }) {
+  if (!ftsQuery) return 0;
+  try {
+    const wheres = ['user_prompts_fts MATCH ?', "p.prompt_text NOT LIKE '<task-notification>%'"];
+    const params = [ftsQuery];
+    if (project) { wheres.push('s.project = ?'); params.push(project); }
+    if (epochFrom) { wheres.push('p.created_at_epoch >= ?'); params.push(epochFrom); }
+    if (epochTo) { wheres.push('p.created_at_epoch <= ?'); params.push(epochTo); }
+    const row = db.prepare(`
+      SELECT COUNT(*) as c
+      FROM user_prompts_fts
+      JOIN user_prompts p ON user_prompts_fts.rowid = p.id
+      JOIN sdk_sessions s ON p.content_session_id = s.content_session_id
+      WHERE ${wheres.join(' AND ')}
+    `).get(...params);
+    return row?.c ?? 0;
+  } catch { return 0; }
+}
+
+/**
+ * Sum true match counts across the sources that contribute to a cross-source (or
+ * source-restricted) search. `obsFtsQuery` lets callers pass the OR-relaxed query
+ * when obs AND→OR fallback fired (the displayed obs rows came from the OR query).
+ * @returns {number} population count, limit/offset-invariant
+ */
+export function countSearchTotal(db, {
+  effectiveSource = null, ftsQuery, obsFtsQuery = null,
+  args = {}, project = null, epochFrom = null, epochTo = null, includeNoise = false,
+}) {
+  let total = 0;
+  if (!effectiveSource || effectiveSource === 'observations') {
+    total += countObsFtsMatches(db, { ftsQuery: obsFtsQuery || ftsQuery, args, epochFrom, epochTo, includeNoise });
+  }
+  if (!effectiveSource || effectiveSource === 'sessions') {
+    total += countSessionFtsMatches(db, { ftsQuery, project, epochFrom, epochTo });
+  }
+  if (!effectiveSource || effectiveSource === 'prompts') {
+    total += countPromptFtsMatches(db, { ftsQuery, project, epochFrom, epochTo });
+  }
+  return total;
+}
+
 export function ftsRowToResult(r, { scoreMultiplier, snippet } = {}) {
   return {
     source: 'obs', id: r.id, type: r.type, title: r.title, subtitle: r.subtitle,
@@ -262,6 +366,15 @@ export function searchObservationsHybrid(db, ctx) {
     if (vecResults.length === 0) return results;
 
     if (results.length > 0) {
+      // RRF fuses by RANK (array index), so the BM25 side must already be in
+      // composite-score order. `results` here is [full-FTS sorted, …concept ×0.7,
+      // …PRF ×0.6] with augmentation rows APPENDED, so its index order is only
+      // BM25-rank for the first block — a downweighted PRF row at the tail would be
+      // handed to RRF as a worse rank than its score warrants, and a strong one as
+      // better. Sort by the calibrated composite score (negative = more relevant)
+      // first so index == composite rank and the type-quality/decay/cite multipliers
+      // actually shape the fused ranking instead of being discarded by insertion order.
+      results.sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
       const rrfRanking = rrfMerge(results, vecResults, ctx.rrfK);  // undefined → RRF_K
       const resultMap = new Map(results.map(r => [r.id, r]));
       for (const vr of vecResults) {

package/server.mjs

@@ -10,7 +10,7 @@ import { extractCjkLikePatterns, cjkPrecisionOk } from './nlp.mjs';
 import { resolveProject as _resolveProjectShared } from './project-utils.mjs';
 import { ensureDb, DB_PATH, DB_DIR, REGISTRY_DB_PATH } from './schema.mjs';
 import { reRankWithContext, markSuperseded, autoBoostIfNeeded, runIdleCleanup, buildServerInstructions } from './server-internals.mjs';
-import { searchObservationsHybrid, findFtsAnchor } from './search-engine.mjs';
+import { searchObservationsHybrid, findFtsAnchor, countSearchTotal } from './search-engine.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
 import {
   cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
@@ -314,7 +314,7 @@ function searchPrompts(ctx) {
   return results;
 }
 
-function formatSearchOutput(paginatedResults, args, ftsQuery, totalCount, isCrossSource, orFallbackFired = false) {
+function formatSearchOutput(paginatedResults, args, ftsQuery, totalCount, orFallbackFired = false) {
   if (paginatedResults.length === 0) {
     const hint = [];
     if (args.query && !ftsQuery) {
@@ -332,7 +332,13 @@ function formatSearchOutput(paginatedResults, args, ftsQuery, totalCount, isCros
   }
 
   const lines = [];
-  const countLabel = isCrossSource && totalCount > paginatedResults.length
+  // "N of M" whenever the population exceeds the page — NOT gated on isCrossSource.
+  // totalCount is the true limit/offset-invariant population (countSearchTotal), so
+  // single-source searches (obs_type / type / importance filters) must surface it too.
+  // The old isCrossSource gate predated countSearchTotal: back then single-source
+  // totalCount was just results.length, so suppressing "of M" hid nothing. Now it hid
+  // the real total, diverging from the CLI (mem-cli.mjs has no such gate). (#8217)
+  const countLabel = totalCount > paginatedResults.length
     ? `${paginatedResults.length} of ${totalCount}`
     : `${paginatedResults.length}`;
   const hasMixed = paginatedResults.some(r => r.source === 'session' || r.source === 'prompt');
@@ -385,9 +391,15 @@ server.registerTool(
     const searchType = args.type;
     const currentProject = inferProject();
 
-    const isCrossSourceRaw = !searchType;
-    const perSourceLimit = isCrossSourceRaw ? Math.max(limit * 3, offset + limit + 10) : limit;
-    const perSourceOffset = isCrossSourceRaw ? 0 : offset;
+    // Over-fetch from offset 0 for EVERY mode, then apply `offset` exactly once at
+    // the merge slice below — identical to the CLI (mem-cli.mjs perSourceOffset=0).
+    // The old single-source branch (perSourceLimit=limit, perSourceOffset=offset)
+    // double-applied offset: it pushed offset into the per-source SQL AND re-sliced
+    // by offset at merge, so explicit `type=observations` paging overlapped (page 0
+    // == page 1) and gapped (oldest rows unreachable). It also fetched only `limit`
+    // rows — fewer than offset+limit — so there was nothing to page into. (#8217)
+    const perSourceLimit = Math.max(limit * 3, offset + limit + 10);
+    const perSourceOffset = 0;
 
     // Parse date bounds to epoch (with validation)
     // date_to with date-only format (YYYY-MM-DD) extends to end-of-day (23:59:59.999Z)
@@ -401,7 +413,7 @@ server.registerTool(
 
     // Early return when query was provided but sanitized to nothing (all FTS5 keywords/special chars)
     if (args.query && !ftsQuery && !epochFrom && !epochTo && !args.obs_type && !args.importance) {
-      return formatSearchOutput([], args, ftsQuery, 0, false);
+      return formatSearchOutput([], args, ftsQuery, 0);
     }
 
     // When obs_type is specified, implicitly restrict to observations only
@@ -502,11 +514,25 @@ server.registerTool(
     }
     // else 'relevance' keeps BM25 score order (already sorted)
 
-    const totalBeforePagination = results.length;
+    // `total` must be the TRUE population, invariant to limit/offset. In cross-source
+    // mode results is over-fetched (perSourceLimit scales with limit+offset), so
+    // results.length is NOT the population — count the real MATCH set instead. Clamp
+    // to >= results.length so vector/concept-augmented obs rows are never undercounted.
+    // (paired-path with mem-cli.mjs via shared countSearchTotal — #8217)
+    const trueTotal = countSearchTotal(db, {
+      effectiveSource: effectiveType || null,
+      ftsQuery,
+      obsFtsQuery: ctx.orFallbackFired === true ? (relaxFtsQueryToOr(ftsQuery) || ftsQuery) : ftsQuery,
+      args: { project: args.project || null, obs_type: args.obs_type || null, importance: args.importance || null, branch: args.branch || null },
+      project: args.project || null,
+      epochFrom, epochTo,
+      includeNoise: args.include_noise === true,
+    });
+    const totalBeforePagination = Math.max(trueTotal, results.length);
     // Always apply pagination — single-source results can exceed SQL LIMIT due to expansion (concept co-occurrence, PRF, vector search)
     const paginatedResults = (offset > 0 || results.length > limit) ? results.slice(offset, offset + limit) : results;
 
-    return formatSearchOutput(paginatedResults, args, ftsQuery, totalBeforePagination, isCrossSource, ctx.orFallbackFired === true);
+    return formatSearchOutput(paginatedResults, args, ftsQuery, totalBeforePagination, ctx.orFallbackFired === true);
   })
 );
 

package/source-files.mjs

@@ -77,6 +77,11 @@ export const SOURCE_FILES = [
   // mem-cli.mjs::cmdSave and server.mjs::mem_save. Statically imported from both
   // entry points; missing it from the manifest broke MCP saves on auto-update.
   'lib/save-observation.mjs',
+  // Single-source observations-table write primitives (insertObservationRow/Files/
+  // Vector). Statically imported by lib/save-observation.mjs and hook-llm.mjs (both
+  // entry-point-reachable); missing it from the manifest would break ALL saves on
+  // auto-update. Same single-source-of-truth pattern (see #8217).
+  'lib/observation-write.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