claude-mem-lite 6.8.3 → 6.9.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.8.3",
+      "version": "6.9.1",
       "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.3",
+  "version": "6.9.1",
   "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/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 {
@@ -114,6 +136,46 @@ const INSTALL_COMMANDS = new Set([
   'release',
 ]);
 
+// A reader that leaves is not an error. `claude-mem-lite search x | head -1`,
+// `| grep -q`, or quitting `less` closes the read end while we are still writing;
+// Node then emits 'error' on the stdout Socket, and with no listener that is an
+// UNHANDLED error event — a ~20-line stack ending in `outVerbatim` where the user
+// expected the shell prompt.
+//
+// WHICH COMMANDS, measured rather than generalised (20 trials each, `| head -1`,
+// pre-fix): `search`, `export`, `recent`, `stats`, `doctor`, `timeline`,
+// `citation-stats` 20/20; `browse` 19/20; `help`, `status`, `context`, `get`,
+// `memdir-audit` 0/20. So NOT "every stdout-bearing command" — what decides it is
+// whether a write is still pending when the reader goes, which depends on how many
+// lines the consumer takes and how the output is batched — NOT on the 64 KB pipe
+// buffer, which an earlier draft of this comment blamed: pre-ship review found
+// `stats` crashing at `head -20` on an output far under it. That output's size is
+// corpus dependent, so no byte count is quoted here. This is also why the crash
+// survived so long — it is invisible to exactly the pipe depths a smoke test picks.
+//
+// Lives HERE, at the published `bin`, and not at `cli/common.mjs`'s `out()`: the
+// crash reproduces on `doctor` too, whose writes are `console.log` inside
+// install.mjs, so a chokepoint fix would cover the CLI half and leave the installer
+// half loud. One process-level listener covers both routes below.
+//
+// SWALLOW, DO NOT EXIT. The first cut called `process.exit(0)` here, on the
+// reasoning that a CLI whose consumer has gone should stop rather than serialise a
+// whole-DB `export` into a dead pipe. Pre-ship review measured what that costs:
+// `doctor | head -1` under `pipefail` exited 0 on 10/10 runs while the same doctor
+// exits 1 unpiped, because `runDoctor` assigns `process.exitCode = 1` AFTER its last
+// print (install.mjs, "Diagnostic-tool exit-code contract") and the forced exit lands
+// first. That silently turns a failing `claude-mem-lite doctor || alert` — the
+// wrapper that contract names — into a passing one. `process.exitCode ?? 0` does not
+// rescue it: the verdict does not exist yet at kill time. Returning instead reads
+// exit 1 on 10/10 and keeps the crash fixed (doctor 0/10, search 0/10 EPIPE stacks).
+// Correctness over the saved work: the process finishes into a pipe nobody reads,
+// which is wasted effort but never a wrong answer. Non-EPIPE is rethrown — this is a
+// classifier, not a blanket swallow, the same charter `explainBrokenInstall` follows.
+process.stdout.on('error', (err) => {
+  if (err && err.code === 'EPIPE') return;
+  throw err;
+});
+
 const cmd = process.argv[2];
 
 // `version` and `-V` are aliases, not extra syntax: the bare subcommand is what a user
@@ -129,10 +191,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

@@ -44,6 +44,15 @@ const MEM_RUNTIME_DIR = resolveRuntimeDir(MEM_DATA_DIR);
 const DB_PATH = join(MEM_DATA_DIR, 'claude-mem-lite.db');
 const OLD_DATA_DIR = join(homedir(), '.claude-mem');
 
+// The two directories `createCliSymlink` can land the `claude-mem-lite` command in, in the
+// order it tries them. Uninstall already swept exactly this pair as an inline literal, and
+// `status` now has to ask the same question ("is the command installed somewhere, just not
+// on PATH?"), so the list is named once rather than typed a third time. `createCliSymlink`
+// itself is deliberately NOT rewritten to iterate it: its shape is primary-then-fallback
+// with different remedies per branch, and flattening that into a loop is a refactor wearing
+// a constant's clothes.
+const CLI_BIN_DIRS = [join(homedir(), '.local', 'bin'), '/usr/local/bin'];
+
 // Detect ephemeral context (npx) — files won't persist after exit
 const IS_NPX =
   process.env.npm_command === 'exec' || PROJECT_DIR.includes('_npx') || PROJECT_DIR.includes('.npm/_');
@@ -55,6 +64,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 +80,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';
@@ -1270,7 +1280,7 @@ async function uninstall() {
   if (!removedAny) warn('MCP server not found or already removed');
 
   // 1b. Remove CLI symlink
-  for (const binDir of [join(homedir(), '.local', 'bin'), '/usr/local/bin']) {
+  for (const binDir of CLI_BIN_DIRS) {
     const cliLink = join(binDir, 'claude-mem-lite');
     // No try/catch: clearLinkPath swallows a permissions failure and returns false, so the
     // wrapper this used to have was unreachable once the existsSync gate moved inside it.
@@ -1653,14 +1663,70 @@ async function status() {
     push('warn', 'database', 'Database: not found', { exists: false });
   }
 
-  // CLI
+  // CLI.
+  //
+  // The probe resolves a BARE name, so a failure conflates three different worlds and the
+  // old single remedy ("run install again to create symlink") was correct in only one of
+  // them. On the common one — `createCliSymlink` put a working link in ~/.local/bin, a
+  // directory a non-login shell frequently does not have on PATH — the advice sends the
+  // user to re-run an installer that will create the very symlink that already exists,
+  // report ✓, and leave `status` saying the same thing. Advice that cannot converge is
+  // worse than the silence it replaced.
+  //
+  // Split on `err.code`: ENOENT is "the name did not resolve" and is the only world the
+  // symlink question applies to. Anything else means the command WAS found and then failed
+  // or timed out (a broken native binding is the live example), where naming PATH is a
+  // second wrong answer — report what actually happened instead.
+  // `linked` is a NEW field on this check, and `--json` republishes every extra key
+  // (`const { level, key, message, ...extra }` below), so it is part of that face's output,
+  // not an internal detail. Nothing in this repo reads it; external consumers of
+  // `status --json` now see `linked: <path>|null`.
   try {
     execFileSync('claude-mem-lite', ['--help'], { encoding: 'utf8', timeout: 5000, stdio: 'pipe' });
     push('ok', 'cli', 'CLI: claude-mem-lite command available', { available: true });
-  } catch {
-    push('warn', 'cli', 'CLI: command not on PATH — run install again to create symlink', {
-      available: false,
-    });
+  } catch (e) {
+    if (e && e.code !== 'ENOENT') {
+      // `e.message` already CARRIES the child's stderr — with stdio:'pipe' Node formats it
+      // as "Command failed: <cmd>\n<stderr>", so the live example (a broken native binding,
+      // whose `nativeBindingRepairHint` line is on stderr) reaches the user unaided.
+      // Measured, because pre-ship review asserted the opposite and a redundant `e.stderr`
+      // suffix was written and then withdrawn: printing both duplicates the text.
+      // Note `e.code` is UNDEFINED for a non-zero exit — only a spawn failure sets ENOENT —
+      // so `!== 'ENOENT'` is what routes this branch, not a truthiness check on the code.
+      push('warn', 'cli', `CLI: on PATH but "claude-mem-lite --help" failed — ${e.message}`, {
+        available: false,
+        linked: null,
+      });
+    } else {
+      // Two properties of `existsSync` matter here and they pull in opposite directions:
+      //   - it FOLLOWS the link, so a DANGLING one reads as absent. That is the answer we
+      //     want: a link pointing at a deleted install is the installer's problem, not
+      //     PATH's, and falls through to the reinstall remedy.
+      //   - it is also true for a DIRECTORY of that name, which would make us print
+      //     "installed at … add it to PATH" about something that can never be executed —
+      //     the exact non-converging advice this block exists to stop. Hence isFile().
+      const isLinkedCli = (d) => {
+        try {
+          return statSync(join(d, 'claude-mem-lite')).isFile();
+        } catch {
+          return false; // ENOENT (absent or dangling), EACCES on the dir, anything else
+        }
+      };
+      const binDir = CLI_BIN_DIRS.find(isLinkedCli);
+      if (binDir) {
+        push(
+          'warn',
+          'cli',
+          `CLI: installed at ${join(binDir, 'claude-mem-lite')} but ${binDir} is not on PATH — add it: export PATH="${binDir}:$PATH"`,
+          { available: false, linked: join(binDir, 'claude-mem-lite') },
+        );
+      } else {
+        push('warn', 'cli', 'CLI: command not on PATH — run install again to create symlink', {
+          available: false,
+          linked: null,
+        });
+      }
+    }
   }
 
   // Old system
@@ -2366,6 +2432,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 +2520,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 +2550,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 +2763,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/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]}`;
+}

package/lib/install-shape.mjs

@@ -116,6 +116,34 @@ export function hasManagedCodeInstall(installDir) {
   return MANAGED_ENTRY_POINTS.every((f) => existsSync(join(installDir, f)));
 }
 
+/**
+ * True when `installDir` holds ANY of `files` — i.e. code was deployed here at some point,
+ * even if it is now incomplete.
+ *
+ * The complement of `hasManagedCodeInstall` above is not one population but two, and they
+ * take OPPOSITE remedies: an install that is DAMAGED (some of it survives) is what `repair`
+ * exists for, while one that was never deployed here needs `install`. `repair` runs from
+ * `<installDir>/cli.mjs`, so prescribing it where nothing was deployed names a binary that
+ * cannot start.
+ *
+ * `files` is a PARAMETER and the caller passes the whole managed list, because this answers
+ * a question about a WIDER population than `hasManagedCodeInstall` does. Pinning both to
+ * MANAGED_ENTRY_POINTS looked tidy — one array, `every` vs `some` — and made the 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 but neither entry point was reported as
+ * a data directory with no install behind it, and told to re-`install` rather than
+ * `repair` — which was runnable, sitting right there.
+ *
+ * @param {string} installDir
+ * @param {string[]} files  The managed file list to test against (SOURCE_FILES at the only
+ *                          call site; a narrower list answers a narrower question).
+ * @returns {boolean}
+ */
+export function hasAnyManagedCode(installDir, files) {
+  if (!installDir || !existsSync(installDir)) return false;
+  return files.some((f) => existsSync(join(installDir, f)));
+}
+
 /**
  * Plugin-cache version dirs that carry runnable code, newest first.
  *