claude-mem-lite 3.56.1 → 3.58.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.56.1",
+      "version": "3.58.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.1",
+  "version": "3.58.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/adopt-cli.mjs

@@ -22,6 +22,7 @@ import {
 } from './memdir.mjs';
 import {
   writeManaged, removeManaged, isAdopted as claudeMdIsAdopted,
+  hasResidue as claudeMdHasResidue,
   needsRefresh, migrateLegacyMemoryDir, hasLegacyMemdirSentinel,
   claudeMdPath, detailDocPath,
 } from './claudemd.mjs';
@@ -311,8 +312,8 @@ function statusAll() {
 
   const known = listKnownProjectDirs();
   let adoptedCount = 0;
-  for (const dir of known) if (claudeMdIsAdopted(dir, PLUGIN_SLUG)) adoptedCount++;
-  log(`[adopt --status] known projects (~/.claude.json): ${known.length} scanned, ${adoptedCount} with a CLAUDE.md managed block.`);
+  for (const dir of known) if (claudeMdHasResidue(dir, PLUGIN_SLUG)) adoptedCount++;
+  log(`[adopt --status] known projects (~/.claude.json): ${known.length} scanned, ${adoptedCount} with a CLAUDE.md managed block or partial residue (detail doc/state).`);
   if (adoptedCount > 0) log('[adopt --status] run `claude-mem-lite unadopt --all` to remove every CLAUDE.md block.');
 
   const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ? 'set' : 'unset';
@@ -347,16 +348,20 @@ function unadoptAll(args) {
 
   // 1. New scheme: scrub CLAUDE.md managed blocks across known project paths.
   const projectDirs = listKnownProjectDirs();
-  let blocks = 0;
+  let blocks = 0, partial = 0;
   for (const dir of projectDirs) {
-    if (!claudeMdIsAdopted(dir, PLUGIN_SLUG)) continue;
+    // hasResidue, not isAdopted: the sweep must also catch PARTIAL residue
+    // (block without detail doc, or an orphaned doc/state sidecar) —
+    // isAdopted's block-AND-doc gate skipped those projects forever.
+    if (!claudeMdHasResidue(dir, PLUGIN_SLUG)) continue;
     if (dryRun) {
-      log(`[unadopt --all --dry-run] ${dir} → would-remove CLAUDE.md block + detail doc`);
+      log(`[unadopt --all --dry-run] ${dir} → would-remove plugin residue (CLAUDE.md block and/or detail doc/state)`);
       blocks++;
       continue;
     }
     const r = removeManaged(dir, PLUGIN_SLUG);
     if (r.action === 'removed') { log(`[unadopt --all] ${dir} → removed`); blocks++; }
+    else { log(`[unadopt --all] ${dir} → cleaned partial residue (detail doc/state, no block)`); partial++; }
   }
 
   // 2. Legacy memory-dir cleanup across every memdir (foreign-content guarded).
@@ -372,7 +377,8 @@ function unadoptAll(args) {
   }
 
   log('');
-  log(`[unadopt --all] ${dryRun ? 'would remove' : 'removed'} ${blocks} CLAUDE.md block(s) across ${projectDirs.length} known project(s); ${legacy} legacy memory-dir sentinel(s) ${dryRun ? 'pending' : 'cleaned'}.`);
+  const partialNote = partial > 0 ? ` (+${partial} partial-residue cleanup(s))` : '';
+  log(`[unadopt --all] ${dryRun ? 'would remove' : 'removed'} ${blocks} CLAUDE.md block(s)${partialNote} across ${projectDirs.length} known project(s); ${legacy} legacy memory-dir sentinel(s) ${dryRun ? 'pending' : 'cleaned'}.`);
   if (projectDirs.length === 0) {
     log('[unadopt --all] no known projects found in ~/.claude.json — if a project was adopted but never opened in Claude Code, run `claude-mem-lite unadopt` from inside it.');
   }
@@ -389,7 +395,7 @@ export function cmdUnadopt(args = []) {
 
   const cwd = detectCwd();
   if (dryRun) {
-    const blockState = claudeMdIsAdopted(cwd, PLUGIN_SLUG) ? 'would-remove CLAUDE.md block + detail doc' : 'no CLAUDE.md block';
+    const blockState = claudeMdHasResidue(cwd, PLUGIN_SLUG) ? 'would-remove CLAUDE.md block + detail doc' : 'no CLAUDE.md block';
     const legacy = hasLegacyMemdirSentinel(cwd, PLUGIN_SLUG) ? 'would-clean legacy memory-dir sentinel' : 'no legacy residue';
     log(`[unadopt --dry-run] ${cwd}`);
     log(`  ${blockState}`);

package/claudemd.mjs

@@ -98,6 +98,20 @@ export function isAdopted(cwd, slug) {
   return blk.body !== null && existsSync(detailDocPath(cwd, slug));
 }
 
+/**
+ * Any trace of adoption that unadopt should clean: managed block OR detail doc
+ * OR state sidecar. Deliberately weaker than isAdopted (whose AND lets a
+ * half-written adopt self-heal on the next SessionStart): the unadopt sweep
+ * gated on isAdopted skipped partial residue forever — e.g. a user deleted the
+ * detail doc but the CLAUDE.md block remained, and `unadopt --all` never
+ * removed it. removeManaged cleans all three pieces, so sweep on any of them.
+ */
+export function hasResidue(cwd, slug) {
+  return readBlock(cwd, slug).body !== null
+    || existsSync(detailDocPath(cwd, slug))
+    || existsSync(stateFilePath(cwd, slug));
+}
+
 /**
  * Whether the installed block/doc has drifted from the shipped content — i.e.
  * a version bump or a template edit means we should refresh. Returns true when

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,9 +4,9 @@
 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 { ensureDbWithWalRecovery, DB_DIR } from './schema.mjs';
 import { getClaudePath as getClaudePathShared, resolveModel as resolveModelShared, flattenForCLI as _flattenForCLI, detectMode as detectLLMMode, callHaiku } from './haiku-client.mjs';
 // Phase D: invited-memory sentinel detection. memdir.mjs/claudemd.mjs only pull in
 // fs/path/os/crypto; adopt-content.mjs is pure strings. No circular deps —
@@ -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;
 }
@@ -145,7 +154,9 @@ export function createSessionId() {
 
 export function openDb() {
   try {
-    return ensureDb();
+    // WAL-corruption self-heal (was server.mjs-only): without it, hooks stayed
+    // silently dead (null DB) on a corrupt WAL until the next MCP server start.
+    return ensureDbWithWalRecovery();
   } catch {
     return null;
   }

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 */ }
@@ -553,6 +635,32 @@ function smokeInstalledRelease(targetDir) {
       const p = join(targetDir, entry);
       if (existsSync(p)) execSync(`${q(process.execPath)} --check ${q(p)}`, { timeout: 10000, stdio: 'ignore' });
     }
+    // `cli.mjs help` exits without opening the DB, so it cannot see a
+    // present-but-unusable better-sqlite3 binding: npm >= 12 blocks
+    // install/lifecycle scripts by default, so the staging `npm install`
+    // above exits 0 with the native .node never compiled (a Node major bump
+    // strands a stale ABI the same way). Direct installs register server.mjs
+    // without the launch.mjs probe, so this gate is their only check. Probe
+    // in a child process (execSync so the unit-test mock intercepts, and so
+    // the running old-version process's require cache can't mask it); on
+    // failure rebuild with scripts enabled for just this dep — plain-rebuild
+    // fallback for older npm — then re-probe. A still-broken binding throws
+    // out of the try, smoke fails, and the caller rolls back to the old
+    // (working) install.
+    if (existsSync(join(targetDir, 'node_modules', 'better-sqlite3'))) {
+      const probeSrc = 'const{createRequire}=require("node:module");const D=createRequire(process.argv[1])("better-sqlite3");new D(":memory:").close();';
+      const probeCmd = `${q(process.execPath)} -e ${q(probeSrc)} ${q(join(targetDir, 'package.json'))}`;
+      try {
+        execSync(probeCmd, { timeout: 20000, stdio: 'ignore' });
+      } catch {
+        try {
+          execSync('npm rebuild better-sqlite3 --dangerously-allow-all-scripts', { cwd: targetDir, timeout: 120000, stdio: 'ignore' });
+        } catch {
+          execSync('npm rebuild better-sqlite3', { cwd: targetDir, timeout: 120000, stdio: 'ignore' });
+        }
+        execSync(probeCmd, { timeout: 20000, stdio: 'ignore' });
+      }
+    }
     return true;
   } catch (e) {
     debugLog('WARN', 'hook-update', `post-install smoke failed (rolling back): ${e.message}`);
@@ -581,6 +689,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 +706,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; }
 }
@@ -466,7 +466,7 @@ if (IS_DEV) {
     ok(`better-sqlite3: ${verify.action}`);
   } else {
     fail(`better-sqlite3 binding unusable after rebuild: ${verify.error}`);
-    log('Try manually: cd ' + INSTALL_DIR + ' && npm rebuild better-sqlite3 --build-from-source');
+    log('Try manually: cd ' + INSTALL_DIR + ' && npm rebuild better-sqlite3 --dangerously-allow-all-scripts');
     process.exit(1);
   }
 }

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;