claude-mem-lite 6.12.0 → 6.12.2

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.12.0",
+      "version": "6.12.2",
       "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.12.0",
+  "version": "6.12.2",
   "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

@@ -165,7 +165,7 @@ is still outside it gets a message naming both sides of the mismatch instead of
 
 Plugin mode manages its own hooks/runtime. On session start it only **checks and reports** new claude-mem-lite versions; it does **not** self-overwrite plugin files in place. Update plugin-mode installs through Claude's plugin workflow.
 
-> **The plugin install is complete on its own** — hooks, MCP tools, and the bundled slash commands (`/mem`, `/lesson`, `/bug`, `/adopt`) all run from the plugin with no second step. The slash commands invoke the bundled CLI by an absolute path resolved from the plugin directory (`${CLAUDE_PLUGIN_ROOT}/cli.mjs <cmd>`), so they work without anything on your `PATH`. A global `claude-mem-lite` **shell** command (for running queries yourself in a terminal) is **optional** — `npm i -g claude-mem-lite` — and is a *separate* npm install: the plugin's auto-update does **not** refresh it, so re-run `npm i -g claude-mem-lite@latest` if you want that shell command kept in sync. You do **not** need it for the plugin to be fully functional.
+> **The plugin install is complete on its own** — hooks, MCP tools, and the bundled slash commands (`/mem`, `/lesson`, `/bug`, `/adopt`) all run from the plugin with no second step. The slash commands invoke the bundled CLI by an absolute path resolved from the plugin directory (`node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" <cmd>`), so they work without anything on your `PATH`. A global `claude-mem-lite` **shell** command (for running queries yourself in a terminal) is **optional** — `npm i -g claude-mem-lite` — and is a *separate* npm install: the plugin's auto-update does **not** refresh it, so re-run `npm i -g claude-mem-lite@latest` if you want that shell command kept in sync. You do **not** need it for the plugin to be fully functional.
 
 > **Auto-adopt writes into your project, on every SessionStart (v3.13+).** The plugin adds a slug-scoped **managed block** to your project's own **`<cwd>/CLAUDE.md`** — a file that is normally committed to git — plus a `<cwd>/.claude/plugin_claude_mem_lite.md` detail file. The block is a system-authority pointer that boosts Claude's proactive use of `mem_recall` / `mem_save`. Everything outside the block is preserved verbatim, and it coexists with other plugins' blocks in the same file ([details](#invited-memory-v232)). This happens on **every** SessionStart, not just the first: the sync is idempotent and re-applies the block if it is edited away, and refreshes it when the shipped template changes. It applies regardless of install path (npm, npx, `/plugin`, manual), so **no manual `/adopt` is needed**.
 >

package/README.zh-CN.md

@@ -129,7 +129,7 @@ v5.1.0 到 v6.1.0 之间，`package.json` 声明的是 `os: ["darwin", "linux"]`
 
 插件模式会管理自己的运行时与钩子。SessionStart 时它现在只会**检查并提示**新版本，不会直接覆盖插件目录中的文件。插件模式请通过 Claude 的插件更新流程完成升级。
 
-> **插件安装本身即完整** —— hooks、MCP 工具、以及捆绑的 slash 命令（`/mem`、`/lesson`、`/bug`、`/adopt`）全部从插件内运行，无需第二步。slash 命令以从插件目录解析出的绝对路径调用捆绑 CLI（`${CLAUDE_PLUGIN_ROOT}/cli.mjs <cmd>`），因此不依赖 `PATH` 上的任何东西。全局 `claude-mem-lite` **shell** 命令（用于你自己在终端里跑查询）是**可选**的 —— `npm i -g claude-mem-lite` —— 且是**独立**的 npm 安装：插件的自动更新**不会**刷新它，想保持同步就重新跑 `npm i -g claude-mem-lite@latest`。插件要完整工作**并不需要**它。
+> **插件安装本身即完整** —— hooks、MCP 工具、以及捆绑的 slash 命令（`/mem`、`/lesson`、`/bug`、`/adopt`）全部从插件内运行，无需第二步。slash 命令以从插件目录解析出的绝对路径调用捆绑 CLI（`node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" <cmd>`），因此不依赖 `PATH` 上的任何东西。全局 `claude-mem-lite` **shell** 命令（用于你自己在终端里跑查询）是**可选**的 —— `npm i -g claude-mem-lite` —— 且是**独立**的 npm 安装：插件的自动更新**不会**刷新它，想保持同步就重新跑 `npm i -g claude-mem-lite@latest`。插件要完整工作**并不需要**它。
 
 ### 方式二：npx（一行命令）
 

package/cli/common.mjs

@@ -417,6 +417,21 @@ export const KNOWN_CLI_FLAGS = new Set([
   // --has?" suggestion. Locked by tests/cli-flag-allowlist.test.mjs.
 ]);
 
+/**
+ * Flags exactly ONE subcommand reads, mapped to that command. KNOWN_CLI_FLAGS is a union, so
+ * without this `recent --apply` was accepted in silence while `--apply` did nothing there.
+ * Every other command mem-cli dispatches now reports such a flag, and the typo suggester stops
+ * offering it there. Install-family commands (doctor, status, …) route to install.mjs and are
+ * not covered. Only flags with a single reader
+ * belong here; tests/cli-flag-allowlist.test.mjs derives that from the sources.
+ */
+export const COMMAND_SCOPED_FLAGS = new Map([
+  ['apply', 'verify-apply'],
+  ['digest', 'verify-apply'],
+  ['print-project', 'verify-apply'],
+  ['undo', 'verify-apply'],
+]);
+
 /** Levenshtein distance, early-exit past `max` (cheap enough for a handful of flags). */
 function editDistance(a, b, max = 2) {
   const m = a.length,
@@ -444,16 +459,25 @@ function editDistance(a, b, max = 2) {
  * project — a typo produced a wrong result with zero signal. Returns [{flag, suggestion}].
  * Unknown flags with NO close match are omitted: they may be a valid flag we didn't
  * catalog, so silence beats a false alarm. Warning-only by contract — never fails.
+ * A flag in COMMAND_SCOPED_FLAGS given to any other `cmd` is reported too, with `owner` set.
  * @param {object} flags Parsed flags from parseArgs.
- * @returns {Array<{flag: string, suggestion: string}>}
+ * @param {string} [cmd] The subcommand being run; without it scoped flags are not checked.
+ * @returns {Array<{flag: string, suggestion: string|null, owner?: string}>}
  */
-export function suggestUnknownFlags(flags) {
+export function suggestUnknownFlags(flags, cmd) {
   const result = [];
   for (const key of Object.keys(flags)) {
+    const owner = COMMAND_SCOPED_FLAGS.get(key);
+    if (cmd && owner && owner !== cmd) {
+      result.push({ flag: key, suggestion: null, owner });
+      continue;
+    }
     if (!key || KNOWN_CLI_FLAGS.has(key)) continue;
     let best = null,
       bestDist = 3;
     for (const known of KNOWN_CLI_FLAGS) {
+      const knownOwner = COMMAND_SCOPED_FLAGS.get(known);
+      if (cmd && knownOwner && knownOwner !== cmd) continue;
       const d = editDistance(key, known);
       if (d < bestDist) {
         bestDist = d;

package/cli/verify-apply.mjs

@@ -23,6 +23,7 @@ import {
   markUndone,
 } from '../lib/verify-apply-core.mjs';
 import { parseArgs, out, fail, rejectBareStringFlags } from './common.mjs';
+import { shellWord } from '../cli-path.mjs';
 
 const USAGE =
   '[mem] Usage: claude-mem-lite verify-apply <proposals.json> [--project P]          (dry run)\n' +
@@ -34,8 +35,6 @@ const BACKUP_DIR = join(DB_DIR, 'backups');
 // The commands this prints must run as printed. `claude-mem-lite` is on PATH only after an
 // optional global npm install (which may also be a different, stale code home), so name the
 // node binary and THIS cli.mjs — the one that produced the plan.
-/** A path as one shell word: as-is when it is plain, single-quoted otherwise. */
-const shellWord = (s) => (/^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`);
 const SELF = process.argv[1] ? `node ${shellWord(process.argv[1])}` : 'claude-mem-lite';
 
 function readJson(path, what) {

package/cli-path.mjs

@@ -22,4 +22,14 @@ import { join, dirname } from 'node:path';
 // module from its unused-export report entirely. Enforced by
 // tests/no-url-module-paths.test.mjs.
 export const CLI_PATH = join(dirname(fileURLToPath(import.meta.url)), 'cli.mjs');
-export const CLI_INVOKE = `node ${CLI_PATH}`;
+/**
+ * A path as one shell word: as-is when it is plain, single-quoted otherwise. Conditional on
+ * purpose — CLI_INVOKE is LLM-visible (MCP instructions, every "Equivalent CLI" hint), so an
+ * ordinary install path must stay byte-identical; only a path with a space or a shell
+ * metacharacter gets quotes, which it needs to survive as ONE argument.
+ * @param {string} s
+ * @returns {string}
+ */
+export const shellWord = (s) => (/^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`);
+
+export const CLI_INVOKE = `node ${shellWord(CLI_PATH)}`;

package/commands/adopt.md

@@ -64,4 +64,4 @@ server builds its instructions once at boot, so the MCP-instructions trim
 (or re-attaches the mem-lite MCP server). A `/exit` + fresh session is enough.
 Same caveat applies in reverse for `/unadopt`.
 
-!node ${CLAUDE_PLUGIN_ROOT}/cli.mjs adopt $ARGUMENTS
+!node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" adopt $ARGUMENTS

package/commands/bug.md

@@ -49,7 +49,7 @@ goes in `--lesson` so it lands in the high-weight `lesson_learned` field.
 body in the positional content and trim `--lesson` to the core description if
 longer:
 
-    node ${CLAUDE_PLUGIN_ROOT}/cli.mjs save "<body>" \
+    node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" save "<body>" \
       --type bugfix \
       --title "<first 60 chars of description>" \
       --lesson "<description, ≤500 chars>" \

package/commands/lesson.md

@@ -42,7 +42,7 @@ field. `--lesson` is capped at 500 chars (longer values are rejected), so for a
 long lesson keep the full text in the positional content and trim `--lesson` to
 the core insight:
 
-    node ${CLAUDE_PLUGIN_ROOT}/cli.mjs save "<full text>" \
+    node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" save "<full text>" \
       --type discovery \
       --title "<first 60 chars of text>" \
       --lesson "<core insight, ≤500 chars>" \

package/commands/mem.md

@@ -23,16 +23,16 @@ Search and browse your project memory efficiently.
 
 When the user invokes `/mem`, parse their intent:
 
-- `/mem search <query>` → run `node ${CLAUDE_PLUGIN_ROOT}/cli.mjs search <query>` via Bash
-- `/mem recent` or `/mem recent 20` → run `node ${CLAUDE_PLUGIN_ROOT}/cli.mjs recent [N]` via Bash
-- `/mem recall <file>` → run `node ${CLAUDE_PLUGIN_ROOT}/cli.mjs recall <file>` via Bash
-- `/mem timeline <id>` → run `node ${CLAUDE_PLUGIN_ROOT}/cli.mjs timeline --anchor <id>` via Bash
+- `/mem search <query>` → run `node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" search <query>` via Bash
+- `/mem recent` or `/mem recent 20` → run `node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" recent [N]` via Bash
+- `/mem recall <file>` → run `node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" recall <file>` via Bash
+- `/mem timeline <id>` → run `node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" timeline --anchor <id>` via Bash
 - `/mem save <text>` → call `mem_save` MCP tool with the text as content
-- `/mem stats` → run `node ${CLAUDE_PLUGIN_ROOT}/cli.mjs stats` via Bash
-- `/mem get <ids>` → run `node ${CLAUDE_PLUGIN_ROOT}/cli.mjs get <ids>` via Bash
+- `/mem stats` → run `node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" stats` via Bash
+- `/mem get <ids>` → run `node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" get <ids>` via Bash
 - `/mem cleanup` → run `mem_maintain(action="scan")`, report pending purge count and stale items to user, ask for confirmation, then run `mem_maintain(action="execute", operations=["purge_stale"], confirm=true)` if confirmed. **`confirm=true` is required and is not optional politeness:** without it the call returns a dry-run PREVIEW and deletes nothing, while still succeeding — so you would report a cleanup that never happened.
 - `/mem cleanup Nd` (e.g. `60d`) → same as above but add `retain_days=N` to only purge items older than N days. **`retain_days` must be between 7 and 365**; anything outside that range is rejected by the schema, so `/mem cleanup 3d` cannot be honoured — say so rather than silently substituting the default.
 - `/mem cleanup keep Nd` (e.g. `keep 14d`) → same as above with `retain_days=N`, same 7–365 range.
-- `/mem <query>` (no subcommand) → treat as search, run `node ${CLAUDE_PLUGIN_ROOT}/cli.mjs search <query>` via Bash
+- `/mem <query>` (no subcommand) → treat as search, run `node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" search <query>` via Bash
 
-Use Bash commands first. For detailed data, use `node ${CLAUDE_PLUGIN_ROOT}/cli.mjs get <id>` via Bash.
+Use Bash commands first. For detailed data, use `node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" get <id>` via Bash.

package/commands/unadopt.md

@@ -43,4 +43,4 @@ Once unadopted, the conservative hook layer (SessionStart `File Lessons` /
 `Key Context`, MCP instructions `WHEN TO USE`) returns to verbose mode on the
 next session start.
 
-!node ${CLAUDE_PLUGIN_ROOT}/cli.mjs unadopt $ARGUMENTS
+!node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" unadopt $ARGUMENTS

package/hook-handoff.mjs

@@ -386,18 +386,28 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
   // (session_summaries.key_decisions is a different column, a JSON array from Haiku), and
   // every existing assertion on it is a substring/regex match on the title, so the added
   // prefix is not a contract change for them.
-  const decisions = db
+  //
+  // The cap applies AFTER the low-signal filter (D#40). This read was `LIMIT 10` → filter →
+  // slice(0, 5), which made the SQL limit a reachability bound: six low-signal rows among the
+  // newest ten evicted older real decisions the section had room for, and two writers raise
+  // importance without reading the title, so such rows do reach this pool. Streaming and
+  // stopping at five keeps the JS filter exactly as it was (the SQL NOT LIKE twin is
+  // case-insensitive, so swapping it in would also change WHICH titles count as noise).
+  const decisions = [];
+  for (const d of db
     .prepare(
       `
     SELECT title, type FROM observations
     WHERE (memory_session_id = ? OR project = ?) AND COALESCE(importance, 1) >= 2
       AND ${liveObsFilterSql('')} ${obsWindowClause}
-    ORDER BY created_at_epoch DESC LIMIT 10
+    ORDER BY created_at_epoch DESC, id DESC
   `,
     )
-    .all(sessionId, project, ...obsWindowParams)
-    .filter((d) => d.title && !LOW_SIGNAL_TITLE.test(d.title))
-    .slice(0, 5);
+    .iterate(sessionId, project, ...obsWindowParams)) {
+    if (!d.title || LOW_SIGNAL_TITLE.test(d.title)) continue;
+    decisions.push(d);
+    if (decisions.length === 5) break;
+  }
 
   // 5b. Next steps — the remaining work a paused note spells out, which is the only
   // next-step source in this system that a human wrote down on purpose. Deliberately not

package/install.mjs

@@ -97,6 +97,7 @@ import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/nat
 import { sweepStaleTestFixtures } from './lib/tmp-fixture-sweep.mjs';
 import { acquireLock } from './lib/proc-lock.mjs';
 import { atomicWriteFileSync } from './lib/atomic-write.mjs';
+import { shellWord } from './cli-path.mjs';
 import { isMemHook, launcherEntryPath } from './lib/hook-prune.mjs';
 
 // Re-export for backward compatibility — tests/install-hook-scripts.test.mjs
@@ -272,7 +273,7 @@ export function hookManifestRepairHint(cacheRoot, marketplaceRoot) {
   const src = join(marketplaceRoot, 'hooks', 'hooks.json');
   const dst = join(cacheRoot, 'hooks', 'hooks.json');
   return pluginCacheHookEvents(marketplaceRoot).ok
-    ? `cp "${src}" "${dst}" && restart Claude Code`
+    ? `cp ${shellWord(src)} ${shellWord(dst)} && restart Claude Code`
     : `no usable marketplace copy to restore from — reinstall the plugin (/plugin uninstall then /plugin install), then restart Claude Code`;
 }
 
@@ -723,7 +724,7 @@ function registerMcpServer() {
       ok('MCP server registered: mem-lite');
     } catch (e) {
       fail('MCP registration failed: ' + e.message);
-      warn('Try manually: claude mcp add -s user -t stdio mem-lite -- node ' + SERVER_PATH);
+      warn(`Try manually: claude mcp add -s user -t stdio mem-lite -- node ${shellWord(SERVER_PATH)}`);
     }
   }
 }
@@ -1674,7 +1675,7 @@ async function status() {
         push(
           'warn',
           'cli',
-          `CLI: installed at ${join(binDir, 'claude-mem-lite')} but ${binDir} is not on PATH — add it: export PATH="${binDir}:$PATH"`,
+          `CLI: installed at ${join(binDir, 'claude-mem-lite')} but ${binDir} is not on PATH — add it: export PATH=${shellWord(binDir)}:"$PATH"`,
           { available: false, linked: join(binDir, 'claude-mem-lite') },
         );
       } else {
@@ -1754,8 +1755,9 @@ async function doctor() {
       return;
     }
     const last = checks[checks.length - 1];
-    // A detail before any check has nothing to attach to — same as today's drop, but the
-    // human face would show it, so this is the one line the two faces cannot share.
+    // Unreachable today: the Node-version check at the top of doctor() always records a
+    // check before the first log(). Kept as a guard — a detail with no check to attach to is
+    // dropped under --json, where the human face would have printed it.
     if (!last) return;
     (last.details ??= []).push(msg.trim());
   };
@@ -2004,7 +2006,7 @@ async function doctor() {
     // misbehaving, which is the worst moment to hand out the one entry that cannot
     // survive a missing module. Pre-ship review of v6.7.0 caught this one left behind.
     dwarn(
-      `Hook self-heal: a recent hook fire degraded to exit-0${detail} — run \`node ${join(PROJECT_DIR, 'cli.mjs')} repair\``,
+      `Hook self-heal: a recent hook fire degraded to exit-0${detail} — run \`node ${shellWord(join(PROJECT_DIR, 'cli.mjs'))} repair\``,
     );
   } else {
     ok('Hook self-heal: no recent silent hook breakage');
@@ -2020,7 +2022,7 @@ async function doctor() {
   // should not pay for another round of child spawns to ask it twice.
   if (brokenRoots.length > 0) {
     fail(
-      `Native DB binding: unusable in ${brokenRoots.map((b) => b.label).join(', ')} — run \`node ${join(PROJECT_DIR, 'cli.mjs')} rebuild-binding\` (repairs every broken install, not just this one)`,
+      `Native DB binding: unusable in ${brokenRoots.map((b) => b.label).join(', ')} — run \`node ${shellWord(join(PROJECT_DIR, 'cli.mjs'))} rebuild-binding\` (repairs every broken install, not just this one)`,
     );
     issues++;
   } else if (breakage) {
@@ -2136,7 +2138,9 @@ async function doctor() {
     );
     for (const p of orphanPaths.slice(0, 5)) log(`    missing: ${p}`);
     if (orphanPaths.length > 5) log(`    ... +${orphanPaths.length - 5} more`);
-    log(`    Repair: node ${join(PROJECT_DIR, 'install.mjs')} uninstall    # removes the dead hook entries`);
+    log(
+      `    Repair: node ${shellWord(join(PROJECT_DIR, 'install.mjs'))} uninstall    # removes the dead hook entries`,
+    );
     issues++;
   } else if (hasHooks) {
     ok('Orphan hooks: none (all hook targets present)');
@@ -2406,12 +2410,12 @@ async function doctor() {
   // already there.
   const noCodeInstall =
     !shape.managed && !shape.activePluginVersion && !hasAnyManagedCode(INSTALL_DIR, SOURCE_FILES);
-  const installRemedy = `node ${join(PROJECT_DIR, 'install.mjs')} install`;
+  const installRemedy = `node ${shellWord(join(PROJECT_DIR, 'install.mjs'))} install`;
   try {
     const skipDrift = !shape.managed && !!shape.activePluginVersion;
     const { checkDevDrift } = await import('./lib/doctor-drift.mjs');
     const r = skipDrift ? null : checkDevDrift(INSTALL_DIR, SOURCE_FILES);
-    const devRemedy = `re-run: node ${join(PROJECT_DIR, 'install.mjs')} install --dev`;
+    const devRemedy = `re-run: node ${shellWord(join(PROJECT_DIR, 'install.mjs'))} install --dev`;
     const nameList = (files, count) => {
       const suffix = count > files.length ? ` +${count - files.length} more` : '';
       return `${files.join(', ')}${suffix}`;
@@ -2483,7 +2487,7 @@ async function doctor() {
               `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)`,
+              `(or: node ${shellWord(join(INSTALL_DIR, 'cli.mjs'))} repair)`,
       );
     }
     // Complete copy install: no message — drift is a dev-install concern.
@@ -2511,7 +2515,7 @@ async function doctor() {
     // `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)`;
+      : `claude-mem-lite self-update (or: node ${shellWord(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) {

package/lib/binding-probe.mjs

@@ -10,6 +10,7 @@ import { execSync, spawnSync } from 'node:child_process';
 import { existsSync, renameSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
+import { shellWord } from '../cli-path.mjs';
 
 // npm >= 12 blocks lifecycle scripts by default, so a plain `npm rebuild` exits 0
 // WITHOUT compiling — see the rebuild() comment below. Step 1 of the heal chain, and
@@ -57,9 +58,10 @@ export const NATIVE_BINDING_SOURCE_BUILD_CMD = 'npm run --prefix node_modules/be
  * @returns {string}
  */
 export function nativeBindingRepairHint(root) {
-  // Quoted: INSTALL_DIR / a plugin-cache root can contain spaces, and an unquoted `cd`
-  // hands the user a command that fails on exactly the machines least able to debug it.
-  const npmPair = `cd "${root}" && ${NATIVE_BINDING_REBUILD_CMD} && ${NATIVE_BINDING_SOURCE_BUILD_CMD}`;
+  // shellWord, not "…": INSTALL_DIR / a plugin-cache root can contain spaces (and, under
+  // double quotes, a `$` or backtick still expands), and a `cd` that splits hands the user a
+  // command that fails on exactly the machines least able to debug it.
+  const npmPair = `cd ${shellWord(root)} && ${NATIVE_BINDING_REBUILD_CMD} && ${NATIVE_BINDING_SOURCE_BUILD_CMD}`;
   // The pair above heals a platform better-sqlite3 ships NO prebuild for. It cannot heal a
   // prebuild that is present and will not load — 13 selects `prebuilds/<target>.node` on
   // existence alone and prefers it over `build/`, so the addon those two commands compile
@@ -68,7 +70,7 @@ export function nativeBindingRepairHint(root) {
   // runs the first command they are given and stops looking when it reports success.
   const cli = join(root, 'cli.mjs');
   if (!existsSync(cli)) return npmPair;
-  return `node "${cli}" rebuild-binding   (or, without the CLI: ${npmPair})`;
+  return `node ${shellWord(cli)} rebuild-binding   (or, without the CLI: ${npmPair})`;
 }
 
 // Set on a re-exec'd child so one failed heal cannot fork-bomb the CLI.

package/lib/db-unusable.mjs

@@ -32,6 +32,7 @@
 
 import { basename, dirname } from 'node:path';
 import { readSnapshots } from './db-backup.mjs';
+import { shellWord } from '../cli-path.mjs';
 
 /** Marker prefix for lib/record-once.mjs. Per project, like the skew one. */
 export const DB_UNUSABLE_MARKER_PREFIX = '.db-unusable-logged-';
@@ -140,7 +141,7 @@ export function isDbUnusableError(err) {
  * @returns {{kind: 'restore'|'set-aside'|'unknown', command: string, note: string, snapshotCount: number}}
  */
 export function dbUnusableRemedy(dbPath) {
-  const clear = `rm -f "${dbPath}-wal" "${dbPath}-shm"`;
+  const clear = `rm -f ${shellWord(`${dbPath}-wal`)} ${shellWord(`${dbPath}-shm`)}`;
   const snap = readSnapshots(dbPath);
   if (!snap.ok) {
     return {
@@ -155,7 +156,7 @@ export function dbUnusableRemedy(dbPath) {
   if (snap.snapshots.length === 0) {
     return {
       kind: 'set-aside',
-      command: `${clear} && mv "${dbPath}" "${dbPath}.corrupt"`,
+      command: `${clear} && mv ${shellWord(dbPath)} ${shellWord(`${dbPath}.corrupt`)}`,
       snapshotCount: 0,
       note:
         'No backup snapshot exists beside the database. That command sets the broken file ' +
@@ -170,7 +171,7 @@ export function dbUnusableRemedy(dbPath) {
     .sort((a, b) => b.mtimeMs - a.mtimeMs || (a.path < b.path ? 1 : -1))[0];
   return {
     kind: 'restore',
-    command: `${clear} && cp "${newest.path}" "${dbPath}"`,
+    command: `${clear} && cp ${shellWord(newest.path)} ${shellWord(dbPath)}`,
     snapshotCount: snap.snapshots.length,
     note:
       `Restores the newest of ${snap.snapshots.length} backup snapshot(s). Move the broken ` +

package/lib/import-jsonl.mjs

@@ -45,18 +45,25 @@ const TOOL_TO_TYPE = {
  * something the scrubber rewrites (a bearer token in a `Bash` command, a path segment shaped
  * like a key) never matched itself and re-imported on every run (R12 pre-ship review P3-4).
  *
- * This returns the RAW title and both sites scrub it through `scrubRecord` exactly once.
- * The first cut scrubbed HERE, which left the storage side scrubbed twice (`scrubRecord`
- * scrubs `title` again) against the preview's once — equal only while `scrubSecrets` is
- * idempotent. It is NOT: `Bash: deploy --token ghp_… secret: v` imported three rows for
- * three runs of one transcript, and `AccountKey=https://a:b@h` drifts through a second
- * arm. `tests/property.test.mjs` claimed to enforce idempotence and was vacuous — its
- * generator produced nothing the scrubber touches. One scrub per side removes the
- * dependency instead of waiting for the pattern table to be reordered (D#46).
+ * One scrub per side, and it happens HERE, so both sites get the same string by
+ * construction and neither may wrap this call in another scrub. An earlier cut scrubbed
+ * here AND left the storage side's `scrubRecord` scrubbing `title` again — equal only while
+ * `scrubSecrets` is idempotent, which it was not until D#52 (`Bash: deploy --token ghp_…
+ * secret: v` imported three rows for three runs). The fix then returned the RAW title for
+ * both sites to scrub (D#46).
+ *
+ * Scrub FIRST, cut second (D#47 P3-8). Cutting first handed the scrubber a token the cut
+ * had split, too short for its own pattern (`ghp_` needs 30+ characters), and the prefix
+ * was stored in plaintext — up to 29 of a GitHub token's 36 secret characters, at 29 of 41
+ * cut positions. The whole title goes through the scrubber; the cap counts from the end of
+ * the `<tool>: ` prefix.
  */
+const IMPORTED_TITLE_DETAIL_MAX = 80;
 function importedObsTitle(toolUse) {
   const detail = toolUse?.input?.command || toolEditPath(toolUse?.input) || '';
-  return `${toolUse?.name || 'unknown'}: ${String(detail).slice(0, 80)}`;
+  const prefix = `${toolUse?.name || 'unknown'}: `;
+  const scrubbed = scrubRecord('observations', { title: `${prefix}${detail}` }).title;
+  return scrubbed.slice(0, prefix.length + IMPORTED_TITLE_DETAIL_MAX);
 }
 
 function dedupKey(parts) {
@@ -113,7 +120,9 @@ function importPrompt(db, ev, project, seenPrompts) {
   if (text.startsWith('<task-notification>')) return false;
   const sessionId = ev.sessionId || 'imported';
   const ts = ev.timestamp || new Date().toISOString();
-  const safe = scrubSecrets(text.slice(0, 10000));
+  // Scrub, THEN cap: cutting first handed the scrubber a token the cap had split, too short
+  // for its own pattern, and stored the prefix (same order bug as importedObsTitle).
+  const safe = scrubSecrets(text).slice(0, 10000);
   // Dedup key uses the scrubbed text so a re-run computes the same key as the
   // first run (which persisted the scrubbed text). Keying on raw input would
   // make idempotency fragile if the scrub policy changes.
@@ -146,14 +155,16 @@ function importToolPair(db, toolUse, toolResult, project) {
 
   const toolName = toolUse.name || 'unknown';
   const type = TOOL_TO_TYPE[toolName] || 'change';
-  const inputJson =
-    typeof toolUse.input === 'object'
-      ? JSON.stringify(toolUse.input).slice(0, 4000)
-      : String(toolUse.input ?? '').slice(0, 4000);
+  // Each part is scrubbed BEFORE its 4000-character cap, for the reason importedObsTitle
+  // gives: a cap that splits a token leaves a prefix too short for the scrubber's pattern.
+  // The body is therefore kept out of the scrubRecord call below, so it is scrubbed once.
+  const inputJson = scrubSecrets(
+    typeof toolUse.input === 'object' ? JSON.stringify(toolUse.input) : String(toolUse.input ?? ''),
+  ).slice(0, 4000);
   const resultText =
     typeof toolResult?.content === 'string'
-      ? toolResult.content
-      : JSON.stringify(toolResult?.content ?? '').slice(0, 4000);
+      ? scrubSecrets(toolResult.content)
+      : scrubSecrets(JSON.stringify(toolResult?.content ?? '')).slice(0, 4000);
 
   // D#35: this gated on `input.file_path` alone, and `NotebookEdit` carries
   // `notebook_path` and never `file_path` — so the branch named NotebookEdit
@@ -184,8 +195,18 @@ function importToolPair(db, toolUse, toolResult, project) {
   // both: `narrative` as the durable home, `text` as the index copy the ingest paths
   // write directly.
   const body = `${inputJson}\n---\n${resultText}`;
-  const safe = scrubRecord('observations', {
-    // This string IS the cross-run dedup key — `importedObsTitle` is the single home for
+  const safe = {
+    ...scrubRecord('observations', {
+      subtitle: '',
+      concepts: '',
+      facts: '',
+      lesson_learned: null,
+      search_aliases: null,
+    }),
+    // Outside scrubRecord on purpose: body and title were each already scrubbed, once.
+    text: body,
+    narrative: body,
+    // The title: this string IS the cross-run dedup key — `importedObsTitle` is the single home for
     // it, because the two sites that must agree byte-for-byte did not. An earlier cut of
     // this round kept the title on `file_path` alone to avoid the migration — and shipped
     // `NotebookEdit: ` with an empty label for exactly the rows D#35 had just made
@@ -196,14 +217,7 @@ function importToolPair(db, toolUse, toolResult, project) {
     // carry the old key, so the next import re-adds each of them ONCE and then
     // matches forever. Stated in the CHANGELOG rather than absorbed silently.
     title: importedObsTitle(toolUse),
-    subtitle: '',
-    text: body,
-    narrative: body,
-    concepts: '',
-    facts: '',
-    lesson_learned: null,
-    search_aliases: null,
-  });
+  };
 
   const inserted = db
     .prepare(
@@ -326,9 +340,9 @@ export async function importJsonl(db, path, { project }) {
     seenToolUseIds.add(callKey);
 
     // Cross-call dedup: synthesize the title the previous run would have written and check
-    // the seenObs set seeded from the DB. Same raw expression AND the same single scrub as
-    // the storage site, so the scrubber cannot rewrite one and not the other.
-    const titlePreview = scrubRecord('observations', { title: importedObsTitle(useEv) }).title;
+    // the seenObs set seeded from the DB. The same function as the storage site, scrub and
+    // cut included, so the scrubber cannot rewrite one and not the other.
+    const titlePreview = importedObsTitle(useEv);
     const ts = useEv.timestamp || new Date().toISOString();
     // Match the storage convention from importToolPair (memId-prefixed) so
     // the seenObs entries seeded from the DB can be matched on a re-run.

package/lib/install-shape.mjs

@@ -33,6 +33,7 @@
 import { existsSync, readdirSync, realpathSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { shellWord } from '../cli-path.mjs';
 
 import {
   probeBindingInFreshProcess,
@@ -324,7 +325,7 @@ export function probeRuntimeRoots(roots, deps = {}) {
           // "none resolvable from a parent directory" and was caught printing that
           // next to a probe error naming the parent tree it had just loaded from.
           error: `${error} — and this install owns no node_modules/better-sqlite3, so there is nothing here to rebuild`,
-          repair: `cd ${root} && npm install --omit=dev`,
+          repair: `cd ${shellWord(root)} && npm install --omit=dev`,
         };
   });
 }

package/lib/native-binding-hint.mjs

@@ -25,6 +25,7 @@ import { join, dirname } from 'node:path';
 import { readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { isNativeBindingError, flattenBindingError } from './binding-probe.mjs';
+import { shellWord } from '../cli-path.mjs';
 
 export const NATIVE_BINDING_HINT_COOLDOWN_MS = 6 * 60 * 60 * 1000; // 6h
 const MARKER_NAME = 'native-binding-hint-last';
@@ -45,7 +46,7 @@ export const NATIVE_BINDING_BROKEN_MARKER = 'native-binding-broken';
 // D#207: join(), not `new URL('../cli.mjs', …)` — that form makes knip drop the named
 // module out of its unused-export report. cli.mjs is a knip entry point so nothing was
 // lost here, but the rule is enforced for the class rather than per-file.
-const CLI_REBUILD_BINDING = `node ${join(dirname(fileURLToPath(import.meta.url)), '..', 'cli.mjs')} rebuild-binding`;
+const CLI_REBUILD_BINDING = `node ${shellWord(join(dirname(fileURLToPath(import.meta.url)), '..', 'cli.mjs'))} rebuild-binding`;
 
 // Stable-ish identity of a fault so DISTINCT failures get DISTINCT cooldown
 // windows: the same fault → same key (suppressed within the window), a different

package/mem-cli.mjs

@@ -3692,11 +3692,13 @@ async function runDispatch(argv) {
   // project — a misspelled flag changed results with zero signal. Warn (stderr, non-fatal)
   // when a flag looks like a misspelling of a real one; stdout + exit code stay untouched,
   // so JSON/text consumers are unaffected. Mirrors the unknown-COMMAND suggester in cli.mjs.
-  for (const { flag, suggestion } of suggestUnknownFlags(parseArgs(cmdArgs).flags)) {
+  for (const { flag, suggestion, owner } of suggestUnknownFlags(parseArgs(cmdArgs).flags, cmd)) {
     process.stderr.write(
-      suggestion
-        ? `[mem] Unknown flag --${flag}; did you mean --${suggestion}?\n`
-        : `[mem] Unknown flag --${flag} — ignored, it had no effect. Run "claude-mem-lite help" for this command's flags.\n`,
+      owner
+        ? `[mem] --${flag} is read only by ${owner}; ${cmd} does not read it.\n`
+        : suggestion
+          ? `[mem] Unknown flag --${flag}; did you mean --${suggestion}?\n`
+          : `[mem] Unknown flag --${flag} — ignored, it had no effect. Run "claude-mem-lite help" for this command's flags.\n`,
     );
   }
 

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.12.0",
+  "version": "6.12.2",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/scripts/hook-launcher.mjs

@@ -125,7 +125,10 @@ const NB_MANUAL_CMD =
 // INSTALL_DIR (import.meta.url) so it works on a plugin-only install, where
 // bare `claude-mem-lite` is not on PATH and ~/.claude-mem-lite/ holds no source.
 // cli.mjs routes `repair` → install.mjs. (review #3)
-const CLI_REPAIR = `node ${join(INSTALL_DIR, 'cli.mjs')} repair`;
+// Quote a path as ONE shell word for a printed command. A copy of cli-path.mjs's, not an
+// import (node: builtins only here); tests/cli-path-invocation.test.mjs keeps them equal.
+const shellWord = (s) => (/^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`);
+const CLI_REPAIR = `node ${shellWord(join(INSTALL_DIR, 'cli.mjs'))} repair`;
 
 // Last-resort recovery string for users whose `cli.mjs repair` path
 // itself failed (install.mjs missing / repair errored / retry still drifting).
@@ -490,7 +493,7 @@ function healNativeBindingIfBroken() {
     const installer = join(INSTALL_DIR, 'install.mjs');
     if (!existsSync(installer)) {
       process.stderr.write(
-        `[claude-mem-lite] native DB binding unusable and install.mjs is missing — run: cd "${INSTALL_DIR}" && ${NB_MANUAL_CMD}\n`,
+        `[claude-mem-lite] native DB binding unusable and install.mjs is missing — run: cd ${shellWord(INSTALL_DIR)} && ${NB_MANUAL_CMD}\n`,
       );
       return;
     }

package/scripts/launch.mjs

@@ -9,6 +9,9 @@ import { homedir } from 'node:os';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = process.env.CLAUDE_PLUGIN_ROOT || join(__dirname, '..');
+// Quote a path as ONE shell word for a printed command. A copy of cli-path.mjs's, not an
+// import (node: builtins only here); tests/cli-path-invocation.test.mjs keeps them equal.
+const shellWord = (s) => (/^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`);
 
 if (!existsSync(join(ROOT, 'node_modules', 'better-sqlite3'))) {
   // Platform gate BEFORE npm, not after it. package.json's `os` field is an npm install
@@ -34,7 +37,7 @@ if (!existsSync(join(ROOT, 'node_modules', 'better-sqlite3'))) {
         `[claude-mem-lite] Nothing was installed, so the MCP server cannot start. See "Platform Support" in the README.\n`,
       );
       process.stderr.write(
-        `[claude-mem-lite] To install anyway: cd "${ROOT}" && npm install --omit=dev --force\n`,
+        `[claude-mem-lite] To install anyway: cd ${shellWord(ROOT)} && npm install --omit=dev --force\n`,
       );
       process.exit(1);
     }
@@ -93,7 +96,7 @@ if (!existsSync(join(ROOT, 'node_modules', 'better-sqlite3'))) {
     process.stderr.write(
       `[claude-mem-lite] npm printed its own error above — read its "npm error code" line first. Common causes: read-only directory, disk full, network blocked.\n`,
     );
-    process.stderr.write(`[claude-mem-lite] Repair: cd "${ROOT}" && npm install --omit=dev\n`);
+    process.stderr.write(`[claude-mem-lite] Repair: cd ${shellWord(ROOT)} && npm install --omit=dev\n`);
     process.exit(1);
   }
 }

package/scripts/pre-tool-recall.js

@@ -648,7 +648,8 @@ try {
       ORDER BY
         CASE WHEN o.lesson_learned IS NOT NULL AND o.lesson_learned != '' THEN 0 ELSE 1 END,
         ${citeFactorClause('o')} DESC,
-        o.created_at_epoch DESC
+        o.created_at_epoch DESC,
+        o.id DESC
       LIMIT ${obsLimit}
     `,
       )
@@ -691,7 +692,8 @@ try {
           ${eventsBodyFilter}
         ORDER BY
           CASE WHEN body IS NOT NULL AND body != '' THEN 0 ELSE 1 END,
-          created_at_epoch DESC
+          created_at_epoch DESC,
+          id DESC
         LIMIT ${eventsLimit}
       `,
         )

package/server.mjs

@@ -75,7 +75,7 @@ import { buildLessonNudge } from './lib/save-nudge.mjs';
 import { formatObsFieldValue, obsFieldLabel, formatPendingPurgeLine } from './cli/common.mjs';
 // 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 { CLI_INVOKE, shellWord } from './cli-path.mjs';
 import { neutralizeContextDelimiters, neutralizeSkillDelimiters, queryLabel } from './format-utils.mjs';
 import {
   memSearchSchema,
@@ -214,7 +214,7 @@ try {
   console.error(`[claude-mem-lite] FATAL: Database cannot be opened: ${err.message}`);
   if (err.walRecoveryAttempted) {
     console.error(
-      `[claude-mem-lite] Try: rm "${DB_PATH}-wal" "${DB_PATH}-shm" or reinstall with: node install.mjs install`,
+      `[claude-mem-lite] Try: rm ${shellWord(`${DB_PATH}-wal`)} ${shellWord(`${DB_PATH}-shm`)} or reinstall with: node install.mjs install`,
     );
   } else {
     console.error(