claude-mem-lite 3.56.0 → 3.57.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.56.0",
+      "version": "3.57.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": "3.56.0",
+  "version": "3.57.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/hook-context.mjs

@@ -1,4 +1,8 @@
 // claude-mem-lite CLAUDE.md context injection and token budgeting
+// SHARED ENGINE — the `hook-` prefix is historical, not a scope. buildSessionContextLines
+// is imported by hook.mjs (SessionStart), mem-cli.mjs (`context` command) and
+// hook-precompact.mjs, so it runs outside the hook pipeline too. Do not assume
+// hook-pipeline session lifecycle or single-writer concurrency here.
 // Handles adaptive time windows, token-budgeted selection, and legacy CLAUDE.md cleanup.
 
 import { basename, join } from 'path';

package/hook-episode.mjs

@@ -109,7 +109,10 @@ export function writeEpisode(episode) {
   const target = episodeFile();
   const tmp = target + `.tmp-${process.pid}`;
   const { _fileSet, ...serializable } = episode;
-  writeFileSync(tmp, JSON.stringify(serializable));
+  // 0600 on the tmp file, not on `target`: mode applies at creation and rename
+  // carries it over, so the buffer is never briefly world-readable. The buffer
+  // holds captured file paths + scrubbed activity — owner-only like the DB.
+  writeFileSync(tmp, JSON.stringify(serializable), { mode: 0o600 });
   try {
     renameSync(tmp, target);
   } catch (err) {
@@ -196,7 +199,7 @@ export function writePendingEntry(entry, sessionId, project) {
   const pendingFile = join(RUNTIME_DIR, `pending-${ts}-${rand}.json`);
   const tmp = pendingFile + '.tmp';
   try {
-    writeFileSync(tmp, JSON.stringify({ entry, sessionId, project, ts }));
+    writeFileSync(tmp, JSON.stringify({ entry, sessionId, project, ts }), { mode: 0o600 });
     renameSync(tmp, pendingFile);
   } catch {
     try { unlinkSync(tmp); } catch {}

package/hook-memory.mjs

@@ -1,7 +1,7 @@
 // claude-mem-lite — Semantic Memory Injection
 // Search past observations for relevant memories to inject as context at user-prompt time.
 
-import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, truncate, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords, neutralizeContextDelimiters } from './utils.mjs';
+import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, truncate, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords, neutralizeContextDelimiters, basenameAnySep } from './utils.mjs';
 import { citeFactorJs } from './scoring-sql.mjs';
 import { recordMetric } from './lib/metrics.mjs';
 import { DB_DIR } from './schema.mjs';
@@ -376,7 +376,9 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
 export function recallForFile(db, filePath, project) {
   if (!db || !filePath) return [];
   try {
-    const basename = filePath.split('/').pop();
+    // Both separators: filePath comes from a hook payload written by the
+    // CLIENT's OS, so a Windows path can reach a POSIX host (and vice versa).
+    const basename = basenameAnySep(filePath);
     const cutoff = Date.now() - FILE_RECALL_LOOKBACK_MS;
     // Escape SQL LIKE wildcards in filename to prevent injection
     const escaped = basename.replace(/%/g, '\\%').replace(/_/g, '\\_');

package/hook-optimize.mjs

@@ -1,4 +1,8 @@
 // claude-mem-lite: LLM-powered database optimization
+// SHARED ENGINE — the `hook-` prefix is historical, not a scope. All three entry
+// surfaces import this: hook.mjs (handleLLMOptimize), server.mjs and mem-cli.mjs
+// (optimizePreview/optimizeRun), plus a lazy import from lib/save-enrich.mjs. Do not
+// assume hook-pipeline session lifecycle or single-writer concurrency here.
 // Background worker for intelligent maintenance: re-enrich, normalize, cluster-merge, smart-compress
 // Triggered from auto-maintain (24h) or manually via mem_optimize MCP tool / CLI
 

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, readdirSync, statSync, unlinkSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, readdirSync, statSync, unlinkSync, chmodSync } 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, detectMode as detectLLMMode, callHaiku } from './haiku-client.mjs';
@@ -114,8 +114,17 @@ export function sweepOrphanEpisodeFiles(runtimeDir, { ageMs = ORPHAN_EPISODE_AGE
   return count;
 }
 
-// Ensure runtime directory exists
-try { if (!existsSync(RUNTIME_DIR)) mkdirSync(RUNTIME_DIR, { recursive: true }); } catch {}
+// Ensure runtime directory exists AND is owner-only (0700), matching the DB dir
+// (schema.mjs). Runtime aux files carry captured file paths + scrubbed activity; on a
+// shared host a 0755 dir would let another local user read them. hardenRuntimeFiles()
+// (server.mjs) sweeps at MCP-server startup, but hooks routinely run before any server
+// exists, so harden here too: create 0700, and chmod a pre-existing dir a prior version
+// created at the default umask. A 0700 dir blocks traversal to every file inside,
+// current and future, regardless of individual file mode (audit sec P3-2 2026-07-24).
+try {
+  if (!existsSync(RUNTIME_DIR)) mkdirSync(RUNTIME_DIR, { recursive: true, mode: 0o700 });
+  else chmodSync(RUNTIME_DIR, 0o700);
+} catch {}
 
 // ─── Session ID Management ───────────────────────────────────────────────────
 
@@ -136,7 +145,7 @@ export function createSessionId() {
   const id = `hook-${project}-${randomUUID().slice(0, 8)}`;
   const file = sessionFile();
   const tmp = file + `.tmp-${process.pid}`;
-  writeFileSync(tmp, JSON.stringify({ id, startedAt: Date.now(), project }));
+  writeFileSync(tmp, JSON.stringify({ id, startedAt: Date.now(), project }), { mode: 0o600 });
   renameSync(tmp, file);
   return id;
 }

package/hook-update.mjs

@@ -480,7 +480,16 @@ async function fetchAssetBuffer(url) {
 // The CLAUDE_MEM_SKIP_SIG_VERIFY escape hatch still forces a skip. publicKey is a
 // param (defaulting to the embedded constant) only so tests can exercise both regimes.
 export async function verifyReleaseAuthenticity(extractedDir, assets, publicKey = RELEASE_PUBLIC_KEY) {
-  if (process.env.CLAUDE_MEM_SKIP_SIG_VERIFY) return { ok: true, action: 'skipped-env' };
+  if (process.env.CLAUDE_MEM_SKIP_SIG_VERIFY) {
+    // Loud on stderr, not via debugLog: this disables the strongest control in the
+    // update path, and debugLog is gated behind CLAUDE_MEM_DEBUG — the one case
+    // where silence is exactly wrong. An operator who set the var sees it; an
+    // attacker who set it in someone's environment loses the quiet.
+    process.stderr.write(
+      '[claude-mem-lite] WARNING: CLAUDE_MEM_SKIP_SIG_VERIFY is set — installing this release WITHOUT signature verification.\n'
+    );
+    return { ok: true, action: 'skipped-env' };
+  }
   if (!publicKey) return { ok: true, action: 'skipped-no-pubkey' };
 
   const list = Array.isArray(assets) ? assets : [];
@@ -518,6 +527,79 @@ export async function verifyReleaseAuthenticity(extractedDir, assets, publicKey
 // Undo a (partial or complete) file swap: delete the freshly-installed files, then
 // rename each backup back into place. Shared by the error path and the MED-5
 // post-install smoke gate so there is ONE rollback implementation.
+// Swap-window marker. The rename loop is atomic per FILE, not per file SET, so a
+// hook process that starts mid-loop can resolve hook.mjs from vN and one of its
+// imports from vN+1 — the install.lock only excludes concurrent WRITERS, not
+// readers. scripts/hook-launcher.mjs skips a fire while this marker is live;
+// hooks are best-effort, so losing one fire beats importing a mixed module graph.
+// Carries pid + ts because the launcher must never be muted permanently by an
+// updater that was killed mid-swap (it applies the same staleness bound).
+const SWAP_MARKER = join(STATE_DIR, 'runtime', 'swap-in-progress');
+// Intent journal, written INSIDE the backup dir before each rename. On a hard kill
+// the backup dir survives (every normal exit deletes it) and this file says exactly
+// which paths were in flight, so the next entry can finish the rollback at the right
+// granularity — a bare directory walk cannot tell a nested relPath from a directory
+// relPath like `node_modules`.
+const SWAP_JOURNAL = '.swap-journal.json';
+
+function markSwapStart() {
+  try {
+    mkdirSync(dirname(SWAP_MARKER), { recursive: true });
+    writeFileSync(SWAP_MARKER, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+  } catch (e) { debugCatch(e, 'markSwapStart'); }
+}
+
+function clearSwapMarker() {
+  try { rmSync(SWAP_MARKER, { force: true }); } catch (e) { debugCatch(e, 'clearSwapMarker'); }
+}
+
+// Write-ahead: journal the INTENT before the rename, never after. Journalling after
+// a successful rename leaves a window where the file has already moved into the
+// backup dir but nothing records it — recovery would then delete the backup dir with
+// the only copy of that file inside it. rollbackInstall guards every entry with
+// existsSync/force, so an intent that never happened is a harmless no-op.
+function journalSwap(backupDir, backedUp, installed) {
+  try {
+    writeFileSync(join(backupDir, SWAP_JOURNAL), JSON.stringify({ backedUp, installed }));
+  } catch (e) { debugCatch(e, 'journalSwap'); }
+}
+
+/**
+ * Finish any swap a previous process was killed in the middle of, then clear its
+ * residue. Called on every install entry, under the install lock, BEFORE a new
+ * staging/backup pair is created.
+ * @returns {number} number of interrupted swaps rolled back
+ */
+export function recoverInterruptedSwaps(targetDir = INSTALL_DIR) {
+  let entries;
+  try { entries = readdirSync(targetDir, { withFileTypes: true }); } catch { return 0; }
+
+  let recovered = 0;
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = join(targetDir, entry.name);
+
+    // Staging holds only copies — nothing was switched out of it, so it is residue,
+    // not a torn swap.
+    if (entry.name.startsWith('.update-staging-')) {
+      try { rmSync(dir, { recursive: true, force: true }); } catch (e) { debugCatch(e, 'recover-staging'); }
+      continue;
+    }
+    if (!entry.name.startsWith('.update-backup-')) continue;
+
+    let journal;
+    try { journal = JSON.parse(readFileSync(join(dir, SWAP_JOURNAL), 'utf8')); } catch { journal = null; }
+    const backedUp = Array.isArray(journal?.backedUp) ? journal.backedUp : [];
+    const installed = Array.isArray(journal?.installed) ? journal.installed : [];
+    // Copies: rollbackInstall reverses the arrays in place.
+    rollbackInstall([...installed], [...backedUp], dir, targetDir);
+    try { rmSync(dir, { recursive: true, force: true }); } catch (e) { debugCatch(e, 'recover-backup'); }
+    recovered++;
+    debugLog('WARN', 'hook-update', `Recovered an interrupted update swap: restored ${backedUp.length} path(s) from ${entry.name}`);
+  }
+  return recovered;
+}
+
 function rollbackInstall(installed, backedUp, backupDir, targetDir) {
   for (const relPath of installed.reverse()) {
     try { rmSync(join(targetDir, relPath), { recursive: true, force: true }); } catch { /* best-effort */ }
@@ -581,6 +663,11 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
   const switchablePaths = buildSwitchablePaths(manifest.SOURCE_FILES);
 
   try {
+    // Finish a prior swap that was hard-killed mid-rename before starting another
+    // one — otherwise this install stacks on top of a mixed-version tree and its
+    // own backup can no longer restore a coherent state.
+    recoverInterruptedSwaps(targetDir);
+
     mkdirSync(stagingDir, { recursive: true });
     mkdirSync(backupDir, { recursive: true });
 
@@ -593,23 +680,30 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
       });
     }
 
-    for (const relPath of switchablePaths) {
-      const stagedPath = join(stagingDir, relPath);
-      if (!existsSync(stagedPath)) continue;
+    markSwapStart();
+    try {
+      for (const relPath of switchablePaths) {
+        const stagedPath = join(stagingDir, relPath);
+        if (!existsSync(stagedPath)) continue;
 
-      const targetPath = join(targetDir, relPath);
-      const backupPath = join(backupDir, relPath);
+        const targetPath = join(targetDir, relPath);
+        const backupPath = join(backupDir, relPath);
 
-      mkdirSync(dirname(targetPath), { recursive: true });
-      mkdirSync(dirname(backupPath), { recursive: true });
+        mkdirSync(dirname(targetPath), { recursive: true });
+        mkdirSync(dirname(backupPath), { recursive: true });
 
-      if (existsSync(targetPath)) {
-        renameSync(targetPath, backupPath);
-        backedUp.push(relPath);
-      }
+        if (existsSync(targetPath)) {
+          backedUp.push(relPath);
+          journalSwap(backupDir, backedUp, installed);
+          renameSync(targetPath, backupPath);
+        }
 
-      renameSync(stagedPath, targetPath);
-      installed.push(relPath);
+        installed.push(relPath);
+        journalSwap(backupDir, backedUp, installed);
+        renameSync(stagedPath, targetPath);
+      }
+    } finally {
+      clearSwapMarker();
     }
 
     // MED-5: before discarding the rollback backup, prove the switched code boots.

package/hook.mjs

@@ -265,7 +265,7 @@ function flushEpisodeGroup(ep) {
 
   const flushFile = join(RUNTIME_DIR, `ep-flush-${Date.now()}-${randomUUID().slice(0, 8)}.json`);
   try {
-    writeFileSync(flushFile, JSON.stringify(ep));
+    writeFileSync(flushFile, JSON.stringify(ep), { mode: 0o600 }); // captured paths + scrubbed activity — owner-only (sec P3-2)
   } catch {
     return 'writefail';
   }
@@ -523,7 +523,7 @@ async function handleStop() {
               if (id) sub.savedId = id;
             } catch (e) { debugCatch(e, 'handleStop-fallback-immediateSave'); }
             const flushFile = join(RUNTIME_DIR, `ep-flush-${Date.now()}-${randomUUID().slice(0, 8)}.json`);
-            writeFileSync(flushFile, JSON.stringify(sub));
+            writeFileSync(flushFile, JSON.stringify(sub), { mode: 0o600 }); // captured paths + scrubbed activity — owner-only (sec P3-2)
             spawnBackground('llm-episode', flushFile);
           }
         }

package/install.mjs

@@ -3,7 +3,7 @@
 
 import { execSync, execFileSync } from 'child_process';
 import { readFileSync, writeFileSync, existsSync, rmSync, mkdirSync, mkdtempSync, copyFileSync, cpSync, renameSync, symlinkSync, unlinkSync, readdirSync, statSync, lstatSync } from 'fs';
-import { join, resolve, dirname, isAbsolute } from 'path';
+import { join, resolve, dirname, isAbsolute, basename } from 'path';
 import { homedir, tmpdir } from 'os';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { createRequire } from 'node:module';
@@ -433,7 +433,7 @@ if (IS_DEV) {
   try {
     const pruned = pruneStaleInstallFiles(DATA_DIR, SOURCE_FILES);
     if (pruned.length > 0) {
-      ok(`Pruned ${pruned.length} stale file(s): ${pruned.map(p => p.split('/').pop()).join(', ')}`);
+      ok(`Pruned ${pruned.length} stale file(s): ${pruned.map(p => basename(p)).join(', ')}`);
     }
   } catch (e) { /* prune is best-effort — never block install */ void e; }
 }

package/lib/recent-core.mjs

@@ -0,0 +1,56 @@
+// Shared "most recent live observations" core for cmdRecent (CLI `recent`) and
+// runRecent (MCP mem_recent).
+//
+// `recent` was the last retrieval command still hand-building its query on both
+// surfaces: the live-rows filter (COALESCE(compressed_into,0)=0 AND superseded_at
+// IS NULL), the optional project/type/since predicates, and the newest-first
+// ORDER BY + LIMIT existed twice, kept in sync by nothing. That WHERE-clause class
+// of drift has recurred three times (CHANGELOG v2.91.0 / v2.92.0 / v3.42.0), which
+// is why search / timeline / recall were each extracted to a core
+// (lib/search-core.mjs, lib/timeline-core.mjs, lib/recall-core.mjs). Same shape here:
+// the data contract lives in this file, argument parsing and rendering stay per-surface.
+//
+// Columns are the SUPERSET of what the two renderers read (CLI wants `importance`,
+// MCP wants `project`) — same convention as recall-core, so neither surface needs
+// its own SELECT list.
+
+const RECENT_COLS = 'id, type, title, subtitle, importance, project, created_at, created_at_epoch';
+
+// Upper bound on rows a single `recent` call may pull, shared so the cap can't
+// drift between surfaces. Pre-extraction this literal lived only in cmdRecent
+// (where the positional [N] path had once skipped it entirely, letting
+// `recent 999999` issue an uncapped full-table dump); mem_recent relied solely on
+// its zod max(100). Clamping here means neither surface can regrow that footgun.
+export const RECENT_MAX = 1000;
+
+/**
+ * Most recent live observations, newest first.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {object} opts
+ * @param {string|null} [opts.project]  Exact project key (already resolved by the caller).
+ * @param {string|null} [opts.type]     Observation type (already validated by the caller).
+ * @param {number|null} [opts.since]    Epoch-ms lower bound on created_at. Each surface
+ *   parses its own duration flag (`--since` / `date_since`) because the error dialects
+ *   differ (CLI fail() vs MCP throw); only the resolved bound crosses into the core.
+ * @param {number} [opts.limit=10]      Clamped to [1, RECENT_MAX].
+ * @returns {object[]} rows carrying RECENT_COLS
+ */
+export function fetchRecent(db, { project = null, type = null, since = null, limit = 10 } = {}) {
+  const params = [];
+  const wheres = ['COALESCE(compressed_into, 0) = 0', 'superseded_at IS NULL'];
+  if (project) { wheres.push('project = ?'); params.push(project); }
+  if (type) { wheres.push('type = ?'); params.push(type); }
+  if (Number.isFinite(since)) { wheres.push('created_at_epoch >= ?'); params.push(since); }
+
+  const safeLimit = Number.isInteger(limit) && limit > 0 ? Math.min(limit, RECENT_MAX) : 10;
+  params.push(safeLimit);
+
+  return db.prepare(`
+    SELECT ${RECENT_COLS}
+    FROM observations
+    WHERE ${wheres.join(' AND ')}
+    ORDER BY created_at_epoch DESC
+    LIMIT ?
+  `).all(...params);
+}

package/lib/save-observation.mjs

@@ -99,9 +99,16 @@ export function saveObservation(db, params) {
   const bigramText = cjkBigrams(indexText);
   const textField = bigramText ? safeContent + ' ' + bigramText : safeContent;
 
+  // Requested supersession targets, normalized before the transaction opens.
+  // Self-reference is filtered inside, once the new id exists.
+  const requestedSupersedes = [...new Set(
+    (Array.isArray(params.supersedes) ? params.supersedes : [])
+      .map(Number).filter((n) => Number.isInteger(n) && n > 0)
+  )];
+
   // Atomic: observation row + observation_files junction + observation_vectors
-  // (TF-IDF). Vector write is best-effort — vocab may be uninitialized on a
-  // fresh DB; failure must not roll back the observation.
+  // (TF-IDF) + supersession tombstones. Vector write is best-effort — vocab may be
+  // uninitialized on a fresh DB; failure must not roll back the observation.
   const saveTx = db.transaction(() => {
     // Manual-save shape: narrative=content, concepts/facts/files_read empty, no
     // subtitle/search_aliases (defaults). Column list single-sourced in lib/observation-write.
@@ -118,34 +125,36 @@ export function saveObservation(db, params) {
     // same indexText the FTS `text` field is built from.
     insertObservationVector(db, savedId, indexText);
 
-    return savedId;
-  });
-  const savedId = saveTx();
-
-  // P4 explicit supersession: tombstone + link prior observations this save
-  // overturns. Only same-project, currently-live rows are eligible — never
-  // tombstone another project's memory or re-stamp an already-superseded row —
-  // and never supersede the row we just wrote. superseded_at drops the row out of
-  // live search (all queries filter superseded_at IS NULL); superseded_by records
-  // WHICH observation replaced it (the missing link in finding #4). The column
-  // already exists (schema.mjs), so no migration is required.
-  let supersededIds = [];
-  const requested = Array.isArray(params.supersedes) ? params.supersedes : [];
-  const ids = [...new Set(
-    requested.map(Number).filter((n) => Number.isInteger(n) && n > 0 && n !== savedId)
-  )];
-  if (ids.length > 0) {
-    const ph = ids.map(() => '?').join(',');
-    const eligible = db.prepare(
-      `SELECT id FROM observations WHERE id IN (${ph}) AND project = ? AND superseded_at IS NULL`
-    ).all(...ids, project).map((r) => r.id);
-    if (eligible.length > 0) {
-      const ph2 = eligible.map(() => '?').join(',');
-      db.prepare(`UPDATE observations SET superseded_at = ?, superseded_by = ? WHERE id IN (${ph2})`)
-        .run(now.getTime(), savedId, ...eligible);
-      supersededIds = eligible;
+    // P4 explicit supersession: tombstone + link prior observations this save
+    // overturns. Only same-project, currently-live rows are eligible — never
+    // tombstone another project's memory or re-stamp an already-superseded row —
+    // and never supersede the row we just wrote. superseded_at drops the row out of
+    // live search (all queries filter superseded_at IS NULL); superseded_by records
+    // WHICH observation replaced it (the missing link in finding #4). The column
+    // already exists (schema.mjs), so no migration is required.
+    //
+    // Runs INSIDE the transaction: committing the correcting row without its
+    // tombstones leaves the contradiction supersession exists to retire — both the
+    // new row and the ones it overturns stay live behind `superseded_at IS NULL`.
+    // Write-the-correction and retire-its-predecessors is one unit or neither.
+    const ids = requestedSupersedes.filter((n) => n !== savedId);
+    let supersededIds = [];
+    if (ids.length > 0) {
+      const ph = ids.map(() => '?').join(',');
+      const eligible = db.prepare(
+        `SELECT id FROM observations WHERE id IN (${ph}) AND project = ? AND superseded_at IS NULL`
+      ).all(...ids, project).map((r) => r.id);
+      if (eligible.length > 0) {
+        const ph2 = eligible.map(() => '?').join(',');
+        db.prepare(`UPDATE observations SET superseded_at = ?, superseded_by = ? WHERE id IN (${ph2})`)
+          .run(now.getTime(), savedId, ...eligible);
+        supersededIds = eligible;
+      }
     }
-  }
+
+    return { savedId, supersededIds };
+  });
+  const { savedId, supersededIds } = saveTx();
 
   return {
     kind: 'saved',

package/lib/search-core.mjs

@@ -287,7 +287,13 @@ const SINGLE_MATCH_BANDS = [
  * Mutates `results` in place; callers re-sort afterwards.
  */
 export function normalizeCrossSourceScores(results, sourceKey) {
-  const scored = results.filter((r) => r.score !== null && r.score !== undefined && r.score !== 0);
+  // scoreScale:'vector' rows (the obs leg when the vector arm is on — RRF-fused
+  // ≈1/(60+rank) ≈ 0.02, or raw cosine ≈0.1-1) are NOT on the BM25 scale the lone-hit
+  // banding below assumes. Exclude them from globalMaxAbs so the cross-source ratio stays
+  // meaningful for BM25 sources, and band a lone vector hit neutrally rather than by an
+  // incomparable (near-zero) ratio that would always sink it (audit P2-12 2026-07-24).
+  const isVector = (r) => r.scoreScale === 'vector';
+  const scored = results.filter((r) => r.score !== null && r.score !== undefined && r.score !== 0 && !isVector(r));
   const globalMaxAbs = scored.length ? Math.max(...scored.map((r) => Math.abs(r.score))) : 0;
   for (const src of ['obs', 'session', 'prompt', 'event']) {
     // score === 0 stays out: for multi-row sources 0/maxAbs would be 0 anyway, and a
@@ -298,10 +304,18 @@ export function normalizeCrossSourceScores(results, sourceKey) {
     const srcResults = results.filter((r) => r[sourceKey] === src && r.score !== null && r.score !== undefined && r.score !== 0);
     if (srcResults.length === 0) continue;
     if (srcResults.length === 1) {
-      const ratio = globalMaxAbs > 0 ? Math.abs(srcResults[0].score) / globalMaxAbs : 0;
-      srcResults[0].score = SINGLE_MATCH_BANDS.find(([floor]) => ratio >= floor)[1];
+      if (isVector(srcResults[0])) {
+        // Vector-scaled lone hit: no BM25-comparable magnitude to band by → neutral mid
+        // (the MED-5 -0.5), neither sunk by a near-zero ratio nor inflated.
+        srcResults[0].score = -0.5;
+      } else {
+        const ratio = globalMaxAbs > 0 ? Math.abs(srcResults[0].score) / globalMaxAbs : 0;
+        srcResults[0].score = SINGLE_MATCH_BANDS.find(([floor]) => ratio >= floor)[1];
+      }
       continue;
     }
+    // Multi-row source (incl. a vector obs leg): within-source max-normalization pins the
+    // best to -1 on the source's own scale, so no cross-source magnitude assumption applies.
     const maxAbs = Math.max(...srcResults.map((r) => Math.abs(r.score)));
     if (maxAbs > 0) {
       for (const r of srcResults) r.score = r.score / maxAbs;

package/mem-cli.mjs

@@ -7,7 +7,7 @@ import { ensureDb, DB_PATH, DB_DIR, REGISTRY_DB_PATH } from './schema.mjs';
 import { truncate, typeIcon, inferProject, scrubSecrets } from './utils.mjs';
 import { resolveProject } from './project-utils.mjs';
 import { TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
-import { _resetVocabCache } from './tfidf.mjs';
+import { _resetVocabCache, vecTextForRow, vectorsEnabled } from './tfidf.mjs';
 import { autoBoostIfNeeded, reRankWithContext } from './search-scoring.mjs';
 import { searchObservationsHybrid } from './search-engine.mjs';
 import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady } from './deep-search.mjs';
@@ -42,9 +42,10 @@ import { readFileSync, existsSync, readdirSync } from 'fs';
 // move each cmdXxx into its own cli/<cmd>.mjs; mem-cli.mjs becomes pure dispatch.
 import { parseArgs, out, fail, relativeTime, fmtDateShort, parseIdToken, formatProbeHints, rejectBareStringFlags, suggestUnknownFlags, OBS_TIME_FIELDS, formatObsFieldValue } from './cli/common.mjs';
 import { saveObservation } from './lib/save-observation.mjs';
-import { rebuildObservationDerived, normalizeScope } from './lib/observation-write.mjs';
+import { rebuildObservationDerived, normalizeScope, insertObservationVector } from './lib/observation-write.mjs';
 import { EXPORT_COLUMNS_SQL } from './lib/export-columns.mjs';
 import { recallByFile } from './lib/recall-core.mjs';
+import { fetchRecent, RECENT_MAX } from './lib/recent-core.mjs';
 import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentTimeline, fetchTimelineWindow } from './lib/timeline-core.mjs';
 import { buildSearchFtsQuery, parseDateBounds, parseDuration, coreRunSearchPipeline } from './lib/search-core.mjs';
 import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
@@ -368,9 +369,8 @@ function cmdRecent(db, args) {
   // this cap, so `recent 999999` issued an uncapped `LIMIT 999999` full-table dump
   // while `recent --limit 999999` correctly rejected → default — exactly the
   // "none capped --limit dumps the whole set" footgun parseIntFlag was extracted
-  // to close (lib/cli-flags.mjs). Keep the literal in one place so the two paths
-  // can't drift apart again.
-  const RECENT_MAX = 1000;
+  // to close (lib/cli-flags.mjs). The literal now lives in lib/recent-core.mjs so
+  // the MCP surface is capped by the same number.
   // isNumericToken first: "2abc"→2 / "1e2"→1 are positive integers that the bare check
   // accepted silently; the positional path must reject garbage like the --limit flag does.
   const isValid = rawArg !== undefined && isNumericToken(rawArg) && Number.isInteger(rawLimit) && rawLimit > 0 && rawLimit <= RECENT_MAX;
@@ -400,25 +400,18 @@ function cmdRecent(db, args) {
     }
   }
 
-  const params = [];
-  const wheres = ['COALESCE(compressed_into, 0) = 0', 'superseded_at IS NULL'];
-  if (project) { wheres.push('project = ?'); params.push(project); }
-  if (type) { wheres.push('type = ?'); params.push(type); }
   // --since: relative lower bound on created_at (e.g. "recent 1000 --since 24h").
+  // Parsed here (not in the core) because the two surfaces reject a bad duration
+  // in their own dialect — CLI fail(), MCP throw.
+  let since = null;
   if (flags.since !== undefined) {
     const d = parseDuration(flags.since);
     if (!d.ok) { fail(`[mem] Invalid --since "${flags.since}". Use <N><unit>, e.g. 7d, 24h, 90m, 2w.`); return; }
-    wheres.push('created_at_epoch >= ?'); params.push(Date.now() - d.ms);
+    since = Date.now() - d.ms;
   }
-  params.push(limit);
 
-  const rows = db.prepare(`
-    SELECT id, type, title, subtitle, importance, created_at_epoch, created_at
-    FROM observations
-    WHERE ${wheres.join(' AND ')}
-    ORDER BY created_at_epoch DESC
-    LIMIT ?
-  `).all(...params);
+  // Shared core with MCP mem_recent: live-rows filter + ordering (lib/recent-core.mjs)
+  const rows = fetchRecent(db, { project, type, since, limit });
 
   if (jsonOutput) {
     out(JSON.stringify({
@@ -1704,6 +1697,9 @@ function cmdExport(db, args) {
   if (limitGiven && rows.length >= limit) {
     process.stderr.write(`[mem] Note: Results capped at ${limit}. Raise --limit or narrow --from/--to to export more.\n`);
   }
+  // Fidelity caveat at backup-creation time (mirrors the restore-side note). stderr,
+  // so stdout stays a clean JSON/JSONL stream for `export > backup.json`.
+  process.stderr.write('[mem] Note: export omits related_ids and supersession links (superseded rows are excluded) — content and value-signals round-trip, the relationship graph does not.\n');
 }
 
 // ─── Restore ───────────────────────────────────────────────────────────────
@@ -1751,6 +1747,8 @@ function cmdRestore(db, argv) {
   const num = (v) => Number.isFinite(Number(v)) ? Math.trunc(Number(v)) : 0;
 
   const dupCheck = db.prepare('SELECT id FROM observations WHERE project = ? AND title = ? AND created_at_epoch = ? LIMIT 1');
+  // Final field state of a restored row, for the post-signalUpdate vector rebuild below.
+  const vecRow = db.prepare('SELECT title, narrative, concepts, lesson_learned, search_aliases FROM observations WHERE id = ?');
   const signalUpdate = db.prepare(`UPDATE observations SET
       text = COALESCE(?, text),
       subtitle = ?, concepts = ?, facts = ?, search_aliases = ?, files_read = ?, branch = COALESCE(?, branch),
@@ -1808,6 +1806,15 @@ function cmdRestore(db, argv) {
         num(r.decay_seen_count), r.last_accessed_at ?? null,
         res.id,
       );
+      // The FTS `text` column re-syncs through the observations _au trigger, but the
+      // TF-IDF vector has no trigger: saveObservation vectorized title+content+lesson,
+      // so every field signalUpdate just applied (concepts, search_aliases) was missing
+      // from the restored row's vector. Rebuild from the row's FINAL state through the
+      // canonical vecTextForRow — the same text every other (re)build path uses. Reading
+      // the row back (rather than reusing the locals) keeps this identical to
+      // maintain-core's rebuildVectors. Skipped entirely while the vector arm is off,
+      // which is the default (lib/observation-write.mjs).
+      if (vectorsEnabled()) insertObservationVector(db, res.id, vecTextForRow(vecRow.get(res.id)));
       restored++;
     } catch (e) {
       malformed++;
@@ -1820,6 +1827,13 @@ function cmdRestore(db, argv) {
   const totalMalformed = malformed + parseFailures;
   const totalLines = rows.length + parseFailures;
   out(`[mem] Restore${dryRun ? ' (dry-run)' : ''}: ${restored} restored, ${skipped} duplicate(s) skipped, ${totalMalformed} malformed/failed from ${totalLines} row(s).`);
+  // Name the lossiness where the user meets it. Export omits related_ids and drops
+  // superseded rows, and restore re-inserts under fresh AUTOINCREMENT ids — so no
+  // cross-link can survive the round-trip. That is a deliberate format tradeoff (stored
+  // ids would be stale after the remap), but "N restored" alone reads as full fidelity.
+  if (restored > 0) {
+    out('[mem] Note: related_ids and supersession links are not carried across export/restore (ids are remapped on restore) — restored rows have no cross-links.');
+  }
 }
 
 // ─── Compress ────────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.56.0",
+  "version": "3.57.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).",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -87,6 +87,7 @@
     "lib/recall-core.mjs",
     "lib/timeline-core.mjs",
     "lib/search-core.mjs",
+    "lib/recent-core.mjs",
     "lib/rrf.mjs",
     "lib/compress-core.mjs",
     "lib/db-backup.mjs",
@@ -168,8 +169,10 @@
     "zod": "^4.3.6"
   },
   "overrides": {
-    "hono": ">=4.12.26",
-    "fast-uri": ">=3.1.2",
+    "hono": ">=4.12.31",
+    "@hono/node-server": ">=2.0.11",
+    "body-parser": ">=2.3.0",
+    "fast-uri": ">=3.1.4 <4",
     "ip-address": ">=10.1.1"
   },
   "devDependencies": {