claude-mem-lite 6.8.2 → 6.9.0

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

@@ -5,7 +5,15 @@
 import { homedir } from 'os';
 import { ensureDbWithWalRecovery, DB_PATH, DB_DIR, CODE_DIR } from './schema.mjs';
 import { resolveRuntimeDir } from './lib/resolve-data-dir.mjs';
-import { truncate, typeIcon, inferProject, scrubSecrets, COMPRESSED_PENDING_PURGE } from './utils.mjs';
+import { isFtsCorruptionError, FTS_CORRUPTION_REMEDY } from './lib/db-unusable.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
@@ -98,6 +106,9 @@ import {
   rejectBareStringFlags,
   resolvePositionalAlias,
   suggestUnknownFlags,
+  resetFlagTracking,
+  inertFilterFlags,
+  inertFilterFlagNotice,
   OBS_TIME_FIELDS,
   formatObsFieldValue,
   obsFieldLabel,
@@ -190,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 */
@@ -272,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).
@@ -325,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;
   }
@@ -476,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".
@@ -514,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;
   }
@@ -575,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".
@@ -948,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`,
       );
@@ -3592,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);
 
@@ -3847,6 +3918,12 @@ export async function run(argv) {
     // agent runs the CLI, the model's context — got a raw Node stack trace. Print the
     // message, keep the stack behind CLAUDE_MEM_DEBUG for whoever is actually debugging.
     process.stderr.write(`[mem] ${cmd || 'command'} failed: ${(e && e.message) || e}\n`);
+    // A damaged FTS5 index reaches here as SQLITE_CORRUPT_VTAB from the first MATCH.
+    // `fts-check` and `doctor` touch the index too — and both already explain themselves —
+    // so `search` is the one command that DEAD-ENDS on SQLite's sentence, while `recent` /
+    // `recall` / `browse` / `context` / `stats` never read the index and keep working.
+    // The remedy is lossless (see FTS_CORRUPTION_REMEDY); the exit code stays 1.
+    if (isFtsCorruptionError(e)) process.stderr.write(`[mem] ${FTS_CORRUPTION_REMEDY}\n`);
     if (process.env.CLAUDE_MEM_DEBUG) process.stderr.write(`${(e && e.stack) || ''}\n`);
     process.exitCode = 1;
   } finally {

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.8.2",
+  "version": "6.9.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "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,
@@ -118,6 +118,7 @@ import { saveWithClosures, formatSupersedeSkipped, formatSupersededNote } from '
 import { applyObsUpdate } from './lib/observation-write.mjs';
 import { EXPORT_COLUMNS_SQL, buildExportWhere } from './lib/export-columns.mjs';
 import { recallByFile } from './lib/recall-core.mjs';
+import { isFtsCorruptionError, FTS_CORRUPTION_REMEDY } from './lib/db-unusable.mjs';
 import { fetchRecent } from './lib/recent-core.mjs';
 import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import {
@@ -374,7 +375,17 @@ function safeHandler(fn, { verbatim = false } = {}) {
       const result = await fn(args, extra);
       return verbatim ? result : defangResult(result, { skillBlocks: true });
     } catch (err) {
-      return defangResult({ content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true });
+      // A damaged FTS5 index arrives here as SQLITE_CORRUPT_VTAB from the first MATCH.
+      // Without this the model got SQLite's own sentence and nothing else, on a fault it
+      // could have had fixed in one command — and mem_recent / mem_recall / mem_browse
+      // keep answering, so the dead end reads as "nothing matched". Both channels carry the
+      // same string here, deliberately: unlike the file-level remedy this one is lossless
+      // (see FTS_CORRUPTION_REMEDY in lib/db-unusable.mjs).
+      const hint = isFtsCorruptionError(err) ? `\n${FTS_CORRUPTION_REMEDY}` : '';
+      return defangResult({
+        content: [{ type: 'text', text: `Error: ${err.message}${hint}` }],
+        isError: true,
+      });
     }
   };
 }
@@ -409,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.');
       }
     }
@@ -438,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;
-}