claude-mem-lite 2.91.0 → 2.93.0

package/lib/maintain-core.mjs

@@ -29,15 +29,35 @@ 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 every hard-delete path:
+// maintain (cleanupBroken/purgeStale) AND the interactive `delete` / MCP mem_delete.
+export function recoverChildrenOf(db, ids) {
+  if (!ids.length) return 0;
+  const ph = ids.map(() => '?').join(',');
+  // `AND id NOT IN (...)`: never "recover" a row that is itself being deleted in the same
+  // call (e.g. `delete 1,2` where #2 was merged into #1). Without it, #2 is un-hidden and
+  // then immediately deleted, inflating the reported recovery count with a row that did not
+  // survive. Recovery should count only children that actually stay live.
+  return db.prepare(
+    `UPDATE observations SET compressed_into = NULL WHERE compressed_into IN (${ph}) AND id NOT IN (${ph})`
+  ).run(...ids, ...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,19 +135,55 @@ 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) {
-      // Skip self-merge: compressed_into=self hides the row from every
-      // compressed_into=0 view (recent/search/browse) — silent data loss from a
-      // typo like `--merge-ids 5:5`. Shared core, so this covers CLI + MCP.
-      if (removeId === keepId) continue;
-      merged += mergeStmt.run(keepId, removeId).changes;
+      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;
 }
 
@@ -142,13 +198,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;
@@ -99,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);
+    // 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(),
+    });
 
-    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);
-    }
-
-    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

@@ -18,6 +18,7 @@ import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from '
 import {
   cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
+  recoverChildrenOf,
   OP_CAP, STALE_AGE_MS, PINNED_INJ_THRESHOLD,
 } from './lib/maintain-core.mjs';
 import { optimizePreview, optimizeRun } from './hook-optimize.mjs';
@@ -32,7 +33,7 @@ import { readFileSync, existsSync, readdirSync } from 'fs';
 // v2.41: shared CLI helpers extracted to cli/common.mjs. Keep this file as the
 // router + remaining-command bodies during the incremental split. Future work:
 // move each cmdXxx into its own cli/<cmd>.mjs; mem-cli.mjs becomes pure dispatch.
-import { parseArgs, out, fail, relativeTime, fmtDateShort, parseIdToken, formatProbeHints } from './cli/common.mjs';
+import { parseArgs, out, fail, relativeTime, fmtDateShort, parseIdToken, formatProbeHints, rejectBareStringFlags } from './cli/common.mjs';
 import { saveObservation } from './lib/save-observation.mjs';
 import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { countRecentHookErrors } from './lib/hook-telemetry.mjs';
@@ -667,6 +668,7 @@ function cmdGet(db, args) {
   }
 
   // Validate --fields against obs schema (only meaningful for obs rows).
+  if (rejectBareStringFlags(flags, ['fields', 'source'])) return;
   let requestedFields = null;
   if (flags.fields) {
     const allRequested = flags.fields.split(',').map(s => s.trim());
@@ -713,6 +715,10 @@ function cmdGet(db, args) {
 
 function cmdTimeline(db, args) {
   const { positional, flags } = parseArgs(args);
+  // Bare `--query` parses to boolean true and crashed downstream in sanitizeFtsQuery
+  // (nlp.mjs string ops on a boolean). No sensible default for a search anchor — reject
+  // cleanly (#8470). (`--project` bare is absorbed by resolveProject's non-string guard.)
+  if (rejectBareStringFlags(flags, ['query'])) return;
   // parseInt('-5') === -5 is truthy, so `|| 5` doesn't rescue negative input.
   // Match cmdSearch's warn-then-default pattern for consistency across CLI flags.
   const parseWindow = (label, raw) => {
@@ -944,6 +950,10 @@ function cmdSave(db, args) {
     return;
   }
 
+  // Reject value-less string flags before they reach .split()/saveObservation as a
+  // boolean `true` (#8470): bare --files/--title/--lesson crashed with a raw stacktrace.
+  if (rejectBareStringFlags(flags, ['title', 'files', 'lesson', 'lesson-learned', 'project', 'type'])) return;
+
   const type = flags.type || 'discovery';
   const validTypes = new Set(['decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change']);
   if (!validTypes.has(type)) {
@@ -1070,6 +1080,8 @@ function cmdDeferAdd(db, args) {
     fail(`[mem] defer add: title too long (${title.length} chars, max 200). Move detail to --detail "<text>".`);
     return;
   }
+  // Reject bare --files/--detail/--project before .split()/bind sees a boolean true (#8470).
+  if (rejectBareStringFlags(flags, ['files', 'detail', 'project'])) return;
   const priority = flags.priority !== undefined ? parseInt(flags.priority, 10) : 2;
   // isNumericToken first: bare parseInt would coerce "3xyz"→3 and silently escalate a
   // deferred item's urgency. Float literals still truncate (#8277).
@@ -1614,11 +1626,19 @@ function cmdDelete(db, args) {
         db.prepare('UPDATE observations SET related_ids = ? WHERE id = ?').run(JSON.stringify(filtered), r.id);
       }
     }
-    return db.prepare(`DELETE FROM observations WHERE id IN (${placeholders})`).run(...ids);
+    // Resurface any rows merged/compressed INTO the doomed keepers before deleting,
+    // else they dangle behind a missing parent (compressed_into has no FK) — invisible
+    // to every COALESCE(compressed_into,0)=0 view and unrecoverable. Same guard the
+    // maintain hard-delete paths use (recoverChildrenOf); the interactive delete path
+    // was missing it. Returned in the result so the user sees the recovery count.
+    const recovered = recoverChildrenOf(db, ids);
+    const deleted = db.prepare(`DELETE FROM observations WHERE id IN (${placeholders})`).run(...ids);
+    return { changes: deleted.changes, recovered };
   });
   const result = deleteTx();
   const missing = ids.filter(id => !rows.some(r => r.id === id));
-  out(`[mem] Deleted ${result.changes} observation(s).${missing.length > 0 ? ` Note: ID(s) ${missing.join(', ')} not found.` : ''}`);
+  const recoveredNote = result.recovered > 0 ? ` Recovered ${result.recovered} merged/compressed child observation(s) to live.` : '';
+  out(`[mem] Deleted ${result.changes} observation(s).${recoveredNote}${missing.length > 0 ? ` Note: ID(s) ${missing.join(', ')} not found.` : ''}`);
 }
 
 // ─── Update ──────────────────────────────────────────────────────────────────
@@ -1644,18 +1664,10 @@ function cmdUpdate(db, args) {
     return;
   }
 
-  // A value-less `--flag` (last arg, or immediately followed by another --flag)
-  // parses to boolean `true` (cli/common.mjs parseArgs). For string-valued fields
-  // that boolean would slip past the string-only empty guards below and reach the
-  // SQLite bind, surfacing a raw "TypeError: SQLite3 can only bind ..." stacktrace
-  // — the same accidental shell-strip class the empty-title guard (#8470) catches.
-  // Reject it cleanly for every string-valued update flag.
-  for (const key of ['title', 'narrative', 'lesson', 'lesson-learned', 'concepts']) {
-    if (flags[key] === true) {
-      fail(`[mem] --${key} requires a value (received a bare flag with no value).`);
-      return;
-    }
-  }
+  // A value-less `--flag` parses to boolean `true` (cli/common.mjs parseArgs); for string
+  // fields that would reach the SQLite bind as a raw "TypeError: SQLite3 can only bind ..."
+  // (#8470). Reject cleanly via the shared guard — single source with the other commands.
+  if (rejectBareStringFlags(flags, ['title', 'narrative', 'lesson', 'lesson-learned', 'concepts'])) return;
 
   const updates = [];
   const params = [];
@@ -2172,6 +2184,9 @@ function cmdRegistry(_memDb, args) {
 
   try {
     if (action === 'search') {
+      // Bare `--query` parses to boolean true; `true || ...` would search for the literal
+      // string "true". Reject it cleanly (#8470) before it becomes a confusing no-match.
+      if (rejectBareStringFlags(flags, ['query', 'category', 'quality'])) return;
       const query = flags.query || positional.slice(1).join(' ');
       if (!query) { fail('[mem] Usage: claude-mem-lite registry search <query> [--type skill|agent] [--category C] [--quality Q]'); return; }
       let results = searchResources(rdb, query, {
@@ -2260,12 +2275,9 @@ function cmdRegistry(_memDb, args) {
     }
 
     if (action === 'import') {
-      // A bare value-less flag parses to boolean `true` (parseArgs); for these string
-      // fields that boolean reaches the SQLite bind in upsertResource and throws a raw
-      // TypeError — same class as the `update` guard above (#8470). Reject up front.
-      for (const key of ['name', 'resource-type', 'invocation-name', 'source', 'repo-url', 'local-path', 'intent-tags', 'domain-tags', 'trigger-patterns', 'capability-summary', 'keywords', 'tech-stack', 'use-cases']) {
-        if (flags[key] === true) { fail(`[mem] --${key} requires a value (received a bare flag with no value).`); return; }
-      }
+      // Bare value-less flags → boolean true → SQLite-bind crash in upsertResource (#8470).
+      // Shared guard — single source with update/remove/the other commands.
+      if (rejectBareStringFlags(flags, ['name', 'resource-type', 'invocation-name', 'source', 'repo-url', 'local-path', 'intent-tags', 'domain-tags', 'trigger-patterns', 'capability-summary', 'keywords', 'tech-stack', 'use-cases'])) return;
       const name = flags.name;
       const resourceType = flags['resource-type'];
       if (!name || !resourceType) { fail('[mem] Usage: claude-mem-lite registry import --name N --resource-type skill|agent [--invocation-name I] [--capability-summary S]'); return; }
@@ -2287,11 +2299,9 @@ function cmdRegistry(_memDb, args) {
     }
 
     if (action === 'remove') {
-      // Bare value-less --name / --resource-type → boolean true → SQLite-bind crash
-      // on the DELETE below; reject like the import branch and the `update` guard.
-      for (const key of ['name', 'resource-type']) {
-        if (flags[key] === true) { fail(`[mem] --${key} requires a value (received a bare flag with no value).`); return; }
-      }
+      // Bare value-less --name / --resource-type → boolean true → SQLite-bind crash on
+      // the DELETE below; shared guard, single source with import/update.
+      if (rejectBareStringFlags(flags, ['name', 'resource-type'])) return;
       const name = flags.name;
       const resourceType = flags['resource-type'];
       if (!name || !resourceType) { fail('[mem] Usage: claude-mem-lite registry remove --name N --resource-type skill|agent'); return; }

package/memdir.mjs

@@ -219,33 +219,58 @@ export function writePluginSection(memdir, { slug, version, contentLine, force =
 /**
  * Remove the plugin's sentinel block plus its state sidecar. External content
  * in MEMORY.md is preserved.
- * @returns {{action: 'removed'|'absent'}}
+ *
+ * Foreign-content guard (symmetric with writePluginSection): a sentinel block with
+ * NO state sidecar is content we cannot prove the plugin authored — the user may have
+ * pasted plugin docs or quoted a sentinel example. Without `force`, such a block is
+ * LEFT IN PLACE (action 'skipped-foreign') instead of being silently deleted. The
+ * adopt side already throws UserEditedError on the same condition; unadopt lacked the
+ * mirror, so it could delete user-authored text that merely resembled the sentinel.
+ *
+ * @param {string} memdir
+ * @param {string} slug
+ * @param {{force?: boolean}} [opts] force=true removes even a no-state (foreign) block.
+ * @returns {{action: 'removed'|'absent'|'skipped-foreign'}}
  */
-export function removePluginSection(memdir, slug) {
-  clearState(memdir, slug);
+export function removePluginSection(memdir, slug, { force = false } = {}) {
   const path = memoryFile(memdir);
-  if (!existsSync(path)) return { action: 'absent' };
+  if (!existsSync(path)) { clearState(memdir, slug); return { action: 'absent' }; }
   const raw = readFileSync(path, 'utf8');
   const match = raw.match(sentinelRegex(slug));
-  if (!match) return { action: 'absent' };
+  if (!match) { clearState(memdir, slug); return { action: 'absent' }; }
+
+  // Only remove a block we have a state sidecar for (proof we wrote it), unless forced.
+  if (!readState(memdir, slug) && !force) {
+    return { action: 'skipped-foreign' };
+  }
+  clearState(memdir, slug);
 
   // Delete the match plus a trailing newline + a preceding blank line so we
   // don't leave a stranded paragraph gap.
+  const blockAtStart = match.index === 0;
   let start = match.index;
   let end = match.index + match[0].length;
   if (raw[end] === '\n') end++;
   if (start > 0 && raw.slice(0, start).endsWith('\n\n')) start--;
   let next = raw.slice(0, start) + raw.slice(end);
-  // Edge case (code review v2.32.3): when the sentinel was the first content
-  // (e.g. two invited-memory plugins coexist and we remove the earlier one),
-  // the tail can still start with a stranded blank line / doubled newlines.
-  // Normalize leading whitespace and collapse any ≥3 consecutive newlines
-  // so the remaining content looks hand-authored.
-  next = next.replace(/^\s+/, '').replace(/\n{3,}/g, '\n\n');
+  // Collapse any ≥3 consecutive newlines left at the removal seam so the remaining
+  // content looks hand-authored. Only strip leading whitespace when OUR block was the
+  // file's first content — otherwise an unconditional `/^\s+/` deleted user-authored
+  // leading blank lines / structure that sat far above our (end-of-file) block.
+  next = next.replace(/\n{3,}/g, '\n\n');
+  if (blockAtStart) next = next.replace(/^\s+/, '');
   atomicWrite(path, next);
   return { action: 'removed' };
 }
 
+/**
+ * Whether a plugin state sidecar exists for this memdir — i.e. the plugin can prove it
+ * wrote the sentinel. Used by unadopt's dry-run to predict the foreign-content skip.
+ */
+export function hasPluginState(memdir, slug) {
+  return readState(memdir, slug) !== null;
+}
+
 /**
  * Whether this memdir has our sentinel. Body edits don't demote the adoption —
  * users who hand-tweak the contract line still count as adopted.

package/nlp.mjs

@@ -11,6 +11,23 @@ export { SYNONYM_MAP, CJK_COMPOUNDS };
 
 const FTS5_KEYWORDS = new Set(['AND', 'OR', 'NOT', 'NEAR']);
 
+/**
+ * True if a CJK bigram is pure grammatical noise that should not enter an FTS query
+ * or the precision gate's `required` set. CJK_STOP_WORDS holds single-char particles
+ * (的/了/是…) plus a few whole multi-char fillers (什么/怎么…); callers used to test a
+ * 2-char bigram with a bare `CJK_STOP_WORDS.has(bg)`, which only caught the whole-filler
+ * case — so a particle-pair bigram like `的了` / `了是` slipped through and (a) forced an
+ * unsatisfiable AND term and (b) made an all-particle query's `required` set non-empty,
+ * wrongly rejecting every candidate. We reject a bigram when it IS a known filler OR when
+ * BOTH characters are single-char stop words. A bigram with only ONE stop char (有效, 目的)
+ * is deliberately kept — those are real compounds, and distinguishing a boundary-straddle
+ * (的全) from a genuine compound needs a dictionary/recall benchmark (deferred).
+ */
+function isCjkNoiseBigram(bg) {
+  if (CJK_STOP_WORDS.has(bg)) return true;
+  return bg.length === 2 && CJK_STOP_WORDS.has(bg[0]) && CJK_STOP_WORDS.has(bg[1]);
+}
+
 // Sort by length descending for greedy matching
 const CJK_SORTED = [...CJK_COMPOUNDS].sort((a, b) => b.length - a.length);
 
@@ -177,7 +194,7 @@ export function cjkPrecisionOk(query, text, threshold) {
   const keywords = extractCjkKeywords(query);
   const required = keywords.length > 0
     ? keywords
-    : cjkBigrams(query).split(' ').filter(b => b && !CJK_STOP_WORDS.has(b));
+    : cjkBigrams(query).split(' ').filter(b => b && !isCjkNoiseBigram(b));
   if (required.length === 0) return true;
   const hit = required.filter(w => text.includes(w)).length;
   return (hit / required.length) >= threshold;
@@ -254,7 +271,7 @@ export function sanitizeFtsQuery(query) {
         const gapBigrams = cjkBigrams(remainder);
         if (gapBigrams) {
           for (const bg of gapBigrams.split(' ')) {
-            if (bg && !CJK_STOP_WORDS.has(bg) && !matched.has(bg)) expandedTokens.push(bg);
+            if (bg && !isCjkNoiseBigram(bg) && !matched.has(bg)) expandedTokens.push(bg);
           }
         }
         continue;
@@ -278,7 +295,7 @@ export function sanitizeFtsQuery(query) {
     );
     if (pureCjkTokens.length > 0) bigrams = cjkBigrams(pureCjkTokens.join(' '));
   }
-  const bigramSet = new Set(bigrams ? bigrams.split(' ').filter(b => b && !CJK_STOP_WORDS.has(b)) : []);
+  const bigramSet = new Set(bigrams ? bigrams.split(' ').filter(b => b && !isCjkNoiseBigram(b)) : []);
   const hasBigrams = bigramSet.size > 0;
   const finalTokens = [];
   const seen = new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.91.0",
+  "version": "2.93.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/project-utils.mjs

@@ -14,6 +14,12 @@ const _cache = new Map();
  */
 export function resolveProject(db, name) {
   if (!name) return name;
+  // Defense-in-depth: a bare `--project` CLI flag parses to boolean `true` (and a
+  // malformed MCP/hook caller could pass any non-string). `true.includes('--')` below
+  // throws a raw TypeError that crashed search/recent/timeline/stats/export/defer-list.
+  // Treat any non-string as "no project filter" (null) — the degradation every caller
+  // already handles for an absent --project — instead of crashing at the root helper.
+  if (typeof name !== 'string') return null;
   if (_cache.has(name)) return _cache.get(name);
   // Already a canonical name (contains "--")? Use as-is.
   if (name.includes('--')) { _cache.set(name, name); return name; }

package/registry-importer.mjs

@@ -336,10 +336,15 @@ export async function importFromGitHub(db, url, opts = {}) {
         indexed_at: new Date().toISOString(),
       });
 
-      // 5g. Update repo_forks and repo_updated_at (not in upsert SQL)
+      // 5g. Update repo_forks and repo_updated_at (not in upsert SQL).
+      // Do NOT touch quality_tier here: UPSERT_SQL never writes it, so a first insert
+      // gets the column DEFAULT 'community' and a re-import preserves whatever tier the
+      // row reached. Re-stamping 'community' downgraded enrichment-promoted tiers
+      // (verified/installed → community) on every content re-import, silently lowering
+      // the resource's BM25 composite rank (tier is a 1.0/2.0/3.0 multiplier).
       db.prepare(
-        'UPDATE resources SET repo_forks = ?, repo_updated_at = ?, quality_tier = ? WHERE id = ?'
-      ).run(repoForks, repoUpdatedAt, 'community', resourceId);
+        'UPDATE resources SET repo_forks = ?, repo_updated_at = ? WHERE id = ?'
+      ).run(repoForks, repoUpdatedAt, resourceId);
 
       results.push({ name, type: item.type, id: resourceId });
       debugLog('INFO', 'importer', `Imported ${item.type}:${name} (id=${resourceId})`);

package/registry-retriever.mjs

@@ -284,6 +284,10 @@ export function filterByProjectDomain(results, projectDomains) {
 //
 // Composite ranking formula:
 //   40% BM25 text relevance
+//   Quality-tier bonus: bounded additive (installed -0.15, verified -0.075). Was a
+//     MULTIPLIER on the BM25 term, which scaled the magnitude of a variable, unbounded,
+//     NEGATIVE signal — letting a weakly-matching installed resource (×3) outrank a
+//     strongly-matching community one. Additive keeps tier a promotion, not an override.
 //   15% Star popularity (saturation normalization — diminishing returns after ~500 stars)
 //   15% Success rate (Laplace smoothing — Beta prior α=1, β=1 for small-sample robustness)
 //   10% Adoption rate (Laplace smoothing)
@@ -301,10 +305,10 @@ export function filterByProjectDomain(results, projectDomains) {
 // Sign convention: more negative = better. BM25 is negative, behavioral signals are subtracted.
 const COMPOSITE_EXPR = `(
     bm25(resources_fts, 3.0, 3.0, 3.0, 2.0, 2.0, 1.0, 1.0, 1.0) * 0.4
-    * CASE COALESCE(r.quality_tier, 'community')
-        WHEN 'installed' THEN 3.0
-        WHEN 'verified' THEN 2.0
-        ELSE 1.0
+    - CASE COALESCE(r.quality_tier, 'community')
+        WHEN 'installed' THEN 0.15
+        WHEN 'verified' THEN 0.075
+        ELSE 0
       END
     - COALESCE(r.repo_stars * 1.0 / (r.repo_stars + 100.0), 0) * 0.15
     - (
@@ -347,7 +351,7 @@ const SEARCH_SQL = `
     WHERE resources_fts MATCH ?
       AND r.status = 'active'
   ) sub
-  ORDER BY composite_score ASC
+  ORDER BY composite_score ASC, id ASC
   LIMIT ?
 `;
 
@@ -362,7 +366,7 @@ const SEARCH_BY_TYPE_SQL = `
       AND r.status = 'active'
       AND r.type = ?
   ) sub
-  ORDER BY composite_score ASC
+  ORDER BY composite_score ASC, id ASC
   LIMIT ?
 `;