claude-mem-lite 6.8.3 → 6.9.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.8.3",
+      "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.3",
+  "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/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/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.
  *

package/mem-cli.mjs

@@ -6,7 +6,14 @@ import { homedir } from 'os';
 import { ensureDbWithWalRecovery, DB_PATH, DB_DIR, CODE_DIR } from './schema.mjs';
 import { resolveRuntimeDir } from './lib/resolve-data-dir.mjs';
 import { isFtsCorruptionError, FTS_CORRUPTION_REMEDY } from './lib/db-unusable.mjs';
-import { truncate, typeIcon, inferProject, scrubSecrets, COMPRESSED_PENDING_PURGE } from './utils.mjs';
+import {
+  truncate,
+  queryLabel,
+  typeIcon,
+  inferProject,
+  scrubSecrets,
+  COMPRESSED_PENDING_PURGE,
+} from './utils.mjs';
 import { resolveProject } from './project-utils.mjs';
 // READ commands resolve the project DB-aware: a subdirectory whose own name holds no rows
 // falls back to the enclosing work-tree root, so `cd src/auth && … recent` reads what the
@@ -99,6 +106,9 @@ import {
   rejectBareStringFlags,
   resolvePositionalAlias,
   suggestUnknownFlags,
+  resetFlagTracking,
+  inertFilterFlags,
+  inertFilterFlagNotice,
   OBS_TIME_FIELDS,
   formatObsFieldValue,
   obsFieldLabel,
@@ -191,7 +201,7 @@ function emitRecallHint(db, query) {
     const n = countRecallableByFile(db, q);
     if (n > 0) {
       out(`[mem] ${n} observation(s) are linked to that file — search indexes text, not file paths.`);
-      out(`[mem] Try: claude-mem-lite recall "${q}"`);
+      out(`[mem] Try: claude-mem-lite recall "${queryLabel(q)}"`);
     }
   } catch {
     /* hint is best-effort; never break search */
@@ -273,12 +283,13 @@ async function cmdSearch(db, args, { llm } = {}) {
   // Haiku call + N hybrid searches; observations-only. NOT the passive path — this
   // is the explicit "search harder" lever for vocabulary-mismatch recall misses.
   // --deep forces deep; --no-deep forces normal; neither = unset (env/default decide).
-  const explicitDeep =
-    flags.deep === true || flags.deep === 'true'
-      ? true
-      : flags['no-deep'] === true || flags['no-deep'] === 'true'
-        ? false
-        : undefined;
+  // Both are read before the precedence contest, deliberately. The ternary short-circuited,
+  // so `search --deep --no-deep` never touched `flags['no-deep']` and the inert-flag notice
+  // called it a flag `search` "does not filter on" with "results above are UNFILTERED" — both
+  // false. A flag that LOST a precedence contest was read; it just did not win.
+  const wantsDeep = flags.deep === true || flags.deep === 'true';
+  const wantsNoDeep = flags['no-deep'] === true || flags['no-deep'] === 'true';
+  const explicitDeep = wantsDeep ? true : wantsNoDeep ? false : undefined;
   const deepMode = resolveDeepMode(explicitDeep, { surface: 'cli' });
 
   // --rerank: opt-in LLM rerank of the fused top-20 (option C, deep-search.mjs).
@@ -326,7 +337,7 @@ async function cmdSearch(db, args, { llm } = {}) {
       out(JSON.stringify({ query, total: 0, returned: 0, offset, limit, deep: false, results: [] }));
     } else {
       emitDeferredTrailer();
-      fail(`[mem] No valid search terms in "${query}"`);
+      fail(`[mem] No valid search terms in "${queryLabel(query)}"`);
     }
     return;
   }
@@ -477,7 +488,7 @@ async function cmdSearch(db, args, { llm } = {}) {
         }),
       );
     } else {
-      out(`[mem] No results for "${query}"`);
+      out(`[mem] No results for "${queryLabel(query)}"`);
       emitRecallHint(db, query);
       // The zero-result path is where the trailer earns its keep — the D#92
       // failure chain was exactly "searched, found nothing, item was deferred".
@@ -515,7 +526,7 @@ async function cmdSearch(db, args, { llm } = {}) {
         }),
       );
     } else {
-      out(`[mem] No results for "${query}" at offset ${offset}`);
+      out(`[mem] No results for "${queryLabel(query)}" at offset ${offset}`);
     }
     return;
   }
@@ -576,7 +587,7 @@ async function cmdSearch(db, args, { llm } = {}) {
   // Pluralize on total — "Found 1 of 44 result" reads wrong; the population (44) drives
   // grammatical number, not the page slice (1).
   out(
-    `[mem] Found ${countLabel} result${total !== 1 ? 's' : ''} for "${query}"${fallbackHint}:${hasMixed ? ' (# observation, S# session, P# prompt, E# event)' : ''}`,
+    `[mem] Found ${countLabel} result${total !== 1 ? 's' : ''} for "${queryLabel(query)}"${fallbackHint}:${hasMixed ? ' (# observation, S# session, P# prompt, E# event)' : ''}`,
   );
   // `~Nt` = est. tokens to fetch this row's full body via mem_get (attachBodyTokens, paired with
   // MCP). Conditional so a row that skipped enrichment renders cleanly, not "~undefinedt".
@@ -949,7 +960,16 @@ function cmdGet(db, args) {
       sections.push(dRows.map(formatDeferredDetail).join('\n\n'));
       totalFound += dRows.length;
     }
-    if (deferredMissing.length > 0) {
+    // This note exists for a MIXED request: other sections still render, so without it the
+    // output looks complete while an id the caller asked for silently produced nothing.
+    // A deferred-only request that matched nothing is not that shape — the terminal branch
+    // below prints the same list plus the `defer list` hint, and running both made
+    // `get D#99` say it twice, the second line a superset of the first. Conditions checked
+    // rather than the note dropped: silencing it outright would blind the case it is for.
+    const deferredOnlyMiss =
+      dRows.length === 0 &&
+      bySrc.obs.length + bySrc.session.length + bySrc.prompt.length + bySrc.event.length === 0;
+    if (deferredMissing.length > 0 && !deferredOnlyMiss) {
       process.stderr.write(
         `[mem] Deferred item(s) not found: ${deferredMissing.map((i) => `D#${i}`).join(', ')}\n`,
       );
@@ -3593,7 +3613,57 @@ import { cmdActivity } from './cli/activity.mjs';
 import { DAY_MS } from './lib/time-constants.mjs';
 // ─── Main Entry Point ────────────────────────────────────────────────────────
 
+/**
+ * Commands that read their own raw argv instead of the object parseArgs returns, so the
+ * inert-flag notice below has no way to observe a flag being consumed and must stay quiet.
+ * `adopt` / `unadopt` hand `cmdArgs` straight to adopt-cli.mjs; `doctor` selects its mode
+ * with `args.includes('--x')`; `cmdOptimize` reads `--project` and `--scope` positionally
+ * (`args.indexOf('--scope')`, and see its own note about parsing flags that way). Adding a
+ * command here is the per-command twin of leaving a flag out of FILTER_FLAGS.
+ *
+ * Do not extend this by hand alone. `tests/cli-argv-parsed-commands-complete.test.mjs`
+ * DERIVES the answer — it walks the dispatcher's switch, reads each handler's body, and
+ * fails if a handler indexes raw argv for a FILTER_FLAGS name without being listed here.
+ * `optimize` was the second miss on this list in one branch (`unadopt --all` was the first),
+ * both found by sweeping invocations, and a sweep only ever covers the population somebody
+ * remembered to enumerate.
+ */
+const ARGV_PARSED_COMMANDS = new Set(['adopt', 'unadopt', 'doctor', 'optimize']);
+
 export async function run(argv) {
+  // The inert-selection-flag notice is emitted HERE rather than inside the dispatcher because
+  // `runDispatch` returns from a dozen places (adopt / unadopt / memdir-audit before the DB is
+  // even opened, plus every `fail()` path), and a notice wired at some of them is a notice that
+  // reports a dropped filter on some commands and not others. `fail()` sets `process.exitCode`
+  // and RETURNS rather than calling process.exit, so this `finally` covers the failure paths too.
+  resetFlagTracking();
+  try {
+    return await runDispatch(argv);
+  } finally {
+    // Silent for commands that never hand their flags to parseArgs. `adopt` / `unadopt` pass
+    // raw `cmdArgs` straight to adopt-cli.mjs, which reads the array itself, and `doctor`
+    // selects its mode with `args.includes('--x')` — so read-tracking cannot see a flag being
+    // consumed there and would call a documented, working flag inert. `unadopt --all` is
+    // exactly that: adopt-cli.mjs's own header documents it and `unadoptAll()` implements it,
+    // and the first version of this notice reported it as ignored. Same class as
+    // `prompts-limit`, which FILTER_FLAGS excludes by name for the same reason — this is the
+    // per-COMMAND half of that rule. Blindness must present as silence, never as a warning.
+    const argvParsed = ARGV_PARSED_COMMANDS.has(argv[0]);
+    // Only when the command SUCCEEDED. The notice is about an answer that is wider than the
+    // one asked for; a command that failed has no answer for it to qualify, and saying "the
+    // results above are UNFILTERED" under an error message describes results that do not
+    // exist. Found by sweeping correct usage for false alarms: `activity search --limit 3`
+    // (no query) fails its own usage check BEFORE anything reads `flags.limit`, so the flag
+    // is genuinely unread and the notice was genuinely wrong. The error IS the feedback there.
+    const inert = process.exitCode || argvParsed ? [] : inertFilterFlags();
+    // stderr only: stdout is a data channel (`search --json | jq`, and commands/mem.md pipes
+    // these outputs into model context), so the notice must not enter it. Exit code untouched —
+    // the command did run, and its answer is real, just wider than the user asked for.
+    if (inert.length > 0) process.stderr.write(inertFilterFlagNotice(argv[0], inert) + '\n');
+  }
+}
+
+async function runDispatch(argv) {
   const cmd = argv[0];
   const cmdArgs = argv.slice(1);
 

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.8.3",
+  "version": "6.9.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "6.8.3",
+      "version": "6.9.0",
       "os": [
         "darwin",
         "linux",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.8.3",
+  "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).",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -91,6 +91,7 @@
     "lib/hook-telemetry.mjs",
     "lib/resolve-data-dir.mjs",
     "lib/data-paths.mjs",
+    "lib/doctor-modes.mjs",
     "lib/export-columns.mjs",
     "lib/file-intel.mjs",
     "lib/reread-guard.mjs",

package/scripts/post-tool-use.sh

@@ -107,7 +107,25 @@ if [[ "$tool" == "Read" ]]; then
         fi
       fi
     fi
-    runtime_dir="${_data_dir}/runtime"
+    # Mirror resolveRuntimeDir() (lib/resolve-data-dir.mjs): CLAUDE_MEM_RUNTIME_DIR wins when
+    # non-empty, and a relative value resolves against cwd. Without this the two sides of the
+    # channel disagreed whenever that override was set — bash appended to
+    # $CLAUDE_MEM_DIR/runtime while hook.mjs read (and hook-shared.mjs reaped) the override
+    # dir, which is both harms named at the top of this branch: every Read dropped from the
+    # episode, and an orphaned file nothing ever collects.
+    #
+    # The override deliberately wins over the test-containment redirect above, because the
+    # Node resolver ignores dataDir entirely once it is set. Mirroring it is the whole point;
+    # a "safer" bash rule here would be a second policy nobody reviewed.
+    #
+    # Builtins only. This is the ~5ms pre-filter — a `node -e` resolver of the kind setup.sh
+    # can afford at SessionStart costs ~27ms measured, on every tool call.
+    if [[ -n "${CLAUDE_MEM_RUNTIME_DIR:-}" ]]; then
+      runtime_dir="$CLAUDE_MEM_RUNTIME_DIR"
+      [[ "$runtime_dir" == /* ]] || runtime_dir="${PWD}/${runtime_dir}"
+    else
+      runtime_dir="${_data_dir}/runtime"
+    fi
     # Owner-only (0700 dir / 0600 file): reads-<project>.txt lists captured file
     # paths, so on a shared host the default umask leaked them to every local user.
     # umask is a shell builtin — no extra process on this ~5ms per-tool-call path

package/scripts/setup.sh

@@ -13,7 +13,51 @@ else
   ROOT="$CLAUDE_PLUGIN_ROOT"
 fi
 
-DATA_DIR="$HOME/.claude-mem-lite"
+# The same three locations lib/data-paths.mjs defines, under the same names. This script
+# carried ONE variable for all three, and under CLAUDE_MEM_DIR that variable is the CODE
+# dir — so every question about the DATABASE was asked of a directory holding none. This
+# repo has now had that confusion three times (v6.3.0, the same fix reintroduced with the
+# halves swapped, and here), which is why the names are spelled out rather than inferred.
+#
+#   CODE_DIR    — ALWAYS homedir. settings.json and the MCP registration bake absolute
+#                 paths to server.mjs / hook.mjs under it, so it must not follow the
+#                 relocation env var. Owns node_modules and the run-once install markers.
+#   DB_DIR      — follows CLAUDE_MEM_DIR. Owns claude-mem-lite.db and its sidecars.
+#   RUNTIME_DIR — follows CLAUDE_MEM_RUNTIME_DIR, else DB_DIR/runtime. Owns state a hook
+#                 writes and another component reads back (see .deps-broken below).
+#
+# ASK the shared resolver rather than re-deriving its rules (absolute-only, "undefined" /
+# "null" rejected) in a second language. lib/resolve-data-dir.mjs is a leaf module — node:
+# builtins only — so it still loads with node_modules missing, which is the state the
+# .deps-broken flag exists to describe. Gated on an override actually being set: with
+# neither var the resolver returns exactly these defaults, and SessionStart should not pay a
+# node spawn to be told that. A resolver that is missing (truncated tree) or that throws
+# (invalid override) leaves the defaults in place; the Node side rejects a bad value loudly
+# enough on its own, and aborting here would fail the user's session start.
+CODE_DIR="$HOME/.claude-mem-lite"
+DB_DIR="$CODE_DIR"
+RUNTIME_DIR="$CODE_DIR/runtime"
+if [[ -n "${CLAUDE_MEM_DIR:-}" || -n "${CLAUDE_MEM_RUNTIME_DIR:-}" ]] && [[ -f "$ROOT/lib/resolve-data-dir.mjs" ]]; then
+  # shellcheck disable=SC2016  # node script single-quoted on purpose; path passed via env, not shell expansion
+  _resolved="$(RESOLVER_MOD="$ROOT/lib/resolve-data-dir.mjs" node -e '
+    const { pathToFileURL } = require("node:url");
+    import(pathToFileURL(process.env.RESOLVER_MOD).href)
+      .then((m) => {
+        const db = m.resolveDataDir(process.env.CLAUDE_MEM_DIR);
+        process.stdout.write(`${db}\n${m.resolveRuntimeDir(db)}\n`);
+      })
+      .catch(() => process.exit(1));
+  ' 2>/dev/null)" || _resolved=""
+  _db="$(printf '%s\n' "$_resolved" | sed -n 1p)"
+  _rt="$(printf '%s\n' "$_resolved" | sed -n 2p)"
+  # Both or neither: a half-applied override is the split this whole block exists to close.
+  if [[ -n "$_db" && -n "$_rt" ]]; then
+    DB_DIR="$_db"
+    RUNTIME_DIR="$_rt"
+  fi
+  unset _resolved _db _rt
+fi
+
 OLD_UNHIDDEN_DIR="$HOME/claude-mem-lite"
 
 # Colors
@@ -36,23 +80,38 @@ log_warn() { echo -e "${YELLOW}⚠${NC} $*" >&2; }
 log_err()  { echo -e "${RED}✗${NC} $*" >&2; }
 
 # 1. Migrate unhidden dir (~/claude-mem-lite/ → ~/.claude-mem-lite/)
-if [[ -d "$OLD_UNHIDDEN_DIR" && ! -d "$DATA_DIR" ]]; then
-  mv "$OLD_UNHIDDEN_DIR" "$DATA_DIR"
+#    CODE_DIR, not DB_DIR, and deliberately: the pre-v0.5 unhidden directory held the
+#    INSTALL — server.mjs, hook.mjs, package.json — and CODE_DIR is the one location that
+#    must never follow the relocation env var. Moving it into a relocated DB_DIR would
+#    strand every absolute path settings.json and the MCP registration baked.
+if [[ -d "$OLD_UNHIDDEN_DIR" && ! -d "$CODE_DIR" ]]; then
+  mv "$OLD_UNHIDDEN_DIR" "$CODE_DIR"
   log_ok "Migrated ~/claude-mem-lite/ → ~/.claude-mem-lite/"
 fi
 
-# 2. Ensure data directory exists (runtime created after migration check)
-mkdir -p "$DATA_DIR"
-log_ok "Data directory: $DATA_DIR"
+# 2. Ensure both locations exist (runtime created after migration check)
+mkdir -p "$CODE_DIR"
+mkdir -p "$DB_DIR"
+if [[ "$DB_DIR" == "$CODE_DIR" ]]; then
+  log_ok "Data directory: $DB_DIR"
+else
+  log_ok "Data directory: $DB_DIR (code: $CODE_DIR)"
+fi
 
 # 3. Legacy ~/.claude-mem/ DB is schema-v16 (no memory_session_id) with no migration bridge to
 #    the current schema — activating it FATALs on first launch ("no such column: memory_session_id")
 #    and the "! -f claude-mem-lite.db" guard would re-copy it every time the user deletes the broken
 #    DB (recovery loop). Mirror install.mjs migrateLegacyClaudeMemData: back it up (don't activate)
 #    and let a fresh DB be created. Source ~/.claude-mem/ is left intact.
+#
+#    DB_DIR, because that guard is the whole convergence argument: it closes when the product
+#    creates claude-mem-lite.db, and the product creates it in DB_DIR. Asked of CODE_DIR under
+#    a relocation it never closed — nothing ever writes a database THERE — so this block
+#    copied the legacy database again on every single SessionStart, without bound. Measured
+#    2026-09-14: control arm stable at 1 backup across three runs, relocated arm 1 → 3.
 OLD_DIR="$HOME/.claude-mem"
-if [[ -f "$OLD_DIR/claude-mem.db" && ! -f "$DATA_DIR/claude-mem-lite.db" && ! -f "$DATA_DIR/claude-mem.db" ]]; then
-  BACKUP="$DATA_DIR/claude-mem-lite.db.legacy-backup-$(date +%s)"
+if [[ -f "$OLD_DIR/claude-mem.db" && ! -f "$DB_DIR/claude-mem-lite.db" && ! -f "$DB_DIR/claude-mem.db" ]]; then
+  BACKUP="$DB_DIR/claude-mem-lite.db.legacy-backup-$(date +%s)"
   if cp "$OLD_DIR/claude-mem.db" "$BACKUP" 2>/dev/null; then
     log_info "Legacy ~/.claude-mem/ DB is schema-incompatible; backed up to $(basename "$BACKUP") (a fresh DB will be created). Old ~/.claude-mem/ preserved."
   else
@@ -60,16 +119,20 @@ if [[ -f "$OLD_DIR/claude-mem.db" && ! -f "$DATA_DIR/claude-mem-lite.db" && ! -f
   fi
 fi
 
-# 4. Rename claude-mem.db → claude-mem-lite.db in same directory
-if [[ -f "$DATA_DIR/claude-mem.db" && ! -f "$DATA_DIR/claude-mem-lite.db" ]]; then
-  mv "$DATA_DIR/claude-mem.db" "$DATA_DIR/claude-mem-lite.db"
-  mv "$DATA_DIR/claude-mem.db-wal" "$DATA_DIR/claude-mem-lite.db-wal" 2>/dev/null || true
-  mv "$DATA_DIR/claude-mem.db-shm" "$DATA_DIR/claude-mem-lite.db-shm" 2>/dev/null || true
+# 4. Rename claude-mem.db → claude-mem-lite.db in same directory (DB_DIR: a relocated user's
+#    pre-rename database sits there, and asking CODE_DIR left it unrenamed and unopened).
+if [[ -f "$DB_DIR/claude-mem.db" && ! -f "$DB_DIR/claude-mem-lite.db" ]]; then
+  mv "$DB_DIR/claude-mem.db" "$DB_DIR/claude-mem-lite.db"
+  mv "$DB_DIR/claude-mem.db-wal" "$DB_DIR/claude-mem-lite.db-wal" 2>/dev/null || true
+  mv "$DB_DIR/claude-mem.db-shm" "$DB_DIR/claude-mem-lite.db-shm" 2>/dev/null || true
   log_ok "Database renamed: claude-mem.db → claude-mem-lite.db"
 fi
 
-# 5. Ensure runtime directory exists (after migration to not mask migration check)
-mkdir -p "$DATA_DIR/runtime"
+# 5. Ensure runtime directories exist (after migration to not mask migration check).
+#    Both: RUNTIME_DIR carries the cross-component flag below, while CODE_DIR/runtime keeps
+#    the two run-once install markers at the bottom of this file.
+mkdir -p "$RUNTIME_DIR"
+mkdir -p "$CODE_DIR/runtime"
 
 # 6. Ensure native dependencies available for hooks (ESM import needs node_modules in resolution chain)
 #    Plugin cache doesn't include node_modules — symlink from data dir or npm install on first run
@@ -81,8 +144,25 @@ mkdir -p "$DATA_DIR/runtime"
 # and exit on the require() error. v2.79: write a JSON flag to runtime/.deps-broken
 # and hook.mjs SessionStart surfaces it in the Claude context as a HIGH-VISIBILITY
 # block; success branches remove the flag so a self-heal stays visible too.
-DEPS_FLAG="$DATA_DIR/runtime/.deps-broken"
-mkdir -p "$DATA_DIR/runtime" 2>/dev/null || true
+#
+# ...and that contract is a two-directory agreement, not a filename. hook.mjs renders the
+# flag from `join(RUNTIME_DIR, '.deps-broken')`, where RUNTIME_DIR is
+# `resolveRuntimeDir(resolveDataDir(CLAUDE_MEM_DIR))` (hook-shared.mjs). Hardcoding a
+# homedir path here meant that under CLAUDE_MEM_DIR / CLAUDE_MEM_RUNTIME_DIR the writer and
+# the reader named two different directories, so the one surface that says "your hooks are
+# degraded" rendered nothing on exactly the installs that had relocated. Measured
+# 2026-09-14: flag planted where this script wrote it → banner 0 times; planted where
+# hook.mjs reads → 1. Same SPLIT shape lib/resolve-data-dir.mjs documents; it survived
+# because tests/runtime-dir-single-home.test.mjs sweeps `walkShipped`, which is every
+# shipped .mjs/.js — a bash hook is structurally outside that population. RUNTIME_DIR is
+# resolved once at the top of this file.
+#
+# ONLY this marker follows the override. `.mcp-dedup-v2.78` and `.residue-warned-v2.55`
+# below are one-shot state about THIS MACHINE's install — a ~/.claude.json edit and a
+# settings.json warning, not state a hook hands to another component — so they stay under
+# CODE_DIR. Read lib/resolve-data-dir.mjs's MOVES/STAYS list before relocating either:
+# moving a run-once marker re-runs what it gated.
+DEPS_FLAG="$RUNTIME_DIR/.deps-broken"
 
 mark_deps_broken() {
   local reason="$1"
@@ -112,9 +192,11 @@ mark_deps_ok() {
 
 if [[ ! -d "$ROOT/node_modules/better-sqlite3" ]]; then
   # Fast path: symlink from data dir (instant, no network needed)
-  if [[ -d "$DATA_DIR/node_modules/better-sqlite3" ]]; then
-    if ln -sfn "$DATA_DIR/node_modules" "$ROOT/node_modules" 2>/dev/null; then
-      log_ok "Dependencies linked from $DATA_DIR"
+  # CODE_DIR: node_modules belongs to the install, not to the data, and must not follow
+  # CLAUDE_MEM_DIR — install.mjs writes it under the homedir install location.
+  if [[ -d "$CODE_DIR/node_modules/better-sqlite3" ]]; then
+    if ln -sfn "$CODE_DIR/node_modules" "$ROOT/node_modules" 2>/dev/null; then
+      log_ok "Dependencies linked from $CODE_DIR"
     fi
   fi
   # Slow path: npm install (first-time only, ~10-20s for native addon)
@@ -219,7 +301,9 @@ fi
 #    pre-v2.79.1 — extra node spawn + JSON parse on every SessionStart for a
 #    near-always no-op). Bump MCP_MIGRATION name to re-run cleanup in future
 #    versions; same shape as the .deps-broken self-heal pattern.
-MCP_MIGRATION="$DATA_DIR/runtime/.mcp-dedup-v2.78"
+# CODE_DIR/runtime, not RUNTIME_DIR: this marker gates a one-shot edit of ~/.claude.json,
+# which is machine state, not per-data-dir state. Relocating it would re-run that edit.
+MCP_MIGRATION="$CODE_DIR/runtime/.mcp-dedup-v2.78"
 if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" && ! -f "$MCP_MIGRATION" ]]; then
   # shellcheck disable=SC2016  # node script single-quoted on purpose; CLAUDE_JSON passed via env, not shell expansion
   CLAUDE_JSON="$HOME/.claude.json" node -e '
@@ -298,7 +382,9 @@ fi
 #    will run every hook twice (direct settings.json hooks AND plugin hooks)
 #    until they run `claude-mem-lite uninstall` to clear the settings.json
 #    entries. /plugin uninstall does not touch settings.json.
-RESIDUE_MARKER="$DATA_DIR/runtime/.residue-warned-v2.55"
+# CODE_DIR/runtime, same reason: the residue it warns about is stale hook entries in
+# ~/.claude/settings.json — one machine, one warning, regardless of where the data lives.
+RESIDUE_MARKER="$CODE_DIR/runtime/.residue-warned-v2.55"
 if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" && ! -f "$RESIDUE_MARKER" ]]; then
   SETTINGS="$HOME/.claude/settings.json"
   if [[ -f "$SETTINGS" ]]; then

package/server.mjs

@@ -76,7 +76,7 @@ import { formatObsFieldValue, obsFieldLabel, formatPendingPurgeLine } from './cl
 // The partial-export warning points the caller at the CLI twin, which exports the complete
 // set by default — the invocation has to be the one that actually works on this install.
 import { CLI_INVOKE } from './cli-path.mjs';
-import { neutralizeContextDelimiters, neutralizeSkillDelimiters } from './format-utils.mjs';
+import { neutralizeContextDelimiters, neutralizeSkillDelimiters, queryLabel } from './format-utils.mjs';
 import {
   memSearchSchema,
   memRecentSchema,
@@ -420,13 +420,18 @@ function formatSearchOutput(
         'This is a recall miss (the rewrite ran), not a query-syntax issue; the memory likely has no related observations.',
       );
     } else if (args.query && !ftsQuery) {
-      hint.push(`Query "${args.query}" was filtered (FTS5 keywords/special chars only).`);
+      hint.push(`Query "${queryLabel(args.query)}" was filtered (FTS5 keywords/special chars only).`);
       hint.push('Tip: use content words instead of operators (AND, OR, NOT, NEAR).');
     } else {
       hint.push('No results found.');
       if (args.query) {
         const expanded = ftsQuery || args.query;
-        if (expanded !== args.query) hint.push(`Searched as: ${expanded}`);
+        // Bounded like the other two echo sites. This one is the worst of the three: it
+        // prints the EXPANDED query, and synonym expansion makes it LARGER than the input
+        // (measured 13,691 chars out for 10,329 in, 1.33x). The first pass of this fix
+        // skipped the branch on the reasoning that it "never renders the label" — true of
+        // the label, false of the echo.
+        if (expanded !== args.query) hint.push(`Searched as: ${queryLabel(expanded)}`);
         hint.push('Tip: check spelling, try broader terms, or use mem_stats to see available data.');
       }
     }
@@ -449,7 +454,7 @@ function formatSearchOutput(
   );
   // P2-6: empty/omitted query falls through to a "listing recent" path — label it explicitly
   // so callers don't mistake BM25-less results for relevance-ranked ones.
-  const qLabel = args.query ? ` for "${args.query}"` : ' (no query — listing recent)';
+  const qLabel = args.query ? ` for "${queryLabel(args.query)}"` : ' (no query — listing recent)';
   // Surface AND→OR fallback so callers (incl. Claude) know a strict multi-term
   // query actually matched only a subset of the terms. Suppressed when the caller
   // explicitly requested OR semantics — there's no "fallback" in that path.

package/source-files.mjs

@@ -60,6 +60,7 @@ export const SOURCE_FILES = [
   // stays loadable without better-sqlite3. Missing from the manifest → auto-update leaves
   // schema.mjs and the repair path with ERR_MODULE_NOT_FOUND on every fire.
   'lib/data-paths.mjs',
+  'lib/doctor-modes.mjs',
   // lib/ — statically imported by hook-llm.mjs (activity) + hook-handoff.mjs (git-state, task-reader);
   // dynamically imported by hook.mjs (startup-dashboard) + mem-cli.mjs (doctor-benchmark, plan-reader).
   'lib/activity.mjs',

package/tfidf.mjs

@@ -1,16 +1,15 @@
-// tfidf.mjs — tokenization + Porter stemming.
+// tfidf.mjs — the Porter stemmer.
 //
 // NAME IS HISTORICAL. This module was the TF-IDF vector search engine (vocabulary, vectors,
 // cosine similarity, vector search, RRF merge). Phase-1 (v3.17.0, 2026-06-27) gated that arm
 // off; Phase-2 removed it. What is left is the text-normalization half, which was never part
 // of the vector arm and has live consumers on the DEFAULT retrieval path:
 //   - porterStem  -> search-scoring.mjs (PRF term extraction)
-//   - tokenize    -> benchmark/adoption-cosine.mjs
+// `tokenize` lived here too until it was moved to benchmark/adoption-cosine.mjs, beside the
+// only callers it had left; this module is now one function under a two-word historical name.
 // RRF_K moved to lib/rrf.mjs, its actual home. See tests/vector-arm-removed.test.mjs for the
 // removal contract and tasks/specs/vector-arm-removal.md for the measurements behind it.
 
-import { cjkBigrams } from './utils.mjs';
-
 // ─── Porter Stemmer ──────────────────────────────────────────────────────────
 // Minimal Porter stemmer (1980). It used to normalize tokens for the TF-IDF vocabulary,
 // where query and document were both stemmed so the vector arm stayed internally
@@ -188,46 +187,3 @@ export function porterStem(w) {
 
   return word;
 }
-
-// ─── Tokenization ───────────────────────────────────────────────────────────
-
-const CJK_RANGE = /[\u4e00-\u9fff\u3400-\u4dbf]/;
-
-/**
- * Tokenize text into stemmed terms.
- * ASCII: lowercase + split + Porter stem.
- * CJK: reuse cjkBigrams() for consistency with FTS5.
- *
- * Built for the TF-IDF vocabulary, which is gone; the surviving consumer is
- * benchmark/adoption-cosine.mjs, which builds its own bags. The "aligned with FTS5's
- * porter tokenizer" claim the old docblock made here is NOT true and was already
- * contradicted by the stemmer's own note above — observations_fts uses unicode61 with no
- * stemming, so these terms are stems and FTS5's are surface forms.
- */
-export function tokenize(text) {
-  if (!text) return [];
-  text = String(text).toLowerCase();
-
-  const tokens = [];
-
-  // Split into ASCII and CJK segments
-  const parts = text.split(/([\u4e00-\u9fff\u3400-\u4dbf]+)/);
-  for (const part of parts) {
-    if (CJK_RANGE.test(part)) {
-      // CJK: use bigrams for consistency with FTS5 indexing
-      const bigrams = cjkBigrams(part);
-      if (bigrams) {
-        for (const t of bigrams.split(/\s+/)) {
-          if (t.length >= 2) tokens.push(t);
-        }
-      }
-    } else {
-      // ASCII: split on non-alphanumeric, then Porter stem
-      for (const t of part.split(/[^a-z0-9]+/)) {
-        if (t.length >= 2) tokens.push(porterStem(t));
-      }
-    }
-  }
-
-  return tokens;
-}

package/utils.mjs

@@ -9,37 +9,35 @@ import { buildLowSignalRegex } from './lib/low-signal-patterns.mjs';
 import { scrubSecrets as _scrubSecrets } from './secret-scrub.mjs';
 
 // ─── Re-exports from extracted modules ──────────────────────────────────────
-// Backward compatibility: all consumers import from utils.mjs
-
+// Backward compatibility: consumers that predate the extraction import from utils.mjs.
+//
+// The barrel carries what in-tree code actually imports THROUGH it, and nothing else.
+// "Backward compatible" here means compatible with this repo's own call sites: there is no
+// `main`/`exports` in package.json, so nothing outside the tree can import this module, and
+// a re-export with no importer is not a compatibility guarantee — it is a name knip has to
+// keep reporting. Eleven were dropped 2026-09-14 after both knip (whose entry set includes
+// tests, so a test-only consumer would have kept them) and a per-name import scan covering
+// named, namespace, dynamic and re-export forms agreed nothing imports them from here.
+// Each one is still exported by its own leaf module, where its real callers import it.
+// Same disposal the `extractResponseFromError` docblock records for the same reason.
 export {
   DECAY_HALF_LIFE_BY_TYPE,
   DEFAULT_DECAY_HALF_LIFE_MS,
   OBS_BM25,
   SESS_BM25,
   EVT_BM25,
-  TYPE_DECAY_CASE,
   TYPE_QUALITY_CASE,
   OBS_FTS_COLUMNS,
   notLowSignalTitleClause,
   noisePenaltyClause,
 } from './scoring-sql.mjs';
-export {
-  cjkBigrams,
-  extractCjkSynonymTokens,
-  extractCjkLikePatterns,
-  SYNONYM_MAP,
-  expandToken,
-  sanitizeFtsQuery,
-  ftsQueryTokens,
-  relaxFtsQueryToOr,
-  FTS_STOP_WORDS,
-  CJK_COMPOUNDS,
-} from './nlp.mjs';
-export { inferProject, resolveProject, _resetProjectCache } from './project-utils.mjs';
-export { scrubSecrets, SECRET_PATTERNS } from './secret-scrub.mjs';
+export { cjkBigrams, sanitizeFtsQuery, ftsQueryTokens, relaxFtsQueryToOr } from './nlp.mjs';
+export { inferProject } from './project-utils.mjs';
+export { scrubSecrets } from './secret-scrub.mjs';
 export { stripPrivate } from './lib/private-strip.mjs';
 export {
   truncate,
+  queryLabel,
   typeIcon,
   fmtDate,
   fmtTime,
@@ -51,7 +49,6 @@ export { computeMinHash, estimateJaccardFromMinHash, jaccardSimilarity } from '.
 export {
   detectBashSignificance,
   extractErrorKeywords,
-  planErrorRecall,
   extractFilePaths,
   stripTestSuffix,
 } from './bash-utils.mjs';