claude-mem-lite 2.61.0 → 2.63.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.61.0",
+      "version": "2.63.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.61.0",
+  "version": "2.63.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/hook-shared.mjs

@@ -4,7 +4,7 @@
 import { execFileSync, spawn } from 'child_process';
 import { randomUUID } from 'crypto';
 import { join } from 'path';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, readdirSync, statSync, unlinkSync } from 'fs';
 import { inferProject, debugCatch } from './utils.mjs';
 import { ensureDb, DB_DIR } from './schema.mjs';
 import { getClaudePath as getClaudePathShared, resolveModel as resolveModelShared, flattenForCLI as _flattenForCLI } from './haiku-client.mjs';
@@ -62,6 +62,37 @@ export const HANDOFF_ANCHOR_MAX_AGE = 72 * 3600000;             // 72h cap on gi
 export const HANDOFF_MATCH_THRESHOLD = 3;                       // min weighted score
 export const CONTINUE_KEYWORDS = /继续|接着|上次|之前的|前面的|刚才|\bcontinue\b|\bresume\b|\bwhere[\s-]+we[\s-]+left\b|\bpick[\s-]+up\b|\bcarry[\s-]+on\b/i;
 
+// Orphan-sweep threshold for `ep-flush-*` / `pending-*` runtime artifacts.
+// handleLLMEpisode's worst-case round-trip is ~60s (delay + LLM call + DB
+// write); 1h leaves a wide safety margin against deleting an in-flight file.
+// Older orphans are crashed workers or pre-shutdown buffers that no live
+// caller will ever pick up, so sweeping them on SessionStart is safe.
+export const ORPHAN_EPISODE_AGE_MS = 60 * 60 * 1000;
+
+// Sweep stale `ep-flush-*` and `pending-*` files in `runtimeDir` whose mtime
+// is older than `ageMs` (default 1h). Returns the number of files removed.
+// fs-only — no DB / no network. Used by handleSessionStart auto-maintain to
+// prevent the doctor "Stale temp files" warning from accumulating across
+// crashes; equivalent to the manual path in `node install.mjs cleanup` but
+// age-gated so concurrent in-flight workers are never raced.
+export function sweepOrphanEpisodeFiles(runtimeDir, { ageMs = ORPHAN_EPISODE_AGE_MS, now = Date.now() } = {}) {
+  let entries;
+  try { entries = readdirSync(runtimeDir); } catch { return 0; }
+  const cutoff = now - ageMs;
+  let count = 0;
+  for (const f of entries) {
+    if (!(f.startsWith('ep-flush-') || f.startsWith('pending-'))) continue;
+    const full = join(runtimeDir, f);
+    try {
+      if (statSync(full).mtimeMs < cutoff) {
+        unlinkSync(full);
+        count++;
+      }
+    } catch { /* concurrent unlink / permission — ignore */ }
+  }
+  return count;
+}
+
 // Ensure runtime directory exists
 try { if (!existsSync(RUNTIME_DIR)) mkdirSync(RUNTIME_DIR, { recursive: true }); } catch {}
 

package/hook.mjs

@@ -40,7 +40,7 @@ import {
   RUNTIME_DIR, EPISODE_BUFFER_SIZE, EPISODE_TIME_GAP_MS,
   SESSION_EXPIRY_MS, STALE_SESSION_MS, STALE_LOCK_MS,
   sessionFile, getSessionId, createSessionId, openDb,
-  spawnBackground,
+  spawnBackground, sweepOrphanEpisodeFiles,
 } from './hook-shared.mjs';
 import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObservation } from './hook-llm.mjs';
 import { extractCitationsFromTranscript, bumpCitationAccess, computeCiteRecall } from './lib/citation-tracker.mjs';
@@ -885,6 +885,17 @@ async function handleSessionStart() {
           }
         }
 
+        // Orphan sweep: remove `ep-flush-*` / `pending-*` runtime files older
+        // than 1h. handleLLMEpisode normally unlinks its own tmpFile on every
+        // exit path, but a crashed worker (OOM, host reboot, kill -9) leaves
+        // the file behind, and the doctor "Stale temp files" warning then
+        // accumulates indefinitely. fs-only; runs inside the 24h gate so it
+        // shares cadence with the rest of auto-maintain.
+        try {
+          const swept = sweepOrphanEpisodeFiles(RUNTIME_DIR);
+          if (swept > 0) debugLog('DEBUG', 'auto-maintain', `swept ${swept} orphan ep-flush/pending file(s)`);
+        } catch (e) { debugCatch(e, 'auto-maintain-orphan-sweep'); }
+
         // Mark maintenance as done (24h gate) — even though compression runs in background
         writeFileSync(maintainFile, JSON.stringify({ epoch: Date.now() }));
         // Weekly summary grouping runs in background to avoid blocking SessionStart

package/install.mjs

@@ -280,6 +280,38 @@ 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);
+// `warnings` are ⚠-level (informational, "All checks passed!" must NOT lie
+// about them).
+export function buildDoctorSummary(issues, warnings) {
+  const wPlural = warnings === 1 ? '' : 's';
+  if (issues === 0 && warnings === 0) return 'All checks passed!';
+  if (issues === 0) return `All critical checks passed (${warnings} warning${wPlural}).`;
+  const warnSuffix = warnings > 0 ? ` (+${warnings} warning${wPlural})` : '';
+  return `${issues} issue(s) found.${warnSuffix}`;
+}
+
 // Dev installs symlink server.mjs → the project's source file. Used to suppress
 // misleading "first run" messages since hook-update.mjs skips state-writes in
 // this mode (see hook-update.mjs isDevMode).
@@ -1152,6 +1184,13 @@ async function status() {
 async function doctor() {
   console.log('\nclaude-mem-lite doctor\n');
   let issues = 0;
+  let warnings = 0;
+  // Doctor-local ⚠ helper: visually identical to the file-level `warn`, but
+  // bumps `warnings` so the summary line can distinguish "fully green" from
+  // "warnings present". Used for informational ⚠ checks; the two ⚠ paths
+  // that ALSO bump `issues` (stale procs, dev drift) keep using the file-level
+  // `warn` directly to avoid double-counting.
+  const dwarn = (msg) => { warnings++; console.log(`  ⚠ ${msg}`); };
 
   // Node version
   const nodeVer = process.version;
@@ -1209,7 +1248,7 @@ async function doctor() {
   } else if (hasHooks) {
     ok('Plugin lifecycle: hooks active');
   } else {
-    warn('Plugin lifecycle: hooks not configured');
+    dwarn('Plugin lifecycle: hooks not configured');
   }
 
   // Database
@@ -1232,7 +1271,7 @@ async function doctor() {
             if (healthy) {
               ok('FTS5 integrity: all indexes healthy');
             } else {
-              warn('FTS5 integrity issues detected:');
+              dwarn('FTS5 integrity issues detected:');
               for (const d of details) log(`    ${d}`);
               log('  Attempting FTS5 rebuild...');
               const { rebuilt, errors } = rebuildFTS(rwDb);
@@ -1243,17 +1282,17 @@ async function doctor() {
             rwDb.close();
           }
         } catch (e) {
-          warn('FTS5 integrity check failed: ' + e.message);
+          dwarn('FTS5 integrity check failed: ' + e.message);
         }
       } else {
-        warn('FTS5 index: missing (will be created on server start)');
+        dwarn('FTS5 index: missing (will be created on server start)');
       }
     } catch (e) {
       fail('Database: ' + e.message);
       issues++;
     }
   } else {
-    warn('Database: not found (will be created)');
+    dwarn('Database: not found (will be created)');
   }
 
   // Check for stale processes
@@ -1287,10 +1326,10 @@ async function doctor() {
       // short-circuits before writing state (see hook-update.mjs isDevMode).
       ok('Update state: skipped (dev mode — symlinked install)');
     } else {
-      warn('Update state: no state file (first run?)');
+      dwarn('Update state: no state file (first run?)');
     }
   } catch {
-    warn('Update state: failed to read');
+    dwarn('Update state: failed to read');
   }
 
   // Dev drift: in dev-mode installs, all SOURCE_FILES entries should be
@@ -1310,7 +1349,7 @@ async function doctor() {
     }
     // Prod (all plain) install: no message — dev-drift is a dev-only concern.
   } catch (e) {
-    warn('Dev drift: check failed — ' + e.message);
+    dwarn('Dev drift: check failed — ' + e.message);
   }
 
   // Stale temp files
@@ -1329,12 +1368,12 @@ async function doctor() {
       }
     }
     if (staleCount > 0) {
-      warn(`Stale temp files: ${staleCount} found (run: node install.mjs cleanup)`);
+      dwarn(`Stale temp files: ${staleCount} found (run: node install.mjs cleanup)`);
     } else {
       ok('Stale temp files: none');
     }
   } catch {
-    warn('Stale temp files: check failed');
+    dwarn('Stale temp files: check failed');
   }
 
   // DB stats
@@ -1350,7 +1389,7 @@ async function doctor() {
       db.close();
       ok(`DB stats: ${sizeMB}MB, ${obsCount} observations, ${sessCount} sessions`);
     } catch (e) {
-      warn('DB stats: ' + e.message);
+      dwarn('DB stats: ' + e.message);
     }
   }
 
@@ -1364,14 +1403,14 @@ async function doctor() {
         sizeStr = execFileSync('du', ['-sh', pluginCacheBase], { encoding: 'utf8', timeout: 5000 }).trim().split('\t')[0];
       } catch { sizeStr = '?'; }
       if (versions.length > 3) {
-        warn(`Plugin cache: ${versions.length} versions (${sizeStr}) — run setup.sh or update to auto-prune to 3`);
+        dwarn(`Plugin cache: ${versions.length} versions (${sizeStr}) — run setup.sh or update to auto-prune to 3`);
       } else {
         ok(`Plugin cache: ${versions.length} version(s) (${sizeStr})`);
       }
     } catch {}
   }
 
-  console.log(`\n  ${issues === 0 ? 'All checks passed!' : `${issues} issue(s) found.`}\n`);
+  console.log(`\n  ${buildDoctorSummary(issues, warnings)}\n`);
 }
 
 // ─── Settings helpers ───────────────────────────────────────────────────────
@@ -1573,34 +1612,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');
   }
@@ -1629,6 +1653,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)) {
@@ -1660,6 +1707,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) {
@@ -1679,7 +1727,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/mem-cli.mjs

@@ -4,14 +4,14 @@
 
 import { homedir } from 'os';
 import { ensureDb, DB_PATH, REGISTRY_DB_PATH } from './schema.mjs';
-import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, jaccardSimilarity, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, isoWeekKey, COMPRESSED_PENDING_PURGE, OBS_BM25, SESS_BM25, DEFAULT_DECAY_HALF_LIFE_MS, notLowSignalTitleClause } from './utils.mjs';
+import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, jaccardSimilarity, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, isoWeekKey, COMPRESSED_PENDING_PURGE, SESS_BM25, DEFAULT_DECAY_HALF_LIFE_MS, notLowSignalTitleClause } from './utils.mjs';
 import { cjkPrecisionOk } from './nlp.mjs';
 import { extractCjkLikePatterns } from './nlp.mjs';
 import { resolveProject } from './project-utils.mjs';
 import { computeTier, TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
 import { getVocabulary, computeVector, rebuildVocabulary, _resetVocabCache } from './tfidf.mjs';
 import { autoBoostIfNeeded, reRankWithContext, markSuperseded } from './server-internals.mjs';
-import { searchObservationsHybrid } from './search-engine.mjs';
+import { searchObservationsHybrid, findFtsAnchor } from './search-engine.mjs';
 import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { optimizePreview, optimizeRun } from './hook-optimize.mjs';
@@ -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'));
@@ -663,24 +683,20 @@ function cmdTimeline(db, args) {
     }
   }
 
-  // Support query-based anchor: `timeline --query "search terms"` or positional
-  // Uses recency-weighted BM25 + project filter (aligned with MCP mem_timeline)
+  // Support query-based anchor: `timeline --query "search terms"` or positional.
+  // Routes through shared findFtsAnchor (paired-path with MCP mem_timeline)
+  // so AND→OR fallback semantics match `search` — without this, queries like
+  // "ep-flush leak" miss rows whose title is "ep-flush ... leaked" that
+  // search would otherwise find via OR relaxation.
   const queryStr = flags.query || positional.join(' ');
   if ((!anchorId || isNaN(anchorId)) && queryStr) {
     const ftsQuery = sanitizeFtsQuery(queryStr);
-    if (ftsQuery) {
-      const nowT = Date.now();
-      const match = db.prepare(`
-        SELECT o.id FROM observations_fts
-        JOIN observations o ON observations_fts.rowid = o.id
-        WHERE observations_fts MATCH ?
-          AND (? IS NULL OR o.project = ?)
-          AND COALESCE(o.compressed_into, 0) = 0
-        ORDER BY ${OBS_BM25}
-          * (1.0 + EXP(-0.693 * (? - o.created_at_epoch) / ${DEFAULT_DECAY_HALF_LIFE_MS}.0))
-        LIMIT 1
-      `).get(ftsQuery, project ?? null, project ?? null, nowT);
-      if (match) anchorId = match.id;
+    const found = findFtsAnchor(db, { ftsQuery, project: project ?? null });
+    if (found) {
+      anchorId = found.id;
+      if (found.relaxed && !anchorNote) {
+        anchorNote = `(query "${queryStr}" relaxed AND→OR — no row matched all terms)`;
+      }
     }
   }
 

package/package.json

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

package/search-engine.mjs

@@ -7,6 +7,7 @@
 
 import {
   OBS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE,
+  DEFAULT_DECAY_HALF_LIFE_MS,
   notLowSignalTitleClause, LOW_SIGNAL_TITLE,
   relaxFtsQueryToOr, debugLog, debugCatch,
 } from './utils.mjs';
@@ -141,6 +142,55 @@ function expandObsByPRF(db, ctx, now, primaryCount, existingIds, results, includ
  *                         perSourceOffset, currentProject, limit, orFallbackFired }
  * @returns {Array} list of result objects (mutated ctx may set orFallbackFired)
  */
+/**
+ * Resolve `timeline --query "..."` / mem_timeline auto-anchor to a single
+ * observation id. Shared between mem-cli.mjs cmdTimeline and server.mjs
+ * mem_timeline so both surfaces use identical AND→OR fallback semantics
+ * (paired-path discipline per #8217).
+ *
+ * Pipeline:
+ *   1. FTS5 MATCH with the sanitized query (AND-by-default), recency-weighted
+ *   2. If AND returns 0 → relaxFtsQueryToOr fallback (mirrors searchObservationsHybrid)
+ *
+ * Always skips compressed rows.
+ *
+ * @param {Database} db
+ * @param {object} opts
+ * @param {string|null} opts.ftsQuery  pre-sanitized FTS5 query
+ * @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 {{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;
+  const now = nowT ?? Date.now();
+  const sql = `
+    SELECT o.id FROM observations_fts
+    JOIN observations o ON observations_fts.rowid = o.id
+    WHERE observations_fts MATCH ?
+      AND (? IS NULL OR o.project = ?)
+      AND COALESCE(o.compressed_into, 0) = 0
+    ORDER BY ${OBS_BM25}
+      * (1.0 + EXP(-0.693 * (? - o.created_at_epoch) / ${halfLifeMs}.0))
+    LIMIT 1
+  `;
+  const stmt = db.prepare(sql);
+  try {
+    const m = stmt.get(ftsQuery, project, project, now);
+    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 { id: m.id, relaxed: true };
+    } catch (e) { debugCatch(e, 'findFtsAnchor-or'); }
+  }
+  return null;
+}
+
 export function searchObservationsHybrid(db, ctx) {
   const { ftsQuery, args, epochFrom, epochTo, perSourceLimit, perSourceOffset, currentProject, limit } = ctx;
   const results = [];

package/server.mjs

@@ -5,12 +5,12 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { jaccardSimilarity, truncate, typeIcon, sanitizeFtsQuery, relaxFtsQueryToOr, inferProject, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, fmtDate, isoWeekKey, debugLog, debugCatch, COMPRESSED_PENDING_PURGE, OBS_BM25, SESS_BM25, DEFAULT_DECAY_HALF_LIFE_MS, isPathConfined, notLowSignalTitleClause } from './utils.mjs';
+import { jaccardSimilarity, truncate, typeIcon, sanitizeFtsQuery, relaxFtsQueryToOr, inferProject, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, fmtDate, isoWeekKey, debugLog, debugCatch, COMPRESSED_PENDING_PURGE, SESS_BM25, DEFAULT_DECAY_HALF_LIFE_MS, isPathConfined, notLowSignalTitleClause } from './utils.mjs';
 import { extractCjkLikePatterns, cjkPrecisionOk } from './nlp.mjs';
 import { resolveProject as _resolveProjectShared } from './project-utils.mjs';
 import { ensureDb, DB_PATH, REGISTRY_DB_PATH } from './schema.mjs';
 import { reRankWithContext, markSuperseded, autoBoostIfNeeded, runIdleCleanup, buildServerInstructions } from './server-internals.mjs';
-import { searchObservationsHybrid } from './search-engine.mjs';
+import { searchObservationsHybrid, findFtsAnchor } from './search-engine.mjs';
 import { effectiveQuiet } from './hook-shared.mjs';
 import { computeTier, TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
 import { memSearchSchema, memRecentSchema, memTimelineSchema, memGetSchema, memDeleteSchema, memSaveSchema, memStatsSchema, memCompressSchema, memMaintainSchema, memOptimizeSchema, memUpdateSchema, memExportSchema, memRecallSchema, memFtsCheckSchema, memRegistrySchema, memBrowseSchema, memUseSchema, tools as TOOL_DEFS } from './tool-schemas.mjs';
@@ -103,7 +103,7 @@ function resolveProject(name) { return _resolveProjectShared(db, name); }
 //   Importance:    0.5 + 0.5 × importance (range 0.5–2.0)
 //   Access bonus:  1 + 0.1 × ln(1 + access_count)
 
-// OBS_BM25, SESS_BM25, TYPE_DECAY_CASE imported from utils.mjs
+// SESS_BM25, TYPE_DECAY_CASE imported from utils.mjs
 const RECENCY_HALF_LIFE_MS = DEFAULT_DECAY_HALF_LIFE_MS;
 
 // ─── MCP Server ─────────────────────────────────────────────────────────────
@@ -612,23 +612,19 @@ server.registerTool(
       }
     }
 
-    // Auto-find anchor via FTS (with recency decay)
+    // 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). 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);
-      if (ftsQuery) {
-        const nowT = Date.now();
-        const row = db.prepare(`
-          SELECT o.id
-          FROM observations_fts
-          JOIN observations o ON observations_fts.rowid = o.id
-          WHERE observations_fts MATCH ?
-            AND (? IS NULL OR o.project = ?)
-            AND COALESCE(o.compressed_into, 0) = 0
-          ORDER BY ${OBS_BM25}
-            * (1.0 + EXP(-0.693 * (? - o.created_at_epoch) / ${RECENCY_HALF_LIFE_MS}.0))
-          LIMIT 1
-        `).get(ftsQuery, args.project ?? null, args.project ?? null, nowT);
-        if (row) anchorId = row.id;
+      const found = findFtsAnchor(db, { ftsQuery, project: args.project ?? null });
+      if (found) {
+        anchorId = found.id;
+        if (found.relaxed && !anchorNote) {
+          anchorNote = `(query "${args.query}" relaxed AND→OR — no row matched all terms)`;
+        }
       }
     }