claude-mem-lite 2.98.0 → 3.0.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.98.0",
+      "version": "3.0.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.98.0",
+  "version": "3.0.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/lib/file-intel.mjs

@@ -0,0 +1,160 @@
+// lib/file-intel.mjs — pure, zero-dependency builder for the PreToolUse:Read
+// "file intelligence" injection (feature ①). Before Claude reads a file, surface
+// its approximate token size + a one-line "what's in it" so the agent can decide
+// to read fully, read a slice, or grep instead.
+//
+// Imported by the hot standalone scripts/pre-tool-recall.js, so it MUST stay
+// dependency-free and cheap: one bounded file read + regex, no heavy imports.
+// (Lesson #8447: fast-path scripts can't pull in utils.mjs, which drags in
+// child_process/nlp/scoring-sql.) estimateContentTokens is therefore a hand-
+// mirror of utils.estimateTokens; tests/file-intel.test.mjs pins the two so a
+// change to the canonical estimator surfaces as a failing mirror test.
+
+import { statSync, openSync, readSync, closeSync } from 'fs';
+import { basename as pathBasename } from 'path';
+
+const SUMMARY_MAX = 80;
+const DEFAULT_MIN_TOKENS = 800;
+const DEFAULT_MAX_READ_BYTES = 24 * 1024;
+
+// Mirror of utils.estimateTokens (ASCII ~4 chars/token, CJK ~1.5). Kept local so
+// the standalone hook stays lean — see file header + the mirror test.
+export function estimateContentTokens(text) {
+  const s = text || '';
+  if (!s) return 1;
+  let cjkCount = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if ((c >= 0x4e00 && c <= 0x9fff) || (c >= 0x3400 && c <= 0x4dbf) ||
+        (c >= 0x3000 && c <= 0x303f) || (c >= 0xff00 && c <= 0xffef) ||
+        (c >= 0xac00 && c <= 0xd7af)) {
+      cjkCount++;
+    }
+  }
+  const asciiLen = s.length - cjkCount;
+  return Math.max(1, Math.ceil(asciiLen / 4) + Math.ceil(cjkCount / 1.5));
+}
+
+// 850 → "850", 6100 → "6.1k", 12000 → "12k".
+export function humanTokens(n) {
+  if (n < 1000) return String(n);
+  if (n < 10000) return (n / 1000).toFixed(1) + 'k';
+  return Math.round(n / 1000) + 'k';
+}
+
+function cap(s) {
+  const t = s.replace(/\s+/g, ' ').trim();
+  return t.length <= SUMMARY_MAX ? t : t.slice(0, SUMMARY_MAX - 1) + '…';
+}
+
+function isGenericComment(text) {
+  if (/^[-=*_#·]{3,}$/.test(text)) return true;
+  const l = text.toLowerCase();
+  return l.startsWith('eslint') || l.startsWith('prettier') || l.startsWith('tslint') ||
+    l.startsWith('stylelint') || l.startsWith('istanbul') || l.startsWith('c8 ') ||
+    l.startsWith('copyright') || l.startsWith('license') || l.startsWith('spdx') ||
+    l.startsWith('use strict') || l.startsWith('@') || l.startsWith('global ') ||
+    l.startsWith('generated') || l.startsWith('auto-generated') || l.startsWith('nolint');
+}
+
+// First meaningful header comment in the first 15 lines, skipping blanks,
+// shebangs, and boilerplate (eslint/license/etc). Stops at the first real code
+// line so we don't scan deep into the body.
+function extractHeaderComment(content) {
+  const lines = content.split('\n');
+  const limit = Math.min(lines.length, 15);
+  for (let i = 0; i < limit; i++) {
+    const t = lines[i].trim();
+    if (!t) continue;
+    if (t.startsWith('#!')) continue; // shebang
+    const m = t.match(/^(?:\/\/\/?|#|--|\/\*\*?|\*)\s*(.+)/);
+    if (m) {
+      const text = m[1].replace(/\*\/\s*$/, '').trim();
+      if (text.length > 4 && !isGenericComment(text)) return text;
+      continue;
+    }
+    break; // real code line — no header comment
+  }
+  return '';
+}
+
+function extractExports(content) {
+  const names = [];
+  const re = /export\s+(?:default\s+)?(?:async\s+)?(?:function\*?|class|const|let|var|interface|type|enum)\s+(\w+)/g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    if (!names.includes(m[1])) names.push(m[1]);
+  }
+  if (names.length === 0) return '';
+  const shown = names.slice(0, 5).join(', ');
+  return names.length > 5 ? `Exports ${shown} + ${names.length - 5} more` : `Exports ${shown}`;
+}
+
+// Best-effort one-line "what's in it". '' when nothing useful is found.
+export function extractFileSummary(content, filename) {
+  const src = content || '';
+  if (!src.trim()) return '';
+  const name = (filename || '').toLowerCase();
+  const dot = name.lastIndexOf('.');
+  const ext = dot >= 0 ? name.slice(dot) : '';
+
+  if (ext === '.md' || ext === '.mdx') {
+    const m = src.match(/^#{1,6}\s+(.+)$/m);
+    if (m) return cap(m[1]);
+  }
+
+  if (ext === '.json') {
+    try {
+      const obj = JSON.parse(src);
+      if (obj && typeof obj.description === 'string' && obj.description.trim()) return cap(obj.description);
+      if (obj && typeof obj.name === 'string' && obj.name.trim()) return cap(obj.name);
+    } catch { /* partial / invalid JSON — no summary */ }
+    return '';
+  }
+
+  const hdr = extractHeaderComment(src);
+  if (hdr) return cap(hdr);
+
+  if (['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(ext)) {
+    const exp = extractExports(src);
+    if (exp) return cap(exp);
+  }
+
+  return '';
+}
+
+export function formatFileIntelLine({ basename, tokens, summary }) {
+  const head = `[mem] 📄 ${basename} ~${humanTokens(tokens)} tok`;
+  return summary ? `${head} · ${summary}` : head;
+}
+
+// IO wrapper: returns the formatted intel line for filePath, or null when the
+// file is unreadable or below the token threshold. Never throws — it runs inside
+// a PreToolUse hook that must always exit 0.
+export function fileIntelFor(filePath, opts = {}) {
+  const minTokens = opts.minTokens ?? DEFAULT_MIN_TOKENS;
+  const maxReadBytes = opts.maxReadBytes ?? DEFAULT_MAX_READ_BYTES;
+
+  let size;
+  try {
+    const st = statSync(filePath);
+    if (!st.isFile()) return null;
+    size = st.size;
+  } catch { return null; }
+
+  try {
+    const fd = openSync(filePath, 'r');
+    try {
+      const buf = Buffer.allocUnsafe(Math.min(size, maxReadBytes));
+      const n = buf.length > 0 ? readSync(fd, buf, 0, buf.length, 0) : 0;
+      const sample = buf.subarray(0, n).toString('utf8');
+      // Files within the read window are estimated exactly; larger files estimate
+      // from byte size (≈4 ASCII bytes/token). The '~' already signals approximation
+      // and we never slurp a multi-MB file inside a hook.
+      const tokens = size <= maxReadBytes ? estimateContentTokens(sample) : Math.ceil(size / 4);
+      if (tokens < minTokens) return null;
+      const summary = extractFileSummary(sample, filePath);
+      return formatFileIntelLine({ basename: pathBasename(filePath), tokens, summary });
+    } finally { closeSync(fd); }
+  } catch { return null; }
+}

package/lib/reread-guard.mjs

@@ -0,0 +1,55 @@
+// lib/reread-guard.mjs — pure logic + one IO helper for feature ② (repeated-read
+// guard). When the agent does a full Read of a file it already read this session
+// and the file is unchanged, nudge it to reuse what it has instead of re-slurping.
+//
+// Imported by the hot standalone scripts/pre-tool-recall.js — stays light, reuses
+// the token estimator from ./file-intel.mjs (also pure). Never throws.
+//
+// False-positive guards (the bit OpenWolf's equivalent omits — its "unless
+// modified" lives only in instructions, not the hook):
+//   - full-vs-full only: paging with offset/limit never warns
+//   - mtime check: a file changed since the prior read never warns
+//   - token floor: re-reading a tiny file is cheap, not worth a nudge
+
+import { statSync, openSync, readSync, closeSync } from 'fs';
+import { estimateContentTokens, humanTokens } from './file-intel.mjs';
+
+const DEFAULT_MIN_TOKENS = 600;
+const DEFAULT_MAX_READ_BYTES = 24 * 1024;
+
+// IO: { mtimeMs, tokens } for an on-disk file, or null. Never throws.
+export function readFileMeta(filePath, maxReadBytes = DEFAULT_MAX_READ_BYTES) {
+  let st;
+  try {
+    st = statSync(filePath);
+    if (!st.isFile()) return null;
+  } catch { return null; }
+
+  const size = st.size;
+  if (size > maxReadBytes) {
+    return { mtimeMs: st.mtimeMs, tokens: Math.ceil(size / 4) };
+  }
+  try {
+    const fd = openSync(filePath, 'r');
+    try {
+      const buf = Buffer.allocUnsafe(size);
+      const n = size > 0 ? readSync(fd, buf, 0, size, 0) : 0;
+      return { mtimeMs: st.mtimeMs, tokens: estimateContentTokens(buf.subarray(0, n).toString('utf8')) };
+    } finally { closeSync(fd); }
+  } catch { return null; }
+}
+
+// Pure: should a repeat read warn? recorded = { mtimeMs, tokens, full }.
+export function shouldWarnReread(recorded, currentMtimeMs, isFullRead, minTokens = DEFAULT_MIN_TOKENS) {
+  if (!recorded || typeof recorded !== 'object') return false;
+  if (!recorded.full || !isFullRead) return false;      // only full-vs-full re-reads
+  if (!(recorded.tokens >= minTokens)) return false;     // big enough to matter
+  if (currentMtimeMs === null || currentMtimeMs === undefined) return false;
+  return currentMtimeMs <= recorded.mtimeMs;             // unchanged since last read
+}
+
+// Pure: the warning line (no framing — the hook prepends the shared framing line).
+export function buildRereadWarning(basename, tokens) {
+  return `[mem] 🔁 You already read ${basename} this session (~${humanTokens(tokens)} tok, unchanged) `
+    + `— reuse what you have instead of re-reading; pass offset/limit if you need a specific part.`;
+}

package/lib/search-core.mjs

@@ -0,0 +1,200 @@
+// Shared cross-source search core (query build / source queries / scoring
+// normalization / sort / pagination math).
+//
+// Single source of truth for cmdSearch (CLI) and mem_search (MCP). The
+// observation path already converged in search-engine.mjs (#8198/#8212); the
+// sessions/prompts FTS queries, CJK precision + LIKE fallback, cross-source
+// score normalization, user-sort, over-fetch sizing, and date-bound parsing
+// were still copy-pasted and synced by "paired-path" comments — the drift
+// class compress-core (ARCH-1), recall-core, and timeline-core were extracted
+// to close. Call sites keep what legitimately differs: flag/schema parsing,
+// result-row dialect (CLI `_source`+raw columns vs MCP `source`+mapped
+// fields), error-message wording, and output rendering.
+//
+// Behavioral asymmetries that are PRESERVED, not converged (documented so a
+// future "fix" is a deliberate contract change, not an accident):
+//   • CLI forces source=observations when --type/--tier/--importance/--branch
+//     is set; MCP only forces it for obs_type.
+//   • CLI warns on inverted --from/--to ranges; MCP does not.
+//   • CLI wraps session/prompt FTS in try/catch for pre-FTS legacy DBs.
+
+import { sanitizeFtsQuery, relaxFtsQueryToOr, SESS_BM25, DEFAULT_DECAY_HALF_LIFE_MS } from '../utils.mjs';
+import { cjkPrecisionOk, extractCjkLikePatterns } from '../nlp.mjs';
+import { computeTier } from '../tier.mjs';
+
+/** Sanitize a user query to FTS5 syntax; optionally force OR semantics. */
+export function buildSearchFtsQuery(query, { or = false } = {}) {
+  let ftsQuery = sanitizeFtsQuery(query);
+  if (ftsQuery && or) ftsQuery = relaxFtsQueryToOr(ftsQuery) || ftsQuery;
+  return ftsQuery;
+}
+
+/**
+ * Parse from/to date bounds to epoch ms. Date-only `to` (YYYY-MM-DD) extends
+ * to end-of-day so "to 2026-06-12" includes that day's rows.
+ * @returns {{ ok: true, epochFrom: number|null, epochTo: number|null }
+ *         | { ok: false, bad: 'from'|'to', value: string }}
+ */
+export function parseDateBounds(fromRaw, toRaw) {
+  const epochFrom = fromRaw ? new Date(fromRaw).getTime() : null;
+  let epochTo = toRaw ? new Date(toRaw).getTime() : null;
+  if (epochTo !== null && toRaw && /^\d{4}-\d{2}-\d{2}$/.test(toRaw)) {
+    epochTo += 86400000 - 1; // extend to 23:59:59.999
+  }
+  if (epochFrom !== null && isNaN(epochFrom)) return { ok: false, bad: 'from', value: fromRaw };
+  if (epochTo !== null && isNaN(epochTo)) return { ok: false, bad: 'to', value: toRaw };
+  return { ok: true, epochFrom, epochTo };
+}
+
+/**
+ * Over-fetch window: every source fetches from offset 0 and the caller slices
+ * [offset, offset+limit) exactly ONCE post-merge. Pushing OFFSET into the
+ * per-source SQL double-applied it and gapped/overlapped pages, because the
+ * obs hybrid path (AND→OR fallback / vector / concept stages) re-adds rows the
+ * SQL OFFSET already skipped (#8217/#8638).
+ */
+export function computePerSourceWindow(limit, offset) {
+  return { perSourceLimit: Math.max(limit * 3, offset + limit + 10), perSourceOffset: 0 };
+}
+
+/** obs-side total query: when the AND→OR fallback fired, count the OR set. */
+export function effectiveObsFtsQuery(ftsQuery, orFallbackFired) {
+  return orFallbackFired ? (relaxFtsQueryToOr(ftsQuery) || ftsQuery) : ftsQuery;
+}
+
+/**
+ * Session FTS search with recency decay + same-project boost. Returns raw SQL
+ * rows: { id, request, completed, project, created_at, created_at_epoch, score }.
+ * `projectBoost` is the inferred current project, only applied when the caller
+ * did NOT filter by project explicitly (pass null then).
+ */
+export function searchSessionsFts(db, { ftsQuery, project = null, projectBoost = null, epochFrom = null, epochTo = null, perSourceLimit, perSourceOffset = 0 }) {
+  const wheres = ['session_summaries_fts MATCH ?'];
+  const params = [Date.now(), projectBoost, projectBoost, ftsQuery];
+  if (project) { wheres.push('s.project = ?'); params.push(project); }
+  if (epochFrom !== null) { wheres.push('s.created_at_epoch >= ?'); params.push(epochFrom); }
+  if (epochTo !== null) { wheres.push('s.created_at_epoch <= ?'); params.push(epochTo); }
+  params.push(perSourceLimit, perSourceOffset);
+  return db.prepare(`
+    SELECT s.id, s.request, s.completed, s.project, s.created_at, s.created_at_epoch,
+           ${SESS_BM25}
+             * (1.0 + EXP(-0.693 * (? - s.created_at_epoch) / ${DEFAULT_DECAY_HALF_LIFE_MS}.0))
+             * (CASE WHEN ? IS NOT NULL AND s.project = ? THEN 2.0 ELSE 1.0 END) as score
+    FROM session_summaries_fts
+    JOIN session_summaries s ON session_summaries_fts.rowid = s.id
+    WHERE ${wheres.join(' AND ')}
+    ORDER BY score
+    LIMIT ? OFFSET ?
+  `).all(...params);
+}
+
+/**
+ * Prompt FTS search with CJK precision gate + CJK LIKE fallback. Returns raw
+ * SQL rows: { id, prompt_text, content_session_id, created_at,
+ * created_at_epoch, score } (fallback rows carry score = 0).
+ *
+ * The precision gate applies to BOTH paths: unicode61 degrades CJK bigram
+ * queries to single-char AND, and the LIKE fallback is an OR'd substring scan
+ * — without the gate each re-admits the common-char noise band the other
+ * dropped (that asymmetry was the actual leak source: FTS returned 0,
+ * fallback filled 20).
+ */
+export function searchPromptsFts(db, { query, ftsQuery, project = null, epochFrom = null, epochTo = null, perSourceLimit, perSourceOffset = 0 }) {
+  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 !== null) { wheres.push('p.created_at_epoch >= ?'); params.push(epochFrom); }
+  if (epochTo !== null) { wheres.push('p.created_at_epoch <= ?'); params.push(epochTo); }
+  params.push(perSourceLimit, perSourceOffset);
+  const rows = db.prepare(`
+    SELECT p.id, p.prompt_text, p.content_session_id, p.created_at, p.created_at_epoch,
+           bm25(user_prompts_fts, 1) as score
+    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 ')}
+    ORDER BY score
+    LIMIT ? OFFSET ?
+  `).all(...params);
+  const kept = query ? rows.filter((r) => cjkPrecisionOk(query, r.prompt_text)) : rows;
+  if (kept.length > 0 || !query) return kept;
+
+  // CJK LIKE fallback: FTS5 unicode61 can't tokenize CJK substrings in prompts
+  const cjkPatterns = extractCjkLikePatterns(query);
+  if (cjkPatterns.length === 0) return kept;
+  const likeConds = cjkPatterns.map(() => 'p.prompt_text LIKE ?');
+  const likeParams = cjkPatterns.map((p) => `%${p}%`);
+  if (project) likeParams.push(project);
+  if (epochFrom !== null) likeParams.push(epochFrom);
+  if (epochTo !== null) likeParams.push(epochTo);
+  likeParams.push(perSourceLimit, perSourceOffset);
+  const fallbackRows = db.prepare(`
+    SELECT p.id, p.prompt_text, p.content_session_id, p.created_at, p.created_at_epoch
+    FROM user_prompts p
+    JOIN sdk_sessions s ON p.content_session_id = s.content_session_id
+    WHERE (${likeConds.join(' OR ')})
+      AND p.prompt_text NOT LIKE '<task-notification>%'
+      ${project ? 'AND s.project = ?' : ''}
+      ${epochFrom !== null ? 'AND p.created_at_epoch >= ?' : ''}
+      ${epochTo !== null ? 'AND p.created_at_epoch <= ?' : ''}
+    ORDER BY p.created_at_epoch DESC
+    LIMIT ? OFFSET ?
+  `).all(...likeParams);
+  return fallbackRows
+    .filter((r) => cjkPrecisionOk(query, r.prompt_text))
+    .map((r) => ({ ...r, score: 0 }));
+}
+
+/**
+ * Normalize each source's BM25 scores to [-1, 0] before cross-source merge.
+ * Prevents observations (BM25 can reach -40) from systematically outranking
+ * sessions (-6) and prompts (-1) regardless of relevance. Sources with a
+ * single scored row are skipped — normalizing would inflate a weak match to
+ * -1.0. Mutates `results` in place; callers re-sort afterwards.
+ */
+export function normalizeCrossSourceScores(results, sourceKey) {
+  for (const src of ['obs', 'session', 'prompt']) {
+    const srcResults = results.filter((r) => r[sourceKey] === src && r.score !== null && r.score !== undefined);
+    if (srcResults.length < 2) continue;
+    const maxAbs = Math.max(...srcResults.map((r) => Math.abs(r.score)));
+    if (maxAbs > 0) {
+      for (const r of srcResults) r.score = r.score / maxAbs;
+    }
+  }
+}
+
+/**
+ * Apply the user-requested sort AFTER relevance scoring. 'relevance' is a
+ * no-op — BM25 score order is already in place from the merge sort.
+ */
+export function applyUserSort(results, sort) {
+  if (sort === 'time') {
+    results.sort((a, b) => (b.created_at_epoch ?? 0) - (a.created_at_epoch ?? 0));
+  } else if (sort === 'importance') {
+    results.sort((a, b) => (b.importance ?? 1) - (a.importance ?? 1) || (b.created_at_epoch ?? 0) - (a.created_at_epoch ?? 0));
+  }
+}
+
+/**
+ * Tier post-filter: batch-lookup full obs rows and keep only those whose
+ * computed tier matches. Non-obs rows pass through untouched. Classification
+ * uses the explicitly-requested project when given — CWD-inferred fallback
+ * breaks computeTier's "obs.project === currentProject" rules on
+ * cross-project searches and silently drops valid rows.
+ * @returns filtered array (input is not mutated)
+ */
+export function applyTierFilter(db, results, { tier, sourceKey, currentProject }) {
+  const obsIds = results.filter((r) => r[sourceKey] === 'obs').map((r) => r.id);
+  if (obsIds.length === 0) return results;
+  const placeholders = obsIds.map(() => '?').join(',');
+  const fullRows = db.prepare(
+    `SELECT id, compressed_into, superseded_at, memory_session_id, project, importance, last_accessed_at, created_at_epoch, type FROM observations WHERE id IN (${placeholders})`
+  ).all(...obsIds);
+  const rowMap = new Map(fullRows.map((r) => [r.id, r]));
+  const tierCtx = { now: Date.now(), currentProject, currentSessionId: '' };
+  return results.filter((r) => {
+    if (r[sourceKey] !== 'obs') return true;
+    const full = rowMap.get(r.id);
+    return full && computeTier(full, tierCtx) === tier;
+  });
+}

package/lib/timeline-core.mjs

@@ -0,0 +1,195 @@
+// Shared "timeline around an anchor" core.
+//
+// Single source of truth for cmdTimeline (CLI) and mem_timeline (MCP). Pre-
+// extraction the anchor-resolution ladder (P#/S# token → nearest obs,
+// bare int → obs with compressed_into re-anchor → prompt/session fallback),
+// the query-anchor wrapper around findFtsAnchor, and the before/after window
+// queries were copy-pasted across both and kept in sync by hand-written
+// "aligned with" comments — the same drift vector compress-core (ARCH-1) and
+// recall-core were extracted to close. Call sites keep what legitimately
+// differs: argument parsing, output rendering (CLI relativeTime text / JSON vs
+// MCP fmtDate lines), and error-message dialect (formatAnchorError owns both
+// dialects so the wording cannot drift independently).
+
+import { parseIdToken } from './id-routing.mjs';
+import { findFtsAnchor } from '../search-engine.mjs';
+import { sanitizeFtsQuery } from '../utils.mjs';
+
+const TIMELINE_COLS = 'id, type, title, subtitle, project, created_at, created_at_epoch';
+
+/** Nearest non-compressed observation to `epoch` (optionally project-scoped). */
+function nearestObservation(db, epoch, project) {
+  return db.prepare(`
+    SELECT id FROM observations
+    WHERE COALESCE(compressed_into, 0) = 0 ${project ? 'AND project = ?' : ''}
+    ORDER BY ABS(created_at_epoch - ?) ASC LIMIT 1
+  `).get(...(project ? [project, epoch] : [epoch]));
+}
+
+/**
+ * Resolve a raw anchor token (number, "N", "#N", "P#N", "S#N") to an
+ * observation id. Prompt/session anchors resolve to the nearest-in-time
+ * observation so before/after semantics still apply; compressed observations
+ * re-anchor to their live parent (negative sentinels error — no canonical
+ * parent); bare ints that miss observations fall back to prompt, then session.
+ *
+ * @returns {{ ok: true, anchorId: number, anchorNote: string|null }
+ *         | { ok: false, error: object }}  — render error via formatAnchorError
+ */
+export function resolveAnchorToken(db, rawAnchor, { project = null } = {}) {
+  const parsed = parseIdToken(rawAnchor);
+  if (!parsed) {
+    return { ok: false, error: { code: 'invalid-token', raw: rawAnchor } };
+  }
+
+  if (parsed.source === 'prompt' || parsed.source === 'session') {
+    const srcTable = parsed.source === 'prompt' ? 'user_prompts' : 'session_summaries';
+    const srcPrefix = parsed.source === 'prompt' ? 'P#' : 'S#';
+    const srcName = parsed.source === 'prompt' ? 'Prompt' : 'Session';
+    const row = db.prepare(`SELECT created_at_epoch FROM ${srcTable} WHERE id = ?`).get(parsed.id);
+    if (!row) return { ok: false, error: { code: 'source-not-found', name: srcName, prefix: srcPrefix, id: parsed.id } };
+    const nearest = nearestObservation(db, row.created_at_epoch, project);
+    if (!nearest) return { ok: false, error: { code: 'no-obs-near', prefix: srcPrefix, id: parsed.id } };
+    return { ok: true, anchorId: nearest.id, anchorNote: `(anchored to #${nearest.id}, closest obs to ${srcPrefix}${parsed.id})` };
+  }
+
+  // Bare "#N" or "N" — observation first. Route compressed obs to its live
+  // parent so the window (which filters compressed) isn't shown around a dead
+  // record; negative sentinels (-1 dropped, -2 pending purge) have no parent.
+  const obsRow = db.prepare('SELECT compressed_into FROM observations WHERE id = ?').get(parsed.id);
+  if (obsRow) {
+    const ci = obsRow.compressed_into;
+    if (ci && ci > 0) {
+      return { ok: true, anchorId: ci, anchorNote: `(anchored to #${ci}, #${parsed.id} was compressed into it)` };
+    }
+    if (ci && ci < 0) {
+      return { ok: false, error: { code: 'compressed-pruned', id: parsed.id } };
+    }
+    return { ok: true, anchorId: parsed.id, anchorNote: null };
+  }
+
+  // Fall back to user_prompts then session_summaries so pasted P#/S# ids still
+  // work when the prefix is omitted — matches prefix-aware routing in search/probe.
+  const promptRow = db.prepare('SELECT created_at_epoch FROM user_prompts WHERE id = ?').get(parsed.id);
+  const sessionRow = promptRow ? null : db.prepare('SELECT created_at_epoch FROM session_summaries WHERE id = ?').get(parsed.id);
+  const hit = promptRow ? { row: promptRow, prefix: 'P#', name: 'prompt' }
+            : sessionRow ? { row: sessionRow, prefix: 'S#', name: 'session' }
+            : null;
+  if (!hit) return { ok: false, error: { code: 'id-not-found', id: parsed.id } };
+  const nearest = nearestObservation(db, hit.row.created_at_epoch, project);
+  if (!nearest) return { ok: false, error: { code: 'no-obs-near', prefix: hit.prefix, id: parsed.id, srcName: hit.name } };
+  return { ok: true, anchorId: nearest.id, anchorNote: `(anchored to #${nearest.id}, closest obs to ${hit.prefix}${parsed.id})` };
+}
+
+/**
+ * Render a resolveAnchorToken error in either caller dialect. Owning BOTH
+ * renderings here is deliberate: the strings are regression-anchored on each
+ * side (tests/cli.test.mjs, tests/server.test.mjs) and previously drifted only
+ * in prefix/period; one table keeps the divergence explicit and frozen.
+ *
+ * cli: "[mem] "-prefixed, no trailing period, flag spelled "--anchor".
+ * mcp: bare sentence with trailing period.
+ */
+export function formatAnchorError(error, dialect) {
+  const cli = dialect === 'cli';
+  switch (error.code) {
+    case 'invalid-token':
+      return cli
+        ? `[mem] Invalid --anchor "${error.raw}". Expected N, #N, P#N, or S#N.`
+        : `Invalid anchor "${error.raw}". Expected N, #N, P#N, or S#N.`;
+    case 'source-not-found':
+      return cli
+        ? `[mem] ${error.name} ${error.prefix}${error.id} not found`
+        : `${error.name} ${error.prefix}${error.id} not found.`;
+    case 'no-obs-near': {
+      const suffix = error.srcName ? ` (${error.srcName})` : '';
+      return cli
+        ? `[mem] No observations near ${error.prefix}${error.id}${suffix}`
+        : `No observations near ${error.prefix}${error.id}${suffix}.`;
+    }
+    case 'compressed-pruned':
+      return cli
+        ? `[mem] Observation #${error.id} was compressed and pruned; no canonical anchor available`
+        : `Observation #${error.id} was compressed and pruned; no canonical anchor available.`;
+    case 'id-not-found':
+      return cli
+        ? `[mem] Observation, prompt, or session with id ${error.id} not found`
+        : `Observation, prompt, or session with id ${error.id} not found.`;
+    default:
+      return cli ? `[mem] Anchor resolution failed` : 'Anchor resolution failed.';
+  }
+}
+
+/**
+ * Query-based anchor: route through shared findFtsAnchor so CLI
+ * `timeline --query` and MCP mem_timeline keep identical AND→OR fallback
+ * semantics (#8217). Returns null when the query sanitizes to nothing or
+ * matches no row; anchorNote is set only when the OR relaxation fired.
+ */
+export function resolveQueryAnchor(db, queryStr, { project = null } = {}) {
+  const ftsQuery = sanitizeFtsQuery(queryStr);
+  const found = findFtsAnchor(db, { ftsQuery, project });
+  if (!found) return null;
+  return {
+    anchorId: found.id,
+    anchorNote: found.relaxed
+      ? `(query "${queryStr}" relaxed AND→OR — no row matched all terms)`
+      : null,
+  };
+}
+
+/** No-anchor fallback: most recent non-compressed observations, newest first. */
+export function fetchRecentTimeline(db, { project = null, limit }) {
+  const compressedFilter = 'COALESCE(compressed_into, 0) = 0';
+  const where = project ? `WHERE ${compressedFilter} AND project = ?` : `WHERE ${compressedFilter}`;
+  const params = project ? [project, limit] : [limit];
+  return db.prepare(`
+    SELECT ${TIMELINE_COLS}
+    FROM observations ${where}
+    ORDER BY created_at_epoch DESC
+    LIMIT ?
+  `).all(...params);
+}
+
+/**
+ * Fetch the before/after window around a resolved anchor id. Bumps the
+ * anchor's access_count (read-path popularity signal), and auto-scopes to the
+ * anchor's project when the caller didn't pass one — "timeline around #N"
+ * means same-project context, not cross-project time-bleed.
+ *
+ * @returns {null | { anchor, beforeRows, afterRows, effectiveProject }}
+ *   null when the anchor row vanished (e.g. deleted between resolve and fetch).
+ *   beforeRows are CHRONOLOGICAL (oldest→newest) — callers no longer reverse.
+ */
+export function fetchTimelineWindow(db, anchorId, { before, after, project = null }) {
+  const anchorRow = db.prepare('SELECT created_at_epoch, project FROM observations WHERE id = ?').get(anchorId);
+  if (!anchorRow) return null;
+
+  try {
+    db.prepare('UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id = ?').run(Date.now(), anchorId);
+  } catch { /* non-critical: FTS5 trigger may fail on corrupted index */ }
+
+  const effectiveProject = project || anchorRow.project;
+  const projectFilter = effectiveProject ? 'AND project = ?' : '';
+  const baseParams = effectiveProject ? [effectiveProject] : [];
+
+  const beforeRows = db.prepare(`
+    SELECT ${TIMELINE_COLS}
+    FROM observations
+    WHERE created_at_epoch < ? AND COALESCE(compressed_into, 0) = 0 AND superseded_at IS NULL ${projectFilter}
+    ORDER BY created_at_epoch DESC
+    LIMIT ?
+  `).all(anchorRow.created_at_epoch, ...baseParams, before).reverse();
+
+  const afterRows = db.prepare(`
+    SELECT ${TIMELINE_COLS}
+    FROM observations
+    WHERE created_at_epoch > ? AND COALESCE(compressed_into, 0) = 0 AND superseded_at IS NULL ${projectFilter}
+    ORDER BY created_at_epoch ASC
+    LIMIT ?
+  `).all(anchorRow.created_at_epoch, ...baseParams, after);
+
+  const anchor = db.prepare(`SELECT ${TIMELINE_COLS} FROM observations WHERE id = ?`).get(anchorId);
+
+  return { anchor, beforeRows, afterRows, effectiveProject };
+}