claude-mem-lite 6.8.2 → 6.9.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.8.2",
+      "version": "6.9.0",
       "source": "./",
       "homepage": "https://github.com/sdsrss/claude-mem-lite",
       "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": "6.8.2",
+  "version": "6.9.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/README.md

@@ -128,7 +128,7 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 - **FTS integrity management** -- `mem_fts_check` tool verifies FTS5 index health or rebuilds indexes on demand, useful after database recovery or when search results seem wrong
 - **Atomic multi-table writes** -- `saveObservation` wraps the observations + observation_files INSERTs in a single `db.transaction()`, preventing orphaned rows on crash
 - **Modular NLP pipeline** -- Synonym maps, stop words, scoring constants, and query building extracted into focused modules (`synonyms.mjs`, `stop-words.mjs`, `scoring-sql.mjs`, `nlp.mjs`) for independent testing and maintenance
-- **Porter-aligned PRF** -- Pseudo-relevance feedback terms are now stemmed with the same Porter algorithm used by FTS5, ensuring PRF expansion terms match the search index
+- **Surface-form PRF expansion** -- `observations_fts` is built on FTS5's default `unicode61` tokenizer, so the index is **not stemmed**: a query term matches the word forms actually stored, and `crash` does not match a row that only contains `crashes`. Pseudo-relevance feedback therefore uses the Porter stemmer only to *bucket* morphological variants when judging which candidate terms are discriminative, and emits the most frequent **surface** form of each — emitting a bare stem (`cach`) would match nothing and kill expansion recall
 
 ## Platform Support
 
@@ -735,7 +735,7 @@ claude-mem-lite/
   hook-semaphore.mjs   # LLM concurrency control: file-based semaphore for background workers
   schema.mjs           # Database schema: single source of truth for tables, migrations, FTS5
   tool-schemas.mjs     # Shared Zod schemas for MCP tool validation
-  tfidf.mjs            # tokenization + Porter stemming (name is historical: the TF-IDF vector engine it held was removed)
+  tfidf.mjs            # the Porter stemmer (name is historical: the TF-IDF vector engine it held was removed)
   tier.mjs             # Temporal tier system: activity-based time window classification
   utils.mjs            # Re-export hub: backward-compatible surface for all utility modules
   nlp.mjs              # FTS5 query building: synonym expansion, CJK bigrams, sanitization

package/adopt-cli.mjs

@@ -425,6 +425,13 @@ function unadoptAll(args) {
       log(`[unadopt --all] ${dir} → cleaned partial residue (detail doc/state, no block)`);
       partial++;
     }
+    // OUTSIDE the branch, because residue is orthogonal to what happened to the block: a
+    // project can have its block removed AND still carry an unpaired sentinel. An orphan is
+    // the one kind of residue the sweep cannot finish — its block has no end marker, so its
+    // extent is unknowable — and the two lines above would otherwise imply the project is
+    // clean. Inside the else-branch it was also unreachable for the 'removed' case, which is
+    // how the print survived a mutation with the whole suite green (pre-ship review P2-2).
+    if (r.residue) log(`  ⚠ ${r.residue}`);
   }
 
   // 2. Legacy memory-dir cleanup across every memdir (foreign-content guarded).
@@ -481,4 +488,8 @@ export function cmdUnadopt(args = []) {
   const mig = migrateLegacyMemoryDir(cwd, PLUGIN_SLUG, { force });
   const migNote = mig.action === 'removed' ? ' (+cleaned legacy memdir)' : '';
   log(`[unadopt] ${cwd} → ${r.action}${migNote}`);
+  // 'partial' is the outcome that used to print as 'absent': the sidecar files are gone but
+  // an unpaired sentinel still holds steering text in the user's CLAUDE.md, and only they can
+  // decide where that text ends. Silence here is what let it survive every sweep.
+  if (r.residue) log(`  ⚠ ${r.residue}`);
 }

package/claudemd.mjs

@@ -59,8 +59,50 @@ function escapeRe(s) {
 // are `\r?\n` (not bare `\n`) so a CLAUDE.md re-saved with Windows CRLF endings
 // still matches — otherwise the block read as "absent" and a fresh LF copy got
 // appended every SessionStart, growing the file without bound (review C1/H2).
+// The body may not contain ANOTHER sentinel of the same slug. `[\s\S]*?` could, and that is
+// not a tidiness point — it is how a match stopped being one block. Drop the `:end` line by
+// hand (a merge resolution, an editor, another tool) and the next adopt appends a second
+// block below whatever the user has written since; the adopt after THAT matched from the
+// orphaned begin, lazily, to the only `:end` in the file — which now sits past the user's
+// text and past the second begin — so `raw.replace(m[0], section)` deleted all of it.
+// Measured 2026-09-13: a "## Deployment runbook" section appended after adoption was gone
+// after two further adopts, silently, with both runs reporting success.
+//
+// The tempered token below cannot span a sentinel, so the engine backtracks to the
+// WELL-FORMED pair and the orphan is simply left alone — which is the right answer for a
+// file we do not own: where the orphaned body ends is genuinely unknowable, so removeManaged
+// reports it (action 'partial') rather than guessing a span to delete.
+//
+// Safe by construction for legitimate blocks: the shipped body carries the slug twice and
+// never as a sentinel (measured: 1304 bytes — 1296 UTF-16 units, the body has em dashes —
+// with zero `:begin` / `:end` occurrences), and the
+// separators stay `\r?\n` for the CRLF reason below.
 function blockBody(esc) {
-  return `<!-- ${esc}:begin (v\\d+) -->\\r?\\n([\\s\\S]*?)\\r?\\n<!-- ${esc}:end -->`;
+  const sentinel = `<!-- ${esc}:(?:begin|end)`;
+  return `<!-- ${esc}:begin (v\\d+) -->\\r?\\n((?:(?!${sentinel})[\\s\\S])*?)\\r?\\n<!-- ${esc}:end -->`;
+}
+
+// Any sentinel LINE of our slug, paired or not. The pair regex above is deliberately blind to
+// an unpaired one; this is what lets residue reporting see what it cannot safely remove.
+function sentinelLineRegexG(slug) {
+  return new RegExp(`<!-- ${escapeRe(slug)}:(?:begin|end)\\b[^>]*-->`, 'g');
+}
+
+/**
+ * Sentinel lines of this slug left in `raw` that no well-formed block accounts for.
+ * Zero on a healthy file (every sentinel belongs to a matched pair) and on a clean one.
+ * @param {string} raw
+ * @param {string} slug
+ * @returns {number}
+ */
+function orphanSentinelCount(raw, slug) {
+  const total = (raw.match(sentinelLineRegexG(slug)) || []).length;
+  let paired = 0;
+  raw.replace(blockRegexG(slug), (whole) => {
+    paired += (whole.match(sentinelLineRegexG(slug)) || []).length;
+    return whole;
+  });
+  return total - paired;
 }
 function blockRegex(slug) {
   return new RegExp(blockBody(escapeRe(slug)));
@@ -137,13 +179,24 @@ export function isAdopted(cwd, slug) {
  * removed it. removeManaged cleans all three pieces, so sweep on any of them.
  */
 export function hasResidue(cwd, slug) {
-  return (
-    readBlock(cwd, slug).body !== null ||
-    existsSync(detailDocPath(cwd, slug)) ||
-    existsSync(stateFilePath(cwd, slug))
-  );
+  const blk = readBlock(cwd, slug);
+  return blk.body !== null || existsSync(detailDocPath(cwd, slug)) || existsSync(stateFilePath(cwd, slug));
 }
 
+// An unpaired sentinel is deliberately NOT in the list above (pre-ship review P2-3). A first
+// cut added it, reasoning that the sweep should see what the pair regex cannot. But
+// orphanSentinelCount counts sentinel-shaped TEXT, and a project the plugin never touched can
+// mention the marker in prose — documenting it, pasting half an example, a changelog line.
+// That one mention let `unadopt --all` into a stranger's project, where removeManaged
+// unconditionally deletes the detail doc and state sidecar and rmdir's an empty `.claude/`,
+// then printed "remove those lines by hand" at the user's own paragraph — and never
+// converged, because the mention is still there on the next sweep.
+//
+// The three entries above are all things the PLUGIN WROTE; a sentinel in prose is not. And
+// the sweep gains nothing by entering: removeManaged cannot clean an orphan anyway, by
+// design. The orphan is reported by removeManaged when unadopt genuinely runs — which is the
+// real failure case, where the doc and sidecar are still present and do bring it in.
+
 /**
  * Whether the installed block/doc has drifted from the shipped content — i.e.
  * a version bump or a template edit means we should refresh. Returns true when
@@ -232,11 +285,25 @@ export function writeManaged(cwd, { slug, version, block, doc }) {
  * Remove our managed block from CLAUDE.md (preserving all other content) and
  * delete the detail doc + state sidecar. Best-effort removes an emptied
  * .claude/ directory.
- * @returns {{action: 'removed'|'absent'}}
+ *
+ * THREE outcomes, not two — the same rule lib/db-unusable.mjs states about backups: "there
+ * is nothing to do" and "I could not finish" must not print in the same voice, because a
+ * green-sounding line ends the reader's search. `absent` used to cover both: with one
+ * sentinel line missing, the pair regex matched nothing, so this returned 'absent' — while
+ * having already deleted the detail doc and the state sidecar and left ~1.3 KB of managed
+ * steering text in the user's CLAUDE.md, which it is then loaded from on every session.
+ * `partial` is that case, and `residue` names what is left so the caller can say so.
+ *
+ * Deliberately does NOT delete an orphaned sentinel's body: where it ends is unknowable
+ * (that is the defect, not a detail), and guessing a span in a file we do not own is how the
+ * adopt side came to delete a user's runbook. Report, do not repair.
+ *
+ * @returns {{action: 'removed'|'partial'|'absent', residue?: string}}
  */
 export function removeManaged(cwd, slug) {
   const p = claudeMdPath(cwd);
   let action = 'absent';
+  let orphans = 0;
   if (existsSync(p)) {
     let raw = readFileSync(p, 'utf8');
     // H2: loop so ALL same-slug blocks are removed, not just the first (a
@@ -283,8 +350,17 @@ export function removeManaged(cwd, slug) {
         atomicWrite(p, raw);
       }
     }
+    // Counted on what is left AFTER the loop, so a healthy file (every sentinel consumed by
+    // a matched pair) reports zero and only a genuinely unpaired line survives the count.
+    orphans = orphanSentinelCount(raw, slug);
   }
+  // Captured BEFORE the deletions below, because they are what it asks about: is there any
+  // evidence the plugin ever wrote in this project? An unpaired sentinel is NOT such
+  // evidence — it is text, and a project that merely documents the marker in prose has one
+  // (pre-ship review P2-3). Reporting residue there means telling a stranger to delete their
+  // own paragraph, on a project this tool has never touched.
   const dp = detailDocPath(cwd, slug);
+  const wasOurs = action === 'removed' || existsSync(dp) || existsSync(stateFilePath(cwd, slug));
   if (existsSync(dp))
     try {
       unlinkSync(dp);
@@ -300,6 +376,18 @@ export function removeManaged(cwd, slug) {
   } catch {
     /* best-effort */
   }
+  // `action` answers ONE question — what happened to the block — and `residue` is an
+  // independent fact that rides alongside it. A first cut let an orphan override 'removed'
+  // too, on the reasoning that both are "unfinished". Pre-ship review P2-1: unadoptAll's
+  // else-branch prints "cleaned partial residue (detail doc/state, no block)" and counts
+  // `partial++`, so a sweep that DID remove a block reported "no block" and tallied zero
+  // removals. Two facts, two fields.
+  const residue =
+    orphans > 0 && wasOurs
+      ? `${orphans} unpaired \`${slug}\` sentinel line(s) remain in ${claudeMdPath(cwd)} — the block they opened has no matching end marker, so its extent cannot be determined safely. Remove those lines and the text they wrap by hand.`
+      : null;
+  if (action === 'removed') return residue ? { action, residue } : { action };
+  if (residue) return { action: 'partial', residue };
   return { action };
 }
 

package/cli/common.mjs

@@ -83,7 +83,120 @@ export function parseArgs(argv) {
       i++;
     }
   }
-  return { positional, flags };
+  return { positional, flags: trackFlagReads(flags) };
+}
+
+// ─── Inert selection flags ───────────────────────────────────────────────────
+//
+// The third cause of the harm parseArgs' docblock names twice. `--include_noise` (underscore
+// spelling) and `--obs_type` (an MCP field name) both parsed, matched no reader, and let the
+// command answer the unfiltered question; both are fixed above. `suggestUnknownFlags` fixes a
+// third case, flags unknown to the whole CLI. What is left is the case where NOTHING is
+// misspelled: `--type` is canonical and real — on `search`, `save` and `export` — so it clears
+// the global known-flag set, and `browse` simply never reads it. Measured before the fix:
+// `browse --type bugfix` printed rows of every type, exit 0, not a word.
+//
+// The check is read-tracking, not a per-command flag manifest, and that is the whole design.
+// A manifest rots, and worse, it cannot see a flag that a command forwards wholesale into a
+// core helper (`cmdSearch` hands the object to the pipeline, `cmdExport` to the writer) —
+// deriving "which flags does this command read" from its own body would fire on every one of
+// those. Watching what the object is actually ASKED for is exact in both directions.
+//
+// Scope is SELECTION-shaped flags only. Those are the ones whose silent drop hands back a
+// wider set that reads as the answer, which is the harm. A `--confirm` that a short-circuited
+// branch never reached is deliberately out of scope: nothing there is wrong, and a warning on
+// correct usage is worse than the silence it replaces.
+//
+// `prompts-limit` is NOT here, and the reason generalises: `doctor --benchmark --prompts-limit`
+// is read off raw `process.argv` in cli/doctor.mjs and never touches a flags object, so
+// read-tracking would call a working flag inert. Anything read off argv must stay out.
+export const FILTER_FLAGS = new Set([
+  'type',
+  'source',
+  'project',
+  'tier',
+  'since',
+  'from',
+  'to',
+  'branch',
+  'scope',
+  'importance',
+  'limit',
+  'offset',
+  'sort',
+  'days',
+  'age-days',
+  // Inclusion toggles, added after the same correct-usage sweep the first batch passed. They
+  // widen or narrow the SET rather than filter within it, and the harm runs the other way:
+  // an ignored `--include-noise` hands back FEWER rows than asked for, and "I searched and it
+  // was not there" is the worst answer a memory tool can give. Held back at first only
+  // because booleans are read inside branches and were the likelier false-alarm shape; the
+  // exit-code gate below turned out to cover that class, and the sweep reads zero.
+  'all',
+  'include-noise',
+  'include-compressed',
+  'deep',
+  'no-deep',
+  'or',
+  'rerank',
+]);
+
+let suppliedFlags = new Set();
+let readFlags = new Set();
+
+/**
+ * Wrap a parsed flags object so every lookup is recorded.
+ *
+ * `get` and `has` are both trapped: a reader spelled `if ('tier' in flags)` must count as a
+ * read exactly like `flags.tier`. `ownKeys` deliberately is NOT — `Object.keys(flags)` is
+ * enumeration, not consumption, and `suggestUnknownFlags` does exactly that on its own parse.
+ */
+function trackFlagReads(flags) {
+  for (const k of Object.keys(flags)) suppliedFlags.add(k);
+  return new Proxy(flags, {
+    get(target, prop, recv) {
+      if (typeof prop === 'string') readFlags.add(prop);
+      return Reflect.get(target, prop, recv);
+    },
+    has(target, prop) {
+      if (typeof prop === 'string') readFlags.add(prop);
+      return Reflect.has(target, prop);
+    },
+  });
+}
+
+/** Start a fresh recording. `run()` calls this per invocation so tests can drive it in a loop. */
+export function resetFlagTracking() {
+  suppliedFlags = new Set();
+  readFlags = new Set();
+}
+
+/**
+ * Selection flags the user supplied that nothing looked at, sorted.
+ *
+ * Read AFTER the command has finished — a flag consumed late (inside a branch, or by a helper
+ * the command awaits) has still been read, and reporting it early would be a false alarm.
+ * @returns {string[]}
+ */
+export function inertFilterFlags() {
+  return [...suppliedFlags].filter((f) => FILTER_FLAGS.has(f) && !readFlags.has(f)).sort();
+}
+
+/**
+ * The sentence the user gets. Says what happened to their results, not what the parser did:
+ * "ignored" alone leaves them to work out whether the output is still the answer they asked
+ * for. It is not.
+ * @param {string} cmd
+ * @param {string[]} inert
+ * @returns {string}
+ */
+export function inertFilterFlagNotice(cmd, inert) {
+  const names = inert.map((f) => `--${f}`).join(' and ');
+  const verb = inert.length > 1 ? 'were' : 'was';
+  return (
+    `[mem] ${names} ${verb} ignored — \`${cmd}\` does not filter on ${inert.length > 1 ? 'them' : 'it'}, ` +
+    `so the results above are UNFILTERED. Run "claude-mem-lite help" for the flags this command reads.`
+  );
 }
 
 // ─── Output Helpers ──────────────────────────────────────────────────────────

package/cli.mjs

@@ -81,6 +81,28 @@ function fileFromError(e) {
   return quoted ? quoted[1] : null;
 }
 
+/**
+ * Is this `doctor` invocation one of the DB-layer modes?
+ *
+ * DYNAMIC on purpose. A static import here would put lib/doctor-modes.mjs in the LAUNCHER's
+ * load graph, and a missing file there kills cli.mjs before any of its own error handling
+ * exists — the user gets a raw ERR_MODULE_NOT_FOUND instead of "this install is incomplete,
+ * run repair". tests/doctor-startup-closure.test.mjs caught exactly that when the import was
+ * static. Same rule as "a recovery path must not import the thing it recovers", applied to
+ * the entry point: nothing the launcher needs before it can speak may be a hard edge.
+ * install.mjs may import it statically — that failure is caught by loadInstaller() below.
+ */
+async function isDoctorDbMode() {
+  try {
+    const { DOCTOR_DB_MODES } = await import('./lib/doctor-modes.mjs');
+    return process.argv.slice(3).some((a) => DOCTOR_DB_MODES.some((m) => a === `--${m}`));
+  } catch {
+    // Unreadable module → treat as the plain install health check, which is the branch that
+    // can still explain a broken install.
+    return false;
+  }
+}
+
 async function loadInstaller() {
   let mod;
   try {
@@ -129,10 +151,7 @@ if (cmd === '--version' || cmd === '-v' || cmd === '-V' || cmd === 'version') {
 } else if (cmd === '--help' || cmd === '-h') {
   const { run } = await import('./mem-cli.mjs');
   await run(['help']);
-} else if (
-  cmd === 'doctor' &&
-  process.argv.slice(3).some((a) => a === '--benchmark' || a === '--metrics' || a === '--session-audit')
-) {
+} else if (cmd === 'doctor' && (await isDoctorDbMode())) {
   // Per #8217: the DB-layer doctor modes (--benchmark / --metrics / --session-audit,
   // each implemented in cli/doctor.mjs) route to mem-cli. Everything else — plain
   // `doctor`, `doctor --` (POSIX end-of-options), and `doctor --json` — stays with

package/format-utils.mjs

@@ -25,6 +25,36 @@ export function truncate(str, max = 80) {
   return str.slice(0, end) + '\u2026';
 }
 
+/**
+ * Longest query echoed back verbatim in a result label. Long enough that no query a human
+ * or an agent actually types is touched — the shapes that exceed it are pasted stack traces,
+ * file dumps and multi-paragraph questions.
+ */
+export const QUERY_LABEL_MAX = 200;
+
+/**
+ * A query as it should appear in output handed back to whoever asked.
+ *
+ * Every search surface labels its answer with the query (`Found N result(s) for "<query>"`),
+ * which is how a caller confirms what was actually searched. Unbounded, that made the size
+ * of the answer track the size of the question: a 50,000-character query produced 50,024
+ * characters of CLI output, and the MCP face — with no argv ceiling — carried the whole
+ * thing back into the model's context. For a tool whose purpose is to spend context
+ * carefully, returning several KB of the caller's own input is the budget it was invoked to
+ * protect.
+ *
+ * Bounded, not silently truncated: the real length travels with the prefix, so the label
+ * still answers the question it exists for. `truncate` handles the surrogate-pair boundary.
+ *
+ * @param {string} query
+ * @returns {string}
+ */
+export function queryLabel(query) {
+  if (typeof query !== 'string') return '';
+  if (query.length <= QUERY_LABEL_MAX) return query;
+  return `${truncate(query, QUERY_LABEL_MAX)} [query truncated; ${query.length} chars]`;
+}
+
 // Two delimiter classes are defanged here:
 //   1. The blocks claude-mem-lite wraps injected context in (claude-mem-context /
 //      memory-context / session-handoff). User-derived text containing one LITERALLY

package/hook-episode.mjs

@@ -18,12 +18,21 @@ import { inferProject, EDIT_TOOLS } from './utils.mjs';
 import { RUNTIME_DIR } from './hook-shared.mjs';
 
 /**
- * Read episode file without locking (for signal handlers only).
+ * Read the episode buffer WITHOUT holding the lock: the dying-process salvage in hook.mjs's
+ * signal handler, and the snapshot Stop / SessionStart take before they flush.
+ *
+ * Same body as `readEpisode` on purpose — the two names record which locking contract the
+ * CALLER is under, and neither function takes a lock itself. What must not differ is the
+ * PATH, so both go through `episodeFile()`. This one used to re-spell it inline, which put
+ * the buffer's name in three places (here, `episodeFile`, and the signal handler's unlink)
+ * and left the salvage path — the one that runs while the process is dying, and the hardest
+ * to notice when it is wrong — as the only one not reading the accessor.
+ *
  * @returns {object|null} Parsed episode or null on failure
  */
 export function readEpisodeRaw() {
   try {
-    return JSON.parse(readFileSync(join(RUNTIME_DIR, `ep-${inferProject()}.json`), 'utf8'));
+    return JSON.parse(readFileSync(episodeFile(), 'utf8'));
   } catch {
     return null;
   }

package/hook-llm.mjs

@@ -924,7 +924,7 @@ export async function handleLLMEpisode() {
 type: pick by strongest signal. decision = explicit tradeoff / "chose X over Y because Z" / rejected an approach (e.g. "Rejected schema migration — single-source module + sync test instead"; "Heterogeneous hook events → heterogeneous context budgets"). bugfix = prior-failing path fixed with a named root cause. feature = new user-visible capability. refactor = behavior unchanged but structure improved. discovery = learned how a system works (read-heavy, no writes). change = routine edit with no new principle (default if unsure and nothing else fits).
 Facts: each MUST be (1) atomic—one claim, (2) self-contained—no pronouns, include file/function name, (3) specific—"refreshToken() in auth.ts:45 uses 1h TTL" not "handles tokens"
 importance: Be strict — default to 1. 0=pure browsing with zero learning value. 1=routine file edits, standard changes, normal workflow (MOST episodes). 2=notable ONLY if it reveals something non-obvious: error fix with discovered root cause, architectural decision with explicit tradeoff, config change with unexpected side effects. 3=critical: breaking change affecting users, security vulnerability fix, data migration. Ask yourself: "would a future session benefit from knowing this?" — if not, it's importance=1.
-lesson_learned: The non-obvious insight a future session would benefit from. Examples: "FTS5 porter stemmer doesn't tokenize CJK — need bigram workaround", "vitest --reporter=verbose hangs on large test suites, use default reporter". Look hard before giving up — most coding episodes contain at least one micro-lesson (an undocumented flag, a surprising default, a debugging shortcut, an unexpected interaction). If literally no insight worth teaching (e.g. version bump, whitespace fix, file rename), output JSON null. Do NOT invent a lesson, do NOT write the strings "none"/"n/a"/"todo"/"tbd"/"-" — those will be discarded as noise.
+lesson_learned: The non-obvious insight a future session would benefit from. Examples: "FTS5's default tokenizer doesn't split CJK — need bigram workaround", "vitest --reporter=verbose hangs on large test suites, use default reporter". Look hard before giving up — most coding episodes contain at least one micro-lesson (an undocumented flag, a surprising default, a debugging shortcut, an unexpected interaction). If literally no insight worth teaching (e.g. version bump, whitespace fix, file rename), output JSON null. Do NOT invent a lesson, do NOT write the strings "none"/"n/a"/"todo"/"tbd"/"-" — those will be discarded as noise.
 scope: ${SCOPE_PROMPT_LEGEND}
 search_aliases: 2-6 alternative search terms someone might use to find this memory later (include CJK if project uses Chinese)`;
 

package/hook.mjs

@@ -288,8 +288,13 @@ for (const sig of ['SIGTERM', 'SIGINT']) {
           if (db) {
             try {
               for (const sub of planEpisodeFlush(ep)) saveEpisodeImmediate(sub, db);
+              // episodeFile(), not a second spelling of `ep-<project>.json`: this is a
+              // DESTRUCTIVE step on the buffer the salvage just persisted, and a path that
+              // drifts from the accessor deletes nothing while reporting success — the next
+              // fire then salvages the same entries again. Every other flush path
+              // (PostToolUse, Stop, SessionStart) already unlinks through the accessor.
               try {
-                unlinkSync(join(RUNTIME_DIR, `ep-${inferProject()}.json`));
+                unlinkSync(episodeFile());
               } catch {}
             } finally {
               try {

package/install.mjs

@@ -55,6 +55,7 @@ const HOOK_PATH = join(INSTALL_DIR, 'hook.mjs');
 // P2-7: both constants and the predicate come from lib/plugin-key.mjs, which hook.mjs also
 // imports — this pair used to be typed out in each.
 import { MARKETPLACE_KEY, PLUGIN_KEY, PLUGIN_NAME, isPluginExplicitlyDisabled } from './lib/plugin-key.mjs';
+import { doctorDbModeHint } from './lib/doctor-modes.mjs';
 const NPM_INSTALL_CMD = 'npm install --omit=dev --no-audit --no-fund';
 
 import {
@@ -70,7 +71,7 @@ import {
   nativeBindingRepairHint,
   isNativeBindingError,
 } from './lib/binding-probe.mjs';
-import { detectInstallShape, probeRuntimeRoots } from './lib/install-shape.mjs';
+import { detectInstallShape, probeRuntimeRoots, hasAnyManagedCode } from './lib/install-shape.mjs';
 import { probeSchemaCompat, schemaSkewRemedy } from './lib/schema-skew.mjs';
 import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/native-binding-hint.mjs';
 import { sweepStaleTestFixtures } from './lib/tmp-fixture-sweep.mjs';
@@ -2366,6 +2367,24 @@ async function doctor() {
   // was ever deployed there, so every entry reads as "missing" and this reported
   // `⚠ Managed files: 121 missing` + an issue on a correct install — prescribing
   // a repair against a path that does not exist.
+  // ...and a THIRD state under the same `!shape.managed`: nothing was ever deployed here.
+  // Both checks below otherwise prescribe `repair`, which re-syncs an install from the signed
+  // release and runs from `<INSTALL_DIR>/cli.mjs` — one of the very entry points whose absence
+  // produced the verdict, so on this shape it hands the reader a command that cannot start.
+  // Damaged (some of the managed files survive) and never-deployed (none do) are different
+  // populations with opposite commands, the same conflation the plugin-only branch above fixed
+  // once already. Declared out here because the hook-script check needs it too and a `const`
+  // inside the try below is not in scope there.
+  //
+  // The population is SOURCE_FILES, not the two entry points. Asking about the entry points
+  // alone made this verdict a claim about two files while the message it gates says "none
+  // present" about all of them: an install holding cli.mjs and every lib/ module, with only
+  // server.mjs and hook.mjs gone, was reported as a data directory with no install behind it
+  // — and sent to re-`install` instead of `repair`, which was runnable from the cli.mjs
+  // already there.
+  const noCodeInstall =
+    !shape.managed && !shape.activePluginVersion && !hasAnyManagedCode(INSTALL_DIR, SOURCE_FILES);
+  const installRemedy = `node ${join(PROJECT_DIR, 'install.mjs')} install`;
   try {
     const skipDrift = !shape.managed && !!shape.activePluginVersion;
     const { checkDevDrift } = await import('./lib/doctor-drift.mjs');
@@ -2436,9 +2455,13 @@ async function doctor() {
       // self-updater is `self-update`. Naming the wrong one sent the user to a
       // usage error at the exact moment their install was incomplete.
       issueWarn(
-        `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 self-update ` +
-          `(or: node ${join(INSTALL_DIR, 'cli.mjs')} repair)`,
+        noCodeInstall
+          ? `Managed files: no claude-mem-lite code is deployed in ${INSTALL_DIR} (${r.missingCount} ` +
+              `file(s) absent, none present) — this is a data directory with no install behind it, not ` +
+              `a damaged one. Fix: ${installRemedy}`
+          : `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 self-update ` +
+              `(or: node ${join(INSTALL_DIR, 'cli.mjs')} repair)`,
       );
     }
     // Complete copy install: no message — drift is a dev-install concern.
@@ -2462,7 +2485,11 @@ async function doctor() {
     // missing files, and install.mjs is the one entry that cannot survive that —
     // its static imports resolve before its first statement. cli.mjs has no static
     // local imports and catches the failure (D#26). Same route, same command.
-    const scriptRemedy = `claude-mem-lite self-update (or: node ${join(INSTALL_DIR, 'cli.mjs')} repair)`;
+    // Never-deployed gets the install command instead, for the reason spelled out at
+    // `noCodeInstall` above: the `repair` route runs from an entry point that is itself absent.
+    const scriptRemedy = noCodeInstall
+      ? installRemedy
+      : `claude-mem-lite self-update (or: node ${join(INSTALL_DIR, 'cli.mjs')} repair)`;
     if (skipScripts) {
       ok('Hook scripts: n/a (plugin-only install — hooks run from the plugin cache)');
     } else if (!h.present) {
@@ -2671,7 +2698,17 @@ async function doctor() {
       ),
     );
   } else {
-    console.log(`\n  ${buildDoctorSummary(issues, warnings)}\n`);
+    console.log(`\n  ${buildDoctorSummary(issues, warnings)}`);
+    // This run checked the INSTALL. The DB-layer modes are a different implementation reached
+    // through the same command name, and nothing else told the user they exist -- a healthy
+    // install with bad retrieval read "All checks passed!" and ended there. Derived from
+    // DOCTOR_DB_MODES so it cannot become a second list to forget. Text only: the exit-code
+    // contract `claude-mem-lite doctor || alert` depends on is untouched.
+    // Phrased as prose, not as `doctor a | b | c`: a line that looks like a command gets
+    // copy-pasted, and `|` is a shell pipe. See doctorDbModeHint()'s note.
+    console.log(
+      `  Deeper checks (database layer): run \`claude-mem-lite doctor\` with ${doctorDbModeHint()}\n`,
+    );
   }
   // Diagnostic-tool exit-code contract: any ✗-level finding must propagate non-zero
   // so CI / wrapper scripts (`claude-mem-lite doctor || alert`) actually trip. Keeps

package/lib/db-unusable.mjs

@@ -67,6 +67,49 @@ export function isFtsCorruptionError(err) {
   return /SQLITE_CORRUPT_VTAB/i.test(`${err?.code || ''}`);
 }
 
+/**
+ * What to do about a damaged FTS5 INDEX — the query-time half of isFtsCorruptionError.
+ *
+ * R10 P3-9 wired the classifier into `ensureDbWithWalRecovery`, which rebuilds and retries.
+ * That covers OPEN time. A structure record damaged inside the index opens fine — nothing
+ * reads it until the first MATCH — so the fault surfaces at QUERY time, and there the two
+ * faces that carry it to a reader (the CLI catch-all, the MCP safeHandler) passed SQLite's
+ * own sentence through with no next step. `recent` / `recall` / `browse` / `context` never
+ * touch FTS and keep answering, which makes that dead end easy to misread as "search found
+ * nothing" rather than "search is broken".
+ *
+ * ONE STRING FOR BOTH CHANNELS, unlike the file-level family below. The split there exists
+ * because that remedy OVERWRITES the database and must not be handed ready-to-run to an
+ * agent holding Bash. This one re-derives every index from its own content table: the rows
+ * are never read from the index, so a rebuild is lossless and idempotent, and `doctor`
+ * already runs it unprompted. Naming "intact" is load-bearing — the reading this line
+ * exists to prevent is "my memories are corrupt".
+ *
+ * SCOPE, measured rather than assumed: a damaged index does not always reach the caller as
+ * SQLITE_CORRUPT_VTAB. `observations_fts_data` holds three rows on a one-observation store —
+ * id=1 (averages), id=10 (the STRUCTURE record) and one leaf page — and which row the damage
+ * lands on decides the code. Over 100 trials each:
+ *
+ *   UPDATE … SET block = randomblob(32) WHERE id > 1   (structure + leaf)  98 VTAB, 2 NOMEM
+ *   UPDATE … SET block = randomblob(32) WHERE id > 10  (leaf only)        100 VTAB, 0 NOMEM
+ *   DELETE … WHERE id > 10                             (leaf only)        100 VTAB, 0 NOMEM
+ *
+ * So NOMEM comes from a mangled STRUCTURE record, where SQLite reads a corrupt varint and asks
+ * for an absurd allocation — not from leaf damage. (A first draft of this paragraph said
+ * "leaf pages", which would send anyone re-measuring `WHERE id > 10` to 0/N and make the
+ * boundary below look vacuous. Caught by the pre-ship claims audit.) That case gets no
+ * remedy, on purpose:
+ * isFtsCorruptionError is what isDbCorruptionError and isDbUnusableError consult, so
+ * admitting SQLITE_NOMEM would answer a real out-of-memory with a full FTS rebuild, and
+ * would tell a user their index is damaged when it may be their RAM. The code cannot
+ * discriminate the two, so this covers the fault it can name.
+ * `tests/fts-corruption-query-time-remedy.test.mjs` pins that boundary.
+ */
+export const FTS_CORRUPTION_REMEDY =
+  'The FTS5 search index is damaged; the stored observations are intact. ' +
+  'Rebuild it losslessly with `claude-mem-lite fts-check rebuild` ' +
+  '(`claude-mem-lite doctor` rebuilds it too, and re-checks everything else).';
+
 /**
  * True when `err` means "this file exists and SQLite cannot use it as a database".
  *

package/lib/doctor-modes.mjs

@@ -0,0 +1,31 @@
+// lib/doctor-modes.mjs — the DB-layer `doctor` modes, in one place.
+//
+// `doctor` is one command name with two implementations: install.mjs's health check, which
+// owns `--json`, and cli/doctor.mjs's DB-layer modes. cli.mjs decides between them by looking
+// for one of these flags, and its comment used to say so with a warning attached — "Adding a
+// NEW DB-layer mode requires extending this list — a deliberate trade for a working --json".
+// A mode added to cli/doctor.mjs and not to that list is answered silently by the install
+// check instead, which is a command answering as a different command.
+//
+// Three consumers now read this instead of spelling the list:
+//   cli.mjs      — the router condition
+//   install.mjs  — the pointer plain `doctor` prints, so the modes are discoverable at all
+//   tests/doctor-mode-router-sync.test.mjs — pins it against what cli/doctor.mjs implements
+//
+// A zero-dependency leaf on purpose. install.mjs is a recovery path and must not import
+// anything that drags a load graph behind it (the lesson lib/data-paths.mjs exists for).
+export const DOCTOR_DB_MODES = ['benchmark', 'metrics', 'session-audit'];
+
+/**
+ * The modes as PROSE — `--benchmark, --metrics or --session-audit`.
+ *
+ * Not `a | b | c`. A line shaped like a command invites a copy-paste, and `|` is a shell
+ * pipe: pasting the first draft produced `bash: --metrics: command not found`. That is the
+ * same defect 32c8923 fixed one commit earlier in this branch (a remedy that named a binary
+ * which could not run), reintroduced two commits later in a different spelling. The wording
+ * around it has to make clear this is a list of options, not a command line.
+ */
+export function doctorDbModeHint() {
+  const flags = DOCTOR_DB_MODES.map((m) => `--${m}`);
+  return `${flags.slice(0, -1).join(', ')} or ${flags[flags.length - 1]}`;
+}