claude-mem-lite 2.78.0 → 2.79.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.78.0",
+      "version": "2.79.0",
       "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.0",
   "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

@@ -1261,6 +1261,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' : 'ies reference'} missing file(s)`);
+    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 +1501,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.0",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/scripts/setup.sh

@@ -69,11 +69,39 @@ 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. Single-line JSON for trivial parse.
+  printf '{"ts":"%s","reason":%s,"root":%s,"repair":%s}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    "\"$reason\"" \
+    "\"$ROOT\"" \
+    "\"cd '$ROOT' && npm install --omit=dev\"" \
+    > "$DEPS_FLAG" 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,10 +109,15 @@ 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.