claude-mem-lite 3.35.2 → 3.36.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.35.2",
+      "version": "3.36.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.35.2",
+  "version": "3.36.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/bash-utils.mjs

@@ -53,7 +53,13 @@ function isExcludedPath(p) {
  * @returns {{isError: boolean, isTest: boolean, isBuild: boolean, isGit: boolean, isDeploy: boolean, isSignificant: boolean}}
  */
 export function detectBashSignificance(input, response) {
-  const cmd = (input.command || '').toLowerCase();
+  // Coerce command to a string at the source. A malformed PostToolUse payload can
+  // hand us a non-string `command` (object/number); `(input.command||'').toLowerCase()`
+  // then threw, and this is called UNGUARDED in the hottest hook path (hook.mjs:309) —
+  // the throw propagated to main()'s exit(0), dropping the ENTIRE tool event (no episode
+  // entry, not even a pending file). A non-string command has nothing to analyze, so
+  // degrading to '' (no significance) is the correct, event-preserving fallback.
+  const cmd = (typeof input?.command === 'string' ? input.command : '').toLowerCase();
   // Skip error keyword matching only when the PRIMARY command is a read/search op (its
   // output naturally contains "error"-like keywords that aren't failures). Anchored on the
   // primary command — NOT "search verb appears anywhere" — so `npm run build 2>&1 | tail`

package/deep-search.mjs

@@ -454,12 +454,19 @@ export async function deepSearch(db, params, { llm, searchFn = defaultSearchFn,
     // it does on the single-query baseline path, so "never worse than baseline"
     // holds in the error dimension too — a DB failure must not be silently
     // swallowed into an empty result (F5). Only rewrite variants are best-effort.
-    if (i === 0) return searchFn(db, v, params) || [];
-    try {
-      return searchFn(db, v, params) || [];
-    } catch {
-      return [];
-    }
+    let list;
+    if (i === 0) list = searchFn(db, v, params) || [];
+    else { try { list = searchFn(db, v, params) || []; } catch { list = []; } }
+    // rrfFuseN fuses by array index as rank, so each list MUST already be in
+    // composite-score order. searchObservationsHybrid appends downweighted
+    // concept(×0.7)/PRF(×0.6) expansion rows to the TAIL unsorted and, on the
+    // vectors-disabled path, returns BEFORE the sort its vector arm applies
+    // (search-engine.mjs:430) — so a sparse variant (common in deep search, the
+    // vocabulary-mismatch path) would hand a tail-ranked expansion row to RRF at a
+    // worse rank than its score earns. Sort so index == composite rank, mirroring
+    // the in-engine sort that already guards the vector-RRF merge.
+    list.sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
+    return list;
   });
 
   const fused = rrfFuseN(lists, rrfK);

package/format-utils.mjs

@@ -74,10 +74,14 @@ export function neutralizeContextDelimiters(s) {
 export function formatErrorRecallHints(rows) {
   if (!rows || rows.length === 0) return '';
   const lines = rows.map((r, i) => {
-    const head = `  #${r.id} [${r.type}] ${truncate(r.title, 60)}`;
+    // Defang title + lesson: this block is written to PostToolUse stdout \u2192 model context,
+    // and observations are stored raw (defense is at the injection boundary, not at save),
+    // so a poisoned lesson carrying a forged <system-reminder>/tool tag would inject here
+    // un-neutralized. Same guard the handoff render applies to its replayed fields.
+    const head = `  #${r.id} [${r.type}] ${neutralizeContextDelimiters(truncate(r.title, 60))}`;
     // Inline the lesson body for the single most-relevant hit only (bounded payload).
     if (i === 0 && typeof r.lesson_learned === 'string' && r.lesson_learned.trim()) {
-      return `${head} \u2014 ${truncate(r.lesson_learned.trim(), 200)}`;
+      return `${head} \u2014 ${neutralizeContextDelimiters(truncate(r.lesson_learned.trim(), 200))}`;
     }
     return head;
   });

package/hook-context.mjs

@@ -79,6 +79,11 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
     SELECT id, type, title, narrative, importance, created_at_epoch, files_modified, lesson_learned
     FROM observations
     WHERE project = ? AND COALESCE(compressed_into, 0) = 0
+      -- superseded invisibility: auto-dedup (hook.mjs) sets superseded_at but leaves
+      -- compressed_into=0, so the compressed filter alone lets the hidden near-duplicate
+      -- resurface in the most-visible surface (injected every SessionStart). Sibling
+      -- keyObs already filters this; obsPool + fallbackObs must match.
+      AND superseded_at IS NULL
       AND ${notLowSignalTitleClause('')}
       AND (
         (created_at_epoch > ? AND importance >= 1)
@@ -116,7 +121,12 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
     const impBoost = 0.5 + 0.5 * (o.importance || 1);
     const lessonBoost = o.lesson_learned ? 1.3 : 1.0;
     const value = recency * typeQuality * impBoost * lessonBoost;
-    const cost = estimateTokens((o.title || '') + (o.narrative || ''));
+    // Cost = ONLY what is injected. The Recent table renders title-only (narrative is neither
+    // pushed nor emitted), so charging title+narrative made the budget measure ~5x the real
+    // injected size — it filled to ~44% of capacity and, worse, the √cost density term penalized
+    // long-narrative rows that cost nothing to inject. Title-only cost fills the budget with the
+    // rows actually shown and makes valueDensity = value per injected token.
+    const cost = estimateTokens(o.title || '');
     return { ...o, value, cost, valueDensity: cost > 0 ? value / Math.sqrt(cost) : 0 };
   });
 
@@ -294,6 +304,7 @@ export function buildSessionContextLines(db, project, now = new Date(), currentC
       SELECT id, type, title, project, created_at
       FROM observations
       WHERE COALESCE(compressed_into, 0) = 0
+        AND superseded_at IS NULL
         AND (
           (created_at_epoch > ? AND importance >= 1)
           OR (created_at_epoch > ? AND importance >= 2)

package/hook-handoff.mjs

@@ -136,10 +136,13 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
     try {
       const tasks = taskReaderModule.readProjectTasks({ projectPath: process.cwd() });
       if (tasks.length > 0) {
+        // Join with the ENTRY separator ('; '), NOT '\n': extractUnfinishedSummary
+        // and renderHandoffFromRow split pending work on UNFINISHED_ENTRY_SEP, so a
+        // '\n'-join collapsed the whole task list into one unreadable multi-line bullet.
         unfinished = tasks
           .slice(0, 5)
           .map(t => `[${t.status}] ${t.title}`)
-          .join('\n');
+          .join(UNFINISHED_ENTRY_SEP);
       }
     } catch { /* task reader is best-effort; never block handoff */ }
   }
@@ -227,7 +230,7 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
     project, type, storedSessionId,
     truncate(safe.working_on, 1000),
     safe.completed,
-    safe.unfinished.length > 3000 ? safe.unfinished.slice(0, 2999) + '…' : safe.unfinished,
+    safe.unfinished.length > 3000 ? Array.from(safe.unfinished).slice(0, 2999).join('') + '…' : safe.unfinished,
     safeKeyFiles,
     safe.key_decisions,
     safe.match_keywords,
@@ -441,7 +444,10 @@ function renderHandoffFromRow(handoff, db, project) {
   if (handoff.key_files) {
     try {
       const files = JSON.parse(handoff.key_files);
-      if (files.length > 0) lines.push('## Key Files', files.map(f => basename(f)).join(', '), '');
+      // Defang basenames too: a filename on disk can contain a literal authority tag
+      // (Linux allows almost any char but '/'), and this is the one field in this block
+      // that was rendered raw while working_on/unfinished/key_decisions all neutralize.
+      if (files.length > 0) lines.push('## Key Files', neutralizeContextDelimiters(files.map(f => basename(f)).join(', ')), '');
     } catch {}
   }
   if (handoff.key_decisions) {

package/hook-memory.mjs

@@ -118,7 +118,12 @@ const STALE_OBS_THRESHOLD_MS = 30 * 86400000;
  * @returns {string} `- [type] title[ | Lesson: X] (#id)[ [verify-before-use]]`
  */
 export function formatMemoryLine(obs) {
-  const lessonTag = obs.lesson_learned ? ` | Lesson: ${obs.lesson_learned}` : '';
+  // truncate (not raw): caps the per-hit token cost (an unbounded lesson bloated every
+  // memory-context line) AND collapses newlines — a multi-line lesson pushed the trailing
+  // "(#NN)" onto a later physical line that failed the "- [" prefix gate in
+  // citation-tracker's UserPromptSubmit extractor, so the obs never entered the
+  // citation-decay denominator (its promote/demote loop was silently dead).
+  const lessonTag = obs.lesson_learned ? ` | Lesson: ${truncate(obs.lesson_learned, 200)}` : '';
   let staleHint = '';
   if (typeof obs.created_at_epoch === 'number'
     && Date.now() - obs.created_at_epoch > STALE_OBS_THRESHOLD_MS
@@ -310,7 +315,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     // Adaptive threshold: scales with corpus size to filter noise.
     // Each result must individually exceed the threshold (not just the top one).
     const obsCount = db.prepare(
-      'SELECT COUNT(*) as c FROM observations WHERE project = ? AND COALESCE(compressed_into, 0) = 0',
+      'SELECT COUNT(*) as c FROM observations WHERE project = ? AND COALESCE(compressed_into, 0) = 0 AND superseded_at IS NULL',
     ).get(project)?.c || 0;
     const { TINY, SMALL, MEDIUM, LARGE } = BM25_THRESHOLD;
     const threshold = obsCount < 5 ? TINY : obsCount < 100 ? SMALL : obsCount < 500 ? MEDIUM : LARGE;
@@ -422,6 +427,7 @@ export function selectImperativeLesson(db, userPrompt, project, excludeIds = [])
       FROM observations
       WHERE project = ?
         AND COALESCE(compressed_into, 0) = 0
+        AND superseded_at IS NULL
         AND COALESCE(importance, 1) >= 2
         AND lesson_learned IS NOT NULL
         AND TRIM(lesson_learned) != ''

package/hook-optimize.mjs

@@ -539,6 +539,14 @@ export function findSmartCompressCandidates(db, ageDays = 30, { project } = {})
     WHERE COALESCE(compressed_into, 0) = 0
       AND COALESCE(importance, 1) = 1
       AND COALESCE(access_count, 0) = 0
+      -- Never auto-compress a lesson-bearing row. Smart-compress sets compressed_into
+      -- on the originals (line ~693), which hides them from every injection/search
+      -- surface AND puts them out of recoverBuriedLessons' reach (it only lifts
+      -- compressed_into=0). A lesson demoted to imp=1 by citation-decay would be
+      -- silently buried by the unattended 24h llm-optimize run. Exact parity with the
+      -- canonical compress sibling selectCompressionCandidates (compress-core.mjs) —
+      -- "lessons never auto-GC" (also enforced in decayAndMarkIdle, maintain-core.mjs).
+      AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
       AND created_at_epoch < ?
       ${projectClause}
     ORDER BY project, created_at_epoch

package/hook-shared.mjs

@@ -75,22 +75,35 @@ export const CONTINUE_KEYWORDS = /继续|接着|上次|之前的|前面的|刚
 // caller will ever pick up, so sweeping them on SessionStart is safe.
 export const ORPHAN_EPISODE_AGE_MS = 60 * 60 * 1000;
 
-// Sweep stale `ep-flush-*` and `pending-*` files in `runtimeDir` whose mtime
-// is older than `ageMs` (default 1h). Returns the number of files removed.
-// fs-only — no DB / no network. Used by handleSessionStart auto-maintain to
-// prevent the doctor "Stale temp files" warning from accumulating across
-// crashes; equivalent to the manual path in `node install.mjs cleanup` but
-// age-gated so concurrent in-flight workers are never raced.
-export function sweepOrphanEpisodeFiles(runtimeDir, { ageMs = ORPHAN_EPISODE_AGE_MS, now = Date.now() } = {}) {
+// `reads-<project>.txt` (bash fast-path Read tracker) is consumed by flushEpisode's
+// rename-collect on the next edit-flush, NOT by a background worker — so a project
+// that reads but never triggers an edit-flush leaves it uncollected and unswept, and
+// it grows without bound (the 1h episode threshold is far too eager: a long read-only
+// investigation legitimately appends to it for hours). A dedicated 24h floor sweeps
+// only genuinely-abandoned trackers (no append AND no flush in a day → its paths are
+// stale to any current episode) while leaving every active session's file untouched.
+export const ORPHAN_READS_AGE_MS = 24 * 60 * 60 * 1000;
+
+// Sweep stale `ep-flush-*` / `pending-*` (older than `ageMs`, default 1h) and
+// `reads-*.txt` (older than `readsAgeMs`, default 24h) files in `runtimeDir` by
+// mtime. Returns the number of files removed. fs-only — no DB / no network. Used by
+// handleSessionStart auto-maintain to prevent the doctor "Stale temp files" warning
+// from accumulating across crashes; equivalent to the manual path in
+// `node install.mjs cleanup` but age-gated so concurrent in-flight workers / active
+// read sessions are never raced.
+export function sweepOrphanEpisodeFiles(runtimeDir, { ageMs = ORPHAN_EPISODE_AGE_MS, readsAgeMs = ORPHAN_READS_AGE_MS, now = Date.now() } = {}) {
   let entries;
   try { entries = readdirSync(runtimeDir); } catch { return 0; }
   const cutoff = now - ageMs;
+  const readsCutoff = now - readsAgeMs;
   let count = 0;
   for (const f of entries) {
-    if (!(f.startsWith('ep-flush-') || f.startsWith('pending-'))) continue;
+    const isEpisode = f.startsWith('ep-flush-') || f.startsWith('pending-');
+    const isReads = f.startsWith('reads-') && f.endsWith('.txt');
+    if (!isEpisode && !isReads) continue;
     const full = join(runtimeDir, f);
     try {
-      if (statSync(full).mtimeMs < cutoff) {
+      if (statSync(full).mtimeMs < (isReads ? readsCutoff : cutoff)) {
         unlinkSync(full);
         count++;
       }

package/hook-update.mjs

@@ -187,7 +187,7 @@ function shouldCheck(state) {
 
 // ── GitHub API ─────────────────────────────────────────────
 // Try releases/latest first, fallback to tags (some repos only use tags)
-async function fetchLatestRelease() {
+export async function fetchLatestRelease() {
   const headers = {
     'Accept': 'application/vnd.github+json',
     'User-Agent': 'claude-mem-lite-updater/1.0',
@@ -235,7 +235,10 @@ async function fetchWithTimeout(url, headers) {
   const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
   try {
     const res = await fetch(url, { signal: controller.signal, headers });
-    if (res.status === 403) {
+    if (res.status === 403 || res.status === 429) {
+      // 429 = GitHub secondary rate limit (403 = primary). Both must route to the 6h
+      // rate-limit backoff, not the 24h transient-failure path — else a 429 defers the
+      // next check a full day instead of retrying on the shorter rate-limit cadence.
       const state = readState();
       saveState({ ...state, rateLimited: true });
       debugLog('DEBUG', 'hook-update', 'GitHub API rate limited; will retry on the 6h rate-limit cadence');

package/hook.mjs

@@ -118,12 +118,13 @@ for (const sig of ['SIGTERM', 'SIGINT']) {
       try {
         const ep = readEpisodeRaw();
         if (ep && ep.entries && ep.entries.length > 0) {
-          // Persist a rule-based observation synchronously BEFORE writing the flush
-          // file — that file has no consumer, so this is the only thing that prevents
-          // the in-flight episode being lost on abnormal termination (audit #6).
+          // Persist a rule-based observation synchronously — the ONLY thing that
+          // salvages the in-flight episode on abnormal termination (audit #6). A
+          // detached llm-episode child can't be spawned from a dying process, so no
+          // ep-flush-* file is written here: it would have NO consumer AND would make
+          // every later handleLLMSummary poll the full CLAUDE_MEM_FLUSH_TIMEOUT (~15s)
+          // waiting for a file that only the 24h orphan-sweep ever removes.
           saveEpisodeImmediate(ep);
-          const flushFile = join(RUNTIME_DIR, `ep-flush-${Date.now()}-${randomUUID().slice(0, 8)}.json`);
-          writeFileSync(flushFile, JSON.stringify(ep));
           try { unlinkSync(join(RUNTIME_DIR, `ep-${inferProject()}.json`)); } catch {}
         }
       } catch {}
@@ -468,16 +469,24 @@ async function handleStop() {
         if (episode && episode.entries && episode.entries.length > 0 && episodeHasSignificantContent(episode)) {
           if (!episode.sessionId) episode.sessionId = sessionId;
           if (!episode.project) episode.project = project;
-          // Immediate save: persist rule-based observation to DB before spawning background worker.
-          // Without this, data is lost if the background worker fails.
-          try {
-            const obs = buildImmediateObservation(episode);
-            const id = saveObservation(obs, episode.project, episode.sessionId);
-            if (id) episode.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(episode));
-          spawnBackground('llm-episode', flushFile);
+          // Split by CC session before saving — parity with flushEpisode's non-contended path
+          // (v3.35.2). Without this, the lock-contended fallback re-merged exactly the interleaved
+          // concurrent-session buffers v3.35.2 split apart, co-attributing two sessions' work into
+          // one garbled observation. planEpisodeFlush returns [episode] by reference for the common
+          // single-session case, so this is a no-op there. Immediate-save each group BEFORE its
+          // flush-file write (same ordering as flushEpisodeGroup) so a worker crash can't lose it.
+          for (const sub of planEpisodeFlush(episode)) {
+            if (!sub.sessionId) sub.sessionId = sessionId;
+            if (!sub.project) sub.project = project;
+            try {
+              const obs = buildImmediateObservation(sub);
+              const id = saveObservation(obs, sub.project, sub.sessionId);
+              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));
+            spawnBackground('llm-episode', flushFile);
+          }
         }
       } finally {
         try { unlinkSync(claimFile); } catch {}

package/install.mjs

@@ -1979,30 +1979,52 @@ async function manualUpdate() {
 // latest code even when local install.mjs / hook-update.mjs are themselves
 // buggy on disk.
 async function repair() {
-  console.log('\nclaude-mem-lite repair — re-syncing from latest GitHub release\n');
+  console.log('\nclaude-mem-lite repair — re-syncing from the latest SIGNED GitHub release\n');
   const stagingDir = mkdtempSync(join(tmpdir(), 'claude-mem-lite-repair-'));
   try {
-    const tarballUrl = 'https://api.github.com/repos/sdsrss/claude-mem-lite/tarball';
+    // Resolve the latest RELEASE (tag) and cryptographically VERIFY it before running any
+    // downloaded code — parity with the auto-update path (hook-update.downloadAndInstall).
+    // The old code fetched `/tarball` (default-branch main HEAD, unreleased WIP) and ran its
+    // install.mjs UNVERIFIED, and this path is auto-triggered by hook-launcher on any
+    // ERR_MODULE_NOT_FOUND — so a drifted install silently self-healed onto main, and a
+    // repo/TLS-MITM compromise achieved RCE, bypassing the Ed25519 signed-release control that
+    // the manual `update` path enforces. Lazy import so a missing/broken hook-update dependency
+    // degrades to the manual fallback (fail-closed) rather than to unverified auto-install.
+    let fetchLatestRelease, verifyReleaseAuthenticity;
+    try {
+      ({ fetchLatestRelease, verifyReleaseAuthenticity } = await import('./hook-update.mjs'));
+    } catch (e) {
+      throw new Error(`cannot load the verified-update path (${e.message}) — refusing to auto-install unverified code`, { cause: e });
+    }
+    const rel = await fetchLatestRelease();
+    if (!rel || !rel.tarballUrl) throw new Error('could not resolve the latest release (network / rate-limit)');
+    // URL allow-list mirrors hook-update.downloadAndInstall — only github.com tarball URLs.
+    if (!/^https:\/\/(?:api\.)?github\.com\/[a-zA-Z0-9./_-]+$/.test(rel.tarballUrl)) {
+      throw new Error(`refusing suspicious tarball URL: ${rel.tarballUrl}`);
+    }
     const tarballPath = join(stagingDir, 'release.tgz');
-    log('Downloading latest release tarball...');
-    execFileSync('curl', ['-sL', '-f', '-H', 'Accept: application/vnd.github+json', tarballUrl, '-o', tarballPath],
+    log(`Downloading release v${rel.version}...`);
+    execFileSync('curl', ['-sL', '-f', '-H', 'Accept: application/vnd.github+json', rel.tarballUrl, '-o', tarballPath],
       { timeout: 60000, stdio: ['ignore', 'pipe', 'inherit'] });
     log('Extracting...');
     execFileSync('tar', ['xzf', tarballPath, '-C', stagingDir, '--strip-components=1'],
       { timeout: 30000, stdio: ['ignore', 'pipe', 'inherit'] });
+    // Verify the Ed25519 signature BEFORE running the downloaded install.mjs. Fail-closed:
+    // any tampering / missing-signature / fetch-failure aborts to the manual fallback.
+    log('Verifying release signature...');
+    const authentic = await verifyReleaseAuthenticity(stagingDir, rel.assets);
+    if (!authentic.ok) throw new Error(`release signature check failed (${authentic.action})`);
     const tarballInstaller = join(stagingDir, 'install.mjs');
-    if (!existsSync(tarballInstaller)) {
-      fail('Tarball missing install.mjs — repair aborted');
-      process.exit(1);
-    }
-    log('Re-running install from freshly-downloaded sources...');
+    if (!existsSync(tarballInstaller)) throw new Error('verified tarball missing install.mjs');
+    log('Re-running install from the verified release sources...');
     execFileSync(process.execPath, [tarballInstaller, 'install'],
       { stdio: 'inherit', timeout: 300000 });
-    ok('Repair complete — broken install resynced from latest release');
+    ok(`Repair complete — resynced from verified release v${rel.version}`);
   } catch (e) {
     fail(`Repair failed: ${e.message}`);
     console.log('');
-    console.log('  Manual fallback — run this in any shell:');
+    console.log('  Automatic repair fails closed rather than run unverified code.');
+    console.log('  Manual fallback — run this in any shell (you are choosing to trust it):');
     console.log('');
     console.log('  T=$(mktemp -d) && curl -sL https://api.github.com/repos/sdsrss/claude-mem-lite/tarball | tar xz -C "$T" --strip-components=1 && node "$T/install.mjs" install');
     console.log('');

package/lib/atomic-write.mjs

@@ -8,7 +8,7 @@
 // This writes to a pid-unique temp then renames (atomic on POSIX), and can drop
 // a one-time ".bak" so a logic bug in the caller's merge is recoverable.
 
-import { writeFileSync, renameSync, existsSync, copyFileSync, mkdirSync } from 'node:fs';
+import { writeFileSync, renameSync, existsSync, copyFileSync, mkdirSync, lstatSync, realpathSync } from 'node:fs';
 import { dirname } from 'node:path';
 
 /**
@@ -22,17 +22,28 @@ import { dirname } from 'node:path';
  *   preserves the last-known-good rather than being overwritten each run.
  */
 export function atomicWriteFileSync(filePath, data, { backup = false } = {}) {
-  const dir = dirname(filePath);
+  // Write THROUGH a symlink to its real target. renameSync onto a symlink NAME replaces the
+  // link with a regular file, silently orphaning a dotfiles-managed (chezmoi/stow/yadm)
+  // config: ~/.claude/settings.json (and ~/.claude.json) get severed from the dotfiles
+  // repo, so future dotfiles edits stop applying and .bak captures the wrong content.
+  // Resolve first, then put the temp in the TARGET's dir so the rename stays same-device
+  // (atomic, no EXDEV). A broken/absent symlink falls through to a direct write.
+  let target = filePath;
+  try {
+    if (lstatSync(filePath).isSymbolicLink()) target = realpathSync(filePath);
+  } catch { /* not a symlink, or missing — write filePath directly */ }
+
+  const dir = dirname(target);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 
-  if (backup && existsSync(filePath) && !existsSync(filePath + '.bak')) {
-    try { copyFileSync(filePath, filePath + '.bak'); } catch { /* best-effort backup */ }
+  if (backup && existsSync(target) && !existsSync(target + '.bak')) {
+    try { copyFileSync(target, target + '.bak'); } catch { /* best-effort backup */ }
   }
 
   // pid-unique temp: a fixed ".tmp" name lets two concurrent installs clobber
-  // each other's temp mid-write. Same-dir temp keeps the rename atomic (no
-  // cross-device move).
-  const tmp = `${filePath}.tmp-${process.pid}`;
+  // each other's temp mid-write. Same-dir-as-target temp keeps the rename atomic (no
+  // cross-device move) even when the target lives in a dotfiles repo on another mount.
+  const tmp = `${target}.tmp-${process.pid}`;
   writeFileSync(tmp, data);
-  renameSync(tmp, filePath);
+  renameSync(tmp, target);
 }

package/lib/deferred-work.mjs

@@ -119,7 +119,9 @@ export function resolveDeferredIds(db, project, tokens) {
         throw new Error(`D#${id} belongs to project "${row.project}", not "${project}"`);
       }
       if (row.status !== 'open') {
-        throw new Error(`D#${id} status is "${row.status}", cannot close (only 'open' items)`);
+        // Verb-neutral: resolveDeferredIds is shared by close (save --closes-deferred)
+        // AND drop (mem_defer_drop), so "cannot close" mis-described the drop path.
+        throw new Error(`D#${id} status is "${row.status}" — only 'open' items can be closed or dropped`);
       }
     } else {
       throw new Error(`invalid token type ${typeof t} — expected D#N or integer ordinal`);

package/lib/doctor-benchmark.mjs

@@ -110,7 +110,12 @@ export function runBenchmark(db, { prompts = [], project = 'mem', skipHookLatenc
    * Returns true iff the simulator would produce a non-empty injection.
    */
   const runInjection = (promptText) => {
-    if (!promptText || promptText.trim().length < 15) return false;
+    // Mirror the real hook's min-length gate (hook-memory.mjs searchRelevantMemories):
+    // 5-char floor for non-CJK, 2 for CJK. The old flat 15 was 3x stricter and dropped
+    // every 5-14-char prompt (and all 2-14-char CJK) the live hook processes, so the
+    // simulated injection_rate systematically under-counted "how often memory fires".
+    const cjk = /[一-鿿㐀-䶿]/.test(promptText || '');
+    if (!promptText || promptText.length < (cjk ? 2 : 5)) return false;
     const q = sanitizeFtsQuery(promptText);
     if (!q) return false;
     try {

package/lib/maintain-core.mjs

@@ -145,6 +145,12 @@ export function cleanupBroken(db, { projectFilter, baseParams, opCap = OP_CAP })
     SELECT id FROM observations
     WHERE COALESCE(compressed_into, 0) = 0
       AND (title IS NULL OR title = '') AND (narrative IS NULL OR narrative = '')
+      -- A lesson-bearing row is NOT "broken" — it still carries the distilled value,
+      -- so empty title+narrative isn't grounds to hard-delete it (a degenerate
+      -- cluster-merge can write merged_title='' onto a row that kept a synthesized
+      -- lesson). Parity with the "lessons never auto-GC" guards in
+      -- decayAndMarkIdle / selectCompressionCandidates / findSmartCompressCandidates.
+      AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
       ${projectFilter} LIMIT ${opCap}
   `).all(...baseParams).map(r => r.id);
   if (!doomed.length) return 0;
@@ -329,6 +335,12 @@ export function purgeStalePreview(db, { projectFilter, baseParams }, retainCutof
 
 /** Delete pending-purge observations older than the retain cutoff. Returns rows deleted. */
 export function purgeStale(db, { projectFilter, baseParams, opCap = OP_CAP }, retainCutoff) {
+  // No lesson guard HERE by design: this hard-DELETE only touches rows already
+  // marked COMPRESSED_PENDING_PURGE, and every writer of that sentinel is itself
+  // lesson-guarded (decayAndMarkIdle above + search-scoring.runIdleCleanup), so a
+  // lesson row can never reach here. INVARIANT: any NEW code that sets
+  // compressed_into = COMPRESSED_PENDING_PURGE MUST carry the "lessons never auto-GC"
+  // guard, or it re-opens the path that hard-deletes lessons through this DELETE.
   const doomed = db.prepare(`
     SELECT id FROM observations
     WHERE compressed_into = ${COMPRESSED_PENDING_PURGE} AND created_at_epoch < ?

package/lib/task-imperative.mjs

@@ -3,6 +3,8 @@
 // measurement that gates Phase 2): ONE tested source of truth so the measured
 // framing and the shipped framing cannot drift. Hot-path-shared → regex/string
 // only, NO heavy imports (lesson #8447), mirroring lib/lesson-idents.mjs.
+// format-utils.mjs is a zero-import pure-string module, so it respects that constraint.
+import { neutralizeContextDelimiters } from '../format-utils.mjs';
 //
 // Delivers a high-value lesson at the task-prompt position as an imperative,
 // task-bound constraint: attribution kept (honest + #NN cite-traceable), the
@@ -11,7 +13,7 @@
 // Spec: docs/superpowers/specs/2026-06-29-task-imperative-memory-injection-design.md
 
 export function formatTaskImperative(lesson, id) {
-  const body = String(lesson || '').trim().replace(/\.$/, '');
+  const body = neutralizeContextDelimiters(String(lesson || '').trim().replace(/\.$/, ''));
   if (!body) return '';
   const tag = (id === undefined || id === null || id === '') ? '' : ` (#${id})`;
   return `Memory — a past lesson applies to THIS task. You must: ${body}.${tag}`;
@@ -27,7 +29,7 @@ export function formatTaskImperative(lesson, id) {
 // / "reference, not an instruction" / appended-below-the-task / no adversarial
 // tokens) are the measured difference between adopt and refuse — do not drift them.
 export function formatSubagentContext(lesson, id) {
-  const body = String(lesson || '').trim().replace(/\.$/, '');
+  const body = neutralizeContextDelimiters(String(lesson || '').trim().replace(/\.$/, ''));
   if (!body) return '';
   const tag = (id === undefined || id === null || id === '') ? '' : `#${id} — `;
   return [

package/mem-cli.mjs

@@ -1621,7 +1621,17 @@ function cmdExport(db, args) {
     process.stderr.write(`[mem] Note: --from "${flags.from}" is after --to "${flags.to}"; this range is empty\n`);
   }
 
-  const limit = parseIntFlag(flags.limit, { name: '--limit', defaultValue: 200, max: 1000 });
+  // Backup default: with no --limit, export the COMPLETE matching set. `export` is
+  // the documented backup half of backup/restore (README; cmdRestore header), yet its
+  // old default capped at 200 (hard max 1000) and the "capped" warning went only to
+  // stderr — so a bare `export > backup.json` on a >200-row store silently wrote a
+  // truncated backup that lost rows on restore, and `--limit 5000` was REJECTED back
+  // to 200 (can't back up >1000 at all). Now: omit --limit → LIMIT -1 (SQLite = no
+  // limit); pass --limit N → honor any positive N (a backup may exceed 1000).
+  const limitGiven = flags.limit !== undefined && flags.limit !== null && flags.limit !== '';
+  const limit = limitGiven
+    ? parseIntFlag(flags.limit, { name: '--limit', defaultValue: 200 })
+    : -1;
   const format = flags.format || 'json';
   if (!['json', 'jsonl'].includes(format)) {
     fail(`[mem] Invalid format "${format}". Use: json or jsonl`);
@@ -1662,8 +1672,8 @@ function cmdExport(db, args) {
     out(JSON.stringify(rows, null, 2));
   }
 
-  if (rows.length >= limit) {
-    process.stderr.write(`[mem] Note: Results capped at ${limit}. Use --from/--to or --limit to export more.\n`);
+  if (limitGiven && rows.length >= limit) {
+    process.stderr.write(`[mem] Note: Results capped at ${limit}. Raise --limit or narrow --from/--to to export more.\n`);
   }
 }
 
@@ -2575,15 +2585,17 @@ Commands:
     --narrative T       New narrative
     --concepts T        Space-separated concept tags
 
-  export                Export observations as JSON/JSONL
-  restore <file>        Restore observations from an export file (JSON/JSONL); --dry-run to preview
+  export                Export observations as JSON/JSONL (complete backup by default)
     --project P         Filter by project
     --type T            Filter by type
     --format F          json (default) or jsonl
     --from DATE         Start date
     --to DATE           End date
     --include-compressed  Include compressed observations
-    --limit N           Max results (default 200, max 1000)
+    --limit N           Cap output at N rows (default: export ALL matching rows)
+  restore <file>        Restore observations from an export file (JSON/JSONL)
+    --project P         Override the restored project for every row
+    --dry-run           Preview what would be restored without writing
 
   compress              Compress old low-value observations
     --execute           Execute compression (preview by default)
@@ -2876,6 +2888,18 @@ async function cmdEnrich(argv) {
 }
 
 async function cmdOptimize(db, args) {
+  // cmdOptimize parses flags positionally (args.indexOf('--task') + args[idx+1])
+  // instead of the shared parseArgs, so the GNU `--flag=value` form silently
+  // vanished: indexOf found no bare `--flag`, dropping the value with zero signal.
+  // On the mutating --run path this was a real footgun — `optimize --run
+  // --task=smart-compress --project=p --max=5` ran ALL tasks across ALL projects at
+  // the default budget (tasks/project undefined → run-everything). Normalize
+  // `--flag=value` into `--flag value` up front so both forms parse identically;
+  // the `--execute=` special-case below already anticipated this for one flag.
+  args = args.flatMap(a => {
+    const m = /^(--[a-z][a-z-]*)=([\s\S]*)$/.exec(a);
+    return m ? [m[1], m[2]] : [a];
+  });
   const run = args.includes('--run');
   const runAll = args.includes('--run-all');
   // Sibling-command flag footgun: optimize executes with --run (compress uses
@@ -3045,11 +3069,15 @@ export async function run(argv) {
   const JSON_SUPPORTED_CMDS = new Set([
     'search', 'context', 'recent', 'recall', 'timeline', 'stats', 'browse', 'export', 'citation-stats',
   ]);
-  // `doctor --benchmark` already emits JSON on its own — don't print the misleading
-  // "doctor outputs text" note for that subpath. Without --benchmark, doctor is text
-  // and the note is still useful.
-  const doctorBenchmark = cmd === 'doctor' && cmdArgs.includes('--benchmark');
-  if (cmdArgs.includes('--json') && !JSON_SUPPORTED_CMDS.has(cmd) && !doctorBenchmark) {
+  // Suppress the note on subpaths that DO emit JSON, so it never FALSELY tells a script
+  // "outputs text" while writing valid JSON to stdout — a false note is worse than a
+  // missing one (it makes the consumer skip a parse that would have succeeded). doctor
+  // emits JSON for --benchmark / --metrics / --session-audit; activity's show/save emit
+  // JSON. Without those sub-flags, doctor is text and the note stays useful.
+  const jsonCapableSubpath =
+    (cmd === 'doctor' && (cmdArgs.includes('--benchmark') || cmdArgs.includes('--metrics') || cmdArgs.includes('--session-audit'))) ||
+    cmd === 'activity';
+  if (cmdArgs.includes('--json') && !JSON_SUPPORTED_CMDS.has(cmd) && !jsonCapableSubpath) {
     process.stderr.write(`[mem] Note: --json is supported only on: ${[...JSON_SUPPORTED_CMDS].join(', ')}. "${cmd}" outputs text.\n`);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.35.2",
+  "version": "3.36.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",
@@ -102,7 +102,6 @@
     "registry.mjs",
     "registry-retriever.mjs",
     "registry-recommend.mjs",
-    "registry-indexer.mjs",
     "registry-scanner.mjs",
     "registry-github.mjs",
     "registry-importer.mjs",

package/registry-recommend.mjs

@@ -18,8 +18,12 @@ export function getRecommendMode() {
 
 // Provisional gate thresholds — calibrated from shadow data before Phase 2 (spec §8).
 // relevance is raw bm25 (negative; more negative = better). Candidate must clear |floor|.
-export const RECO_BM25_FLOOR = -1.5;     // require row.relevance <= -1.5
-export const RECO_MARGIN = 0.5;          // require candidates[1].relevance - candidates[0].relevance >= 0.5
+export const RECO_BM25_FLOOR = -1.5;     // floor stays on raw bm25 (absolute topical relevance)
+// Margin is measured in COMPOSITE space (the metric that orders + selects the winner), NOT raw
+// bm25 — see applyGate. composite = bm25*0.4 - priors, so the scale is ~0.4x raw; 0.5 raw ≈ 0.2
+// composite is the principled starting point. Final value comes from `recommend-stats --sweep`
+// after dogfood (D#47); DEFAULT_SWEEP_MARGINS is likewise on the composite scale.
+export const RECO_MARGIN = 0.2;          // require candidates[1].composite_score - candidates[0].composite_score >= this
 const RECO_COOLDOWN_MS = 300_000;        // 5 min, mirrors T4 SKILL_COOLDOWN_MS (internal)
 
 // Lazy runtime-path resolution: read CLAUDE_MEM_DIR at call time (mirrors schema.mjs:13
@@ -35,9 +39,14 @@ const TOKEN_SPLIT = /[^a-z0-9一-鿿]+/;
 export function fetchInstalledSkillCandidates(rdb, promptText, limit = 10) {
   if (!rdb || !promptText) return [];
   let rows;
-  try { rows = searchResources(rdb, promptText, { type: 'skill', limit }); }
+  // Over-fetch, THEN filter to installed. quality_tier='installed' is a post-SQL JS filter, so a
+  // plain LIMIT starves installed skills that rank below other-tier matches: a weak installed
+  // match sitting past the top-N is sliced off → the gate sees no candidate → spurious
+  // no_candidate BLOCK (the −0.15 installed composite bonus is negligible vs the bm25 spread).
+  // A wide headroom lets the composite-best installed skill actually survive to the gate.
+  try { rows = searchResources(rdb, promptText, { type: 'skill', limit: Math.max(limit * 5, 50) }); }
   catch { return []; }
-  return rows.filter(r => r.quality_tier === 'installed');
+  return rows.filter(r => r.quality_tier === 'installed').slice(0, limit);
 }
 
 /**
@@ -65,7 +74,13 @@ export function applyGate(candidates, promptText, cooldownSet) {
   const top = candidates[0];
   if (!(top.relevance <= RECO_BM25_FLOOR)) return { verdict: 'BLOCK', reason: 'below_floor', candidate: top };
   if (candidates.length >= 2) {
-    const margin = candidates[1].relevance - top.relevance; // positive when top is clearly better
+    // Separation measured in the SAME metric that ordered the candidates (composite_score),
+    // NOT relevance. candidates arrive composite ASC so `top` IS the composite winner; a raw
+    // relevance margin let a composite-promoted top sit BELOW candidates[1] in relevance →
+    // negative margin → spurious low_margin BLOCK (and a permanent dead-zone in the ROC sweep).
+    // composite2 - composite1 is >= 0 by sort order. The floor above stays on raw bm25 — the
+    // absolute-relevance gate that stops a popular-but-irrelevant composite promotion.
+    const margin = candidates[1].composite_score - top.composite_score;
     if (!(margin >= RECO_MARGIN)) return { verdict: 'BLOCK', reason: 'low_margin', candidate: top };
   }
   if (!intentMatch(promptText, top)) return { verdict: 'BLOCK', reason: 'intent_mismatch', candidate: top };
@@ -192,11 +207,13 @@ export function computeFunnel(days = 7) {
   return stats;
 }
 
-// Default sweep grid (B3). Raw BM25 magnitudes for real matches run ≈ -10..-15, so the
-// shipped floor (-1.5) is far more permissive than it looks; the grid spans that real range
-// so the ROC curve actually moves. Override via `recommend-stats --sweep --floors a,b --margins x,y`.
+// Default sweep grid (B3). FLOORS are raw bm25 (real matches run ≈ -10..-15, so the shipped
+// -1.5 floor is far more permissive than it looks; the grid spans that real range). MARGINS are
+// on the COMPOSITE scale (composite = bm25*0.4 - priors), matching replayGate's margin metric —
+// the old raw-bm25 grid [0,0.5,1,2,4] was ~2.5x too wide for composite separations.
+// Override via `recommend-stats --sweep --floors a,b --margins x,y`.
 export const DEFAULT_SWEEP_FLOORS = [-1.5, -5, -8, -10, -12];
-export const DEFAULT_SWEEP_MARGINS = [0, 0.5, 1, 2, 4];
+export const DEFAULT_SWEEP_MARGINS = [0, 0.05, 0.1, 0.2, 0.4];
 
 /**
  * Recompute the gate verdict for a logged reco row at a hypothetical (floor, margin),
@@ -207,7 +224,15 @@ export function replayGate(row, floor, margin) {
   const r1 = row.relevance;
   // null/undefined relevance coerces to 0/NaN, so `r1 <= floor` is false → BLOCK (no null check).
   if (!(r1 <= floor)) return 'BLOCK';
-  if (Number.isFinite(row.rel2) && !((row.rel2 - r1) >= margin)) return 'BLOCK';
+  // Margin on composite when the row logged it (post-switch rows), matching the live applyGate
+  // metric; fall back to the legacy relevance margin for rows written before composite1/composite2
+  // existed (they age out of the 7d sweep window). Single-candidate rows (no rel2/composite2) skip
+  // the margin gate either way. NOTE: sweep `margin` is on the COMPOSITE scale for new rows.
+  if (Number.isFinite(row.composite1) && Number.isFinite(row.composite2)) {
+    if (!((row.composite2 - row.composite1) >= margin)) return 'BLOCK';
+  } else if (Number.isFinite(row.rel2)) {
+    if (!((row.rel2 - r1) >= margin)) return 'BLOCK';
+  }
   if (!row.intentTop) return 'BLOCK';
   if (row.cooldownTop) return 'BLOCK';
   return 'PASS';
@@ -230,11 +255,25 @@ export function computeSweep(days = 7, floors = DEFAULT_SWEEP_FLOORS, margins =
   }
   const grid = [];
   for (const floor of floors) for (const margin of margins) {
-    let pass = 0, matchPass = 0, matchAdopt = 0;
+    let pass = 0;
+    // Matched precision MUST dedup (session, skill) exactly like computeFunnel (mPass/mAdopt
+    // via per-session Sets). Counting raw reco rows here inflated matchPass by every repeat
+    // recommendation of the same skill in one session, so the sweep's precision silently
+    // disagreed with the funnel headline and was biased toward frequently-recommended skills —
+    // corrupting the exact (floor,margin) signal the sweep exists to inform. `pass` stays a raw
+    // volume count (it is not a precision denominator).
+    const passBySession = new Map(); // session -> Set<skillLower> that PASSED at this cell
     for (const r of recos) {
       if (replayGate(r, floor, margin) !== 'PASS') continue;
       pass++;
-      if (r.session) { matchPass++; if (adoptBySession.get(r.session)?.has(lc(r.skill))) matchAdopt++; }
+      if (!r.session) continue;
+      if (!passBySession.has(r.session)) passBySession.set(r.session, new Set());
+      passBySession.get(r.session).add(lc(r.skill));
+    }
+    let matchPass = 0, matchAdopt = 0;
+    for (const [session, skills] of passBySession) {
+      const adopted = adoptBySession.get(session);
+      for (const sk of skills) { matchPass++; if (adopted?.has(sk)) matchAdopt++; }
     }
     grid.push({ floor, margin, pass, matchPass, matchAdopt, precision: matchPass ? matchAdopt / matchPass : null });
   }
@@ -265,8 +304,10 @@ export function recommendSkill(rdb, promptText, project, opts = {}) {
     // NOT the registry short name ('superpowers-tdd') — adoption rows log toolInput.skill (the slug),
     // so logging top.name made in-session matched precision a guaranteed 0 for every namespaced skill.
     skill: top ? (top.invocation_name || top.name) : null,
-    relevance: top ? top.relevance : null,
-    rel2: candidates[1] ? candidates[1].relevance : null,
+    relevance: top ? top.relevance : null,                    // floor replay (absolute bm25)
+    rel2: candidates[1] ? candidates[1].relevance : null,     // legacy margin replay (pre-composite rows)
+    composite1: top ? top.composite_score : null,             // margin replay (composite — the live gate metric)
+    composite2: candidates[1] ? candidates[1].composite_score : null,
     intentTop: top ? intentMatch(promptText, top) : false,
     cooldownTop: top ? cooldownSet.has(String(top.name).toLowerCase()) : false,
     ncand: candidates.length,

package/registry.mjs

@@ -62,8 +62,9 @@ const RESOURCES_SCHEMA = `
 `;
 
 // Canonical FTS5 column order — all consumers must use this order.
-// BM25 weights (positional): trigger_patterns(5), keywords(3), capability_summary(3),
+// BM25 weights (positional): trigger_patterns(3), keywords(3), capability_summary(3),
 //   intent_tags(2), use_cases(2), domain_tags(1), tech_stack(1), name(1)
+//   — must match the bm25(resources_fts, 3,3,3,2,2,1,1,1) call in COMPOSITE_EXPR.
 const FTS5_SCHEMA = `
   CREATE VIRTUAL TABLE IF NOT EXISTS resources_fts USING fts5(
     trigger_patterns,
@@ -371,12 +372,23 @@ const UPSERT_SQL = `
     repo_stars=CASE WHEN excluded.repo_stars > 0 THEN excluded.repo_stars ELSE repo_stars END,
     local_path=excluded.local_path, file_hash=excluded.file_hash,
     invocation_name=CASE WHEN excluded.invocation_name != '' THEN excluded.invocation_name ELSE invocation_name END,
-    intent_tags=excluded.intent_tags, domain_tags=excluded.domain_tags,
-    action_type=excluded.action_type, trigger_patterns=excluded.trigger_patterns,
-    capability_summary=excluded.capability_summary, input_type=excluded.input_type,
-    output_type=excluded.output_type, prerequisites=excluded.prerequisites,
-    keywords=excluded.keywords, tech_stack=excluded.tech_stack,
-    use_cases=excluded.use_cases, complexity=excluded.complexity,
+    -- Preserve-on-empty (mirror repo_stars/invocation_name above): a PARTIAL re-upsert --
+    -- e.g. "registry import --name X --capability-summary ...", where mem-cli defaults every
+    -- other flag to '' -- must NOT blank the FTS text columns and silently drop the resource
+    -- out of search (import is the ONLY registry edit path; there is no update subcommand).
+    -- Full upserts are unaffected: every field is non-empty, so the CASE picks excluded.
+    intent_tags=CASE WHEN excluded.intent_tags != '' THEN excluded.intent_tags ELSE intent_tags END,
+    domain_tags=CASE WHEN excluded.domain_tags != '' THEN excluded.domain_tags ELSE domain_tags END,
+    action_type=CASE WHEN excluded.action_type != '' THEN excluded.action_type ELSE action_type END,
+    trigger_patterns=CASE WHEN excluded.trigger_patterns != '' THEN excluded.trigger_patterns ELSE trigger_patterns END,
+    capability_summary=CASE WHEN excluded.capability_summary != '' THEN excluded.capability_summary ELSE capability_summary END,
+    input_type=CASE WHEN excluded.input_type != '' THEN excluded.input_type ELSE input_type END,
+    output_type=CASE WHEN excluded.output_type != '' THEN excluded.output_type ELSE output_type END,
+    prerequisites=excluded.prerequisites,
+    keywords=CASE WHEN excluded.keywords != '' THEN excluded.keywords ELSE keywords END,
+    tech_stack=CASE WHEN excluded.tech_stack != '' THEN excluded.tech_stack ELSE tech_stack END,
+    use_cases=CASE WHEN excluded.use_cases != '' THEN excluded.use_cases ELSE use_cases END,
+    complexity=excluded.complexity,
     indexed_at=excluded.indexed_at, updated_at=datetime('now')
 `;
 

package/schema.mjs

@@ -816,7 +816,14 @@ const DEFERRED_CLEANUPS = [
             }
           }
           if (canonical) {
-            for (const table of ['observations', 'sdk_sessions', 'session_summaries']) {
+            // Rename the short project to canonical on EVERY project-scoped table.
+            // Originally only the first three were rewritten, so a short-named
+            // project's deferred TODOs (deferred_work), activity (events), citation
+            // history (citation_log), and /clear-/exit handoffs (session_handoffs)
+            // were stranded on the old name — invisible to every project-scoped query
+            // after normalization. All seven carry a `project` column (verified).
+            for (const table of ['observations', 'sdk_sessions', 'session_summaries',
+                                 'session_handoffs', 'citation_log', 'events', 'deferred_work']) {
               db.prepare(`UPDATE ${table} SET project = ? WHERE project = ?`).run(canonical.project, shortName);
             }
           }

package/scripts/post-tool-use.sh

@@ -22,6 +22,12 @@ if [[ "$tool" == "Read" ]]; then
   if [[ "$input" =~ \"file_path\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]]; then
     file_path="${BASH_REMATCH[1]}"
     _dir="${CLAUDE_PROJECT_DIR:-$PWD}"
+    # Strip trailing slashes so ${_dir##*/} / ${_dir%/*} match Node's path.basename /
+    # path.dirname in inferProject(). Without this, CLAUDE_PROJECT_DIR="/org/proj/"
+    # gave bash "proj--" (empty base) while JS gave "org--proj" — a name mismatch that
+    # made flushEpisode read a DIFFERENT reads-<project>.txt, silently dropping this
+    # session's Read context AND orphaning the bash-named file (nothing ever collects it).
+    while [[ "$_dir" == */ && ${#_dir} -gt 1 ]]; do _dir="${_dir%/}"; done
     _base="${_dir##*/}"
     _parent="${_dir%/*}"; _parent="${_parent##*/}"
     if [[ -n "$_parent" && "$_parent" != "." && "$_parent" != "/" ]]; then
@@ -29,8 +35,11 @@ if [[ "$tool" == "Read" ]]; then
     else
       project="${_base}"
     fi
-    # Sanitize project name to match utils.mjs inferProject()
+    # Sanitize + truncate to 100 to match utils.mjs inferProject() EXACTLY
+    # (raw.replace(/[^a-zA-Z0-9_.-]/g,'-').slice(0,100)). A >100-char parent--base
+    # otherwise diverges from the JS side (same reads-file mismatch as above).
     project="${project//[^a-zA-Z0-9_.-]/-}"
+    project="${project:0:100}"
     project="${project:-unknown}"
     # Honor CLAUDE_MEM_DIR relocation (mirrors schema.mjs DB_DIR → hook-shared RUNTIME_DIR).
     # hook.mjs flushEpisode reads reads-<project>.txt from CLAUDE_MEM_DIR/runtime; if this

package/search-engine.mjs

@@ -259,6 +259,7 @@ function expandObsByPRF(db, ctx, now, primaryCount, existingIds, results, includ
     SELECT o.title, o.narrative FROM observations_fts
     JOIN observations o ON observations_fts.rowid = o.id
     WHERE observations_fts MATCH ? AND COALESCE(o.compressed_into, 0) = 0
+      AND o.superseded_at IS NULL
       AND (? IS NULL OR o.project = ?)
     ORDER BY ${OBS_BM25}
     LIMIT 8
@@ -304,7 +305,9 @@ function expandObsByPRF(db, ctx, now, primaryCount, existingIds, results, includ
  *   1. FTS5 MATCH with the sanitized query (AND-by-default), recency-weighted
  *   2. If AND returns 0 → relaxFtsQueryToOr fallback (mirrors searchObservationsHybrid)
  *
- * Always skips compressed rows.
+ * Always skips compressed AND superseded rows — paired with searchObservationsHybrid /
+ * buildObsFtsQuery so `timeline --query` / mem_timeline never anchor on a memory that
+ * search itself hides (an anchor on a replaced row strands navigation on stale content).
  *
  * @param {Database} db
  * @param {object} opts
@@ -324,6 +327,7 @@ export function findFtsAnchor(db, { ftsQuery, project = null, nowT = null, halfL
     WHERE observations_fts MATCH ?
       AND (? IS NULL OR o.project = ?)
       AND COALESCE(o.compressed_into, 0) = 0
+      AND o.superseded_at IS NULL
     ORDER BY ${OBS_BM25}
       * (1.0 + EXP(-0.693 * MAX(0, ? - o.created_at_epoch) / ${halfLifeMs}.0))
     LIMIT 1

package/search-scoring.mjs

@@ -199,6 +199,7 @@ export function expandQueryByConcepts(db, ftsQuery, project) {
       SELECT o.concepts FROM observations_fts
       JOIN observations o ON observations_fts.rowid = o.id
       WHERE observations_fts MATCH ? AND COALESCE(o.compressed_into, 0) = 0
+        AND o.superseded_at IS NULL
         AND (? IS NULL OR o.project = ?)
       ORDER BY ${OBS_BM25}
       LIMIT 20
@@ -281,6 +282,11 @@ export function runIdleCleanup(db) {
         WHERE importance <= 1 AND COALESCE(access_count, 0) = 0
           AND type IN (${types})
           AND created_at_epoch < ? AND COALESCE(compressed_into, 0) = 0
+          -- Never auto-mark a lesson-bearing row for purge. This idle path is the
+          -- MCP-server sibling of maintain-core.decayAndMarkIdle and must carry the
+          -- SAME "lessons never auto-GC" guard; without it a lesson demoted to imp≤1
+          -- by citation-decay gets pending-purge'd here and hard-deleted by purgeStale.
+          AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
       `).run(cutoff);
       totalMarked += marked.changes;
 
@@ -289,6 +295,10 @@ export function runIdleCleanup(db) {
         WHERE COALESCE(compressed_into, 0) = 0 AND importance = 1
           AND type IN (${types})
           AND created_at_epoch < ?
+          -- Same lesson guard: auto-compress (-1) hides the row from all retrieval and
+          -- recoverBuriedLessons only re-floors live (compressed_into=0) rows, so a
+          -- compressed lesson is unrecoverable. Parity with selectCompressionCandidates.
+          AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
       `).run(cutoff);
       totalCompressed += compressed.changes;
     }

package/source-files.mjs

@@ -13,7 +13,7 @@ export const SOURCE_FILES = [
   'plugin-cache-guard.mjs',
   'haiku-client.mjs', 'utils.mjs', 'schema.mjs',
   'package.json', 'package-lock.json', 'skill.md',
-  'registry.mjs', 'registry-scanner.mjs', 'registry-indexer.mjs',
+  'registry.mjs', 'registry-scanner.mjs',
   'registry-retriever.mjs', 'resource-discovery.mjs',
   // registry-recommend.mjs: statically imported by hook.mjs (PostToolUse adoption probe)
   // and scripts/user-prompt-search.js (UserPromptSubmit shadow recommendation).

package/tool-schemas.mjs

@@ -92,7 +92,7 @@ export const memSearchSchema = {
   limit: coerceInt.pipe(z.number().int().min(1).max(100)).optional().describe('Max results (default 20)'),
   offset: coerceInt.pipe(z.number().int().min(0)).optional().describe('Offset for pagination'),
   sort: z.enum(['relevance', 'time', 'importance']).optional().describe('Sort order: relevance (default, BM25), time (newest first), importance (highest first)'),
-  include_noise: z.boolean().optional().describe('Include hook-llm fallback titles ("Modified X", "Worked on X", raw error logs) — hidden by default as they have ~3% access rate'),
+  include_noise: coerceBool.optional().describe('Include hook-llm fallback titles ("Modified X", "Worked on X", raw error logs) — hidden by default as they have ~3% access rate'),
   or: coerceBool.optional().describe('Force OR semantics between query terms from the start (default: AND with automatic OR-fallback when AND returns 0). Aligns with CLI --or.'),
   deep: coerceBool.optional().describe('Tri-state LLM multi-query/HyDE deep search (observations-only). true=force; false=never; omit=AUTO (default ON for mem_search): a normal search that returns weak/few results auto-escalates with ONE Haiku call (query rewritten to keyword/concept/HyDE variants, RRF-fused). Set CLAUDE_MEM_AUTO_DEEP=0 to disable AUTO. Passive recall stays single-query.'),
   rerank: coerceBool.optional().describe('Opt-in: LLM-rerank the deep-search candidates for ranking precision (one extra Haiku call, ~1.4s). Requires deep=true (no effect on AUTO/normal). Reserve for hard, ranking-sensitive queries where the right memory is likely retrieved but mis-ranked — skip for routine search. Default off.'),
@@ -249,7 +249,7 @@ export const memExportSchema = {
 export const memRecallSchema = {
   file: z.string().min(1).describe('File path or filename to recall observations for'),
   limit: coerceInt.pipe(z.number().int().min(1).max(50)).optional().describe('Max results (default 10)'),
-  include_noise: z.boolean().optional().describe('Include hook-llm fallback titles ("Modified X", "Worked on X", raw error logs) — hidden by default for parity with mem_search'),
+  include_noise: coerceBool.optional().describe('Include hook-llm fallback titles ("Modified X", "Worked on X", raw error logs) — hidden by default for parity with mem_search'),
 };
 
 export const memFtsCheckSchema = {

package/registry-indexer.mjs

@@ -1,175 +0,0 @@
-// claude-mem-lite: Resource indexer — extracts metadata via Haiku LLM
-// Called during installation and when resource content changes
-
-import { upsertResource } from './registry.mjs';
-import { callHaikuJSON } from './haiku-client.mjs';
-import { debugLog, debugCatch, truncate } from './utils.mjs';
-
-// ─── Index Prompt ────────────────────────────────────────────────────────────
-
-/**
- * Build the LLM prompt for extracting structured metadata from a resource.
- * @param {object} resource Scanned resource with name, type, and content
- * @returns {string} Prompt string for Haiku JSON extraction
- */
-function buildIndexPrompt(resource) {
-  const content = truncate(resource.content, 3000);
-  return `Analyze this Claude Code ${resource.type} definition and extract structured metadata.
-Return ONLY valid JSON, no markdown fences.
-
-<resource-name>${resource.name}</resource-name>
-<resource-type>${resource.type}</resource-type>
-<content>
-${content}
-</content>
-
-JSON format:
-{"intent_tags":"comma-separated intent keywords (e.g. test,debug,deploy,review)","domain_tags":"comma-separated tech/language tags (e.g. javascript,react,python)","action_type":"analyze|generate|transform|validate|deploy|configure|review","trigger_patterns":"natural language describing when to use this (e.g. when user needs to write tests; when debugging errors)","capability_summary":"50-100 char description of what it does","keywords":"specific technical terms, framework names, method names not duplicating intent_tags (e.g. jest,vitest,red-green-refactor,pytest)","tech_stack":"specific frameworks and tools this works with (e.g. jest,vitest,mocha,pytest)","use_cases":"3-5 specific usage scenarios separated by semicolons","input_type":"code|file|directory|url|text","output_type":"report|file|diff|terminal_output|analysis"}`;
-}
-
-// ─── Fallback Extraction ─────────────────────────────────────────────────────
-
-/**
- * Extract basic metadata from resource content using regex when Haiku fails.
- * Better than nothing — provides minimal FTS5 searchability.
- */
-function fallbackExtract(resource) {
-  const content = (resource.content || '').toLowerCase();
-  const name = resource.name.toLowerCase();
-
-  // Infer intent tags from name and common patterns
-  const intentMap = {
-    commit: 'commit,git,version-control',
-    test: 'test,testing,tdd,qa',
-    debug: 'debug,troubleshoot,fix,error',
-    review: 'review,code-review,quality',
-    lint: 'lint,format,style,quality',
-    deploy: 'deploy,release,ci,cd',
-    build: 'build,compile,bundle',
-    refactor: 'refactor,clean,simplify',
-    security: 'security,audit,vulnerability',
-    perf: 'performance,optimize,benchmark',
-    doc: 'documentation,readme,docs',
-    design: 'design,ui,ux,frontend',
-    infra: 'infrastructure,devops,cloud',
-  };
-
-  const intentTagSet = new Set();
-  for (const [key, tags] of Object.entries(intentMap)) {
-    if (name.includes(key) || content.includes(key)) {
-      for (const t of tags.split(',')) intentTagSet.add(t);
-    }
-  }
-  const intentTags = [...intentTagSet].join(',');
-
-  // Infer domain tags from content
-  const domainPatterns = [
-    [/\b(javascript|typescript|node|npm|yarn|pnpm)\b/, 'javascript,typescript,node'],
-    [/\b(python|pip|poetry|django|flask)\b/, 'python'],
-    [/\b(react|vue|angular|svelte|next)\b/, 'frontend,javascript'],
-    [/\b(rust|cargo)\b/, 'rust'],
-    [/\b(go|golang)\b/, 'go'],
-    [/\b(docker|kubernetes|k8s|terraform)\b/, 'infrastructure,devops'],
-    [/\b(postgres|mysql|sqlite|mongodb)\b/, 'database'],
-    [/\b(api|rest|graphql|grpc)\b/, 'api,backend'],
-  ];
-
-  let domainTags = '';
-  for (const [pattern, tags] of domainPatterns) {
-    if (pattern.test(content)) {
-      domainTags = domainTags ? `${domainTags},${tags}` : tags;
-    }
-  }
-
-  return {
-    intent_tags: intentTags || resource.type,
-    domain_tags: domainTags || '',
-    action_type: resource.type === 'agent' ? 'analyze' : 'generate',
-    trigger_patterns: `when user needs ${name.replace(/-/g, ' ')} functionality`,
-    capability_summary: truncate(`${resource.type}: ${name.replace(/-/g, ' ')}`, 100),
-    input_type: 'code',
-    output_type: resource.type === 'agent' ? 'analysis' : 'file',
-  };
-}
-
-// ─── Single Resource Indexing ────────────────────────────────────────────────
-
-/**
- * Index a single resource: call Haiku for metadata, then upsert to DB.
- * Falls back to regex extraction if Haiku fails.
- * @param {Database} db Registry database
- * @param {object} resource Scanned resource object
- * @returns {Promise<number>} Resource ID
- */
-export async function indexResource(db, resource) {
-  const prompt = buildIndexPrompt(resource);
-  let metadata = await callHaikuJSON(prompt, { timeout: 15000, maxTokens: 400 });
-
-  if (!metadata || !metadata.capability_summary) {
-    debugLog('WARN', 'indexer', `Haiku failed for ${resource.name}, using fallback`);
-    metadata = fallbackExtract(resource);
-  }
-
-  const now = new Date().toISOString();
-  const id = upsertResource(db, {
-    name: resource.name,
-    type: resource.type,
-    status: 'active',
-    source: resource.source,
-    repo_url: resource.repoUrl || null,
-    repo_stars: resource.repoStars || 0,
-    local_path: resource.localPath,
-    file_hash: resource.fileHash,
-    intent_tags: metadata.intent_tags || '',
-    domain_tags: metadata.domain_tags || '',
-    action_type: metadata.action_type || '',
-    trigger_patterns: metadata.trigger_patterns || '',
-    capability_summary: metadata.capability_summary || '',
-    input_type: metadata.input_type || '',
-    output_type: metadata.output_type || '',
-    keywords: metadata.keywords || '',
-    tech_stack: metadata.tech_stack || '',
-    use_cases: metadata.use_cases || '',
-    prerequisites: typeof metadata.prerequisites === 'object'
-      ? JSON.stringify(metadata.prerequisites) : '{}',
-    indexed_at: now,
-  });
-
-  return id;
-}
-
-/**
- * Index multiple resources sequentially.
- * Logs progress and continues on individual failures.
- * @param {Database} db Registry database
- * @param {object[]} resources Array of scanned resources
- * @returns {Promise<{indexed: number, failed: number}>} Results summary
- */
-export async function indexAll(db, resources) {
-  let indexed = 0;
-  let failed = 0;
-
-  for (const resource of resources) {
-    try {
-      await indexResource(db, resource);
-      indexed++;
-      debugLog('DEBUG', 'indexer', `indexed: ${resource.type}/${resource.name}`);
-    } catch (e) {
-      failed++;
-      debugCatch(e, `indexResource(${resource.name})`);
-      // Mark as error in DB so it can be retried later
-      try {
-        upsertResource(db, {
-          name: resource.name,
-          type: resource.type,
-          status: 'error',
-          source: resource.source,
-          local_path: resource.localPath,
-          file_hash: resource.fileHash,
-        });
-      } catch {}
-    }
-  }
-
-  return { indexed, failed };
-}