claude-mem-lite 2.78.0 → 2.79.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.78.0",
+      "version": "2.79.1",
       "source": "./",
       "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.78.0",
+  "version": "2.79.1",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -138,6 +138,8 @@ The original sends **everything to the LLM and hopes it filters well**. claude-m
 
 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.
 
+> **First session per project: run `/adopt` once.** Plugin install gives you the MCP server + hooks + slash commands, but the **invited-memory sentinel** (a system-authority pointer that boosts Claude's proactive use of `mem_recall` / `mem_save`) is opt-in and project-scoped. Without it the hooks still record observations and inject context, but Claude is far less likely to call the MCP tools on its own. One-time per project: `/adopt`. Remove with `/unadopt`.
+
 ### Method 2: npx (one-liner)
 
 ```bash
@@ -511,6 +513,14 @@ Data in `~/.claude-mem-lite/` is preserved by default. Delete manually if needed
 rm -rf ~/.claude-mem-lite/
 ```
 
+### Mixed-install residue (read this if you've used multiple install methods)
+
+`/plugin uninstall` only removes the plugin manifest — it **does not touch `~/.claude/settings.json`**. If you've ever run `claude-mem-lite install` (npx or git-clone path), hook entries pointing at `~/.claude-mem-lite/hook.mjs` were written into your user-global settings, and they keep firing after `/plugin uninstall`. If `~/.claude-mem-lite/hook.mjs` still exists they double-fire alongside the plugin; if you also ran `rm -rf ~/.claude-mem-lite/` they error every session.
+
+**The safe sequence is**: run `claude-mem-lite uninstall` first (which cleans the settings.json hooks plus the global MCP registration), then `/plugin uninstall claude-mem-lite`, then optionally `rm -rf ~/.claude-mem-lite/`.
+
+If you already uninstalled in the wrong order, `claude-mem-lite doctor` flags orphan hooks under `Orphan hooks:` with the exact cleanup command.
+
 ## Project Structure
 
 ```

package/README.zh-CN.md

@@ -147,6 +147,8 @@ node install.mjs install
 
 1. **安装依赖** -- `npm install --omit=dev`（编译原生 `better-sqlite3`）
 2. **注册 MCP 服务器** -- `mem-lite` 服务器，包含 15 个工具（search、recent、recall、timeline、get、save、update、stats、delete、compress、maintain、export、fts_check、browse、registry）。v2.78 前服务器名为通用的 `mem`，现已改名为 `mem-lite` 避免与用户其它 `.mcp.json` 冲突；工具名（`mem_search`/`mem_recall` 等）保持不变。
+
+> **每个项目第一次使用，跑一次 `/adopt`。** Plugin 安装给你 MCP server + hooks + slash commands，但**邀请式 memory 哨兵**（一条提升 Claude 主动调用 `mem_recall` / `mem_save` 的 system-authority 指针）是按项目 opt-in 的。不跑 `/adopt` 时 hooks 仍记录观察、注入上下文，但 Claude 不太会主动调 MCP 工具。一次性、按项目：`/adopt`；撤销 `/unadopt`。
 3. **配置钩子** -- `PostToolUse`、`PreToolUse`、`SessionStart`、`Stop`、`UserPromptSubmit` 生命周期钩子
 4. **创建数据目录** -- `~/.claude-mem-lite/`（隐藏目录），存放数据库、运行时和托管资源文件
 5. **自动迁移** -- 自动检测 `~/.claude-mem/`（原版 claude-mem）或 `~/claude-mem-lite/`（v0.5 前的非隐藏目录），将数据库和运行时文件迁移到 `~/.claude-mem-lite/`，原目录保持不变
@@ -474,6 +476,14 @@ npx claude-mem-lite uninstall --purge
 rm -rf ~/.claude-mem-lite/
 ```
 
+### 混装残留（用过多种安装方式的话务必看一下）
+
+`/plugin uninstall` 只删 plugin manifest，**不会动 `~/.claude/settings.json`**。如果你曾经跑过 `claude-mem-lite install`（npx 或 git-clone 路径），指向 `~/.claude-mem-lite/hook.mjs` 的 hook 条目就被写进了你的 user-global settings；`/plugin uninstall` 之后它们还在每会话触发。如果 `~/.claude-mem-lite/hook.mjs` 还在 → 与 plugin 双触发；如果你又 `rm -rf ~/.claude-mem-lite/` → 每次会话报错。
+
+**正确顺序**：先 `claude-mem-lite uninstall`（清 settings.json 的 hook + 全局 MCP 注册），再 `/plugin uninstall claude-mem-lite`，最后可选 `rm -rf ~/.claude-mem-lite/`。
+
+顺序搞错了的话，`claude-mem-lite doctor` 会在 `Orphan hooks:` 一节标出残留并给清理命令。
+
 ## 项目结构
 
 ```

package/hook.mjs

@@ -20,7 +20,7 @@
 
 import { randomUUID } from 'crypto';
 import { join } from 'path';
-import { readFileSync, writeFileSync, unlinkSync, readdirSync, renameSync, statSync } from 'fs';
+import { readFileSync, writeFileSync, unlinkSync, readdirSync, renameSync, statSync, existsSync } from 'fs';
 import { homedir } from 'os';
 import {
   truncate, inferProject, detectBashSignificance,
@@ -1115,6 +1115,33 @@ async function handleSessionStart() {
       if (citeNudge) {
         dashboardText = dashboardText ? `${citeNudge}\n${dashboardText}` : citeNudge;
       }
+      // v2.79: surface setup.sh dependency-install failure as a high-visibility
+      // line at the very top of the dashboard. setup.sh writes runtime/.deps-broken
+      // (JSON: ts/reason/root/repair) on failure and removes it on success — so
+      // a stale flag self-heals on the next clean SessionStart. Without this
+      // surface, hook degradation looks identical to "nothing happening" until
+      // the user notices missing context days later.
+      try {
+        const depsFlag = join(RUNTIME_DIR, '.deps-broken');
+        if (existsSync(depsFlag)) {
+          let detail = 'unknown';
+          let repair = '';
+          try {
+            const raw = readFileSync(depsFlag, 'utf8').trim();
+            const parsed = JSON.parse(raw);
+            detail = parsed.reason || detail;
+            repair = parsed.repair || '';
+          } catch { /* corrupt flag — surface the fact only */ }
+          const nudgeLines = [
+            '⚠️ [claude-mem-lite] Hook dependencies failed to install on the last SessionStart.',
+            `   Reason: ${detail}`,
+          ];
+          if (repair) nudgeLines.push(`   Repair: ${repair}`);
+          nudgeLines.push('   Until fixed, PreToolUse / PostToolUse / memory injection are degraded.');
+          const nudge = nudgeLines.join('\n');
+          dashboardText = dashboardText ? `${nudge}\n${dashboardText}` : nudge;
+        }
+      } catch (e) { debugCatch(e, 'session-start-deps-flag'); }
       if (dashboardText) {
         process.stdout.write(JSON.stringify({
           suppressOutput: true,

package/install.mjs

@@ -1086,8 +1086,12 @@ async function status() {
     // Accept either the current "mem-lite" registration or the legacy "mem"
     // name (pre-v2.78) so a user mid-upgrade still sees a green status until
     // setup.sh / install.mjs purges the legacy entry on next run.
-    const registered = list.includes('mem-lite:') || list.includes('mem-lite ')
-      || list.includes('mem:') || /\bmem\b\s/.test(list);
+    // v2.79.1: dropped a `/\bmem\b\s/` fallback regex — the `\b` word boundary
+    // also matched "mem-lite" (because `-` is a non-word char), so the regex
+    // was always-true noise (benign only because the mem-lite checks short-
+    // circuited first). `claude mcp list` formats as `<name>: <command>`, so
+    // the two colon-form checks below cover every shape.
+    const registered = list.includes('mem-lite:') || list.includes('mem:');
     push(registered ? 'ok' : 'fail', 'mcp', registered ? 'MCP server: registered' : 'MCP server: not registered', { registered });
   } catch {
     push('warn', 'mcp', 'Could not check MCP status', { registered: null });
@@ -1261,6 +1265,24 @@ async function doctor() {
     dwarn('Plugin lifecycle: hooks not configured');
   }
 
+  // Orphan hooks: settings.json entries referencing hook files that no longer
+  // exist on disk. Trips when a user runs `/plugin uninstall` and/or
+  // `rm -rf ~/.claude-mem-lite/` without first running `claude-mem-lite uninstall`
+  // (which clears the settings.json entries). The hooks keep firing and exit
+  // with require-error noise every session. README's Uninstall section warns
+  // about the right ordering; this check flags the broken state so it surfaces
+  // even when the user skipped the README.
+  const orphanPaths = collectOrphanHookPaths(settings);
+  if (orphanPaths.length > 0) {
+    fail(`Orphan hooks: ${orphanPaths.length} settings.json entr${orphanPaths.length === 1 ? 'y references a missing file' : 'ies reference missing files'}`);
+    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`);
+    issues++;
+  } else if (hasHooks) {
+    ok('Orphan hooks: none (all hook targets present)');
+  }
+
   // Database
   if (existsSync(DB_PATH)) {
     try {
@@ -1483,6 +1505,48 @@ function hasMemHooksConfigured(settings) {
   );
 }
 
+/**
+ * Walk every mem-hook command in settings.json and collect any absolute file
+ * paths that don't currently exist on disk. Used by doctor() to surface
+ * post-uninstall residue ("/plugin uninstall claude-mem-lite" leaves
+ * settings.json hooks pointing at ~/.claude-mem-lite/hook.mjs; if the user
+ * then deleted that directory, every session start dispatches to a missing
+ * file).
+ *
+ * Path extraction: command strings look like:
+ *   node "/home/sds/.claude-mem-lite/hook.mjs" session-start
+ *   bash "/home/sds/.claude-mem-lite/scripts/post-tool-use.sh"
+ *   node "/home/sds/.claude-mem-lite/scripts/pre-tool-recall.js"
+ * We pick the first quoted absolute path; if there is no quoted token we fall
+ * back to the first whitespace-delimited absolute-looking token after the
+ * interpreter. ${CLAUDE_PLUGIN_ROOT}-templated commands are ignored — those
+ * are plugin-owned hooks resolved by Claude Code at runtime, not by us.
+ */
+export function collectOrphanHookPaths(settings) {
+  if (!settings?.hooks) return [];
+  const out = [];
+  for (const configs of Object.values(settings.hooks)) {
+    if (!Array.isArray(configs)) continue;
+    for (const cfg of configs) {
+      if (!isMemHook(cfg)) continue;
+      for (const h of cfg.hooks || []) {
+        const cmd = h.command || '';
+        if (cmd.includes('${CLAUDE_PLUGIN_ROOT}')) continue;
+        const quoted = cmd.match(/"([^"]+)"/);
+        let path = quoted ? quoted[1] : null;
+        if (!path) {
+          // unquoted: split on whitespace, take the first arg that looks like an absolute path
+          const parts = cmd.split(/\s+/);
+          path = parts.find(p => p.startsWith('/') && (p.endsWith('.mjs') || p.endsWith('.js') || p.endsWith('.sh'))) || null;
+        }
+        if (!path) continue;
+        if (!existsSync(path) && !out.includes(path)) out.push(path);
+      }
+    }
+  }
+  return out;
+}
+
 /**
  * v2.48 P1-4: prune top-level stale files left behind by removed-module upgrades.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.78.0",
+  "version": "2.79.1",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/scripts/setup.sh

@@ -69,11 +69,46 @@ mkdir -p "$DATA_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
+#
+# Visibility contract: `npm install` failure here used to be a stderr-only log_warn,
+# invisible to the Claude session unless the operator was watching the terminal.
+# When it fails (no toolchain, blocked network, read-only FS) every hook silently
+# degrades — pre-tool-recall, post-tool-use, session-start all import better-sqlite3
+# 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
+
+mark_deps_broken() {
+  local reason="$1"
+  # Embed reason + repair command so hook.mjs renders a complete error without
+  # having to re-derive them. Delegate JSON serialization to node so embedded
+  # quotes / shell metachars in $ROOT or $reason can't produce an invalid file
+  # (bash `printf '"..%s.."'` cannot escape arbitrary strings safely; v2.79 fix).
+  MARK_REASON="$reason" MARK_ROOT="$ROOT" MARK_FLAG="$DEPS_FLAG" node -e '
+    const fs = require("fs");
+    const reason = process.env.MARK_REASON || "unknown";
+    const root = process.env.MARK_ROOT || "";
+    fs.writeFileSync(process.env.MARK_FLAG, JSON.stringify({
+      ts: new Date().toISOString(),
+      reason,
+      root,
+      repair: `cd ${JSON.stringify(root)} && npm install --omit=dev`,
+    }) + "\n");
+  ' 2>/dev/null || true
+}
+
+mark_deps_ok() {
+  rm -f "$DEPS_FLAG" 2>/dev/null || true
+}
+
 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"
+      mark_deps_ok
     fi
   fi
   # Slow path: npm install (first-time only, ~10-20s for native addon)
@@ -81,24 +116,31 @@ if [[ ! -d "$ROOT/node_modules/better-sqlite3" ]]; then
     log_info "Installing dependencies (first-time setup)..."
     if (cd "$ROOT" && npm install --omit=dev --no-audit --no-fund 2>&1) >&2; then
       log_ok "Dependencies installed"
+      mark_deps_ok
     else
-      log_warn "Dependency install failed — hooks may have limited functionality"
+      log_warn "Dependency install failed — hooks may have limited functionality (flag: $DEPS_FLAG)"
+      mark_deps_broken "npm install --omit=dev failed in plugin cache root"
     fi
   fi
+else
+  # Deps already present — make sure we don't keep stale broken flag around
+  mark_deps_ok
 fi
 
-# 7. MCP cleanup: idempotently clean stale registrations from older installs.
-#    This runs on every plugin SessionStart because old global entries may still
-#    exist even after an earlier migration marker was written.
+# 7. MCP cleanup: one-shot purge of stale global MCP registrations.
 #    - Pre-2.10: direct installs left a global "mem" MCP alongside plugin MCP.
 #    - Pre-2.78: plugin and global registrations used the generic name "mem";
 #      v2.78 renamed to "mem-lite" — any stale global "mem" must be purged so
 #      Claude Code doesn't surface duplicate (old "mem" + new "mem-lite") tool
 #      prefixes side-by-side.
 #    Root .mcp.json in the installed plugin cache is required for Claude Code to
-#    register plugin MCP; only stale global/marketplace copies should be removed.
+#    register plugin MCP; only stale global/marketplace copies are removed.
+#    v2.79.1: marker file now actually gates entry (was touched but never read
+#    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"
-if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
+if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" && ! -f "$MCP_MIGRATION" ]]; then
   CLAUDE_JSON="$HOME/.claude.json" node -e '
     const fs = require("fs");
     let changed = false;

package/server.mjs

@@ -2272,6 +2272,12 @@ process.on('unhandledRejection', (err) => { debugCatch(err, 'unhandledRejection'
 // server in one Claude Code session). Two records with close timestamps and
 // the same ppid is the smoking gun. Never throws — telemetry must not block
 // startup. Disable with MEM_DISABLE_SPAWN_LOG=1.
+//
+// File mode: no explicit chmod. Payload is `{ts, pid, ppid, argv1, version}` —
+// no secrets, no project content. Pre-v2.79.1 passed `{mode: 0o600}` to
+// appendFileSync but that only applies on file creation (umask-default after
+// the first append), so the "0600" claim was misleading honesty-wise. Honest
+// comment > misleading code.
 if (process.env.MEM_DISABLE_SPAWN_LOG !== '1') {
   try {
     if (!existsSync(RUNTIME_DIR)) mkdirSync(RUNTIME_DIR, { recursive: true });
@@ -2282,7 +2288,7 @@ if (process.env.MEM_DISABLE_SPAWN_LOG !== '1') {
       argv1: process.argv[1] || '',
       version: PKG_VERSION,
     }) + '\n';
-    appendFileSync(join(RUNTIME_DIR, 'mcp-spawns.log'), line, { mode: 0o600 });
+    appendFileSync(join(RUNTIME_DIR, 'mcp-spawns.log'), line);
   } catch { /* never block startup on telemetry failure */ }
 }