claude-mem-lite 3.35.1 → 3.36.0

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.1",
+  "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 = {