claude-mem-lite 6.2.0 → 6.4.0

package/.claude-plugin/marketplace.json

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

package/README.md

@@ -598,7 +598,12 @@ Your data directory (`~/.claude-mem-lite/`) is untouched by install/rollback; sc
 
 ### doctor
 
-Checks Node.js version, dependencies, server/hook files, database integrity, FTS5 indexes, and stale processes.
+Checks Node.js version, dependencies, server/hook files, database integrity, FTS5 indexes,
+stale processes, MCP registration, and whether the marketplace clone can still be updated.
+
+It runs `claude mcp list` to answer the registration question, and that **health-checks every
+MCP server you have configured** — i.e. briefly launches each one, including remote endpoints.
+`status` deliberately does not: on a plugin install it answers from the manifest instead.
 
 ### status
 
@@ -617,9 +622,11 @@ claude-mem-lite repair
 **If `repair` itself fails** (the bin is older than v2.84.0, or the bin is also broken), run this one-liner — it pulls a fresh tarball into a temp dir and runs *that* tarball's `install.mjs`, bypassing every file on your disk:
 
 ```bash
-T=$(mktemp -d) && curl -sL https://api.github.com/repos/sdsrss/claude-mem-lite/tarball | tar xz -C "$T" --strip-components=1 && node "$T/install.mjs" install
+T=$(mktemp -d) && U=$(curl -sL https://api.github.com/repos/sdsrss/claude-mem-lite/releases/latest | grep -o '"tarball_url"[^,]*' | cut -d'"' -f4) && curl -sL "$U" | tar xz -C "$T" --strip-components=1 && node "$T/install.mjs" install
 ```
 
+It resolves the latest **release** tag first. A shell one-liner cannot verify the release signature the way `repair` does, so running it is a trust decision you are making explicitly — that is why it is the last resort and not the first suggestion.
+
 After it finishes, `~/.claude-mem-lite/` is back in sync with the latest release and `claude-mem-lite repair` is available for next time.
 
 ## Uninstall
@@ -643,6 +650,19 @@ Data in `~/.claude-mem-lite/` is preserved by default. Delete manually if needed
 rm -rf ~/.claude-mem-lite/
 ```
 
+**`/plugin uninstall` does not delete the plugin cache.** Claude Code materializes each
+version under `~/.claude/plugins/cache/`, with its own `node_modules`. While the plugin is
+installed these get pruned to the newest three (SessionStart does it, and so does the update
+path), so the directory is bounded — measured at 241 MB — not unbounded. But `/plugin
+uninstall` removes the manifest and there is no uninstall hook a plugin can attach to, so the
+hooks stop firing and whatever is left is never reclaimed. `claude-mem-lite uninstall` does
+reclaim it, but after `/plugin uninstall` that command may no longer be on your PATH. Either
+run it **first**, or delete the directory yourself:
+
+```bash
+rm -rf ~/.claude/plugins/cache/sdsrss/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.

package/README.zh-CN.md

@@ -478,7 +478,11 @@ npx claude-mem-lite doctor            # 诊断问题
 
 ### doctor
 
-检查 Node.js 版本、依赖、服务器/钩子文件、数据库完整性、FTS5 索引和残留进程。
+检查 Node.js 版本、依赖、服务器/钩子文件、数据库完整性、FTS5 索引、残留进程、MCP 注册状态，
+以及 marketplace clone 是否还能被更新。
+
+它用 `claude mcp list` 回答注册状态那一问，而这会**对你配置的每个 MCP server 做健康检查**——
+也就是逐个短暂启动，包括远程 endpoint。`status` 刻意不这么做：插件形态下它从 manifest 回答。
 
 ### status
 
@@ -497,9 +501,11 @@ claude-mem-lite repair
 **如果 `repair` 自己也跑不起来**（bin 比 v2.84.0 旧，或 bin 也坏了），用这条单行命令——它把最新 tarball 拉到临时目录、跑 *那份* tarball 里的 `install.mjs`，完全不依赖你磁盘上的任何文件：
 
 ```bash
-T=$(mktemp -d) && curl -sL https://api.github.com/repos/sdsrss/claude-mem-lite/tarball | tar xz -C "$T" --strip-components=1 && node "$T/install.mjs" install
+T=$(mktemp -d) && U=$(curl -sL https://api.github.com/repos/sdsrss/claude-mem-lite/releases/latest | grep -o '"tarball_url"[^,]*' | cut -d'"' -f4) && curl -sL "$U" | tar xz -C "$T" --strip-components=1 && node "$T/install.mjs" install
 ```
 
+它会先解析出最新 **release** 的 tag。shell 单行命令无法像 `repair` 那样校验 release 签名，所以跑它等于你自己做了一次信任决定——这也是它排在最后、而不是被优先推荐的原因。
+
 跑完之后，`~/.claude-mem-lite/` 就和最新 release 对齐，`claude-mem-lite repair` 下次再遇到类似问题也能直接用了。
 
 ## 卸载
@@ -523,6 +529,17 @@ npx claude-mem-lite uninstall --purge
 rm -rf ~/.claude-mem-lite/
 ```
 
+**`/plugin uninstall` 不会删 plugin cache。** Claude Code 会把每个版本展开到
+`~/.claude/plugins/cache/` 下，各带一份 `node_modules`。插件还装着的时候，这些会被裁剪到最新
+三个版本（SessionStart 会做，更新路径也会做），所以这个目录是有上限的——实测 241 MB——而不是无限
+增长。但 `/plugin uninstall` 只移除 manifest，插件又没有可挂的卸载生命周期钩子，于是钩子停止触发，
+剩下的东西再也没人回收。`claude-mem-lite uninstall` 能回收它，但 `/plugin uninstall` 之后这个命令
+可能已经不在 PATH 上了。所以要么**先**跑它，要么自己删：
+
+```bash
+rm -rf ~/.claude/plugins/cache/sdsrss/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/` → 每次会话报错。

package/hook-shared.mjs

@@ -22,6 +22,12 @@ import { resolveRuntimeDir } from './lib/resolve-data-dir.mjs';
 // Pure-`node:`/local module (it imports only binding-probe + native-binding-hint, and
 // neither imports this file) — no cycle.
 import { recordHookError } from './lib/hook-telemetry.mjs';
+import {
+  isSchemaSkewError,
+  schemaSkewFromError,
+  shouldRecordSkew,
+  SKEW_MARKER_PREFIX,
+} from './lib/schema-skew.mjs';
 // Audit 2026-09-05 P1-2 (carried from 2026-09-02 P2-9): `callLLM`, the quiet/adoption
 // predicates and the handoff constants moved into `lib/` because two lib modules
 // imported them from here and dragged this file's whole import graph — haiku-client,
@@ -237,6 +243,7 @@ export const GC_PROJECT_MARKER_PREFIXES = Object.freeze([
   // forever. `.skill-cooldown-` / `.skill-reco-cooldown-` left with the skill registry in
   // v5.0.0; a prefix for files nothing writes any more is dead weight in a hot-path loop.
   'last-mark-compressible-', // per-project auto-compress 24h gate
+  SKEW_MARKER_PREFIX, // per-project schema-skew log dedup; regenerated on the next skewed open
 ]);
 
 // Records of a completed side effect — never age out. `ep-`/`ep-flush-`/
@@ -382,12 +389,58 @@ export function createSessionId() {
 
 // ─── Database ────────────────────────────────────────────────────────────────
 
+// Last forward-incompat ("the DB is newer than me") failure seen in THIS process, or null.
+// SessionStart needs the two version numbers to render its notice and openDb has just been
+// handed them, so this beats a second DB open — and on a skew there may be no working
+// binding to open with anyway.
+let lastSkew = null;
+
+/**
+ * The schema skew that made the most recent openDb() return null, or null.
+ * Cleared by any successful open, so a heal mid-session stops the notice.
+ *
+ * @returns {{dbVersion: number|null, binaryVersion: number|null}|null}
+ */
+export function lastSchemaSkew() {
+  return lastSkew;
+}
+
 export function openDb() {
   try {
     // WAL-corruption self-heal (was server.mjs-only): without it, hooks stayed
     // silently dead (null DB) on a corrupt WAL until the next MCP server start.
-    return ensureDbWithWalRecovery();
+    const db = ensureDbWithWalRecovery();
+    lastSkew = null;
+    return db;
   } catch (e) {
+    // Forward-incompat is its own family: it cannot be healed by anything this process can
+    // do, it repeats on every single open, and it is the one failure the USER has to act on.
+    // Record it once and hand the numbers to SessionStart, which is the surface that speaks.
+    // Forward-incompat is its own family: nothing this process can do heals it, it repeats on
+    // every single open, and it is the one failure the USER has to act on. Dedup lives in
+    // lib/schema-skew.mjs so the `ups` face — which opens the DB itself and logged its own 15
+    // of the day's 727 lines — shares one implementation instead of drifting from this one.
+    //
+    // shouldRecordSkew is TOTAL by contract. Nothing in this catch may throw: the first cut
+    // called getSessionId() here, which MINTS and writes a session id, so an unwritable
+    // runtime dir turned openDb() itself into a thrower. All 13 call sites are written to
+    // no-op on null and none of them expects an exception.
+    if (isSchemaSkewError(e)) {
+      lastSkew = schemaSkewFromError(e) || { dbVersion: null, binaryVersion: null };
+      // Guarded even though inferProject() reads env and cwd: "the only statement in this
+      // catch cannot throw" was true of the original one-line body and stopped being true
+      // the moment anything was added. An unscoped marker is a worse dedup, not a crash.
+      let project = '';
+      try {
+        project = inferProject();
+      } catch {
+        /* total: the marker degrades to one shared file */
+      }
+      if (shouldRecordSkew(RUNTIME_DIR, project, lastSkew)) {
+        recordHookError('hook-shared:db-open', e, RUNTIME_DIR);
+      }
+      return null;
+    }
     // Still null, still no throw — a hook must never crash the host session, and all
     // eight call sites in hook.mjs are written to no-op on null. But "returned null"
     // used to be the ONLY trace: nothing reached runtime/hook-errors/, so `stats`

package/hook-update.mjs

@@ -20,7 +20,12 @@ import {
 import { join, dirname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { tmpdir, homedir } from 'node:os';
-import { DB_DIR, CODE_DIR } from './schema.mjs';
+// lib/data-paths.mjs, NOT schema.mjs: this module is what install.mjs::repair() imports to
+// reach the signature-verified release path, and schema.mjs statically imports
+// better-sqlite3 — so importing two path constants from there made the verified repair
+// unreachable on exactly the broken-install state it exists to repair (2026-09-08).
+// tests/repair-path-no-native-dep.test.mjs fails on any package edge reachable from here.
+import { DB_DIR, CODE_DIR } from './lib/data-paths.mjs';
 import { debugCatch, debugLog } from './utils.mjs';
 import { NATIVE_BINDING_SOURCE_BUILD_CMD } from './lib/binding-probe.mjs';
 // Local manifest is fallback only — the active manifest is loaded from the
@@ -228,7 +233,11 @@ function isPluginMode() {
 }
 
 // ── Dev Mode Detection ─────────────────────────────────────
-function isDevMode() {
+// Exported since the schema-skew notice needs it: a dev checkout must be told `git pull`,
+// never a command that would overwrite its working tree. Re-implementing the check at the
+// call site would make it the second copy of a predicate this file has already had to get
+// right twice (whole-dir symlink, then per-file drift) — the twin-drift class.
+export function isDevMode() {
   try {
     // A dev checkout always carries a .git dir. This catches a whole-directory
     // symlink (~/.claude-mem-lite -> /repo): lstat on server.mjs there follows the

package/hook.mjs

@@ -60,7 +60,9 @@ import {
   episodeHasSignificantContent,
   explainSignificance,
 } from './hook-episode.mjs';
-import { DB_DIR } from './schema.mjs';
+// CODE_DIR, not DB_DIR: the schema-skew notice asks which CODE homes exist, and those are
+// always homedir-rooted even when CLAUDE_MEM_DIR relocates the data.
+import { DB_DIR, CODE_DIR } from './schema.mjs';
 import { cleanupClaudeMdLegacyBlock, buildSessionContextLines } from './hook-context.mjs';
 import { entry as preCompactEntry } from './hook-precompact.mjs';
 import {
@@ -82,6 +84,7 @@ import {
   spawnBackground,
   sweepOrphanEpisodeFiles,
   sweepStaleProjectMarkers,
+  lastSchemaSkew,
 } from './hook-shared.mjs';
 import { handleLLMEpisode, handleLLMSummary, saveEpisodeImmediate } from './hook-llm.mjs';
 import { readFastSummarySource, insertFastSummary, FAST_SUMMARY_LIMITS } from './lib/fast-summary.mjs';
@@ -2290,6 +2293,67 @@ async function buildStartupDashboardText(db, project) {
   }
 }
 
+/**
+ * Tell the user their memory is version-skewed, on the one surface they read.
+ *
+ * Only fires when openDb() failed for THIS reason — hook-shared records the two version
+ * numbers as it catches, so nothing is re-derived and no second DB open is attempted (on a
+ * skew there may be no usable binding to open with).
+ *
+ * Everything is dynamically imported: this is a cold path that must not cost the healthy
+ * SessionStart an install-shape scan. And it goes through the queue helpers, never a bare
+ * console.log — SessionStart merges three would-be stdout contributors into ONE envelope,
+ * and writing raw prose alongside it once made the host deliver the whole JSON object to
+ * the model as literal text (tests/session-start-stdout-envelope.test.mjs).
+ */
+async function emitSchemaSkewNotice() {
+  try {
+    const skew = lastSchemaSkew();
+    if (!skew) return;
+    const [shapeMod, updateMod, skewMod] = await Promise.all([
+      import('./lib/install-shape.mjs'),
+      import('./hook-update.mjs'),
+      import('./lib/schema-skew.mjs'),
+    ]);
+    const shape = shapeMod.detectInstallShape({ installDir: CODE_DIR });
+    // WHICH tree is running this hook, not which trees exist. CLAUDE_PLUGIN_ROOT is set in
+    // every hook process Claude Code spawns, so on a machine holding BOTH a managed install
+    // and a plugin cache it is the only thing that knows which one is behind. Deciding from
+    // the machine's global shape printed `claude-mem-lite self-update` beneath a line naming
+    // the plugin cache — a repair that cannot advance the tree it had just named.
+    const runningRoot = process.env.CLAUDE_PLUGIN_ROOT || CODE_DIR;
+    const remedy = skewMod.schemaSkewRemedy({
+      managed: shape.managed,
+      activePluginVersion: shape.activePluginVersion,
+      dev: updateMod.isDevMode(),
+      root: runningRoot,
+    });
+    const notice = skewMod.formatSchemaSkewNotice({
+      dbVersion: skew.dbVersion,
+      binaryVersion: skew.binaryVersion,
+      remedy,
+      // Name the home only when the remedy is about that home, so the two can never disagree.
+      codeHome:
+        remedy.kind === 'plugin' && shape.activePluginVersion
+          ? `plugin cache v${shape.activePluginVersion.version}`
+          : undefined,
+    });
+    // BOTH channels, and the HUMAN one is the point. queueHookContext reaches the model;
+    // lib/hook-stdout.mjs's queueHookSystemMessage is documented "for the HUMAN, not the
+    // model" and names v3.70.0 for making exactly this mistake — folding a banner into
+    // additionalContext "kept its content and lost its audience". A notice whose whole job is
+    // to hand the user a command must not depend on the assistant volunteering it.
+    // flushHookStdout merges both into one envelope, so this is additive: the model learns
+    // memory is unavailable, the user gets the repair.
+    queueHookSystemMessage(notice);
+    queueHookContext('SessionStart', notice);
+  } catch (e) {
+    // A hook must never crash the host session, and a notice that cannot render is still
+    // better handled by staying quiet than by taking SessionStart down with it.
+    debugCatch(e, 'session-start-schema-skew');
+  }
+}
+
 async function handleSessionStart() {
   // GC stale per-session cooldown files. Cheap (<5ms typical) and idempotent;
   // moved here from pre-tool-recall.js's hot path.
@@ -2471,7 +2535,16 @@ async function handleSessionStart() {
   const project = inferProject();
 
   const db = openDb();
-  if (!db) return;
+  if (!db) {
+    // A null DB used to end SessionStart in total silence. For most causes that is right —
+    // they are transient, or a repair path is already running. Forward-incompat is neither:
+    // it persists until the user installs newer code, it disables every write path, and the
+    // only other signal it produces is a `-32000 Connection closed` from the MCP host, which
+    // names nothing. Measured 2026-09-08: a whole day of it, >=648 log lines, zero words to
+    // the user. This is the surface the user actually reads.
+    await emitSchemaSkewNotice();
+    return;
+  }
 
   try {
     const now = new Date();