claude-mem-lite 6.3.0 → 6.5.0

package/lib/db-backup.mjs

@@ -43,26 +43,51 @@ export const BACKUP_EVICTION_GRACE_MS = 7 * DAY_MS;
 // user's hand-made `cp db db.before-upgrade.bak` must never be auto-unlinked.
 const SNAPSHOT_STAMP_RE = /-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-\d+-\d+\.bak$/;
 
-/** All `<db>.<tag>-<ts>.bak` snapshots for `dbPath`, any tag, with size + mtime. */
-export function listSnapshots(dbPath) {
+/**
+ * Snapshots for `dbPath`, keeping "there are none" and "I could not look" APART.
+ *
+ * `listSnapshots` below collapses both into `[]`, which is fine for its callers (a budget
+ * sweep has nothing to do either way) and wrong for anything that REPORTS to a human: a
+ * diagnostic that says "no backup exists" when it actually could not read the directory
+ * ends the reader's search with a false fact. Same rule the doctor bash-hook check
+ * settled on — "nothing to check" and "I could not look" are different answers.
+ *
+ * @returns {{ok: true, snapshots: Array<{path:string,size:number,mtimeMs:number}>}
+ *          | {ok: false, reason: string}}
+ */
+export function readSnapshots(dbPath) {
+  let names;
+  let dir;
+  let prefix;
+  // dirname/basename inside the try, not outside it: `listSnapshots` below has always been
+  // total (it returned [] for any input), and one of this function's callers runs inside
+  // `doctor`'s DB catch block, where the repo's openDb precedent says nothing may throw.
+  // Computing the path outside would make listSnapshots(undefined) a TypeError.
   try {
-    const dir = dirname(dbPath);
-    const prefix = `${basename(dbPath)}.`;
-    const out = [];
-    for (const n of readdirSync(dir)) {
-      if (!n.startsWith(prefix) || !n.endsWith('.bak')) continue;
-      const full = join(dir, n);
-      try {
-        const st = statSync(full);
-        out.push({ path: full, size: st.size, mtimeMs: st.mtimeMs });
-      } catch {
-        /* raced away */
-      }
+    dir = dirname(dbPath);
+    prefix = `${basename(dbPath)}.`;
+    names = readdirSync(dir);
+  } catch (e) {
+    return { ok: false, reason: e?.code || e?.message || 'unreadable' };
+  }
+  const snapshots = [];
+  for (const n of names) {
+    if (!n.startsWith(prefix) || !n.endsWith('.bak')) continue;
+    const full = join(dir, n);
+    try {
+      const st = statSync(full);
+      snapshots.push({ path: full, size: st.size, mtimeMs: st.mtimeMs });
+    } catch {
+      /* raced away */
     }
-    return out;
-  } catch {
-    return [];
   }
+  return { ok: true, snapshots };
+}
+
+/** All `<db>.<tag>-<ts>.bak` snapshots for `dbPath`, any tag, with size + mtime. */
+export function listSnapshots(dbPath) {
+  const r = readSnapshots(dbPath);
+  return r.ok ? r.snapshots : [];
 }
 
 /**

package/lib/db-unusable.mjs

@@ -0,0 +1,178 @@
+// lib/db-unusable.mjs — the database file is not a usable database.
+//
+// The sibling of lib/schema-skew.mjs, and it exists for the same reason: the throw is
+// correct, and everything downstream of it was missing. Measured 2026-09-08 in a sandboxed
+// HOME with a corrupted header:
+//
+//   • CLI (`search` / `recent` / `stats` / `get` / `save` / `browse` / `fts-check`) — all exit
+//     1 with the SQLite message. Correct.
+//   • `status` — "⚠ Database: exists but check failed". Correct.
+//   • `doctor` — names the file and prints an exact repair command. Correct.
+//   • Hooks — `openDb()` returns null, `hook.mjs`'s `const db = openDb(); if (!db) return;`
+//     ends SessionStart with EMPTY stdout and EMPTY stderr, and every fire wrote another
+//     stack trace to runtime/hook-errors/. Nothing the user sees says memory is off.
+//
+// State that last figure carefully, because the first draft got it wrong twice over: it said
+// "20 fires → 10 identical ~1.5 KB records", which was a MIXED fire set (only some events
+// reach this path) reported as if it were 20 SessionStarts, and a size nobody measured.
+// Re-measured over 20 SessionStart fires: 20 records, 859-873 bytes each — one per fire, and
+// ~1.7x smaller than claimed. `recordHookError` caps the stack at 6 frames and the message at
+// 500 chars, so the per-record size is bounded; the unbounded quantity is the COUNT.
+//
+// So the one surface the user is actually looking at during a session was the only silent
+// one, on a condition that never heals by itself. That is the schema-skew shape exactly, and
+// this module is deliberately its mirror image so the two cannot drift apart.
+//
+// It imports no native binding: the static graph is 10 modules and zero package edges (the
+// only bare specifiers anywhere in it are the `node:` builtins). That is the property that
+// matters — a classifier the hook path may need while the binding is the broken thing must
+// not sit behind a native import. It is NOT as tight as schema-skew.mjs, which imports
+// `node:` builtins and nothing else; this one reaches `db-backup → utils → …` for
+// `readSnapshots`. Same guarantee, larger graph — do not restate it as "same discipline".
+
+import { basename, dirname } from 'node:path';
+import { readSnapshots } from './db-backup.mjs';
+
+/** Marker prefix for lib/record-once.mjs. Per project, like the skew one. */
+export const DB_UNUSABLE_MARKER_PREFIX = '.db-unusable-logged-';
+
+// SQLite's own spellings for "this file is not a usable database". Kept here as the single
+// definition so install.mjs's doctor check and the hook path classify identically — they used
+// to hold one copy each, which is this repo's named twin-drift class.
+//
+// Deliberately NOT matching "unable to open database file": that is a PERMISSIONS or
+// missing-directory failure, whose remedy is nothing like the two below, and answering it
+// with "move the file aside" would tell a user to destroy a healthy store.
+const UNUSABLE_RE = /not a database|disk image is malformed/i;
+
+/**
+ * Whether an error is a damaged FTS5 INDEX rather than a damaged database file.
+ *
+ * THE MESSAGE CANNOT TELL THEM APART. SQLite reports a damaged index as
+ * SQLITE_CORRUPT_VTAB with the same "database disk image is malformed" text the file-level
+ * faults use, so the code is the only discriminator — and matching on message alone is what
+ * conflated them before R10 P3-9. The remedy is rebuildFTS, which the FTS content lets us do
+ * losslessly; treating it as file corruption would offer `cp <old snapshot> <db>` over a
+ * database whose rows are all intact.
+ *
+ * This lives HERE rather than in schema.mjs (which re-exports it, so every existing importer
+ * is unchanged) because both consumers of the distinction now need it and schema.mjs imports
+ * better-sqlite3 — a classifier the hook path may need while the binding is the broken thing
+ * must not be behind a native import.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isFtsCorruptionError(err) {
+  return /SQLITE_CORRUPT_VTAB/i.test(`${err?.code || ''}`);
+}
+
+/**
+ * True when `err` means "this file exists and SQLite cannot use it as a database".
+ *
+ * Accepts anything thrown (Error, string, null) because recordHookError does.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isDbUnusableError(err) {
+  if (!err) return false;
+  // FIRST, and for the same reason isDbCorruptionError does it first: a damaged index is a
+  // HEALTHY FILE, and every remedy below is wrong — and destructive — for one.
+  if (isFtsCorruptionError(err)) return false;
+  return UNUSABLE_RE.test(String(err.message ?? err ?? ''));
+}
+
+/**
+ * What the user should actually run. Three outcomes, never two — the same rule schema-skew.mjs
+ * states: "there is no backup" and "I could not look for one" must not print in the same
+ * voice, because a green-sounding line ends the reader's search.
+ *
+ * `snapshotCount` is part of the return rather than something a caller re-derives: doctor's
+ * sentence names it ("Restore the newest of 2 backup snapshot(s)"), and a second
+ * `readSnapshots` call to recover a number this function already had would be a second
+ * directory read that can disagree with the first.
+ *
+ * @param {string} dbPath
+ * @returns {{kind: 'restore'|'set-aside'|'unknown', command: string, note: string, snapshotCount: number}}
+ */
+export function dbUnusableRemedy(dbPath) {
+  const clear = `rm -f "${dbPath}-wal" "${dbPath}-shm"`;
+  const snap = readSnapshots(dbPath);
+  if (!snap.ok) {
+    return {
+      kind: 'unknown',
+      command: '',
+      snapshotCount: 0,
+      note:
+        `Could not read ${dirname(dbPath)} to look for a backup snapshot (${snap.reason}) — ` +
+        `fix that directory first, then look for ${basename(dbPath)}.*.bak beside the database.`,
+    };
+  }
+  if (snap.snapshots.length === 0) {
+    return {
+      kind: 'set-aside',
+      command: `${clear} && mv "${dbPath}" "${dbPath}.corrupt"`,
+      snapshotCount: 0,
+      note:
+        'No backup snapshot exists beside the database. That command sets the broken file ' +
+        'aside so a fresh store is created on the next session — memories in it are not ' +
+        'recoverable without a backup.',
+    };
+  }
+  // Newest by mtime, ties broken by name (which carries an ISO stamp) so the answer is total
+  // rather than dependent on readdir order — the D#9 shape.
+  const newest = snap.snapshots
+    .slice()
+    .sort((a, b) => b.mtimeMs - a.mtimeMs || (a.path < b.path ? 1 : -1))[0];
+  return {
+    kind: 'restore',
+    command: `${clear} && cp "${newest.path}" "${dbPath}"`,
+    snapshotCount: snap.snapshots.length,
+    note:
+      `Restores the newest of ${snap.snapshots.length} backup snapshot(s). Move the broken ` +
+      'file aside first if you want to keep it for inspection.',
+  };
+}
+
+/**
+ * The user-facing block. Short on purpose — at SessionStart it shares one stdout envelope
+ * with the startup dashboard and the `<claude-mem-context>` block.
+ *
+ * @param {{dbPath: string, remedy: ReturnType<typeof dbUnusableRemedy>}} info
+ * @returns {string}
+ */
+export function formatDbUnusableNotice({ dbPath, remedy }) {
+  const lines = [
+    '⚠️ [claude-mem-lite] Memory is OFF: the database file cannot be opened.',
+    `   ${dbPath} exists but SQLite does not recognise it as a database.`,
+  ];
+  if (remedy.command) lines.push(`   ${remedy.command}`);
+  if (remedy.note) lines.push(`   ${remedy.note}`);
+  lines.push('   Until then, saves and recall are disabled. `claude-mem-lite doctor` re-checks.');
+  return lines.join('\n');
+}
+
+/**
+ * The same fact, with NO COMMAND IN IT, for the model channel.
+ *
+ * The schema-skew twin sends one string to both channels and that is safe there — its
+ * commands are `git pull` / `claude plugin update` / `npm i -g`. This family's remedy is
+ * `rm -f …-wal …-shm && cp "<snapshot>" "<db>"`, which OVERWRITES the database, and handing
+ * a ready-to-run irreversible shell line to an agent that has Bash — with no addressee and no
+ * "ask first" — is a different proposition. Worse, the restore arm defeats its own advice: a
+ * reader who acts on the command line destroys the broken file the next line tells them to
+ * keep for inspection.
+ *
+ * So the human gets the command and the model gets the situation. Both still learn memory is
+ * off, which is the point of using both channels at all.
+ *
+ * @returns {string}
+ */
+export function formatDbUnusableModelNotice() {
+  return [
+    '⚠️ [claude-mem-lite] Memory is OFF for this session: the database file is unreadable.',
+    '   Saves and recall are disabled. Do not attempt to repair it yourself — tell the user to',
+    '   run `claude-mem-lite doctor`, which prints the exact command for their machine.',
+  ].join('\n');
+}

package/lib/plugin-key.mjs

@@ -24,8 +24,11 @@
 /** Marketplace this plugin is published under. */
 export const MARKETPLACE_KEY = 'sdsrss';
 
+/** This plugin's own name — the directory Claude Code materializes versions under. */
+export const PLUGIN_NAME = 'claude-mem-lite';
+
 /** The key Claude Code writes under `enabledPlugins` in `~/.claude/settings.json`. */
-export const PLUGIN_KEY = `claude-mem-lite@${MARKETPLACE_KEY}`;
+export const PLUGIN_KEY = `${PLUGIN_NAME}@${MARKETPLACE_KEY}`;
 
 /**
  * Whether the user has EXPLICITLY switched the plugin off.

package/lib/record-once.mjs

@@ -0,0 +1,71 @@
+// lib/record-once.mjs — "has this condition already been logged recently, for this project?"
+//
+// Extracted from lib/schema-skew.mjs when a SECOND unhealable DB-open family needed the same
+// dedup (a database file that is not a database). Both callers run inside `openDb()`'s catch,
+// where the contract is return-null-never-throw, and both log a multi-line stack trace on a
+// condition that repeats on every single hook fire until a human intervenes — the shape that
+// put >=648 identical lines in one day's runtime/hook-errors/ before the skew round.
+//
+// Copying the implementation instead would be this repo's named twin-drift class, on a
+// function whose two hard properties (total, fails-toward-recording) were each paid for with
+// a review round.
+//
+// TOTAL by contract — every path returns a boolean and nothing escapes. The first version of
+// the skew dedup called `getSessionId()` from inside the catch, which is not a read: it MINTS
+// and writes a session id, so an unwritable runtime dir turned `openDb()` itself into a
+// thrower. Keep every filesystem call in this file inside its own try.
+//
+// FAILS TOWARD RECORDING — an unreadable or unwritable marker must never silence the log.
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * One hour. The condition persists until the user acts, so "record it once, ever" would be
+ * defensible; an hour keeps the log's remaining job (when did this start, is it still
+ * happening) answerable at <=24 lines/day/project.
+ */
+export const RELOG_INTERVAL_MS = 60 * 60 * 1000;
+
+/**
+ * @param {string} runtimeDir Where the marker lives.
+ * @param {string} markerPrefix Distinguishes conditions; the project is appended to it.
+ * @param {string} project Marker scope. PER PROJECT, deliberately: one shared marker keyed on
+ *   a per-project value let two projects on one data dir overwrite each other's key, so every
+ *   fire recorded again — measured at 8 fires / 2 projects → 8 records. Anything falsy
+ *   collapses to one shared file, which is a worse dedup rather than a crash.
+ * @param {string} key Re-record when this changes: new information is not the fault already
+ *   logged.
+ * @param {{now?: number, intervalMs?: number}} [opts]
+ * @returns {boolean} true = write the log line now
+ */
+export function shouldRecordOnce(
+  runtimeDir,
+  markerPrefix,
+  project,
+  key,
+  { now = Date.now(), intervalMs = RELOG_INTERVAL_MS } = {},
+) {
+  try {
+    const scope = String(project || 'unscoped').replace(/[^A-Za-z0-9._-]/g, '_');
+    const file = join(runtimeDir, markerPrefix + scope);
+    try {
+      const prev = JSON.parse(readFileSync(file, 'utf8'));
+      if (prev.key === key && typeof prev.ts === 'number' && now - prev.ts < intervalMs) return false;
+    } catch {
+      /* absent, unreadable or corrupt → record */
+    }
+    try {
+      // The dir may not exist yet: hook-shared creates RUNTIME_DIR at module scope, but the
+      // `ups` face does not import it, so on a fresh data dir the first marker write failed
+      // silently and the SECOND fire recorded again.
+      mkdirSync(runtimeDir, { recursive: true });
+      writeFileSync(file, JSON.stringify({ key, ts: now }), { mode: 0o600 });
+    } catch {
+      /* an unwritable marker must not suppress the record */
+    }
+    return true;
+  } catch {
+    return true;
+  }
+}

package/lib/save-observation.mjs

@@ -140,6 +140,7 @@ export function formatSupersedeSkipped(skipped) {
  * @param {string} params.project                 Resolved project key.
  * @param {string[]} [params.files=[]]            File paths to attach (junction table).
  * @param {string|null} [params.lesson_learned]   Caller validates ≤500 chars.
+ * @param {boolean} [params.force=false]          Skip the near-duplicate window (below).
  * @param {Date}   [params.now]                   Override for tests.
  * Both result shapes carry `supersededIds` (observations actually tombstoned) and
  * `supersedeSkipped` (requested but NOT tombstoned, each with a `reason`:
@@ -257,11 +258,21 @@ export function saveObservation(db, params) {
     malformed: malformedSupersedes,
   } = splitSupersedeTokens(rawSupersedes);
 
-  const dupMatch = recent.find(
-    (r) =>
-      jaccardSimilarity(r.title, safeTitle) > DEDUP_JACCARD_THRESHOLD ||
-      jaccardSimilarity(r.text || '', safeContent) > DEDUP_JACCARD_THRESHOLD,
-  );
+  // `force` is the escape hatch, and it is opt-in for a reason on each side. The window
+  // exists to stop hook-driven auto-saves re-accumulating one story, and it must stay the
+  // default. But it also refuses a LEGITIMATE distinct memory: measured 2026-09-08, three
+  // deliberately different lessons about the same file inside five minutes collapsed to one
+  // save, the second and third answered with "Skipped: similar to existing #N" and exit 0 —
+  // and there was no flag, so the only workaround was to reword until Jaccard fell below
+  // 0.7, i.e. to degrade the memory to get it stored. A caller who has read that message and
+  // still means it can say so.
+  const dupMatch = params.force
+    ? undefined
+    : recent.find(
+        (r) =>
+          jaccardSimilarity(r.title, safeTitle) > DEDUP_JACCARD_THRESHOLD ||
+          jaccardSimilarity(r.text || '', safeContent) > DEDUP_JACCARD_THRESHOLD,
+      );
   if (dupMatch) {
     // D#201: a dedup short-circuit swallows the requested supersession too — you
     // write a correction, it reads as a near-duplicate of something saved in the

package/lib/schema-skew.mjs

@@ -38,9 +38,10 @@
 // child process (probeSchemaCompatInFreshProcess).
 
 import { spawnSync } from 'node:child_process';
-import { readFileSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { shouldRecordOnce } from './record-once.mjs';
 
 /** Machine-readable marker set by schema.mjs on the forward-incompat throw. */
 export const SCHEMA_SKEW_CODE = 'CLAUDE_MEM_SCHEMA_TOO_NEW';
@@ -76,38 +77,28 @@ export const SKEW_RELOG_INTERVAL_MS = 60 * 60 * 1000;
  * @param {{now?: number, intervalMs?: number}} [opts]
  * @returns {boolean}
  */
-export function shouldRecordSkew(
-  runtimeDir,
-  project,
-  info,
-  { now = Date.now(), intervalMs = SKEW_RELOG_INTERVAL_MS } = {},
-) {
+export function shouldRecordSkew(runtimeDir, project, info, opts = {}) {
+  // The body moved to lib/record-once.mjs when a second unhealable DB-open family needed the
+  // same dedup; this signature and its key derivation stay here because they are skew's, not
+  // the generic helper's. A changed version pair always re-records: a PARTIAL upgrade (the
+  // binary moves v48→v49 while the DB moves to v50) is new information, not the fault already
+  // logged.
+  // The key derivation is INSIDE a try because this function's contract is TOTAL and the
+  // extraction briefly lost that: `info` reaches here from a catch block, and a property
+  // getter or `toString` that throws would have propagated out of `openDb()`'s catch — the
+  // same shape as the `getSessionId()` incident this module's header cites. Unreachable from
+  // today's two callers (both pass a plain object or null); restored anyway, because the
+  // sentence at hook-shared.mjs's call site asserts the property, not the reachability.
+  let key;
   try {
-    const scope = String(project || 'unscoped').replace(/[^A-Za-z0-9._-]/g, '_');
-    const file = join(runtimeDir, SKEW_MARKER_PREFIX + scope);
-    const key = `${info?.dbVersion ?? '?'}:${info?.binaryVersion ?? '?'}`;
-    try {
-      const prev = JSON.parse(readFileSync(file, 'utf8'));
-      // A changed version pair always re-records: a PARTIAL upgrade (the binary moves v48→v49
-      // while the DB moves to v50) is new information, not the fault we already logged.
-      if (prev.key === key && typeof prev.ts === 'number' && now - prev.ts < intervalMs) return false;
-    } catch {
-      /* absent, unreadable or corrupt → record */
-    }
-    try {
-      // The dir may not exist yet. hook-shared creates RUNTIME_DIR at module scope, but the
-      // `ups` face does not import it — so on a fresh data dir the first marker write failed
-      // silently and the SECOND fire recorded again. Measured: 4 ups fires produced 2 records
-      // instead of 1, both from the same call site, with the marker present afterwards.
-      mkdirSync(runtimeDir, { recursive: true });
-      writeFileSync(file, JSON.stringify({ key, ts: now }), { mode: 0o600 });
-    } catch {
-      /* an unwritable marker must not suppress the record */
-    }
-    return true;
+    key = `${info?.dbVersion ?? '?'}:${info?.binaryVersion ?? '?'}`;
   } catch {
-    return true;
+    key = '?:?';
   }
+  return shouldRecordOnce(runtimeDir, SKEW_MARKER_PREFIX, project, key, {
+    intervalMs: SKEW_RELOG_INTERVAL_MS,
+    ...opts,
+  });
 }
 
 // The shipped message, which older builds throw with no code field at all. Kept as a

package/lib/timeline-core.mjs

@@ -18,6 +18,23 @@ import { liveObsFilterSql } from './inject-search-core.mjs';
 
 const TIMELINE_COLS = 'id, type, title, subtitle, project, created_at, created_at_epoch';
 
+// A P#/S#/E# anchor names a row that BELONGS to a project, and both surfaces document the
+// conversion as "the nearest-in-time observation in the same project". It was resolved
+// globally, which does not merely pick one odd row: fetchTimelineWindow below then scopes
+// the whole before/after window to `project || anchorRow.project`, so one cross-project
+// anchor moves the entire rendered timeline into another project with nothing marking it.
+// Each source therefore reports its own project alongside the epoch. `user_prompts` has no
+// project column — it reaches one through the session that owns the prompt, which is the
+// same edge `sdk_sessions` already carries for every other prompt-scoped read.
+const SOURCE_ROW_SQL = {
+  prompt: `SELECT p.created_at_epoch AS created_at_epoch, s.project AS project
+             FROM user_prompts p
+             LEFT JOIN sdk_sessions s ON s.content_session_id = p.content_session_id
+            WHERE p.id = ?`,
+  session: 'SELECT created_at_epoch, project FROM session_summaries WHERE id = ?',
+  event: 'SELECT created_at_epoch, project FROM events WHERE id = ?',
+};
+
 /** Nearest live (non-compressed, non-superseded) observation to `epoch`. */
 function nearestObservation(db, epoch, project) {
   return db
@@ -48,17 +65,25 @@ export function resolveAnchorToken(db, rawAnchor, { project = null } = {}) {
   }
 
   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);
+    const row = db.prepare(SOURCE_ROW_SQL[parsed.source]).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 } };
+    const nearest = nearestObservation(db, row.created_at_epoch, project ?? row.project ?? null);
+    if (!nearest)
+      return {
+        ok: false,
+        error: {
+          code: 'no-obs-near',
+          prefix: srcPrefix,
+          id: parsed.id,
+          scope: project ?? row.project ?? null,
+        },
+      };
     return {
       ok: true,
       anchorId: nearest.id,
@@ -71,11 +96,15 @@ export function resolveAnchorToken(db, rawAnchor, { project = null } = {}) {
   // nearest observation by epoch. Without this explicit branch an E#N token would fall through
   // to the bare-int obs lookup below and silently resolve to the COLLIDING observation id.
   if (parsed.source === 'event') {
-    const row = db.prepare('SELECT created_at_epoch FROM events WHERE id = ?').get(parsed.id);
+    const row = db.prepare(SOURCE_ROW_SQL.event).get(parsed.id);
     if (!row)
       return { ok: false, error: { code: 'source-not-found', name: 'Event', prefix: 'E#', id: parsed.id } };
-    const nearest = nearestObservation(db, row.created_at_epoch, project);
-    if (!nearest) return { ok: false, error: { code: 'no-obs-near', prefix: 'E#', id: parsed.id } };
+    const nearest = nearestObservation(db, row.created_at_epoch, project ?? row.project ?? null);
+    if (!nearest)
+      return {
+        ok: false,
+        error: { code: 'no-obs-near', prefix: 'E#', id: parsed.id, scope: project ?? row.project ?? null },
+      };
     return {
       ok: true,
       anchorId: nearest.id,
@@ -124,21 +153,25 @@ export function resolveAnchorToken(db, rawAnchor, { project = 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 promptRow = db.prepare(SOURCE_ROW_SQL.prompt).get(parsed.id);
+  const sessionRow = promptRow ? null : db.prepare(SOURCE_ROW_SQL.session).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);
+  const nearest = nearestObservation(db, hit.row.created_at_epoch, project ?? hit.row.project ?? null);
   if (!nearest)
     return {
       ok: false,
-      error: { code: 'no-obs-near', prefix: hit.prefix, id: parsed.id, srcName: hit.name },
+      error: {
+        code: 'no-obs-near',
+        prefix: hit.prefix,
+        id: parsed.id,
+        srcName: hit.name,
+        scope: project ?? hit.row.project ?? null,
+      },
     };
   return {
     ok: true,
@@ -169,9 +202,15 @@ export function formatAnchorError(error, dialect) {
         : `${error.name} ${error.prefix}${error.id} not found.`;
     case 'no-obs-near': {
       const suffix = error.srcName ? ` (${error.srcName})` : '';
+      // NAME THE SCOPE. Since the anchor became project-scoped, this is the answer a caller
+      // gets when the source row's own project holds no live observations — and without the
+      // scope the message reads as "that id has no neighbours anywhere", which is a different
+      // and wrong fact. `--project` is the lever, so say it.
+      const where = error.scope ? ` in project "${error.scope}"` : '';
+      const hint = error.scope ? ' — pass --project to search another' : '';
       return cli
-        ? `[mem] No observations near ${error.prefix}${error.id}${suffix}`
-        : `No observations near ${error.prefix}${error.id}${suffix}.`;
+        ? `[mem] No observations near ${error.prefix}${error.id}${suffix}${where}${hint}`
+        : `No observations near ${error.prefix}${error.id}${suffix}${where}.`;
     }
     case 'compressed-pruned':
       return cli