claude-mem-lite 2.97.0 → 2.99.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.97.0",
+      "version": "2.99.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.97.0",
+  "version": "2.99.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/observation-write.mjs

@@ -9,7 +9,7 @@
 // + 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';
+import { debugCatch, cjkBigrams } from '../utils.mjs';
 
 // Canonical column order — must mirror the observations schema (schema.mjs).
 const OBS_COLUMNS = [
@@ -65,3 +65,20 @@ export function insertObservationVector(db, obsId, vecText) {
       .run(obsId, Buffer.from(vec.buffer), vocab.version, Date.now());
   } catch (e) { debugCatch(e, 'insertObservationVector'); }
 }
+
+/**
+ * Rebuild an observation's derived columns after a field UPDATE: the FTS `text`
+ * column (incl. CJK bigrams + search_aliases, matching the ingest paths) and the
+ * TF-IDF vector. cmdUpdate (CLI) and mem_update (MCP) previously hand-copied this
+ * block — the same drift class #8614/#8639 closed for compress/maintain. Caller
+ * owns the transaction (vector write is internally non-critical).
+ */
+export function rebuildObservationDerived(db, obsId) {
+  const row = db.prepare('SELECT title, subtitle, narrative, concepts, facts, lesson_learned, search_aliases FROM observations WHERE id = ?').get(obsId);
+  if (!row) return;
+  const base = [row.title, row.subtitle, row.narrative, row.concepts, row.facts, row.lesson_learned, row.search_aliases].filter(Boolean).join(' ');
+  const bigrams = cjkBigrams((row.title || '') + ' ' + (row.narrative || ''));
+  const textField = bigrams ? base + ' ' + bigrams : base;
+  db.prepare('UPDATE observations SET text = ? WHERE id = ?').run(textField, obsId);
+  insertObservationVector(db, obsId, textField);
+}

package/lib/recall-core.mjs

@@ -0,0 +1,43 @@
+// Single source of truth for file-keyed recall: the observation_files junction
+// query, LIKE-wildcard escaping, noise filtering, and the access-count bump.
+// cmdRecall (mem-cli.mjs) and mem_recall (server.mjs) previously hand-copied all
+// four — the drift class that produced the mem_get formatter drift (#8678) and
+// the maintain hand-sync drift (#8614). Renderers stay per-surface; the data
+// contract lives here.
+
+import { basename } from 'path';
+import { notLowSignalTitleClause } from '../utils.mjs';
+
+/**
+ * Recall observations linked to a file (basename or full path). Returns
+ * { filename, rows } where rows carry the column superset both surfaces render.
+ * Side effect: bumps access_count / last_accessed_at on every returned row —
+ * recall IS engagement, and the tier/decay system feeds on these counters.
+ */
+export function recallByFile(db, file, { limit = 10, includeNoise = false } = {}) {
+  const filename = basename(file);
+  const escaped = filename.replace(/%/g, '\\%').replace(/_/g, '\\_');
+  const likePattern = `%${escaped}`;
+  const noiseClause = includeNoise ? '' : `AND ${notLowSignalTitleClause('o')}`;
+  const rows = db.prepare(`
+    SELECT DISTINCT o.id, o.type, o.title, o.lesson_learned, o.importance,
+                    o.created_at, o.created_at_epoch, o.project
+    FROM observations o
+    JOIN observation_files of2 ON of2.obs_id = o.id
+    WHERE COALESCE(o.compressed_into, 0) = 0
+      AND (of2.filename = ? OR of2.filename LIKE ? ESCAPE '\\')
+      ${noiseClause}
+    ORDER BY o.created_at_epoch DESC
+    LIMIT ?
+  `).all(filename, likePattern, limit);
+
+  if (rows.length > 0) {
+    const ph = rows.map(() => '?').join(',');
+    try {
+      db.prepare(`UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id IN (${ph})`)
+        .run(Date.now(), ...rows.map(r => r.id));
+    } catch { /* non-critical: FTS5 trigger may fail on corrupted index */ }
+  }
+
+  return { filename, rows };
+}

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 };
+}