claude-mem-lite 6.1.0 → 6.2.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.1.0",
+      "version": "6.2.0",
       "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": "6.1.0",
+  "version": "6.2.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

@@ -134,16 +134,23 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 
 | Platform | Status | Notes |
 |----------|--------|-------|
-| **Linux** | Supported | Primary development and testing platform |
+| **Linux** | Supported | Primary development and testing platform; the whole CI matrix runs here |
 | **macOS** | Supported | Fully compatible (Intel and Apple Silicon) |
-| **Windows** | Not supported | Uses POSIX shell scripts (`post-tool-use.sh`, `setup.sh`) and Unix file locking; WSL2 may work but is untested |
+| **Windows** | Installs, not CI-covered | The MCP server, the CLI and the `node` hooks work (`better-sqlite3` ships `win32-x64` and `win32-arm64` prebuilds, so nothing is compiled). **Three hook commands run under `bash`** — `setup.sh`, `post-tool-use.sh`, `pre-agent-inject.sh` — and need Git for Windows or WSL on `PATH`; `claude-mem-lite doctor` reports it when `bash` cannot be found. No GitHub Actions runner exercises Windows, so this rests on user reports ([#28](https://github.com/sdsrss/claude-mem-lite/issues/28)), not on a green pipeline |
+| **WSL2** | Untested | Linux under the hood, so it should behave as the Linux row; nobody has reported either way |
+
+From v5.1.0 through v6.1.0, `package.json` declared `os: ["darwin", "linux"]`. That is an npm *install*
+gate, not a runtime check: on Windows it made `npm install` exit `EBADPLATFORM`, which the
+plugin launcher runs on the first MCP start after every plugin update — so the server never
+came up and `/mcp` reported `CONNECTION_CLOSED`. `win32` is now in the list. A platform that
+is still outside it gets a message naming both sides of the mismatch instead of a guess.
 
 ## Requirements
 
 - **Node.js** >= 22
 - **Claude Code** CLI installed and configured (`claude` command available)
-- **SQLite3** support (provided by `better-sqlite3`, compiled on install)
-- **Platform**: Linux or macOS (see [Platform Support](#platform-support))
+- **SQLite3** support (provided by `better-sqlite3` 13, which ships prebuilt binaries for 8 platforms — no compiler needed on any of them; a platform it has no prebuild for falls back to building from source)
+- **Platform**: Linux or macOS; Windows installs and runs but is not CI-covered and needs Git Bash or WSL for three hooks (see [Platform Support](#platform-support))
 
 ## Installation
 

package/README.zh-CN.md

@@ -100,16 +100,22 @@
 
 | 平台 | 状态 | 说明 |
 |------|------|------|
-| **Linux** | 支持 | 主要开发和测试平台 |
+| **Linux** | 支持 | 主要开发和测试平台；整个 CI 矩阵都跑在这里 |
 | **macOS** | 支持 | 完全兼容（Intel 和 Apple Silicon） |
-| **Windows** | 暂不支持 | 使用 POSIX shell 脚本（`post-tool-use.sh`、`setup.sh`）和 Unix 文件锁；WSL2 可能可用但未经测试 |
+| **Windows** | 可安装，但无 CI 覆盖 | MCP server、CLI 和 `node` 类 hook 均可用（`better-sqlite3` 自带 `win32-x64` / `win32-arm64` 预编译产物，无需编译）。**有三个 hook 命令走 `bash`** —— `setup.sh`、`post-tool-use.sh`、`pre-agent-inject.sh` —— 需要 PATH 上有 Git for Windows 或 WSL；`bash` 找不到时 `claude-mem-lite doctor` 会报出来。GitHub Actions 没有 Windows runner，所以这一行依据的是用户报告（[#28](https://github.com/sdsrss/claude-mem-lite/issues/28)）而不是绿色流水线 |
+| **WSL2** | 未测试 | 底层就是 Linux，预期与 Linux 行一致；但无人报告过实际结果 |
+
+v5.1.0 到 v6.1.0 之间，`package.json` 声明的是 `os: ["darwin", "linux"]`。那是 npm 的**安装**门禁，不是运行时检查：
+在 Windows 上它让 `npm install` 以 `EBADPLATFORM` 退出，而插件启动器每次插件更新后的首次 MCP 启动都要跑这条
+安装 —— 于是 server 起不来，`/mcp` 报 `CONNECTION_CLOSED`。现在 `win32` 已加入该列表。仍不在列表内的平台会拿到
+一条同时点明“声明了什么”和“当前是什么”的消息，而不是一句猜测。
 
 ## 环境要求
 
 - **Node.js** >= 22（v4.0.0 起：better-sqlite3 13 要求 >=22，Node 20 已于 2026-04 EOL；`package.json` 的 `engines` 是唯一事实来源）
 - **Claude Code** CLI 已安装并配置（`claude` 命令可用）
-- **SQLite3** 支持（由 `better-sqlite3` 提供，安装时编译）
-- **平台**：Linux 或 macOS（参见[平台支持](#平台支持)）
+- **SQLite3** 支持（由 `better-sqlite3` 13 提供，它自带 8 个平台的预编译产物，这些平台上都不需要编译器；没有对应预编译产物的平台才会回退到源码编译）
+- **平台**：Linux 或 macOS；Windows 可安装运行，但无 CI 覆盖，且三个 hook 需要 Git Bash 或 WSL（参见[平台支持](#平台支持)）
 
 ## 安装
 

package/install.mjs

@@ -61,6 +61,7 @@ import {
   scanPluginCacheHookPollution,
   hasInstallManagedHooks,
   pluginCacheHookEvents,
+  settingsHookCommands,
 } from './plugin-cache-guard.mjs';
 import { SOURCE_FILES, HOOK_SCRIPT_FILES } from './source-files.mjs';
 import {
@@ -266,6 +267,59 @@ export function buildDoctorSummary(issues, warnings) {
   return `${issues} issue(s) found.${warnSuffix}`;
 }
 
+/**
+ * How many LIVE hook commands invoke `bash`, and which scripts they are.
+ *
+ * There are two hook registrations and only one is live per install shape, which is what
+ * the first cut of doctor's interpreter check got wrong (pre-ship review P1-1). The plugin
+ * shape reads `hooks/hooks.json` out of the plugin cache. The npm / npx / `git clone` shape
+ * has no such file — `hooks/hooks.json` is in RELEASE_SIGNED_FILES but NOT in SOURCE_FILES,
+ * so nothing deploys it to ~/.claude-mem-lite/ — and registers its hooks in settings.json
+ * instead. Reading only the manifest therefore answered "zero bash hooks" on the one shape
+ * where two of them are live.
+ *
+ * Returns THREE outcomes, never two. `count: null` means no registration could be read, and
+ * that is deliberately distinct from a count of zero: zero is an answer, null is the absence
+ * of one, and a diagnostic that reports them identically tells the reader to stop looking.
+ *
+ * @param {{manifestPath: string, settingsCommands?: string[], installDir: string}} opts
+ * @returns {{count: number|null, source: 'manifest'|'settings'|null, scripts: string[]}}
+ */
+export function resolveBashHookCount({ manifestPath, settingsCommands = [], installDir }) {
+  const basenames = (commands) =>
+    commands
+      .map((c) => {
+        const m = c.match(/([^/"\s]+\.sh)/);
+        return m ? m[1] : c;
+      })
+      .sort();
+
+  if (existsSync(manifestPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      const commands = [];
+      for (const matchers of Object.values(parsed?.hooks || {})) {
+        for (const m of matchers || []) {
+          for (const h of m?.hooks || []) commands.push(String(h?.command || ''));
+        }
+      }
+      const bash = commands.filter((c) => c.startsWith('bash '));
+      return { count: bash.length, source: 'manifest', scripts: basenames(bash) };
+    } catch {
+      // A torn manifest is not evidence of zero bash hooks. Fall through to settings.json,
+      // and if that says nothing about us either, the caller gets null.
+    }
+  }
+  // Only OUR entries: settings.json is shared with every other tool the user installs, so a
+  // foreign `bash "…"` line is not ours to report on, and — the discriminating half — a
+  // settings.json that names nothing of ours is not evidence that no hook needs bash. It is
+  // evidence we are reading the wrong registration.
+  const ours = settingsCommands.filter((c) => c.includes(installDir));
+  if (ours.length === 0) return { count: null, source: null, scripts: [] };
+  const bash = ours.filter((c) => c.startsWith('bash '));
+  return { count: bash.length, source: 'settings', scripts: basenames(bash) };
+}
+
 // Dev installs symlink server.mjs → the project's source file. Used to suppress
 // misleading "first run" messages since hook-update.mjs skips state-writes in
 // this mode (see hook-update.mjs isDevMode).
@@ -1865,6 +1919,68 @@ async function doctor() {
     dwarn('Hook scripts: check failed — ' + e.message);
   }
 
+  // Hook interpreter. Some hook commands are `bash "<script>"` (the PostToolUse and
+  // Agent prefilters, plus setup.sh in the plugin manifest) — the rest are `node`. If bash
+  // cannot run, those commands fail and nothing says so; the check above grades whether the
+  // FILES are present, which they are.
+  //
+  // Keyed on whether bash runs, not on process.platform === 'win32'. A Windows user with
+  // Git for Windows on PATH — the normal case, since Claude Code shells out to bash for its
+  // own Bash tool — has a working configuration and must not be warned; a stripped
+  // container with no bash has a broken one and must be, whatever its platform. This is
+  // also what issue #28's P3-19 intent asked for: `os: [darwin, linux]` was added so a
+  // Windows user "should be told rather than handed a string of silent catch blocks", and
+  // blocking the install told them nothing. This is the telling.
+  try {
+    const {
+      count: bashCommands,
+      source: countSource,
+      scripts: bashScripts,
+    } = resolveBashHookCount({
+      manifestPath: join(PROJECT_DIR, 'hooks', 'hooks.json'),
+      settingsCommands: settingsHookCommands(homedir()),
+      installDir: INSTALL_DIR,
+    });
+    if (bashCommands === null) {
+      // NOT `ok`. Pre-ship review (P1-1) found the first cut printing "no hook command needs
+      // bash" here, on a shape where two of them are registered — a green line that ends the
+      // reader's search is worse than the silence this check exists to remove.
+      dwarn(
+        'Hook interpreter: could not read either hook registration — neither ' +
+          `${join(PROJECT_DIR, 'hooks', 'hooks.json')} nor a claude-mem-lite entry in ` +
+          `${join(homedir(), '.claude', 'settings.json')} — so whether any hook needs bash is unknown.`,
+      );
+    } else if (bashCommands === 0) {
+      ok(`Hook interpreter: no hook command needs bash (per the ${countSource})`);
+    } else {
+      let bashOk = false;
+      try {
+        execFileSync('bash', ['-c', 'exit 0'], { stdio: 'ignore', timeout: 5000 });
+        bashOk = true;
+      } catch {
+        /* not resolvable, or not runnable — either way the hooks that need it cannot fire */
+      }
+      if (bashOk) {
+        ok(`Hook interpreter: bash present (${bashCommands} hook command(s) need it)`);
+      } else {
+        // dwarn, not an issue: everything else works. Saying "broken" about an install
+        // whose MCP server and node hooks are fine would be the mirror of the defect that
+        // sent this round's reporter looking at their disk and their network.
+        // The scripts are NAMED from the live registration rather than described from
+        // memory — the first cut wrote "(episode Read-tracking and the subagent prefilter)",
+        // a two-item gloss on a count of three (P3-1).
+        dwarn(
+          `Hook interpreter: bash not found on PATH — the ${bashCommands} hook command(s) that ` +
+            `invoke it cannot fire (${bashScripts.join(', ')}). The MCP server and the node ` +
+            'hooks are unaffected. On Windows, install Git for Windows or use WSL; elsewhere ' +
+            'this means a stripped PATH.',
+        );
+      }
+    }
+  } catch (e) {
+    dwarn('Hook interpreter: check failed — ' + e.message);
+  }
+
   // Stale temp files
   try {
     // hook-update + the episode workers write runtime/ + staging under DB_DIR

package/lib/platform-gate.mjs

@@ -0,0 +1,87 @@
+// lib/platform-gate.mjs — is THIS platform inside the `os` list package.json declares?
+//
+// Why this is a module and not four lines inside scripts/launch.mjs, which is its only
+// consumer: launch.mjs cannot be imported. Its top level installs dependencies, probes the
+// native binding and then imports the MCP server, so a test that imported it would start a
+// server. The alternative to a real import is a source-text scan of launch.mjs, which this
+// repo has repeatedly found to be walkable — a guard that greps for a string passes for a
+// change that keeps the string and deletes the behaviour. So the predicate lives here where
+// tests can drive it, and launch.mjs keeps the wording and the exit.
+//
+// `os` is an npm INSTALL GATE, evaluated against the ROOT package being installed. npm
+// rejects with EBADPLATFORM before it resolves anything, which is why a platform left off
+// the list does not degrade — it fails the install outright, and in plugin mode that install
+// is on the path of every first MCP launch after an update (issue #28).
+//
+// Node built-ins only: this runs BEFORE `npm install`, so node_modules may not exist yet.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * npm's own `checkList` from npm-install-checks, reproduced rather than approximated.
+ *
+ * The rule is not "is it in the list": an entry may be NEGATED with `!`, and a list of
+ * nothing but negations allows every platform it does not name. `list.includes(platform)`
+ * agrees with npm on the simple case and disagrees on `["!win32"]` — where it would tell a
+ * linux user their platform is unsupported while npm installs happily. A diagnostic that is
+ * wrong in that direction is worse than none.
+ *
+ * @param {string[]|string} list The `os` value as declared.
+ * @param {string} platform A `process.platform` value.
+ * @returns {boolean} True when npm would allow the install.
+ */
+export function platformAllowed(list, platform) {
+  const entries = typeof list === 'string' ? [list] : list;
+  if (!Array.isArray(entries)) return true;
+  if (entries.length === 1 && entries[0] === 'any') return true;
+  let negated = 0;
+  let match = false;
+  for (const entry of entries) {
+    const negate = typeof entry === 'string' && entry.startsWith('!');
+    const test = negate ? entry.slice(1) : entry;
+    if (negate) {
+      negated++;
+      if (platform === test) return false;
+    } else if (platform === test) {
+      match = true;
+    }
+  }
+  // An all-negation list (and, by the same arithmetic, an empty one) allows anything it
+  // has not vetoed above.
+  return match || negated === entries.length;
+}
+
+/**
+ * The `os` list `<root>/package.json` declares, or null when there is nothing to enforce.
+ *
+ * Fails OPEN on every error. A missing or torn package.json is the incomplete-install case
+ * that launch-preflight.mjs already diagnoses with a repair command; turning it into a
+ * platform complaint here would replace a good message with a wrong one.
+ *
+ * @param {string} root Directory holding package.json.
+ * @returns {string[]|null}
+ */
+export function readDeclaredPlatforms(root) {
+  const p = join(root, 'package.json');
+  if (!existsSync(p)) return null;
+  try {
+    const os = JSON.parse(readFileSync(p, 'utf8'))?.os;
+    if (typeof os === 'string') return [os];
+    return Array.isArray(os) ? os : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Would npm refuse to install this package on this platform?
+ *
+ * @param {{root: string, platform?: string}} opts
+ * @returns {{blocked: boolean, declared: string[]|null, platform: string}}
+ */
+export function platformGate({ root, platform = process.platform }) {
+  const declared = readDeclaredPlatforms(root);
+  if (declared === null) return { blocked: false, declared: null, platform };
+  return { blocked: !platformAllowed(declared, platform), declared, platform };
+}

package/npm-shrinkwrap.json

@@ -1,15 +1,16 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "6.1.0",
+      "version": "6.2.0",
       "os": [
         "darwin",
-        "linux"
+        "linux",
+        "win32"
       ],
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.30.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.1.0",
+  "version": "6.2.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).",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -9,7 +9,8 @@
   },
   "os": [
     "darwin",
-    "linux"
+    "linux",
+    "win32"
   ],
   "bin": {
     "claude-mem-lite": "./cli.mjs"
@@ -106,6 +107,7 @@
     "lib/hook-stdout.mjs",
     "lib/proc-lock.mjs",
     "lib/atomic-write.mjs",
+    "lib/platform-gate.mjs",
     "lib/hook-prune.mjs",
     "lib/proxy-fetch.mjs",
     "lib/llm-provider-probe.mjs",

package/plugin-cache-guard.mjs

@@ -117,8 +117,16 @@ export function hasInstallManagedHooks(opts) {
   }
 }
 
-/** Every `command` string under settings.json `hooks`, in registration order. */
-function settingsHookCommands(home) {
+/**
+ * Every `command` string under settings.json `hooks`, in registration order.
+ *
+ * Exported since the issue-#28 round: doctor's hook-interpreter check needs the LIVE
+ * registration, and on the npm / npx / `git clone` shape that is settings.json rather than
+ * `hooks/hooks.json` (which SOURCE_FILES does not deploy). Reading it here rather than
+ * hand-rolling a second walk keeps the two consumers on one parser — the twin-drift class
+ * this repo keeps paying for.
+ */
+export function settingsHookCommands(home) {
   const settingsPath = join(home, '.claude', 'settings.json');
   if (!existsSync(settingsPath)) return [];
   let s;

package/scripts/launch.mjs

@@ -11,6 +11,36 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = process.env.CLAUDE_PLUGIN_ROOT || join(__dirname, '..');
 
 if (!existsSync(join(ROOT, 'node_modules', 'better-sqlite3'))) {
+  // Platform gate BEFORE npm, not after it. package.json's `os` field is an npm install
+  // gate: npm exits EBADPLATFORM without resolving anything, so the catch below sees only
+  // "Command failed" and answers with a fixed cause list that cannot contain this cause.
+  // That is issue #28 — a Windows user got CONNECTION_CLOSED in /mcp plus a wrong reason,
+  // where the field was added (b6a2579, R10 P3-19) precisely so they would be TOLD.
+  // Letting npm fail and then guessing is the shape that failed; asking the manifest first
+  // is the shape that names both sides of the mismatch. Guarded import: lib/ can be absent
+  // in an incomplete install, which launch-preflight.mjs below diagnoses properly, and a
+  // missing diagnostic must never become a new failure mode.
+  try {
+    const { platformGate } = await import('../lib/platform-gate.mjs');
+    const gate = platformGate({ root: ROOT });
+    if (gate.blocked) {
+      process.stderr.write(
+        `[claude-mem-lite] npm install is blocked by this package's own platform list (npm EBADPLATFORM).\n`,
+      );
+      process.stderr.write(
+        `[claude-mem-lite]   package.json declares os: ${gate.declared.join(', ')} — this machine is ${gate.platform}\n`,
+      );
+      process.stderr.write(
+        `[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`,
+      );
+      process.exit(1);
+    }
+  } catch (e) {
+    process.stderr.write(`[claude-mem-lite] platform check skipped: ${e.message}\n`);
+  }
   process.stderr.write('[claude-mem-lite] Installing dependencies...\n');
   try {
     execSync('npm install --omit=dev', {
@@ -55,8 +85,13 @@ if (!existsSync(join(ROOT, 'node_modules', 'better-sqlite3'))) {
       (e?.signal ? `npm killed by ${e.signal}` : '') ||
       'unknown error';
     process.stderr.write(`[claude-mem-lite] npm install failed in ${ROOT} — ${detail}\n`);
+    // "Likely cause: …" until issue #28: it asserted three causes, and the one that was
+    // actually firing (EBADPLATFORM, gated above) was not among them. stderr is inherited,
+    // so npm's own `npm error code <CODE>` line is already on this stream a few lines up —
+    // point at that instead of competing with it. A guess presented as a diagnosis costs
+    // more than no diagnosis: it sends the reader looking at their disk and their network.
     process.stderr.write(
-      `[claude-mem-lite] Likely cause: read-only directory, disk full, or network blocked.\n`,
+      `[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.exit(1);

package/source-files.mjs

@@ -142,6 +142,11 @@ export const SOURCE_FILES = [
   // + auto-update lock). Must ship or a partial install/update skips them.
   'lib/proc-lock.mjs',
   'lib/atomic-write.mjs',
+  // Dynamically imported by scripts/launch.mjs BEFORE `npm install` runs, to answer
+  // EBADPLATFORM with both sides of the mismatch instead of a guessed cause (issue #28).
+  // The import is guarded, so omitting this file would not crash the launcher — it would
+  // silently restore the wrong diagnosis, which is the failure this shipped to fix.
+  'lib/platform-gate.mjs',
   // Shared settings.json hook classification + dangling-entry reconciliation.
   // Statically imported by install.mjs AND dynamically by hook-update.mjs's
   // post-swap step — missing it from the manifest would break auto-update's