claude-mem-lite 3.68.0 → 3.69.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.68.0",
+      "version": "3.69.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.68.0",
+  "version": "3.69.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/cli/common.mjs

@@ -200,10 +200,10 @@ export const KNOWN_CLI_FLAGS = new Set([
   'after', 'age-days', 'all', 'anchor', 'batch', 'before', 'benchmark', 'body', 'branch',
   'capability-summary', 'category', 'closes-deferred', 'concepts', 'confirm', 'days', 'deep',
   'detail', 'domain-tags', 'dry-run', 'enrich', 'execute', 'fields', 'file', 'files', 'floors',
-  'force', 'format', 'from', 'has', 'help', 'id', 'ids', 'content', 'importance', 'include-compressed', 'include-noise',
+  'force', 'format', 'from', 'help', 'id', 'ids', 'content', 'importance', 'include-compressed', 'include-noise',
   'intent-tags', 'invocation-name', 'json', 'key', 'keywords', 'lesson', 'lesson-learned', 'limit',
   'local-path', 'margins', 'max', 'memdir', 'merge-ids', 'metrics', 'name', 'narrative', 'no-deep',
-  'offset', 'ops', 'or', 'out', 'priority', 'project', 'quality', 'query', 'reason', 'repo-url',
+  'offset', 'ops', 'or', 'priority', 'project', 'quality', 'query', 'reason', 'repo-url',
   'rerank', 'resource-type', 'retain-days', 'retry', 'run', 'run-all', 'scope', 'session-audit',
   'sidechain', 'since', 'sort', 'source', 'status', 'sweep', 'task', 'tech-stack', 'text', 'tier', 'title',
   'to', 'trigger-patterns', 'type', 'use-cases', 'verbose',
@@ -217,6 +217,15 @@ export const KNOWN_CLI_FLAGS = new Set([
   // warn-on-every-unknown-flag flip turned the omission into a false warning on a
   // documented, working command.
   'prompts-limit',
+  // Entries here MUST be read by a `claude-mem-lite` subcommand. A flag that no
+  // command reads is worse than an absent one: it converts the "ignored, it had no
+  // effect" warning into silence, so the user's dropped flag reads as accepted.
+  // `out` sat here until the 2026-08-17 e2e round for that exact reason: `--out` is a
+  // benchmark-script flag (benchmark/longmemeval-rerank.mjs), never a CLI one, so
+  // `export --out backup.json` printed the whole export to stdout and said nothing
+  // about the file it did not write. `has` went the same round: no reader, no help
+  // entry, and (per the v3.34.0 notes) the source of the misleading "did you mean
+  // --has?" suggestion. Locked by tests/cli-flag-allowlist.test.mjs.
 ]);
 
 /** Levenshtein distance, early-exit past `max` (cheap enough for a handful of flags). */

package/hook-semaphore.mjs

@@ -56,6 +56,17 @@ export const sleepMs = (ms) => new Promise(r => setTimeout(r, ms));
 // same age escape hatch the reaper applies to other processes' slots. 0 = not held.
 let localHeldAt = 0;
 
+/**
+ * Test-only: force the local hold record to an arbitrary age. The staleness
+ * escape hatch above is otherwise unreachable in a test — it needs a record
+ * older than LLM_SEM_STALE_MS (120s), and a suite cannot wait that long. It was
+ * shipped untested in v3.68.0 and a post-tag review showed the gate still passed
+ * 16/16 when the escape hatch was deleted outright. Mirrors the `_resetMode` /
+ * `_resetHeadlessFlag` hooks in haiku-client.mjs.
+ * @param {number} ts epoch ms, or 0 for "not held"
+ */
+export function _setLocalHeldAt(ts) { localHeldAt = ts; }
+
 /**
  * Acquire a file-based semaphore slot for LLM calls.
  * Uses acquire-then-verify: atomically creates a slot file, then checks total count.

package/hook.mjs

@@ -878,8 +878,15 @@ async function handleStop() {
     }
   }
 
-  // Spawn background for session summary (pass sessionId and project)
-  spawnBackground('llm-summary', sessionId, project);
+  // Spawn background for session summary (pass sessionId and project).
+  // CLAUDE_MEM_SKIP_SUMMARY brings this in line with every other background
+  // worker (auto-compress / llm-optimize / auto-maintain all have one). It was
+  // the only ungated spawnBackground, which made Stop untestable end-to-end
+  // without residue: the detached child outlives the parent process an e2e test
+  // waits on, then recreates the sandbox tree behind the test's cleanup. Any
+  // grace period for that is a race, not a barrier — the post-tag review timed a
+  // recreate at 432ms and watched a 300ms grace lose.
+  if (!process.env.CLAUDE_MEM_SKIP_SUMMARY) spawnBackground('llm-summary', sessionId, project);
 
   // Clean session file AFTER spawning background
   try { unlinkSync(sessionFile()); } catch {}
@@ -1523,7 +1530,14 @@ async function handleSessionStart() {
     // Stdout is the sole context-delivery channel. The SessionStart hook output
     // is injected as a <system-reminder> at session start, giving Claude the
     // full summary + handoff state + observations table fresh from the DB.
-    process.stdout.write(`<claude-mem-context>\n${fullContext}\n</claude-mem-context>\n`);
+    // Skip the wrapper entirely when there is no body. On a brand-new install every
+    // section is empty, and the hook still emitted `<claude-mem-context>\n\n</...>` —
+    // a framing block that asserts a memory surface and then shows nothing, which is
+    // both wasted context and an active misread ("memory exists and is empty" is a
+    // reason NOT to call mem_*). Non-empty output is byte-identical.
+    if (fullContext.trim()) {
+      process.stdout.write(`<claude-mem-context>\n${fullContext}\n</claude-mem-context>\n`);
+    }
 
     // D#123 (review C-1): persist the Key Context ids ACTUALLY rendered above so
     // handleUserPrompt can exclude exactly those from <memory-context> — and

package/install.mjs

@@ -1721,24 +1721,63 @@ async function doctor() {
   try {
     const { checkDevDrift } = await import('./lib/doctor-drift.mjs');
     const r = checkDevDrift(INSTALL_DIR, SOURCE_FILES);
-    if (r.drift || (r.devMode && r.missingCount > 0)) {
+    const devRemedy = `re-run: node ${join(PROJECT_DIR, 'install.mjs')} install --dev`;
+    const nameList = (files, count) => {
+      const suffix = count > files.length ? ` +${count - files.length} more` : '';
+      return `${files.join(', ')}${suffix}`;
+    };
+    if (r.devMode) {
       const parts = [];
       if (r.plainCount > 0) {
-        const names = r.plainFiles.slice(0, 5).join(', ');
-        const suffix = r.plainCount > 5 ? ` +${r.plainCount - 5} more` : '';
-        parts.push(`${r.plainCount} non-symlink: ${names}${suffix}`);
+        parts.push(`${r.plainCount} non-symlink: ${nameList(r.plainFiles.slice(0, 5), r.plainCount)}`);
       }
-      if (r.missingCount > 0) {
-        const names = r.missingFiles.join(', ');
-        const suffix = r.missingCount > r.missingFiles.length ? ` +${r.missingCount - r.missingFiles.length} more` : '';
-        parts.push(`${r.missingCount} missing: ${names}${suffix}`);
+      if (r.missingEntryCount > 0) {
+        parts.push(`${r.missingEntryCount} missing ENTRY POINT: ${nameList(r.missingEntryFiles, r.missingEntryCount)}`);
       }
-      warn(`Dev drift: ${parts.join('; ')} (re-run: node ${join(PROJECT_DIR, 'install.mjs')} install --dev)`);
+      if (parts.length > 0) {
+        // Hard: a non-symlink means repo edits stop propagating, and a missing entry point
+        // means the hook/CLI command that names that path cannot start at all. A hybrid
+        // install also loses the realpath argument below — a COPIED entry point resolves
+        // its imports against the install dir, so absent modules can throw there.
+        if (r.missingModuleCount > 0) {
+          parts.push(`${r.missingModuleCount} missing module: ${nameList(r.missingModuleFiles, r.missingModuleCount)}`);
+        }
+        warn(`Dev drift: ${parts.join('; ')} (${devRemedy})`);
+        issues++;
+      } else if (r.missingModuleCount > 0) {
+        // Informational, NOT an issue: in a pure-symlink install every entry point resolves
+        // to the repo, and Node resolves each module's imports against that REALPATH — so an
+        // import-only file absent from the install dir is unreachable, not broken. Reporting
+        // it as drift prescribed `install --dev` for a demonstrably healthy install (the
+        // maintainer's own machine ran every one of those modules fine while doctor called
+        // them missing).
+        dwarn(`Dev drift: ${r.symlinkCount} symlinks, 0 plain, all entry points present — `
+          + `${r.missingModuleCount} import-only file(s) not linked into the install dir `
+          + `(${nameList(r.missingModuleFiles, r.missingModuleCount)}). Harmless: Node resolves `
+          + `imports against each entry point's realpath, i.e. the repo. ${devRemedy} to link them.`);
+      } else {
+        ok(`Dev drift: clean (${r.symlinkCount} symlinks, 0 plain, 0 missing)`);
+      }
+    } else if (r.missingCount > 0) {
+      // COPY install (npm / plugin / `install` without --dev). Here the realpath argument
+      // does NOT apply: entry points are real files, so `../lib/x.mjs` resolves against the
+      // install dir and a missing module is an ERR_MODULE_NOT_FOUND on every hook fire.
+      // This case used to print NOTHING — checkDevDrift returns devMode=false and both the
+      // warning and the all-clear were gated on devMode, so the shape where missing files
+      // are FATAL was the silent one (#8268's rule failing in the other direction).
+      const parts = [];
+      if (r.missingEntryCount > 0) {
+        parts.push(`${r.missingEntryCount} entry point: ${nameList(r.missingEntryFiles, r.missingEntryCount)}`);
+      }
+      if (r.missingModuleCount > 0) {
+        parts.push(`${r.missingModuleCount} module: ${nameList(r.missingModuleFiles, r.missingModuleCount)}`);
+      }
+      warn(`Managed files: ${r.missingCount} missing (${parts.join('; ')}) — a copy install resolves `
+        + `imports against the install dir, so these throw at hook time. Fix: claude-mem-lite update `
+        + `(or: node ${join(INSTALL_DIR, 'install.mjs')} repair)`);
       issues++;
-    } else if (r.devMode) {
-      ok(`Dev drift: clean (${r.symlinkCount} symlinks, 0 plain, 0 missing)`);
     }
-    // Prod (all plain) install: no message — dev-drift is a dev-only concern.
+    // Complete copy install: no message — drift is a dev-install concern.
   } catch (e) {
     dwarn('Dev drift: check failed — ' + e.message);
   }

package/lib/doctor-drift.mjs

@@ -11,6 +11,25 @@
 import { existsSync, lstatSync } from 'fs';
 import { join } from 'path';
 
+// Files something EXECUTES by path (the CLI, the MCP server, a hook entry) as opposed to
+// files that are only ever `import`ed. The distinction decides whether an absent file
+// matters in a symlink install: Node resolves an ESM specifier against the importing
+// module's REALPATH, so a symlinked entry point resolves `../lib/x.mjs` inside the REPO and
+// never looks at the install dir. An absent import-only module is therefore unreachable
+// dead weight there — while an absent ENTRY POINT is fatal in every shape, because the
+// command names that path directly.
+//
+// Scope note (pre-tag review): this classifies only what the CALLER passes in, and
+// install.mjs passes SOURCE_FILES, which holds zero `scripts/` entries — hook scripts are
+// installed from the separate HOOK_SCRIPT_FILES manifest. An earlier draft mapped those
+// into this set; it could never match a single path, so it is gone rather than left as
+// inert code implying coverage it does not have. Extending doctor to check the hook-script
+// manifest is real work with its own fixture, and is tracked as deferred rather than
+// implied here.
+const ENTRY_POINTS = new Set([
+  'cli.mjs', 'mem-cli.mjs', 'server.mjs', 'hook.mjs', 'install.mjs',
+]);
+
 export function checkDevDrift(installDir, sourceFiles) {
   if (!existsSync(installDir)) {
     return { devMode: false, drift: false, symlinkCount: 0, plainCount: 0, plainFiles: [], missingCount: 0, details: [] };
@@ -34,6 +53,8 @@ export function checkDevDrift(installDir, sourceFiles) {
   // because there's nothing to drift from.)
   const devMode = symlinkFiles.length > 0;
   const drift = devMode && plainFiles.length > 0;
+  const missingEntry = missing.filter((rel) => ENTRY_POINTS.has(rel));
+  const missingModules = missing.filter((rel) => !ENTRY_POINTS.has(rel));
   return {
     devMode,
     drift,
@@ -42,6 +63,12 @@ export function checkDevDrift(installDir, sourceFiles) {
     plainFiles,
     missingCount: missing.length,
     missingFiles: missing.slice(0, 5),
+    // Split so the caller can grade by consequence rather than by count: an entry point is
+    // fatal in every install shape, an import-only module only in a copy install.
+    missingEntryCount: missingEntry.length,
+    missingEntryFiles: missingEntry.slice(0, 5),
+    missingModuleCount: missingModules.length,
+    missingModuleFiles: missingModules.slice(0, 5),
     details: plainFiles.slice(0, 5),
   };
 }

package/lib/get-core.mjs

@@ -23,6 +23,21 @@ export const SESSION_DETAIL_FIELDS = ['id', 'request', 'investigated', 'learned'
  * @param {number[]} ids
  * @returns {object[]} full observation rows (SELECT *), created order
  */
+export function supersededNotice(row) {
+  if (!row || !row.superseded_at) return null;
+  // Every LIST surface (search / recent / timeline / browse / injection) filters
+  // superseded rows out, so the only way to reach one is to name its id — which is
+  // exactly what a stale citation in a transcript, a note, or an old handoff does.
+  // Both detail faces render fields in OBS_FIELDS order, putting `lesson_learned`
+  // near the top and `superseded_at` ~15 lines below it: a reader taking the first
+  // actionable line away from `mem_get(1)` takes the RETRACTED advice and never
+  // reaches the marker. Hoist it to the header so the retraction is read first.
+  const by = typeof row.superseded_by === 'number' ? `#${row.superseded_by}` : null;
+  return by
+    ? `⚠ RETRACTED — superseded by ${by}. Read ${by} instead; the fields below are the withdrawn version.`
+    : '⚠ RETRACTED — superseded (auto-dedup or merge). The fields below are the withdrawn version.';
+}
+
 export function fetchObsDetail(db, ids) {
   const ph = ids.map(() => '?').join(',');
   try {

package/lib/import-jsonl.mjs

@@ -102,11 +102,18 @@ function importToolPair(db, toolUse, toolResult, project) {
   const filesRead = toolName === 'Read' && toolUse.input?.file_path
       ? [toolUse.input.file_path] : [];
 
+  // `narrative` carries the body and `text` is the derived search blob
+  // (lib/observation-write.mjs rebuildObservationDerived). Writing the payload to `text`
+  // ONLY left every imported row outside that invariant, so a later `update` rebuilt
+  // `text` from a narrative that was empty and dropped the payload. Store the body in
+  // both: `narrative` as the durable home, `text` as the index copy the ingest paths
+  // write directly.
+  const body = `${inputJson}\n---\n${resultText}`;
   const safe = scrubRecord('observations', {
     title: `${toolName}: ${(toolUse.input?.command || toolUse.input?.file_path || '').slice(0, 80)}`,
     subtitle: '',
-    text: `${inputJson}\n---\n${resultText}`,
-    narrative: '',
+    text: body,
+    narrative: body,
     concepts: '',
     facts: '',
     lesson_learned: null,
@@ -265,6 +272,13 @@ export async function importJsonl(db, path, { project }) {
 
   // Orphan tool_use fallback: persist tool_use events that never paired with
   // a tool_result (truncated transcript / killed Claude Code session).
+  //
+  // `orphans` is a SUBSET counter, not a sibling of `observations`: each one writes a
+  // real observation row via the same importToolPair path. Counting it only under
+  // `orphans` made the summary say "+0 observations" for an import that had just
+  // written rows — a user backfilling a truncated transcript (the common shape, since
+  // the newest session is usually still open) read that as "nothing imported" and had
+  // no reason to run `recent`. The caller renders the subset relation explicitly.
   let orphans = 0;
   if (pendingToolUse.size > 0) {
     const tx2 = db.transaction(() => {
@@ -273,7 +287,7 @@ export async function importJsonl(db, path, { project }) {
           content: '[tool_use without result — transcript truncated]',
           timestamp: useEv.timestamp,
         };
-        if (tryImportToolPair(useEv, fauxResult)) orphans++;
+        if (tryImportToolPair(useEv, fauxResult)) { orphans++; observations++; }
       }
     });
     tx2();

package/lib/observation-write.mjs

@@ -86,12 +86,76 @@ export function insertObservationVector(db, obsId, vecText) {
  */
 // P2-12: internal-only since applyObsUpdate became the single update choke point
 // (both faces previously imported this directly; un-exported per knip discipline).
+/**
+ * The `text` search blob a row's columns imply, for a given narrative. Factored out so the
+ * rebuild can ask "is `text` already what I would derive?" with the exact same expression
+ * it writes — a second, drifting copy of the concatenation would defeat the check.
+ * @param {object} row observations row (title/subtitle/concepts/facts/lesson_learned/search_aliases)
+ * @param {string} narrative narrative to derive with ('' probes the already-derived shape)
+ * @returns {string}
+ */
+function derivedText(row, narrative) {
+  const base = [row.title, row.subtitle, narrative, row.concepts, row.facts, row.lesson_learned, row.search_aliases]
+    .filter(Boolean).join(' ');
+  const bigrams = cjkBigrams((row.title || '') + ' ' + (narrative || ''));
+  return bigrams ? base + ' ' + bigrams : base;
+}
+
+/**
+ * Does `text` look like an already-derived search blob rather than an orphaned body?
+ *
+ * Byte-equality against derivedText() cannot answer this: the OTHER producer of these rows
+ * (hook-llm.mjs buildFtsTextField) joins concepts + facts + aliases + bigrams and omits
+ * title and narrative entirely, so its output never equals this module's concatenation.
+ * What both derived shapes DO share is that every token comes from the row's own
+ * enrichment fields. A real body — an import-jsonl tool payload, a user's prose — carries
+ * tokens found nowhere else on the row. So: all-known ⇒ derived ⇒ do not promote.
+ * The title-only case falls out of the same test.
+ * @param {object} row observations row
+ * @returns {boolean}
+ */
+function looksAlreadyDerived(row) {
+  const text = String(row.text || '').trim();
+  if (!text) return true;
+  const known = new Set(
+    ([row.title, row.subtitle, row.concepts, row.facts, row.lesson_learned, row.search_aliases]
+      .filter(Boolean).join(' ') + ' ' + cjkBigrams(String(row.title || '')))
+      .split(/\s+/).filter(Boolean)
+  );
+  const tokens = text.split(/\s+/).filter(Boolean);
+  return tokens.length > 0 && tokens.every((t) => known.has(t));
+}
+
 function rebuildObservationDerived(db, obsId) {
-  const row = db.prepare('SELECT title, subtitle, narrative, concepts, facts, lesson_learned, search_aliases FROM observations WHERE id = ?').get(obsId);
+  const row = db.prepare('SELECT title, subtitle, narrative, concepts, facts, lesson_learned, search_aliases, text FROM observations WHERE id = ?').get(obsId);
   if (!row) return;
-  const base = [row.title, row.subtitle, row.narrative, row.concepts, row.facts, row.lesson_learned, row.search_aliases].filter(Boolean).join(' ');
-  const bigrams = cjkBigrams((row.title || '') + ' ' + (row.narrative || ''));
-  const textField = bigrams ? base + ' ' + bigrams : base;
+  // Deriving `text` from these columns is sound ONLY while `narrative` holds the body.
+  // Two ingest shapes break that: import-jsonl writes `narrative: ''` with the whole
+  // payload in `text`, and OBS_DEFAULTS defaults `narrative` to '' for any caller that
+  // omits it. On such a row the rebuild used to derive from a base with no body in it, so
+  // `update <id> --importance 3` — a field unrelated to content — replaced the payload
+  // with nothing but the row's own title. Unrecoverable: update takes no snapshot (only
+  // `delete` does), and the row also stopped matching searches for its own contents.
+  //
+  // Repair in place instead of guessing: promote the orphaned body into `narrative`, then
+  // derive. Content-preserving, and idempotent because the next rebuild sees a non-empty
+  // narrative.
+  //
+  // "Empty narrative" alone is NOT enough to conclude that `text` holds a body. A second
+  // production shape has an empty narrative legitimately: hook-llm.mjs (`narrative:
+  // obs.narrative || ''`), persistHaikuSummary and hook-optimize.mjs all write rows whose
+  // `text` is ALREADY the derived FTS blob — concepts + facts + aliases + CJK bigrams,
+  // which never contains a narrative. Promoting that blob would write bigram fragments
+  // ("构认", "证模") into a user-visible field rendered by both get faces, injected into
+  // context and fed to compress — irreversibly, since update takes no snapshot. Caught
+  // pre-tag by review; reproduced, then closed with looksAlreadyDerived() — see there for
+  // why byte-equality against derivedText() is the wrong test.
+  let narrative = row.narrative;
+  if ((!narrative || !narrative.trim()) && !looksAlreadyDerived(row)) {
+    narrative = row.text;
+    db.prepare('UPDATE observations SET narrative = ? WHERE id = ?').run(narrative, obsId);
+  }
+  const textField = derivedText(row, narrative);
   db.prepare('UPDATE observations SET text = ? WHERE id = ?').run(textField, obsId);
   insertObservationVector(db, obsId, textField);
 }

package/mem-cli.mjs

@@ -9,7 +9,7 @@ import { resolveProject } from './project-utils.mjs';
 import { _resetVocabCache, vecTextForRow, vectorsEnabled } from './tfidf.mjs';
 import { reRankWithContext } from './search-scoring.mjs';
 import { searchObservationsHybrid } from './search-engine.mjs';
-import { fetchObsDetail, OBS_FIELDS, SESSION_DETAIL_FIELDS } from './lib/get-core.mjs';
+import { fetchObsDetail, OBS_FIELDS, SESSION_DETAIL_FIELDS, supersededNotice } from './lib/get-core.mjs';
 import { collectBrowseTiers, getActiveMemorySessionId, BROWSE_TIERS, BROWSE_TIER_LABELS } from './lib/browse-core.mjs';
 import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady } from './deep-search.mjs';
 import { ensureRegistryDb, upsertResource, collectRegistryStats, listResourcesRanked, formatRegistryListLine } from './registry.mjs';
@@ -532,6 +532,9 @@ function renderObsRows(db, ids, requestedFields) {
   const parts = [];
   for (const r of rows) {
     const lines = [`#${r.id} [${r.type}] ${fmtDateShort(r.created_at)}`];
+    // Retraction first (shared with mem_get via get-core) — see supersededNotice.
+    const retracted = supersededNotice(r);
+    if (retracted) lines.push(retracted);
     for (const f of fields) {
       if (f === 'id' || f === 'type' || f === 'created_at') continue;
       const val = r[f];
@@ -1853,7 +1856,21 @@ function cmdRestore(db, argv) {
   const totalMalformed = malformed + parseFailures;
   const totalLines = rows.length + parseFailures;
   const tombstoneNote = tombstoned > 0 ? `, ${tombstoned} compressed member(s) rejected (keeper-absorbed or auto-retired tombstones)` : '';
-  out(`[mem] Restore${dryRun ? ' (dry-run)' : ''}: ${restored} restored, ${skipped} duplicate(s) skipped${tombstoneNote}, ${totalMalformed} malformed/failed from ${totalLines} row(s).`);
+  // Past tense only when rows were actually written. `Restore (dry-run): 6 restored` reads
+  // as done to anyone skimming past the parenthetical, and this command's whole job is to
+  // let a user check a backup BEFORE trusting it.
+  out(`[mem] Restore${dryRun ? ' (dry-run)' : ''}: ${restored} ${dryRun ? 'would be restored (at most)' : 'restored'}`
+    + `, ${skipped} duplicate(s) ${dryRun ? 'would be skipped' : 'skipped'}${tombstoneNote}`
+    + `, ${totalMalformed} malformed/failed from ${totalLines} row(s).`);
+  if (dryRun) {
+    // The preview applies the durable exact-dup guard (project+title+created_at) but NOT
+    // saveObservation's Jaccard near-duplicate collapse, which only exists once rows are
+    // being written. Measured: a backup holding two same-titled weekly summaries previewed
+    // 10 and restored 9. Simulating Jaccard here would mean a second copy of the dedup rule
+    // — the drift class this codebase keeps paying for — so the number is labelled an upper
+    // bound instead. Run without --dry-run for the exact count.
+    out('[mem] Note: the preview does not simulate near-duplicate collapse, so the real run may restore fewer.');
+  }
   // Name the lossiness where the user meets it. Export omits related_ids and drops
   // superseded rows, and restore re-inserts under fresh AUTOINCREMENT ids — so no
   // cross-link can survive the round-trip. That is a deliberate format tradeoff (stored
@@ -2823,6 +2840,8 @@ Commands:
     recent [N]          Most recent events [--type T] [--project P]
     show <id>           Show full event row by id
     delete <id1,id2,…>  Delete events by ID (preview by default; use --confirm to execute)
+    promote             Promote insight-bearing events (body + importance>=2) to searchable
+                        observations (preview by default; use --execute to apply)
 
     Valid types: bugfix, lesson, bug, discovery, refactor, feature, observation, decision
     --files (plural, comma-split) preferred; --file (singular) kept for back-compat.
@@ -2964,14 +2983,18 @@ async function cmdImportJsonl(db, argv) {
     totalSkip += r.skipped;
     totalOrphans += r.orphans || 0;
     totalRecognized += r.recognized || 0;
-    out(`[mem] ${f}: +${r.prompts} prompts, +${r.observations} observations, ${r.orphans || 0} orphan tool_use, ${r.skipped} skipped`);
+    out(`[mem] ${f}: +${r.prompts} prompts, +${r.observations} observations`
+      + `${r.orphans ? ` (${r.orphans} from unpaired tool_use)` : ''}, ${r.skipped} skipped`);
   }
   const errorTail = errorCount > 0 ? `, ${errorCount} file(s) errored` : '';
-  out(`[mem] Total: ${totalPrompts} prompts, ${totalObs} observations, ${totalOrphans} orphan tool_use, ${totalSkip} skipped from ${files.length} file(s)${errorTail}.`);
-  if (totalPrompts > 0 || totalObs > 0 || totalOrphans > 0) {
-    // Orphan tool_use events persist as (truncated) observations, so they count as
-    // "something was imported" — otherwise an orphan-only first import would wrongly
-    // fall through to the "already imported" no-op branch below.
+  out(`[mem] Total: ${totalPrompts} prompts, ${totalObs} observations`
+    + `${totalOrphans ? ` (${totalOrphans} from unpaired tool_use)` : ''}`
+    + `, ${totalSkip} skipped from ${files.length} file(s)${errorTail}.`);
+  if (totalPrompts > 0 || totalObs > 0) {
+    // Orphan tool_use events persist as (truncated) observations and are counted INSIDE
+    // totalObs (lib/import-jsonl.mjs), so they already count as "something was imported"
+    // — an orphan-only first import must not fall through to the "already imported"
+    // no-op branch below.
     out(`[mem] Try: claude-mem-lite recent 5 --project ${project}`);
   } else if (totalRecognized > 0) {
     // Lines WERE Claude Code transcript events but produced no new rows — the file

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.68.0",
+  "version": "3.69.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.68.0",
+      "version": "3.69.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.26.0",
         "better-sqlite3": "^12.6.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.68.0",
+  "version": "3.69.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",

package/project-utils.mjs

@@ -12,6 +12,20 @@ const _cache = new Map();
 /**
  * Infer a sanitized project name from CLAUDE_PROJECT_DIR, PWD, or cwd.
  * Format: "parent--basename" with non-alphanumeric chars replaced by hyphens.
+ *
+ * Deliberately does NOT anchor on the git work-tree root. That was tried and reverted
+ * before it shipped: it fixes `cd src/auth && claude-mem-lite recent` (session rooted at
+ * the repo root, CLI run deeper) but BREAKS the mirror case, which is more common —
+ * CLAUDE_PROJECT_DIR is the directory Claude Code was started in, not the repo root, so
+ * `cd packages/api && claude` makes hooks write `packages--api` while a plain terminal in
+ * the same directory would walk to the work-tree root and read `mono--monorepo`.
+ * Reproduced pre-tag: hooks saved to `packages--api`, `recent` answered
+ * `No recent observations (h1--mono)`. Splitting a monorepo user's namespace silently is
+ * worse than the subdirectory case, and unlike it, cwd-derivation at least keeps the hook
+ * and CLI faces agreeing whenever the session root and cwd match. A correct fix has to
+ * consult the DB for which candidate actually holds rows; this module is DB-free and on
+ * the hook hot path, so it is not the place. Tracked as deferred work.
+ *
  * @returns {string} Sanitized project identifier safe for use in filenames
  */
 export function inferProject() {

package/scripts/pre-tool-recall.js

@@ -19,6 +19,13 @@ import { shouldWarnReread, buildRereadWarning, readFileMeta } from '../lib/rerea
 import { recordMetric } from '../lib/metrics.mjs';
 import { presentIdents } from '../lib/lesson-idents.mjs';
 import { neutralizeContextDelimiters } from '../format-utils.mjs';
+// Recall queries the SAVE-path project, so this MUST produce the same string as the
+// save path. It used to be a hand-kept copy of the same 6 lines; that copy had already
+// drifted once (missing the process.env.PWD fallback, so a symlinked project dir
+// recalled nothing) and would have drifted again when the 2026-08-17 e2e round taught inferProject to
+// anchor on the git work-tree root. project-utils.mjs is a leaf module over path/fs/os
+// only — cheaper than several imports this script already carries.
+import { inferProject } from '../project-utils.mjs';
 
 import { DAY_MS } from '../lib/time-constants.mjs';
 // CLAUDE_MEM_DIR matches schema.mjs / main CLI — one env var sandboxes the
@@ -127,21 +134,6 @@ async function bridgeTopLesson(rows, changeText) {
 
 // ─── Helpers ────────────────────────────────────────────────────────────────
 
-// SYNC: must produce the SAME string as utils.mjs::inferProject (the path obs are SAVED
-// under) and the bash post-tool-use.sh fast-path — recall queries the SAVE-path project.
-// This previously used process.cwd() WITHOUT the process.env.PWD fallback the other two
-// have, so under a symlinked project dir (PWD = logical/symlinked path, cwd = resolved)
-// with CLAUDE_PROJECT_DIR unset it computed a DIFFERENT project than the save path and
-// silently recalled nothing. Resolution order + sanitize + 100-char cap now match utils.
-function inferProject() {
-  const dir = process.env.CLAUDE_PROJECT_DIR || process.env.PWD || process.cwd();
-  const base = basename(dir);
-  const parent = basename(join(dir, '..'));
-  const raw = (parent && parent !== '.' && parent !== '/')
-    ? `${parent}--${base}` : base;
-  return raw.replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 100);
-}
-
 function readCooldown(cooldownPath) {
   try { return JSON.parse(readFileSync(cooldownPath, 'utf8')); } catch { return {}; }
 }

package/scripts/user-prompt-search.js

@@ -144,12 +144,35 @@ const OR_TOP_BM25_FLOOR = TOP_REL_FLOOR === 0
 // one was dropped by the OR floor at |bm25| 3.8–15.2 < 30. The plugin is inert
 // during exactly the window where a new user decides whether it earns its keep.
 //
-// Fix: scale both floors by ln(N+1)/ln(N_REF+1), capped at 1.0 — the same log
-// shape the IDF term has, so the SIGNAL↔NOISE separation the maintainer measured
+// Fix: scale both floors by the corpus's MAX ATTAINABLE IDF over the reference
+// corpus's, capped at 1.0, so the SIGNAL↔NOISE separation the maintainer measured
 // (signal ≥41, noise ≤22 at N_REF) is preserved proportionally at any N. At
 // N ≥ N_REF the factor is exactly 1.0, so every established install keeps
 // byte-identical behavior; only genuinely-new installs relax.
 //
+// 2026-08-17 e2e round — the ramp shape. The first cut used ln(N+1)/ln(N_REF+1), which has the
+// right asymptotics but the wrong small-N behavior: FTS5's IDF term is
+// `log((N - df + 0.5) / (df + 0.5))`, which is EXACTLY 0 at N=2/df=1 and stays far
+// below ln(N+1) for the whole first-week window. Re-measured end-to-end through the
+// production write path (lib/save-observation.mjs — a raw INSERT skips CJK bigram
+// expansion and understates the corpus, which is how the first cut's ramp table was
+// misread), 1 planted target + topically clustered filler, CJK prose prompt carrying
+// no identifier for the bypass to rescue:
+//
+//   N              2     3     4     5     6    10    25    80
+//   top|bm25|     0.0   5.1   7.0   9.5  11.4  15.5  22.2  30.3
+//   ln ramp floor 5.2   6.5   7.6   8.4   9.2  11.3  15.3  20.7   ← DROP at N≤4
+//   idf ramp floor 0.0  2.6   4.3   5.5   6.5   9.3  14.1  20.0   ← admits all
+//
+// The two ramps agree within 8% at N≥30 and within 2% at N≥200, so this re-shape is
+// confined to the window it is meant to fix. Accepted tradeoff: on a ≤2-row corpus the
+// scale is EXACTLY 0 (FTS5's max IDF is 0 there), which disables both set-level floors
+// rather than lowering them, and just above that they are small; so the best lexical match
+// is injected even when it is weak.
+// That is the intended trade — the alternative measured behavior is total silence, and
+// a 4-row corpus has no room to bury signal under noise. The upstream
+// hasExplicitSignal gate, not these floors, is what suppresses noise prompts.
+//
 // N counts the WHOLE observations table, not the project: FTS5 computes IDF over
 // the entire index and `o.project = ?` is a post-MATCH filter. Verified — a
 // 2-row project on a 302-row install scores 31.5, matching the 300-row global
@@ -158,7 +181,25 @@ const OR_TOP_BM25_FLOOR = TOP_REL_FLOOR === 0
 const FLOOR_REF_CORPUS = Number(process.env.CLAUDE_MEM_UPS_FLOOR_REF_CORPUS || 584);
 
 /**
- * Scale factor in (0, 1] for the absolute score floors, by total corpus size.
+ * FTS5's IDF term for the best case a query can hit: a term appearing in exactly
+ * one row (df=1) of an n-row index. SQLite computes
+ * `log((n - df + 0.5) / (df + 0.5))`, so this is the ceiling any single-term bm25
+ * contribution can reach at corpus size n — the quantity the absolute floors are
+ * implicitly denominated in. Clamped at 0: below n=2 the formula goes negative,
+ * which as a scale would flip the comparison rather than relax it.
+ * @param {number} n Row count.
+ * @returns {number} Max attainable IDF at this corpus size, ≥ 0.
+ */
+function maxIdf(n) {
+  // n <= 1 makes the numerator non-positive → Math.log returns NaN or -Infinity, and
+  // Math.max(0, NaN) is NaN, not 0. Short-circuit instead: a 0- or 1-row index has no
+  // term that can discriminate, so the max attainable IDF is 0.
+  if (!(n > 1)) return 0;
+  return Math.max(0, Math.log((n - 1 + 0.5) / 1.5));
+}
+
+/**
+ * Scale factor in [0, 1] for the absolute score floors, by total corpus size.
  *
  * Short-circuits with a bounded probe: if a row exists at offset N_REF-1 the
  * corpus is at or above the reference and the factor is 1.0 — no COUNT scan on
@@ -173,7 +214,12 @@ export function corpusFloorScale(db) {
     const atRef = db.prepare('SELECT 1 FROM observations LIMIT 1 OFFSET ?').get(FLOOR_REF_CORPUS - 1);
     if (atRef) return 1;
     const { c = 0 } = db.prepare('SELECT count(*) AS c FROM observations').get() || {};
-    return Math.min(1, Math.log(c + 1) / Math.log(FLOOR_REF_CORPUS + 1));
+    const refIdf = maxIdf(FLOOR_REF_CORPUS);
+    // Degenerate reference (CLAUDE_MEM_UPS_FLOOR_REF_CORPUS set to 2 or 3, where
+    // maxIdf is 0 or near it): division would blow up or divide by zero. Treat the
+    // floors as fully calibrated, matching the FLOOR_REF_CORPUS <= 1 guard above.
+    if (!(refIdf > 0)) return 1;
+    return Math.min(1, maxIdf(c) / refIdf);
   } catch {
     // Any probe failure → behave exactly as before the ramp existed.
     return 1;
@@ -761,10 +807,22 @@ async function main() {
     // when CLAUDE_MEM_UPS_IDENTIFIER_BYPASS=0 (bypass is default-on), then it is a no-op.
     const promptIdentifiers = IDENTIFIER_BYPASS ? extractTechIdentifiers(promptText) : [];
 
-    if (intent?.useRecent) {
-      // Recall intent: show recent observations
-      rows = searchRecent(db, project, intent.limit);
-    } else if (REQUIRE_EXPLICIT_SIGNAL && !signalPresent) {
+    // Recall intent ("之前 / previously / 记得 …") used to short-circuit straight to
+    // searchRecent, discarding the prompt text — so the most explicit memory request a
+    // user can make was the one answered without reading what they asked about. Measured
+    // on a 600-row corpus, two prompts one word apart: "分页接口又报 500 了，边界问题怎么处理"
+    // put the right row at rank 1, while "…之前那个边界问题是怎么处理的" surfaced NEITHER it
+    // nor anything related — 5 unrelated recency rows instead. Adding the recall keyword
+    // removed the answer and spent the injection budget on noise.
+    //
+    // Recency is still the right answer for a CONTENTLESS recall prompt ("之前我们在做什么"),
+    // which has no topic to match — so it becomes a FALLBACK (below) rather than a
+    // short-circuit. The explicit-signal gate needs no recall-intent carve-out:
+    // hasExplicitSignal already returns true whenever `intent` is truthy, and recall intent
+    // implies that, so a recall prompt cannot reach the no-signal branch. (An earlier draft
+    // added `!recentFallback &&` here; review showed the condition was dead.)
+    const recentFallback = Boolean(intent?.useRecent);
+    if (REQUIRE_EXPLICIT_SIGNAL && !signalPresent) {
       // No explicit signal — skip FTS pipeline + prompt-fallback. sigRows
       // is already empty (errSig was null else signalPresent would be true).
       // Registry skill pointer below remains unaffected (its own name match).
@@ -848,6 +906,13 @@ async function main() {
       rows = rows.slice(0, MAX_RESULTS);
     }
 
+    // Recall-intent fallback (see the `recentFallback` rationale above): only when the
+    // prompt named nothing the corpus matches. A contentless "之前我们在做什么" lands here
+    // and behaves exactly as it did before; a topical recall prompt no longer does.
+    if (rows.length === 0 && recentFallback) {
+      rows = searchRecent(db, project, intent.limit);
+    }
+
     // A (v2.32.8): prepend error-signature hits (higher precision), dedup, cap.
     if (sigRows.length > 0) {
       const sigIds = new Set(sigRows.map(r => r.id));

package/server.mjs

@@ -23,7 +23,7 @@ import {
 } from './lib/maintain-core.mjs';
 import { snapshotDb } from './lib/db-backup.mjs';
 import { deleteObservations, previewDeleteRows } from './lib/delete-core.mjs';
-import { fetchObsDetail, OBS_FIELDS, SESSION_DETAIL_FIELDS } from './lib/get-core.mjs';
+import { fetchObsDetail, OBS_FIELDS, SESSION_DETAIL_FIELDS, supersededNotice } from './lib/get-core.mjs';
 import { collectBrowseTiers, getActiveMemorySessionId, BROWSE_TIERS, BROWSE_TIER_LABELS } from './lib/browse-core.mjs';
 import { effectiveQuiet, RUNTIME_DIR } from './hook-shared.mjs';
 import { computeStatsFeed } from './lib/stats-core.mjs';
@@ -628,6 +628,9 @@ server.registerTool(
       for (const row of rows) {
         foundBySource.obs.add(row.id);
         const lines = [`── #${row.id} ──`];
+        // Retraction first (shared with the CLI `get` via get-core) — see supersededNotice.
+        const retracted = supersededNotice(row);
+        if (retracted) lines.push(retracted);
         for (const f of renderFields) {
           const val = row[f];
           if (val === null || val === undefined || val === '') continue;
@@ -826,6 +829,9 @@ server.registerTool(
     inputSchema: memSaveSchema,
   },
   safeHandler(async (args) => {
+    // `obs_type` → `type`: the sibling read tools all name it obs_type (see the schema
+    // comment). Without this, an unknown key was dropped and the row saved as `discovery`.
+    args = applyArgAliases(args, { obs_type: 'type' });
     if (args.project) args = { ...args, project: resolveProject(args.project) };
     const project = args.project || inferProject();
 
@@ -1661,6 +1667,8 @@ server.registerTool(
     inputSchema: memUpdateSchema,
   },
   safeHandler(async (args) => {
+    // `obs_type` → `type`, same alias mem_save takes — see the schema comment.
+    args = applyArgAliases(args, { obs_type: 'type' });
     const obs = db.prepare('SELECT id, title FROM observations WHERE id = ?').get(args.id);
     if (!obs) return { content: [{ type: 'text', text: `Observation #${args.id} not found` }], isError: true };
 

package/tool-schemas.mjs

@@ -204,6 +204,13 @@ export const memSaveSchema = {
   content: z.string().min(1).max(50000).describe('Memory content to save'),
   title: z.string().optional().describe('Short title'),
   type: OBS_TYPE_ENUM.optional().describe('Observation type (default: discovery)'),
+  // Alias, same treatment memRecentSchema gives `type`. mem_search/mem_recall/mem_recent
+  // all name this field `obs_type`, mem_save named it only `type`, and the schema is
+  // non-strict — so `mem_save(obs_type: "bugfix")` (the shape a caller reaches for right
+  // after a search) dropped the unknown key and saved a `discovery` row with no error.
+  // A silently-wrong type changes type_quality ranking AND makes the row invisible to
+  // every `--type bugfix` filter, so it must not be a silent coercion.
+  obs_type: OBS_TYPE_ENUM.optional().describe('Alias for `type` (parity with mem_search/mem_recent)'),
   project: z.string().optional().describe('Project name (default: inferred from CWD)'),
   importance: coerceInt.pipe(z.number().int().min(1).max(3)).optional().describe('Importance level: 1=routine, 2=notable, 3=critical (default: 2 for explicit saves)'),
   files: coerceStringArray.optional().describe('File paths associated with this observation. Stored in the `files_modified` column and rendered as `files` — passing a path here does not assert the file was edited; a file you only read belongs here too'),
@@ -261,6 +268,11 @@ export const memUpdateSchema = {
   // '' would blank narrative/lesson/concepts irrecoverably (mem_update takes no snapshot).
   narrative: z.string().refine(s => s.trim() !== '', 'narrative cannot be empty').optional().describe('New narrative/content'),
   type: OBS_TYPE_ENUM.optional().describe('New observation type'),
+  // Same alias as memSaveSchema, for the same reason and found by the same review: without
+  // it `mem_update({id, importance: 3, obs_type: 'bugfix'})` reported
+  // "Updated observation #N: importance" and dropped the type silently. (obs_type alone
+  // errored loudly with "No fields to update", so only the mixed call was dangerous.)
+  obs_type: OBS_TYPE_ENUM.optional().describe('Alias for `type` (parity with mem_search/mem_recent)'),
   importance: coerceInt.pipe(z.number().int().min(1).max(3)).optional().describe('New importance (1-3)'),
   // 500-char cap mirrors memSaveSchema + cmdUpdate — update was the one path
   // that let overlong lessons leak into the DB via MCP.