claude-mem-lite 2.62.1 → 2.64.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/cli/fts-check.mjs

@@ -8,7 +8,7 @@ export function cmdFtsCheck(db, args) {
   const { positional } = parseArgs(args);
   const action = positional[0];
   if (!action || !['check', 'rebuild'].includes(action)) {
-    fail('[mem] Usage: mem fts-check <check|rebuild>');
+    fail('[mem] Usage: claude-mem-lite fts-check <check|rebuild>');
     return;
   }
 

package/install.mjs

@@ -280,6 +280,25 @@ function ok(msg) { console.log(`  ✓ ${msg}`); }
 function warn(msg) { console.log(`  ⚠ ${msg}`); }
 function fail(msg) { console.log(`  ✗ ${msg}`); }
 
+// Pure JSON-version field bumper for the release pipeline. Reads `filePath`,
+// walks `keyPath` (e.g. `['version']` or `['plugins', 0, 'version']`), and
+// rewrites only when the new value differs. Returns `{ changed, prev }` so
+// callers can log "X → Y" with the captured-before-mutation value — pre-2.63.0
+// the plugin.json branch in syncVersions logged "Y → Y" because it read the
+// field after assignment.
+export function bumpJsonField(filePath, keyPath, newVal) {
+  const json = JSON.parse(readFileSync(filePath, 'utf8'));
+  let parent = json;
+  for (let i = 0; i < keyPath.length - 1; i++) parent = parent?.[keyPath[i]];
+  if (!parent) return { changed: false, prev: undefined };
+  const lastKey = keyPath[keyPath.length - 1];
+  const prev = parent[lastKey];
+  if (prev === newVal) return { changed: false, prev };
+  parent[lastKey] = newVal;
+  writeFileSync(filePath, JSON.stringify(json, null, 2) + '\n');
+  return { changed: true, prev };
+}
+
 // Doctor's final summary line. Pure function so the 4-way contract
 // (clean / warnings-only / issues / mixed) is unit-testable without spinning
 // up the full doctor pipeline. `issues` are ✗-level (action required);
@@ -1276,14 +1295,29 @@ async function doctor() {
     dwarn('Database: not found (will be created)');
   }
 
-  // Check for stale processes
+  // Check for stale processes — extends beyond legacy chroma/worker to
+  // catch MCP launchers / servers from cached old plugin versions. Auto-update
+  // bumps installed_plugins.json but cannot kill the MCP process spawned for
+  // an active session, so v2.60.0/v2.61.0 launchers commonly outlive their
+  // version (recurrent pattern, see #2580 for the gsd analogue). Filtering
+  // strategy: legacy chroma/worker = always stale; cache-path launchers = only
+  // when their version segment ≠ current package.json version; dev-install
+  // paths (no version segment) are never flagged.
   try {
-    const procs = execFileSync('pgrep', ['-af', 'chroma|claude-mem.*worker'], { encoding: 'utf8', timeout: 5000, stdio: 'pipe' }).trim();
-    // Filter out the pgrep process itself (matches its own pattern)
-    const real = procs.split('\n').filter(l => !l.includes('pgrep'));
-    if (real.length > 0) {
-      warn('Old processes running:\n    ' + real.join('\n    '));
+    const procs = execFileSync('pgrep', ['-af', 'chroma|claude-mem-lite.*(scripts/launch|server)\\.mjs|claude-mem.*worker'], { encoding: 'utf8', timeout: 5000, stdio: 'pipe' }).trim();
+    const lines = procs.split('\n').filter(l => l && !l.includes('pgrep'));
+    let currentVersion = '';
+    try { currentVersion = JSON.parse(readFileSync(join(PROJECT_DIR, 'package.json'), 'utf8')).version; } catch { /* fall through with empty version */ }
+    const stale = lines.filter(l => {
+      if (/chroma|claude-mem.*worker/.test(l)) return true;
+      const m = l.match(/claude-mem-lite\/(\d+\.\d+\.\d+)\/(scripts\/launch|server)\.mjs/);
+      return m && currentVersion && m[1] !== currentVersion;
+    });
+    if (stale.length > 0) {
+      warn(`Old processes running${currentVersion ? ` (current: v${currentVersion})` : ''}:\n    ` + stale.join('\n    '));
       issues++;
+    } else {
+      ok('No stale processes');
     }
   } catch {
     ok('No stale processes');
@@ -1314,19 +1348,31 @@ async function doctor() {
   }
 
   // Dev drift: in dev-mode installs, all SOURCE_FILES entries should be
-  // symlinks. A plain file means an earlier install (or manual cp) copied it,
-  // so edits in the repo won't propagate to INSTALL_DIR — hook runtime and
-  // test runtime silently diverge.
+  // symlinks. A plain file means an earlier install (or manual cp) copied it
+  // (edits in the repo won't propagate). A missing entry (neither symlink nor
+  // plain) means an earlier install never wrote the file — same divergence
+  // class. Per #8043: "is this file present ≠ is this install consistent" —
+  // missing is tracked separately by checkDevDrift but the caller MUST surface
+  // it to honour #8268's "gate the all-green string on every counter" rule.
   try {
     const { checkDevDrift } = await import('./lib/doctor-drift.mjs');
     const r = checkDevDrift(INSTALL_DIR, SOURCE_FILES);
-    if (r.drift) {
-      const names = r.details.join(', ');
-      const suffix = r.plainCount > r.details.length ? ` +${r.plainCount - r.details.length} more` : '';
-      warn(`Dev drift: ${r.plainCount} non-symlink file(s) in dev install: ${names}${suffix} (re-run: node ${join(PROJECT_DIR, 'install.mjs')} install --dev)`);
+    if (r.drift || (r.devMode && r.missingCount > 0)) {
+      const parts = [];
+      if (r.plainCount > 0) {
+        const names = r.plainFiles.slice(0, 5).join(', ');
+        const suffix = r.plainCount > 5 ? ` +${r.plainCount - 5} more` : '';
+        parts.push(`${r.plainCount} non-symlink: ${names}${suffix}`);
+      }
+      if (r.missingCount > 0) {
+        const names = r.missingFiles.join(', ');
+        const suffix = r.missingCount > r.missingFiles.length ? ` +${r.missingCount - r.missingFiles.length} more` : '';
+        parts.push(`${r.missingCount} missing: ${names}${suffix}`);
+      }
+      warn(`Dev drift: ${parts.join('; ')} (re-run: node ${join(PROJECT_DIR, 'install.mjs')} install --dev)`);
       issues++;
     } else if (r.devMode) {
-      ok(`Dev drift: clean (${r.symlinkCount} symlinks, 0 plain)`);
+      ok(`Dev drift: clean (${r.symlinkCount} symlinks, 0 plain, 0 missing)`);
     }
     // Prod (all plain) install: no message — dev-drift is a dev-only concern.
   } catch (e) {
@@ -1593,34 +1639,19 @@ function syncVersions() {
   const version = pkg.version;
   log(`package.json version: ${version}`);
 
-  // Sync plugin.json
   const pluginJsonPath = join(PROJECT_DIR, '.claude-plugin', 'plugin.json');
   if (existsSync(pluginJsonPath)) {
-    const pluginJson = JSON.parse(readFileSync(pluginJsonPath, 'utf8'));
-    if (pluginJson.version !== version) {
-      pluginJson.version = version;
-      writeFileSync(pluginJsonPath, JSON.stringify(pluginJson, null, 2) + '\n');
-      ok(`plugin.json: ${pluginJson.version} → ${version}`);
-    } else {
-      ok(`plugin.json: already ${version}`);
-    }
+    const r = bumpJsonField(pluginJsonPath, ['version'], version);
+    ok(r.changed ? `plugin.json: ${r.prev} → ${version}` : `plugin.json: already ${version}`);
   } else {
     warn('plugin.json not found');
   }
 
-  // Sync marketplace.json
   const marketJsonPath = join(PROJECT_DIR, '.claude-plugin', 'marketplace.json');
   if (existsSync(marketJsonPath)) {
-    const marketJson = JSON.parse(readFileSync(marketJsonPath, 'utf8'));
-    const plugin = marketJson.plugins?.[0];
-    if (plugin && plugin.version !== version) {
-      const prev = plugin.version;
-      plugin.version = version;
-      writeFileSync(marketJsonPath, JSON.stringify(marketJson, null, 2) + '\n');
-      ok(`marketplace.json: ${prev} → ${version}`);
-    } else if (plugin) {
-      ok(`marketplace.json: already ${version}`);
-    }
+    const r = bumpJsonField(marketJsonPath, ['plugins', 0, 'version'], version);
+    if (r.prev === undefined) warn('marketplace.json: plugins[0] not found');
+    else ok(r.changed ? `marketplace.json: ${r.prev} → ${version}` : `marketplace.json: already ${version}`);
   } else {
     warn('marketplace.json not found');
   }
@@ -1649,6 +1680,29 @@ function syncVersions() {
   console.log('');
 }
 
+// Regenerate package-lock.json via npm@10.9.2 to guarantee CI parity. The
+// drift this prevents: `npm install --package-lock-only` on npm@11+ silently
+// strips top-level `@emnapi/core` + `@emnapi/runtime` entries when those are
+// transitive deps of platform-optional bindings (e.g. `@oxc-parser/binding-*`
+// from knip), and CI's bundled npm@10 (Node 22 default in GitHub Actions)
+// then refuses `npm ci` with EUSAGE. Same recipe bit twice (#8271 / 2.58.2 /
+// 2.62.1) before this guard. The packageManager field in package.json
+// declares the same version for corepack-aware tooling. Network cost: ~5-30s
+// per release; release cadence makes this acceptable.
+function regenerateLockfile() {
+  console.log('\nclaude-mem-lite release — regenerate lockfile (npm@10.9.2)\n');
+  try {
+    execFileSync('npx', ['--yes', 'npm@10.9.2', 'install'], {
+      stdio: 'inherit',
+      cwd: PROJECT_DIR,
+    });
+    ok('lockfile regenerated');
+  } catch (e) {
+    fail('lockfile regen failed: ' + e.message);
+    throw e;
+  }
+}
+
 // ─── Main ───────────────────────────────────────────────────────────────────
 
 export async function main(argv = process.argv.slice(2)) {
@@ -1680,6 +1734,7 @@ export async function main(argv = process.argv.slice(2)) {
       break;
     case 'release':
       syncVersions();
+      if (!flags.has('--no-lock')) regenerateLockfile();
       break;
     default:
       if (IS_NPX) {
@@ -1699,7 +1754,7 @@ Usage:
   node install.mjs cleanup            Remove stale temp/staging files
   node install.mjs cleanup-hooks      Remove only claude-mem-lite hooks from settings.json
   node install.mjs self-update         Check for and install updates
-  node install.mjs release            Sync version to plugin.json + marketplace.json
+  node install.mjs release            Sync versions (plugin/marketplace/CLAUDE.md) + regen lockfile via npm@10.9.2 (use --no-lock to skip lock regen)
 
   npx claude-mem-lite                 Install via npx (one-liner)
 `);

package/lib/doctor-drift.mjs

@@ -41,6 +41,7 @@ export function checkDevDrift(installDir, sourceFiles) {
     plainCount: plainFiles.length,
     plainFiles,
     missingCount: missing.length,
+    missingFiles: missing.slice(0, 5),
     details: plainFiles.slice(0, 5),
   };
 }

package/lib/save-observation.mjs

@@ -1,5 +1,5 @@
 // Shared "save one observation" pipeline — used by both mem-cli.mjs::cmdSave
-// (CLI `mem save`) and server.mjs::mem_save (MCP tool).
+// (CLI `claude-mem-lite save`) and server.mjs::mem_save (MCP tool).
 //
 // Pre-extraction (v2.60.0) the same dedup → scrub → minhash → CJK-bigram →
 // transactional INSERT block lived inline in both call sites (~110 lines × 2,

package/mem-cli.mjs

@@ -34,7 +34,7 @@ function cmdSearch(db, args) {
   const { positional, flags } = parseArgs(args);
   const query = positional.join(' ');
   if (!query) {
-    fail('[mem] Usage: mem search <query> [--type TYPE] [--source SOURCE] [--limit N] [--project P] [--from DATE] [--to DATE] [--importance N] [--branch B] [--offset N] [--sort relevance|time|importance] [--include-noise]');
+    fail('[mem] Usage: claude-mem-lite search <query> [--type TYPE] [--source SOURCE] [--limit N] [--project P] [--from DATE] [--to DATE] [--importance N] [--branch B] [--offset N] [--sort relevance|time|importance] [--include-noise]');
     return;
   }
 
@@ -400,7 +400,7 @@ function cmdRecall(db, args) {
   const { positional, flags } = parseArgs(args);
   const file = positional.join(' ');
   if (!file) {
-    fail('[mem] Usage: mem recall <file> [--limit N] [--include-noise]');
+    fail('[mem] Usage: claude-mem-lite recall <file> [--limit N] [--include-noise]');
     return;
   }
 
@@ -447,6 +447,25 @@ function cmdRecall(db, args) {
 
 const OBS_FIELDS = ['id', 'type', 'title', 'subtitle', 'narrative', 'text', 'facts', 'concepts', 'lesson_learned', 'search_aliases', 'files_read', 'files_modified', 'project', 'created_at', 'memory_session_id', 'prompt_number', 'importance', 'related_ids', 'access_count', 'branch', 'superseded_at', 'superseded_by', 'last_accessed_at'];
 
+// Integer-typed time-epoch fields on the observations table that the `get`
+// command renders. Callers expect raw ms (audit) AND a relative-time hint
+// (human-scan), so formatObsFieldValue emits both. Other epoch fields like
+// `created_at_epoch` / `optimized_at` / `last_injected_at` aren't in
+// OBS_FIELDS so they don't surface via `get`.
+export const OBS_TIME_FIELDS = ['superseded_at', 'last_accessed_at'];
+
+// Pure formatter — null/undefined/non-time pass through; time fields on
+// integer values render as `<raw> (<relative>)` mirroring the convention
+// already used by `recent` / `timeline` / `recall`. Pre-2.63.0 the get
+// path printed bare ms (e.g. `last_accessed_at: 1778357330957`).
+export function formatObsFieldValue(field, val) {
+  if (val === null || val === undefined) return val;
+  if (OBS_TIME_FIELDS.includes(field) && typeof val === 'number') {
+    return `${val} (${relativeTime(val)})`;
+  }
+  return val;
+}
+
 function renderObsRows(db, ids, requestedFields) {
   const placeholders = ids.map(() => '?').join(',');
   try {
@@ -465,8 +484,9 @@ function renderObsRows(db, ids, requestedFields) {
       const val = r[f];
       if (val === null || val === undefined || val === '') continue;
       if (f === 'text' && r.narrative && typeof val === 'string' && val.startsWith(r.narrative)) continue;
+      const formatted = formatObsFieldValue(f, val);
       const maxLen = f === 'narrative' ? 1000 : f === 'lesson_learned' ? 500 : f === 'text' ? 500 : 200;
-      const display = typeof val === 'string' && val.length > maxLen ? val.slice(0, maxLen) + '…' : val;
+      const display = typeof formatted === 'string' && formatted.length > maxLen ? formatted.slice(0, maxLen) + '…' : formatted;
       lines.push(`${f}: ${display}`);
     }
     parts.push(lines.join('\n'));
@@ -510,7 +530,7 @@ function cmdGet(db, args) {
   const { positional, flags } = parseArgs(args);
   const idStr = positional.join(',');
   if (!idStr) {
-    fail('[mem] Usage: mem get <id1,id2,...> [--source obs|session|prompt] [--fields f1,f2,...]\n' +
+    fail('[mem] Usage: claude-mem-lite get <id1,id2,...> [--source obs|session|prompt] [--fields f1,f2,...]\n' +
          '        IDs accept prefix from search output: #123 (obs), P#123 (prompt), S#123 (session).');
     return;
   }
@@ -672,7 +692,12 @@ function cmdTimeline(db, args) {
   if ((!anchorId || isNaN(anchorId)) && queryStr) {
     const ftsQuery = sanitizeFtsQuery(queryStr);
     const found = findFtsAnchor(db, { ftsQuery, project: project ?? null });
-    if (found) anchorId = found;
+    if (found) {
+      anchorId = found.id;
+      if (found.relaxed && !anchorNote) {
+        anchorNote = `(query "${queryStr}" relaxed AND→OR — no row matched all terms)`;
+      }
+    }
   }
 
   // No anchor: show most recent observations (aligned with MCP mem_timeline fallback)
@@ -760,7 +785,7 @@ function cmdSave(db, args) {
   const { positional, flags } = parseArgs(args);
   const text = positional.join(' ');
   if (!text) {
-    fail('[mem] Usage: mem save "<text>" [--type T] [--title T] [--importance N] [--project P] [--files f1,f2] [--lesson T]');
+    fail('[mem] Usage: claude-mem-lite save "<text>" [--type T] [--title T] [--importance N] [--project P] [--files f1,f2] [--lesson T]');
     return;
   }
 
@@ -1112,7 +1137,7 @@ function cmdDelete(db, args) {
   const { positional, flags } = parseArgs(args);
   const idStr = positional.join(',');
   if (!idStr) {
-    fail('[mem] Usage: mem delete <id1,id2,...> [--confirm]');
+    fail('[mem] Usage: claude-mem-lite delete <id1,id2,...> [--confirm]');
     return;
   }
 
@@ -1122,7 +1147,7 @@ function cmdDelete(db, args) {
   const nonObs = tokens.filter(t => /^[PpSs]#?\d+$/.test(t));
   if (nonObs.length > 0) {
     fail(`[mem] delete only works on observations. Rejected: ${nonObs.join(', ')}. ` +
-         `Prompts and sessions are append-only — inspect with \`mem get P#N --source prompt\` / \`--source session\`.`);
+         `Prompts and sessions are append-only — inspect with \`claude-mem-lite get P#N --source prompt\` / \`--source session\`.`);
     return;
   }
   const ids = tokens.map(t => {
@@ -1190,7 +1215,7 @@ function cmdUpdate(db, args) {
   const parsed = raw ? parseIdToken(raw) : null;
   const id = parsed && parsed.source === null ? parsed.id : parseInt(raw, 10);
   if (!id || isNaN(id)) {
-    fail('[mem] Usage: mem update <id> [--title T] [--type T] [--importance N] [--lesson T] [--narrative T] [--concepts T]');
+    fail('[mem] Usage: claude-mem-lite update <id> [--title T] [--type T] [--importance N] [--lesson T] [--narrative T] [--concepts T]');
     return;
   }
 
@@ -1417,7 +1442,7 @@ function cmdMaintain(db, args) {
   const { positional, flags } = parseArgs(args);
   const action = positional[0];
   if (!action || !['scan', 'execute'].includes(action)) {
-    fail('[mem] Usage: mem maintain <scan|execute> [--ops cleanup,decay,boost,dedup,purge_stale,rebuild_vectors] [--project P] [--retain-days N] [--merge-ids keepId:removeId,...]');
+    fail('[mem] Usage: claude-mem-lite maintain <scan|execute> [--ops cleanup,decay,boost,dedup,purge_stale,rebuild_vectors] [--project P] [--retain-days N] [--merge-ids keepId:removeId,...]');
     return;
   }
 
@@ -1697,7 +1722,7 @@ function cmdRegistry(_memDb, args) {
   const { positional, flags } = parseArgs(args);
   const action = positional[0];
   if (!action || !['list', 'stats', 'search', 'import', 'remove', 'reindex'].includes(action)) {
-    fail('[mem] Usage: mem registry <list|stats|search|import|remove|reindex> [--type skill|agent] [--query Q] [--name N] [--resource-type T]');
+    fail('[mem] Usage: claude-mem-lite registry <list|stats|search|import|remove|reindex> [--type skill|agent] [--query Q] [--name N] [--resource-type T]');
     return;
   }
 
@@ -1713,7 +1738,7 @@ function cmdRegistry(_memDb, args) {
   try {
     if (action === 'search') {
       const query = flags.query || positional.slice(1).join(' ');
-      if (!query) { fail('[mem] Usage: mem registry search <query> [--type skill|agent] [--category C] [--quality Q]'); return; }
+      if (!query) { fail('[mem] Usage: claude-mem-lite registry search <query> [--type skill|agent] [--category C] [--quality Q]'); return; }
       let results = searchResources(rdb, query, {
         type: flags.type || undefined,
         limit: (flags.category || flags.quality) ? 20 : 10,
@@ -1803,7 +1828,7 @@ function cmdRegistry(_memDb, args) {
     if (action === 'import') {
       const name = flags.name;
       const resourceType = flags['resource-type'];
-      if (!name || !resourceType) { fail('[mem] Usage: mem registry import --name N --resource-type skill|agent [--invocation-name I] [--capability-summary S]'); return; }
+      if (!name || !resourceType) { fail('[mem] Usage: claude-mem-lite registry import --name N --resource-type skill|agent [--invocation-name I] [--capability-summary S]'); return; }
       const fields = { name, type: resourceType, status: 'active', source: flags.source || 'user' };
       for (const f of ['repo-url', 'local-path', 'invocation-name', 'intent-tags', 'domain-tags', 'trigger-patterns', 'capability-summary', 'keywords', 'tech-stack', 'use-cases']) {
         const camel = f.replace(/-([a-z])/g, (_, c) => '_' + c);
@@ -1824,7 +1849,7 @@ function cmdRegistry(_memDb, args) {
     if (action === 'remove') {
       const name = flags.name;
       const resourceType = flags['resource-type'];
-      if (!name || !resourceType) { fail('[mem] Usage: mem registry remove --name N --resource-type skill|agent'); return; }
+      if (!name || !resourceType) { fail('[mem] Usage: claude-mem-lite registry remove --name N --resource-type skill|agent'); return; }
       const result = rdb.prepare('DELETE FROM resources WHERE type = ? AND name = ?').run(resourceType, name);
       out(result.changes > 0 ? `[mem] Removed: ${resourceType}:${name}` : '[mem] Not found.');
       return;

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.62.1",
+  "version": "2.64.0",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
+  "packageManager": "npm@10.9.2",
   "engines": {
     "node": ">=20"
   },

package/search-engine.mjs

@@ -152,7 +152,7 @@ function expandObsByPRF(db, ctx, now, primaryCount, existingIds, results, includ
  *   1. FTS5 MATCH with the sanitized query (AND-by-default), recency-weighted
  *   2. If AND returns 0 → relaxFtsQueryToOr fallback (mirrors searchObservationsHybrid)
  *
- * Returns the matched observation id, or null. Always skips compressed rows.
+ * Always skips compressed rows.
  *
  * @param {Database} db
  * @param {object} opts
@@ -160,7 +160,8 @@ function expandObsByPRF(db, ctx, now, primaryCount, existingIds, results, includ
  * @param {string|null} [opts.project] restrict to this project (boost-by-membership; null = no filter)
  * @param {number} [opts.nowT]         Date.now() override (for deterministic tests)
  * @param {number} [opts.halfLifeMs]   recency half-life (default DEFAULT_DECAY_HALF_LIFE_MS)
- * @returns {number|null}
+ * @returns {{id:number, relaxed:boolean}|null}  `relaxed:true` when AND returned 0 and OR rescued —
+ *   callers should surface a "(relaxed AND→OR)" hint to mirror search transparency.
  */
 export function findFtsAnchor(db, { ftsQuery, project = null, nowT = null, halfLifeMs = DEFAULT_DECAY_HALF_LIFE_MS } = {}) {
   if (!ftsQuery) return null;
@@ -178,13 +179,13 @@ export function findFtsAnchor(db, { ftsQuery, project = null, nowT = null, halfL
   const stmt = db.prepare(sql);
   try {
     const m = stmt.get(ftsQuery, project, project, now);
-    if (m) return m.id;
+    if (m) return { id: m.id, relaxed: false };
   } catch (e) { debugCatch(e, 'findFtsAnchor-and'); }
   const orQuery = relaxFtsQueryToOr(ftsQuery);
   if (orQuery && orQuery !== ftsQuery) {
     try {
       const m = stmt.get(orQuery, project, project, now);
-      if (m) return m.id;
+      if (m) return { id: m.id, relaxed: true };
     } catch (e) { debugCatch(e, 'findFtsAnchor-or'); }
   }
   return null;

package/server.mjs

@@ -614,11 +614,18 @@ server.registerTool(
 
     // Auto-find anchor via FTS (with recency decay). Routes through shared
     // findFtsAnchor so CLI `timeline --query` and MCP mem_timeline use
-    // identical AND→OR fallback semantics (paired-path per #8217).
+    // identical AND→OR fallback semantics (paired-path per #8217). When the
+    // OR fallback fired, surface a hint so the caller knows the match was
+    // not an exact AND coverage of the query — mirrors search transparency.
     if (!anchorId && args.query) {
       const ftsQuery = sanitizeFtsQuery(args.query);
       const found = findFtsAnchor(db, { ftsQuery, project: args.project ?? null });
-      if (found) anchorId = found;
+      if (found) {
+        anchorId = found.id;
+        if (found.relaxed && !anchorNote) {
+          anchorNote = `(query "${args.query}" relaxed AND→OR — no row matched all terms)`;
+        }
+      }
     }
 
     // No anchor: return most recent