claude-mem-lite 3.1.0 → 3.1.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.1.0",
+      "version": "3.1.1",
       "source": "./",
       "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": "3.1.0",
+  "version": "3.1.1",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -160,7 +160,7 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 
 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 absolute path (`node ~/.claude-mem-lite/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 (`${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 fires on the first SessionStart per project (v2.82.1+).** The plugin automatically writes the **invited-memory sentinel** (a system-authority pointer that boosts Claude's proactive use of `mem_recall` / `mem_save`) into the project's memdir — **no manual `/adopt` needed**, regardless of install path (npm, npx, `/plugin`, manual). Per-project opt-out: `claude-mem-lite adopt --disable` (`--enable` to re-arm). Global opt-out: `export MEM_NO_AUTO_ADOPT=1`. Manual `/adopt` remains available for re-applying after edits and for the `--all` batch path.
 
@@ -263,9 +263,9 @@ surface — reach them through the CLI column in the second table.
 | `mem_update` | `claude-mem-lite update <id>` | Edit an observation in place. |
 | `mem_stats` | `claude-mem-lite stats` | Counts, type distribution, daily activity. |
 | `mem_delete` | `claude-mem-lite delete <id>` | Preview / confirm workflow, FTS5 cleanup. |
-| `mem_compress` | `claude-mem-lite compress --preview` | Roll up old low-value observations. |
-| `mem_maintain` | `claude-mem-lite maintain --action scan` | dedup / decay / cleanup / rebuild_vectors. |
-| `mem_optimize` | `claude-mem-lite optimize --action preview` | LLM-powered re-enrich / normalize / cluster-merge. |
+| `mem_compress` | `claude-mem-lite compress` | Roll up old low-value observations (preview default; `--execute` to apply). |
+| `mem_maintain` | `claude-mem-lite maintain scan --ops dedup,decay` | dedup / decay / cleanup / rebuild_vectors (`scan` previews, `execute` applies). |
+| `mem_optimize` | `claude-mem-lite optimize` | LLM-powered re-enrich / normalize / cluster-merge (preview default; `--run` to apply). |
 | `mem_export` | `claude-mem-lite export` | JSON / JSONL dump, filters by project, type, date. |
 | `mem_fts_check` | `claude-mem-lite fts-check [--rebuild]` | FTS5 integrity + rebuild. |
 | `mem_browse` | `claude-mem-lite browse` | Tier-grouped dashboard (working / active / archive). |

package/README.zh-CN.md

@@ -127,6 +127,8 @@
 
 插件模式会管理自己的运行时与钩子。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`。插件要完整工作**并不需要**它。
+
 ### 方式二：npx（一行命令）
 
 ```bash
@@ -223,9 +225,9 @@ v2.34.0 起服务端注册 17 个工具，但 `tools/list` 只暴露 6 个 **核
 | `mem_update` | `claude-mem-lite update <id>` | 原地更新某条观察。 |
 | `mem_stats` | `claude-mem-lite stats` | 计数、类型分布、每日活动。 |
 | `mem_delete` | `claude-mem-lite delete <id>` | 预览 / 确认流程，FTS5 自动清理。 |
-| `mem_compress` | `claude-mem-lite compress --preview` | 压缩旧的低价值观察。 |
-| `mem_maintain` | `claude-mem-lite maintain --action scan` | 去重 / decay / 清理 / 向量重建。 |
-| `mem_optimize` | `claude-mem-lite optimize --action preview` | LLM 深度优化：re-enrich / normalize / cluster-merge。 |
+| `mem_compress` | `claude-mem-lite compress` | 压缩旧的低价值观察（默认 preview；`--execute` 执行）。 |
+| `mem_maintain` | `claude-mem-lite maintain scan --ops dedup,decay` | 去重 / decay / 清理 / 向量重建（`scan` 预览，`execute` 执行）。 |
+| `mem_optimize` | `claude-mem-lite optimize` | LLM 深度优化：re-enrich / normalize / cluster-merge（默认 preview；`--run` 执行）。 |
 | `mem_export` | `claude-mem-lite export` | JSON / JSONL 导出，支持项目/类型/日期过滤。 |
 | `mem_fts_check` | `claude-mem-lite fts-check [--rebuild]` | FTS5 完整性检查与重建。 |
 | `mem_browse` | `claude-mem-lite browse` | 分层仪表盘（working / active / archive）。 |

package/adopt-content.mjs

@@ -7,6 +7,8 @@
 // docs/plans/2026-04-16-invited-memory-pattern.md so installs do a version-
 // bump replace instead of treating the old content as a user edit.
 
+import { CLI_INVOKE } from './cli-path.mjs';
+
 export const PLUGIN_SLUG = 'claude-mem-lite';
 export const CURRENT_SENTINEL_VERSION = 'v1';
 
@@ -26,7 +28,7 @@ export function getIndexLine() {
 export function getDetailDoc() {
   return `# claude-mem-lite 插件契约
 
-> 由 \`node ~/.claude-mem-lite/cli.mjs adopt\` 生成；卸载用 \`node ~/.claude-mem-lite/cli.mjs unadopt\`。
+> 由 \`${CLI_INVOKE} adopt\` 生成；卸载用 \`${CLI_INVOKE} unadopt\`。
 > 设计背景见 docs/plans/2026-04-16-invited-memory-pattern.md。
 
 ## 何时调用 MCP 工具
@@ -58,37 +60,37 @@ MCP 层，按名 \`tools/call\` 仍可命中，但对 Claude Code 这类只读 t
 
 | 场景 | CLI |
 |------|-----|
-| 清理过期记忆 | \`node ~/.claude-mem-lite/cli.mjs maintain scan --ops purge_stale\` → \`maintain execute --ops purge_stale\` |
-| 深度优化（Haiku） | \`node ~/.claude-mem-lite/cli.mjs optimize\`（默认 preview；\`--run\` 执行，\`--task re-enrich,normalize,cluster-merge,smart-compress\` 选阶段） |
-| 压缩旧条目 | \`node ~/.claude-mem-lite/cli.mjs compress\`（默认 preview；\`--execute\` 执行，\`--age-days N\` 改阈值） |
-| FTS5 索引检查 / 重建 | \`node ~/.claude-mem-lite/cli.mjs fts-check [--rebuild]\` |
-| tier 分组浏览 | \`node ~/.claude-mem-lite/cli.mjs browse [--tier active]\` |
-| 导出 JSON/JSONL | \`node ~/.claude-mem-lite/cli.mjs export [--format jsonl]\` |
-| 统计总量 / 健康 | \`node ~/.claude-mem-lite/cli.mjs stats [--days 30]\` |
-| 删除某条 | \`node ~/.claude-mem-lite/cli.mjs delete <id>[,<id>]\` |
-| 更新某条 | \`node ~/.claude-mem-lite/cli.mjs update <id> [--title ...]\` |
-| 列 / 搜索 / 导入 skill-agent registry | \`node ~/.claude-mem-lite/cli.mjs registry <list\\|search\\|import>\` |
+| 清理过期记忆 | \`${CLI_INVOKE} maintain scan --ops purge_stale\` → \`maintain execute --ops purge_stale --confirm\`（execute 删行必须带 \`--confirm\`，否则只预览） |
+| 深度优化（Haiku） | \`${CLI_INVOKE} optimize\`（默认 preview；\`--run\` 执行，\`--task re-enrich,normalize,cluster-merge,smart-compress\` 选阶段） |
+| 压缩旧条目 | \`${CLI_INVOKE} compress\`（默认 preview；\`--execute\` 执行，\`--age-days N\` 改阈值） |
+| FTS5 索引检查 / 重建 | \`${CLI_INVOKE} fts-check [--rebuild]\` |
+| tier 分组浏览 | \`${CLI_INVOKE} browse [--tier active]\` |
+| 导出 JSON/JSONL | \`${CLI_INVOKE} export [--format jsonl]\` |
+| 统计总量 / 健康 | \`${CLI_INVOKE} stats [--days 30]\` |
+| 删除某条 | \`${CLI_INVOKE} delete <id>[,<id>]\` |
+| 更新某条 | \`${CLI_INVOKE} update <id> [--title ...]\` |
+| 列 / 搜索 / 导入 skill-agent registry | \`${CLI_INVOKE} registry <list\\|search\\|import>\` |
 | 按 registry 名载入 skill/agent | （MCP only：\`mem_use\`；由用户主动请求时才使用） |
 
 ## CLI 速查（常用检索）
 
 | 命令 | 用途 |
 |------|------|
-| \`node ~/.claude-mem-lite/cli.mjs search "query"\` | FTS5 全文搜索 |
-| \`node ~/.claude-mem-lite/cli.mjs search "err" --type bugfix\` | 按类型过滤 |
-| \`node ~/.claude-mem-lite/cli.mjs recall "file.mjs"\` | 文件相关记忆 |
-| \`node ~/.claude-mem-lite/cli.mjs recent 5\` | 最近 5 条 |
-| \`node ~/.claude-mem-lite/cli.mjs get 42,43\` | 按 ID 展开 |
-| \`node ~/.claude-mem-lite/cli.mjs timeline --anchor 42\` | 时间线上下文 |
+| \`${CLI_INVOKE} search "query"\` | FTS5 全文搜索 |
+| \`${CLI_INVOKE} search "err" --type bugfix\` | 按类型过滤 |
+| \`${CLI_INVOKE} recall "file.mjs"\` | 文件相关记忆 |
+| \`${CLI_INVOKE} recent 5\` | 最近 5 条 |
+| \`${CLI_INVOKE} get 42,43\` | 按 ID 展开 |
+| \`${CLI_INVOKE} timeline --anchor 42\` | 时间线上下文 |
 
 ## 质量门槛
 
 - \`mem_save\` 的 \`lesson_learned\` 不要写 \`none\`——写不出教训就保持 NULL
-- \`decision\` 命中率 72.7% vs \`change\` 16.5%——一条好 decision ≈ 20 条 change
+- \`decision\` 的命中率高于 \`change\`（当前遥测约 3:1，数值会漂移——用 \`${CLI_INVOKE} stats\` 实测，别套固定倍数）；方向稳健：一条好 decision 抵数条 change
 - 一般搜索跳过 \`obs_type\` 让系统自动路由；特定意图再过滤
 
 ## 卸载
 
-\`node ~/.claude-mem-lite/cli.mjs unadopt\` 精确移除 sentinel 段 + 本文件；其它 MEMORY.md 内容不动。
+\`${CLI_INVOKE} unadopt\` 精确移除 sentinel 段 + 本文件；其它 MEMORY.md 内容不动。
 `;
 }

package/cli-path.mjs

@@ -0,0 +1,21 @@
+// cli-path.mjs — single source of truth for invoking the bundled CLI by an
+// absolute, install-shape-independent path.
+//
+// cli.mjs is a sibling of this module at the package root, so import.meta.url
+// resolves it correctly on EVERY install shape: plugin cache, `npm i -g`
+// symlink farm, and manual/dev checkout. The pre-v3.1.1 hardcoded
+// `~/.claude-mem-lite/cli.mjs` only existed on direct-install symlink farms —
+// on a plugin-only install setup.sh provisions the data dir but never
+// materializes source there, so that path is a module-not-found. See the
+// 2026-06-20 code review, findings #1/#2/#3/#13.
+//
+// Use this for JS-emitted, runtime-resolved surfaces (MCP `instructions`, the
+// per-tool "Equivalent CLI" hints, hook recovery lines, the generated adopt
+// doc). Plugin MANIFEST files (commands/*.md, .mcp.json) must instead use the
+// literal `${CLAUDE_PLUGIN_ROOT}` token, which Claude Code — not the shell —
+// substitutes at execution time (the env var is absent from a plain Bash env).
+
+import { fileURLToPath } from 'node:url';
+
+export const CLI_PATH = fileURLToPath(new URL('./cli.mjs', import.meta.url));
+export const CLI_INVOKE = `node ${CLI_PATH}`;

package/commands/adopt.md

@@ -57,4 +57,4 @@ session. After running `adopt`:
 
 Same caveat applies in reverse for `/unadopt`.
 
-!node ~/.claude-mem-lite/cli.mjs adopt $ARGUMENTS
+!node ${CLAUDE_PLUGIN_ROOT}/cli.mjs adopt $ARGUMENTS

package/commands/bug.md

@@ -42,7 +42,7 @@ Build the body as `<description>\n\nRepro:\n<repro-steps>` (or just
 
 Run via Bash:
 
-    node ~/.claude-mem-lite/cli.mjs activity save \
+    node ${CLAUDE_PLUGIN_ROOT}/cli.mjs activity save \
       --type bug \
       --title "<first 60 chars of description>" \
       --body "<body>" \

package/commands/lesson.md

@@ -37,7 +37,7 @@ Run via Bash — the CLI takes the lesson text as positional args and stores
 the full text as the title (the `activity save` command uses title-as-body
 when `--body` is absent):
 
-    node ~/.claude-mem-lite/cli.mjs activity save \
+    node ${CLAUDE_PLUGIN_ROOT}/cli.mjs activity save \
       --type lesson \
       --title "<first 60 chars of text>" \
       --body "<full text>" \

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-mem-lite/cli.mjs search <query>` via Bash
-- `/mem recent` or `/mem recent 20` → run `node ~/.claude-mem-lite/cli.mjs recent [N]` via Bash
-- `/mem recall <file>` → run `node ~/.claude-mem-lite/cli.mjs recall <file>` via Bash
-- `/mem timeline <id>` → run `node ~/.claude-mem-lite/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-mem-lite/cli.mjs stats` via Bash
-- `/mem get <ids>` → run `node ~/.claude-mem-lite/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"])` if confirmed
 - `/mem cleanup Nd` (e.g. `60d`) → same as above but use `retain_days=N` to only purge items older than N days
 - `/mem cleanup keep Nd` (e.g. `keep 14d`) → same as above with `retain_days=N`
-- `/mem <query>` (no subcommand) → treat as search, run `node ~/.claude-mem-lite/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-mem-lite/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

@@ -27,4 +27,4 @@ Once unadopted, the conservative hook layer (SessionStart `File Lessons` /
 `Key Context`, MCP instructions `WHEN TO USE`) goes back to verbose mode —
 Claude Code will see the full injection again on the next session start.
 
-!node ~/.claude-mem-lite/cli.mjs unadopt $ARGUMENTS
+!node ${CLAUDE_PLUGIN_ROOT}/cli.mjs unadopt $ARGUMENTS

package/install.mjs

@@ -1369,6 +1369,23 @@ async function doctor() {
     issues++;
   }
 
+  // Hook self-heal runtime: the launcher (scripts/hook-launcher.mjs) degrades a
+  // broken install to exit 0 so it never spams a Node stack trace on every hook
+  // fire. That silence is intentional but hides failure — it drops a breakage
+  // marker so this check can surface the otherwise-invisible degraded state.
+  const brokenMarker = join(MEM_DATA_DIR, 'runtime', 'hook-launcher-broken');
+  if (existsSync(brokenMarker)) {
+    let detail = '';
+    try {
+      const b = JSON.parse(readFileSync(brokenMarker, 'utf8'));
+      const ageH = Math.round((Date.now() - (b.ts || 0)) / 3600000);
+      detail = ` (last: ${b.reason || 'unknown'}, ~${ageH}h ago)`;
+    } catch { /* unreadable marker → bare warning */ }
+    dwarn(`Hook self-heal: a recent hook fire degraded to exit-0${detail} — run \`node ${join(PROJECT_DIR, 'install.mjs')} repair\``);
+  } else {
+    ok('Hook self-heal: no recent silent hook breakage');
+  }
+
   // Plugin/hook lifecycle state
   const settings = readSettings();
   const hasHooks = hasMemHooksConfigured(settings);

package/lib/native-binding-hint.mjs

@@ -19,31 +19,62 @@
 // hook dependency graph (no schema.mjs / better-sqlite3 import).
 
 import { join } from 'node:path';
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 
 export const NATIVE_BINDING_HINT_COOLDOWN_MS = 6 * 60 * 60 * 1000; // 6h
 const MARKER_NAME = 'native-binding-hint-last';
 
+// Resolvable invocation of the bundled CLI's repair path. Absolute via
+// import.meta.url (cli.mjs is one dir up from lib/) so it works on a plugin-only
+// install, where bare `claude-mem-lite` is not on PATH. cli.mjs routes `repair`
+// → install.mjs. (review #3)
+const CLI_REPAIR = `node ${fileURLToPath(new URL('../cli.mjs', import.meta.url))} repair`;
+
+// Stable-ish identity of a fault so DISTINCT failures get DISTINCT cooldown
+// windows: the same fault → same key (suppressed within the window), a different
+// fault → different key → surfaces even within the window. djb2 over the message
+// keeps it dependency-free (no node:crypto). (review #8/#15)
+function errKey(message = '') {
+  const m = String(message);
+  let h = 5381;
+  for (let i = 0; i < m.length; i++) h = ((h * 33) ^ m.charCodeAt(i)) >>> 0;
+  return h.toString(36);
+}
+
 /**
- * True at most once per cooldown window. Persists the last-hint timestamp as
- * file CONTENT (not mtime) under runtimeDir so callers can inject `now`
- * deterministically in tests. Best-effort: any fs error returns true — showing
- * the hint beats silently swallowing a real problem.
+ * True at most once per cooldown window FOR A GIVEN `key`. Persists
+ * "<epochMs>\t<key>" as file CONTENT (not mtime) under runtimeDir so callers can
+ * inject `now` deterministically in tests. A different `key` (a distinct fault)
+ * resets the window, so a new problem is never silenced by an earlier, unrelated
+ * one. Best-effort: any fs error returns true — showing the hint beats silently
+ * swallowing a real problem.
  *
  * @param {string} runtimeDir Directory for the marker file
  * @param {number} [now] Current epoch ms (injectable)
  * @param {number} [cooldownMs] Suppression window
+ * @param {string} [key] Fault identity; same key within the window → suppressed
  * @returns {boolean}
  */
-export function nativeBindingHintDue(runtimeDir, now = Date.now(), cooldownMs = NATIVE_BINDING_HINT_COOLDOWN_MS) {
+export function nativeBindingHintDue(runtimeDir, now = Date.now(), cooldownMs = NATIVE_BINDING_HINT_COOLDOWN_MS, key = '') {
   const marker = join(runtimeDir, MARKER_NAME);
   try {
-    const last = Number(readFileSync(marker, 'utf8'));
-    if (Number.isFinite(last) && now - last < cooldownMs) return false;
+    const raw = readFileSync(marker, 'utf8');
+    // Format "<epochMs>\t<key>"; a legacy bare "<epochMs>" parses with key ''.
+    const tab = raw.indexOf('\t');
+    const last = Number(tab === -1 ? raw : raw.slice(0, tab));
+    const lastKey = tab === -1 ? '' : raw.slice(tab + 1);
+    if (Number.isFinite(last) && lastKey === key && now - last < cooldownMs) return false;
   } catch { /* no/invalid marker → due */ }
   try {
-    if (!existsSync(runtimeDir)) mkdirSync(runtimeDir, { recursive: true });
-    writeFileSync(marker, String(now));
+    mkdirSync(runtimeDir, { recursive: true });
+    // Atomic write (tmp + rename) so a concurrent reader sees the old or the new
+    // COMPLETE value, never a torn timestamp that parses NaN → spurious "due" →
+    // duplicate hint. The residual read-then-decide race can still emit twice, but
+    // the hint is cosmetic and 6h-rate-limited, so that is acceptable. (#7/#10)
+    const tmp = `${marker}.tmp-${process.pid}`;
+    writeFileSync(tmp, `${now}\t${key}`);
+    renameSync(tmp, marker);
   } catch { /* best-effort */ }
   return true;
 }
@@ -63,9 +94,12 @@ export function nativeBindingHintDue(runtimeDir, now = Date.now(), cooldownMs =
 export function formatHookError(err, event, { now = Date.now(), runtimeDir } = {}) {
   const ts = new Date(now).toISOString();
   if (err && err.code === 'ERR_DLOPEN_FAILED') {
-    if (runtimeDir && !nativeBindingHintDue(runtimeDir, now)) return null;
+    // Key the cooldown on the fault identity so a DISTINCT native failure within
+    // the window still surfaces (a second ABI mismatch after a partial rebuild, a
+    // corrupt .node) instead of being silenced by a prior, different DLOPEN. (#8/#15)
+    if (runtimeDir && !nativeBindingHintDue(runtimeDir, now, NATIVE_BINDING_HINT_COOLDOWN_MS, errKey(err.message))) return null;
     return `[claude-mem-lite] [${ts}] [WARN] ${event}: native DB binding can't load ` +
-      `(likely a Node version change) — auto-heals on next MCP server start, or run: claude-mem-lite repair`;
+      `(likely a Node version change) — auto-heals on next MCP server start, or run: ${CLI_REPAIR}`;
   }
   return `[claude-mem-lite] [${ts}] [ERROR] ${event}: ${err && err.message}`;
 }

package/package.json

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

package/scripts/hook-launcher.mjs

@@ -24,7 +24,7 @@
 // would defeat the entire purpose — the launcher must survive a broken
 // install.
 
-import { existsSync, mkdirSync, writeFileSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, statSync, unlinkSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -37,8 +37,18 @@ const RUNTIME_DIR = process.env.CLAUDE_MEM_DIR
   : join(homedir(), '.claude-mem-lite', 'runtime');
 const HEAL_MARKER = join(RUNTIME_DIR, 'hook-launcher-lastheal');
 const HEAL_COOLDOWN_MS = 6 * 60 * 60 * 1000;
+// Observable breakage state: written when the launcher degrades a broken install
+// to exit 0, cleared once the install is confirmed healthy. `doctor` reads it so
+// the intentional silence (no stack trace per fire) stays detectable. (#4/#8)
+const BROKEN_MARKER = join(RUNTIME_DIR, 'hook-launcher-broken');
 
-// Last-resort recovery string for users whose `claude-mem-lite repair` path
+// Resolvable invocation of the bundled CLI's repair path. Absolute via
+// 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`;
+
+// Last-resort recovery string for users whose `cli.mjs repair` path
 // itself failed (install.mjs missing / repair errored / retry still drifting).
 // Duplicated in install.mjs::repair() catch; both are reachable when local
 // scripts are broken, so neither can import a shared constant.
@@ -76,13 +86,51 @@ async function runEntry({ bustCache = false } = {}) {
 // Anchor on any path the error exposes — the missing URL and/or the importer
 // (present in both messages as "imported from <path>"). If it sits inside our
 // install, a self-heal could fix it.
+// package.json dependency set of THIS install — read lazily, best-effort. Lets
+// isLocalModuleErr tell a genuinely-ours missing bare dependency (better-sqlite3,
+// zod, …) apart from a foreign/mistyped package name that merely happens to be
+// imported from an install-dir file. The former is self-healable; the latter is
+// a real packaging bug that must surface a Node stack trace rather than be
+// swallowed by an exit-0 self-heal. (review #5/#7)
+function ownDependencies() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(INSTALL_DIR, 'package.json'), 'utf8'));
+    return new Set([
+      ...Object.keys(pkg.dependencies || {}),
+      ...Object.keys(pkg.optionalDependencies || {}),
+    ]);
+  } catch {
+    return null; // unreadable package.json → caller stays permissive
+  }
+}
+
 function isLocalModuleErr(e) {
   if (!e || e.code !== 'ERR_MODULE_NOT_FOUND') return false;
-  const importer = /imported from (.+?)\s*$/.exec(String(e.message || ''))?.[1];
-  const paths = [e.url, importer]
-    .filter(Boolean)
-    .map((p) => String(p).replace(/^file:\/\//, ''));
-  return paths.some((p) => p.startsWith(INSTALL_DIR) || p.includes('.claude-mem-lite'));
+  // Missing RELATIVE module: e.url is the missing file's URL. Ours iff it sits
+  // under our install dir (the `.claude-mem-lite` substring also covers the
+  // symlink-farm dev/direct-install case where INSTALL_DIR is the realpath).
+  if (e.url) {
+    const p = String(e.url).replace(/^file:\/\//, '');
+    return p.startsWith(INSTALL_DIR) || p.includes('.claude-mem-lite');
+  }
+  // Missing BARE dependency: e.url is UNDEFINED; message is
+  // `Cannot find package '<name>' imported from <importer>`. The (.+) capture
+  // needs no `m` flag (`.` stops at a newline) and so tolerates a multi-line
+  // message that appends a hint line after the importer path — the old
+  // `(.+?)\s*$` returned undefined there and misclassified the dep. (review #11/#15)
+  const msg = String(e.message || '');
+  const importer = /imported from (.+)/.exec(msg)?.[1]?.trim();
+  if (!importer) return false;
+  const importerPath = importer.replace(/^file:\/\//, '');
+  if (!(importerPath.startsWith(INSTALL_DIR) || importerPath.includes('.claude-mem-lite'))) return false;
+  // Importer is ours — but only self-heal if the missing package is one we
+  // actually declare. A foreign/typo'd name re-throws so the bug is visible.
+  const pkgName = /Cannot find package '([^']+)'/.exec(msg)?.[1];
+  const deps = ownDependencies();
+  if (!deps || !pkgName) return true; // best-effort: can't verify → stay permissive
+  // Normalize sub-path / scoped imports to the package root (better-sqlite3/x → better-sqlite3).
+  const root = pkgName.startsWith('@') ? pkgName.split('/').slice(0, 2).join('/') : pkgName.split('/')[0];
+  return deps.has(root);
 }
 
 // Human-readable label for the "Detected broken install (<reason>)" line:
@@ -107,11 +155,29 @@ function recordHealAttempt() {
   } catch { /* best-effort */ }
 }
 
+// Drop the 6h cooldown once a heal fully resolves. The marker is written BEFORE
+// spawn (rate-limits concurrent fires), but a SUCCESSFUL heal must not keep
+// blocking an unrelated later breakage that happens within the window. (#6/#9)
+function clearHealMarker() {
+  try { unlinkSync(HEAL_MARKER); } catch { /* already gone — fine */ }
+}
+
+function recordBreakage(reason) {
+  try {
+    mkdirSync(RUNTIME_DIR, { recursive: true });
+    writeFileSync(BROKEN_MARKER, JSON.stringify({ reason, ts: Date.now() }));
+  } catch { /* best-effort */ }
+}
+
+function clearBreakage() {
+  try { if (existsSync(BROKEN_MARKER)) unlinkSync(BROKEN_MARKER); } catch { /* best-effort */ }
+}
+
 async function attemptHeal(reason) {
   if (recentHealAttempt()) {
     process.stderr.write(
       `[claude-mem-lite] Self-heal skipped (last attempt < 6h ago).\n` +
-      `[claude-mem-lite] Manual recovery: claude-mem-lite repair\n` +
+      `[claude-mem-lite] Manual recovery: ${CLI_REPAIR}\n` +
       `[claude-mem-lite] If that fails, run: ${TARBALL_FALLBACK}\n`,
     );
     return false;
@@ -160,19 +226,30 @@ if (rest.includes('session-start')) {
 
 try {
   await runEntry();
+  // A clean session-start fire confirms the install is healthy → clear any stale
+  // breakage marker. Gated to session-start so the per-tool hot path pays nothing.
+  if (rest.includes('session-start')) clearBreakage();
 } catch (e) {
   if (!isLocalModuleErr(e)) throw e;
-  const healed = await attemptHeal(describeFailure(e));
+  const reason = describeFailure(e);
+  const healed = await attemptHeal(reason);
   if (!healed) {
     // Broken/missing dependency we can't repair right now (repair failed, or
     // was skipped within the 6h cooldown). attemptHeal already wrote actionable
     // guidance — degrade quietly instead of re-throwing the original import
-    // error, which would spew a Node stack trace on every hook fire.
+    // error, which would spew a Node stack trace on every hook fire. Record the
+    // breakage so the exit-0 silence stays observable to `doctor`. (#4/#8)
+    recordBreakage(reason);
     process.exit(0);
   }
   try {
     await runEntry({ bustCache: true });
+    // Fully healed: drop the cooldown so an UNRELATED later break can heal
+    // immediately (#6/#9), and clear the breakage marker.
+    clearHealMarker();
+    clearBreakage();
   } catch (retryErr) {
+    recordBreakage(`retry-failed: ${retryErr.message}`);
     process.stderr.write(
       `[claude-mem-lite] Hook still failing after self-heal: ${retryErr.message}\n` +
       `[claude-mem-lite] Manual recovery: ${TARBALL_FALLBACK}\n`,

package/server-internals.mjs

@@ -4,6 +4,7 @@
 import { debugCatch, COMPRESSED_AUTO, COMPRESSED_PENDING_PURGE, OBS_BM25 } from './utils.mjs';
 import { BASE_STOP_WORDS } from './stop-words.mjs';
 import { porterStem } from './tfidf.mjs';
+import { CLI_INVOKE } from './cli-path.mjs';
 
 // ─── MCP Server Instructions Builder ───────────────────────────────────────
 // Phase A (v2.31.3+): when quiet=true, drops WHEN-TO-USE proactive-trigger and
@@ -14,13 +15,13 @@ import { porterStem } from './tfidf.mjs';
 const INSTRUCTIONS_BASE = [
   'Long-term memory across sessions. Hooks auto-inject context; CLI preferred for explicit queries.',
   '',
-  'CLI (via Bash) — invoke as `node ~/.claude-mem-lite/cli.mjs <cmd>` (shipped with the plugin), or bare `claude-mem-lite <cmd>` only if you ran the optional global `npm i -g claude-mem-lite`:',
-  '  claude-mem-lite search "query"              — FTS5 full-text search',
-  '  claude-mem-lite search "err" --type bugfix  — filter by type',
-  '  claude-mem-lite recall "file.mjs"           — file-related memories',
-  '  claude-mem-lite recent 5                    — latest observations',
-  '  claude-mem-lite get 42,43                   — full details by ID',
-  '  claude-mem-lite timeline --anchor 42        — chronological context',
+  `CLI (via Bash) — invoke as \`${CLI_INVOKE} <cmd>\` (resolves on any install shape; the bare \`claude-mem-lite\` shorthand works only after an optional global \`npm i -g claude-mem-lite\`):`,
+  `  ${CLI_INVOKE} search "query"  — FTS5 full-text search`,
+  `  ${CLI_INVOKE} search "err" --type bugfix  — filter by type`,
+  `  ${CLI_INVOKE} recall "file.mjs"  — file-related memories`,
+  `  ${CLI_INVOKE} recent 5  — latest observations`,
+  `  ${CLI_INVOKE} get 42,43  — full details by ID`,
+  `  ${CLI_INVOKE} timeline --anchor 42  — chronological context`,
   '',
   'MCP tools: mem_search, mem_recent, mem_save, mem_get, mem_recall, mem_timeline for programmatic access (always available — no PATH/CLI install needed).',
   'mem_save: Save non-obvious insights (bugfix lessons, architecture decisions).',

package/source-files.mjs

@@ -6,7 +6,7 @@
 
 export const SOURCE_FILES = [
   // Entry points and top-level modules
-  'cli.mjs', 'server.mjs', 'server-internals.mjs', 'search-engine.mjs', 'tool-schemas.mjs',
+  'cli.mjs', 'cli-path.mjs', 'server.mjs', 'server-internals.mjs', 'search-engine.mjs', 'tool-schemas.mjs',
   'hook.mjs', 'hook-shared.mjs', 'hook-llm.mjs', 'hook-memory.mjs', 'skip-tools.mjs',
   'hook-semaphore.mjs', 'hook-episode.mjs', 'hook-context.mjs', 'hook-handoff.mjs',
   'hook-update.mjs', 'hook-optimize.mjs', 'hook-precompact.mjs',

package/tool-schemas.mjs

@@ -2,6 +2,7 @@
 // Single source of truth — used by server.mjs (runtime) and contract.test.mjs (validation tests)
 
 import { z } from 'zod';
+import { CLI_INVOKE } from './cli-path.mjs';
 
 export const OBS_TYPE_ENUM = z.enum(['decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change']);
 
@@ -349,7 +350,7 @@ export const tools = [
       '  - Looking for prior art on a module/feature before refactoring\n' +
       '  - User asks "have we seen this before" or references something not in visible context\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs search "<query>" [--type bugfix]',
+      'Equivalent CLI: ' + CLI_INVOKE + ' search "<query>" [--type bugfix]',
     inputSchema: memSearchSchema,
   },
   {
@@ -367,7 +368,7 @@ export const tools = [
       '  - User asks "what did we do yesterday / last" with no topic keyword\n' +
       '  - Verifying that a just-made change was captured as an observation\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs recent [N]',
+      'Equivalent CLI: ' + CLI_INVOKE + ' recent [N]',
     inputSchema: memRecentSchema,
   },
   {
@@ -387,7 +388,7 @@ export const tools = [
       '  - A search hit is interesting and you want its chronological neighbours\n' +
       '  - Replaying a session narrative around a known observation ID\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs timeline --anchor <ID> [--before N --after N]',
+      'Equivalent CLI: ' + CLI_INVOKE + ' timeline --anchor <ID> [--before N --after N]',
     inputSchema: memTimelineSchema,
   },
   {
@@ -407,7 +408,7 @@ export const tools = [
       '\n' +
       'On miss, response includes "Try: …" hint listing other sources the ID lives in.\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs get <id>[,<id>,...] — accepts P#/S#/# prefix.',
+      'Equivalent CLI: ' + CLI_INVOKE + ' get <id>[,<id>,...] — accepts P#/S#/# prefix.',
     inputSchema: memGetSchema,
   },
   {
@@ -425,7 +426,7 @@ export const tools = [
       '  - Cleaning up an observation saved from a test run or incorrect save\n' +
       '  - Always run once with confirm=false, then again with confirm=true\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs delete <id>[,<id>,...] [--confirm]',
+      'Equivalent CLI: ' + CLI_INVOKE + ' delete <id>[,<id>,...] [--confirm]',
     inputSchema: memDeleteSchema,
     hidden: true,
   },
@@ -444,7 +445,7 @@ export const tools = [
       '  - After a non-obvious architecture/tradeoff decision — set type="decision", lesson_learned="<constraint + why>"\n' +
       '  - User explicitly asks "remember this" or "save a note that ..."\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs save --type bugfix --lesson "..." "<content>"',
+      'Equivalent CLI: ' + CLI_INVOKE + ' save --type bugfix --lesson "..." "<content>"',
     inputSchema: memSaveSchema,
   },
   {
@@ -462,7 +463,7 @@ export const tools = [
       '  - Diagnosing why search feels sparse or noisy at a macro level\n' +
       '  - Auditing a project before major compression/maintenance\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs stats [--project X] [--days 30]',
+      'Equivalent CLI: ' + CLI_INVOKE + ' stats [--project X] [--days 30]',
     inputSchema: memStatsSchema,
     hidden: true,
   },
@@ -481,7 +482,7 @@ export const tools = [
       '  - After a major project phase completes and old per-file observations are noise\n' +
       '  - Stats show thousands of low-importance rows dragging search quality\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs compress [--execute] [--age-days 90]  (preview is default)',
+      'Equivalent CLI: ' + CLI_INVOKE + ' compress [--execute] [--age-days 90]  (preview is default)',
     inputSchema: memCompressSchema,
     hidden: true,
   },
@@ -500,7 +501,7 @@ export const tools = [
       '  - After bulk imports or a long offline period\n' +
       '  - User asks for periodic maintenance / cleanup\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs maintain scan --ops dedup,decay',
+      'Equivalent CLI: ' + CLI_INVOKE + ' maintain scan --ops dedup,decay',
     inputSchema: memMaintainSchema,
     hidden: true,
   },
@@ -519,7 +520,7 @@ export const tools = [
       '  - stats show many degraded (title-only, no lesson) observations\n' +
       '  - Start with action="preview" to see candidates before spending tokens\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs optimize [--run|--run-all] [--task re-enrich,normalize,cluster-merge,smart-compress] [--max N]  (preview is default)',
+      'Equivalent CLI: ' + CLI_INVOKE + ' optimize [--run|--run-all] [--task re-enrich,normalize,cluster-merge,smart-compress] [--max N]  (preview is default)',
     inputSchema: memOptimizeSchema,
     hidden: true,
   },
@@ -538,7 +539,7 @@ export const tools = [
       '  - Looking for a tool by capability → action="search" with keywords\n' +
       '  - User explicitly asks to import a GitHub repo → action="import_url"\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs registry <list|search|import|...> [args]',
+      'Equivalent CLI: ' + CLI_INVOKE + ' registry <list|search|import|...> [args]',
     inputSchema: memRegistrySchema,
     hidden: true,
   },
@@ -576,7 +577,7 @@ export const tools = [
       '  - You later discover additional context worth appending to lesson_learned\n' +
       '  - Reclassifying an observation after its true type becomes clear\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs update <id> [--title ...] [--lesson ...]',
+      'Equivalent CLI: ' + CLI_INVOKE + ' update <id> [--title ...] [--lesson ...]',
     inputSchema: memUpdateSchema,
     hidden: true,
   },
@@ -595,7 +596,7 @@ export const tools = [
       '  - Moving observations between machines or projects\n' +
       '  - User asks for a JSON snapshot of a project\'s memories\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs export [--format jsonl] [--project X] [--limit 500]',
+      'Equivalent CLI: ' + CLI_INVOKE + ' export [--format jsonl] [--project X] [--limit 500]',
     inputSchema: memExportSchema,
     hidden: true,
   },
@@ -614,7 +615,7 @@ export const tools = [
       '  - User asks "what do we know about <file>"\n' +
       '  - Investigating a recurring issue in a file you have not touched recently\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs recall "<file>" [--limit 10]',
+      'Equivalent CLI: ' + CLI_INVOKE + ' recall "<file>" [--limit 10]',
     inputSchema: memRecallSchema,
   },
   {
@@ -632,7 +633,7 @@ export const tools = [
       '  - After a crash, power loss, or manual DB edit\n' +
       '  - doctor / stats flags FTS integrity problems\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs fts-check [--rebuild]',
+      'Equivalent CLI: ' + CLI_INVOKE + ' fts-check [--rebuild]',
     inputSchema: memFtsCheckSchema,
     hidden: true,
   },
@@ -651,7 +652,7 @@ export const tools = [
       '  - Triaging what to compress or clean up before running maintenance\n' +
       '  - Scanning for interesting anchors to follow up with mem_timeline\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs browse [--tier active] [--project X]',
+      'Equivalent CLI: ' + CLI_INVOKE + ' browse [--tier active] [--project X]',
     inputSchema: memBrowseSchema,
     hidden: true,
   },
@@ -670,7 +671,7 @@ export const tools = [
       '  - Wrap-up phase enumerates follow-up items for the next session\n' +
       '  - Bug surfaces but root cause is out of this session\'s scope\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs defer add "<title>" [--priority 1|2|3] [--detail "..."] [--files a.mjs,b.mjs]',
+      'Equivalent CLI: ' + CLI_INVOKE + ' defer add "<title>" [--priority 1|2|3] [--detail "..."] [--files a.mjs,b.mjs]',
     inputSchema: memDeferSchema,
   },
   {
@@ -687,7 +688,7 @@ export const tools = [
       '  - About to refer to "item N" and need to confirm what N points to\n' +
       '  - Auditing carry-forward state across multiple sessions\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs defer list [--project X] [--limit 10]',
+      'Equivalent CLI: ' + CLI_INVOKE + ' defer list [--project X] [--limit 10]',
     inputSchema: memDeferListSchema,
   },
   {
@@ -705,7 +706,7 @@ export const tools = [
       '  - Scope changed and the work is no longer needed\n' +
       '  - User explicitly says "drop the deferred X, never mind"\n' +
       '\n' +
-      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs defer drop <D#N|ordinal> --reason "..."',
+      'Equivalent CLI: ' + CLI_INVOKE + ' defer drop <D#N|ordinal> --reason "..."',
     inputSchema: memDeferDropSchema,
   },
 ];