claude-mem-lite 3.0.0 → 3.1.0

package/.claude-plugin/marketplace.json

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

@@ -160,6 +160,8 @@ 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.
+
 > **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.
 
 ### Method 2: npx (one-liner)

package/adopt-content.mjs

@@ -26,7 +26,7 @@ export function getIndexLine() {
 export function getDetailDoc() {
   return `# claude-mem-lite 插件契约
 
-> 由 \`claude-mem-lite adopt\` 生成；卸载用 \`claude-mem-lite unadopt\`。
+> 由 \`node ~/.claude-mem-lite/cli.mjs adopt\` 生成；卸载用 \`node ~/.claude-mem-lite/cli.mjs unadopt\`。
 > 设计背景见 docs/plans/2026-04-16-invited-memory-pattern.md。
 
 ## 何时调用 MCP 工具
@@ -58,28 +58,28 @@ MCP 层，按名 \`tools/call\` 仍可命中，但对 Claude Code 这类只读 t
 
 | 场景 | CLI |
 |------|-----|
-| 清理过期记忆 | \`claude-mem-lite maintain --action scan\` → \`--action execute\` |
-| 深度优化（Haiku） | \`claude-mem-lite optimize --action preview\` |
-| 压缩旧条目 | \`claude-mem-lite compress --preview\` |
-| FTS5 索引检查 / 重建 | \`claude-mem-lite fts-check [--rebuild]\` |
-| tier 分组浏览 | \`claude-mem-lite browse [--tier active]\` |
-| 导出 JSON/JSONL | \`claude-mem-lite export [--format jsonl]\` |
-| 统计总量 / 健康 | \`claude-mem-lite stats [--days 30]\` |
-| 删除某条 | \`claude-mem-lite delete <id>[,<id>]\` |
-| 更新某条 | \`claude-mem-lite update <id> [--title ...]\` |
-| 列 / 搜索 / 导入 skill-agent registry | \`claude-mem-lite registry <list\\|search\\|import>\` |
+| 清理过期记忆 | \`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>\` |
 | 按 registry 名载入 skill/agent | （MCP only：\`mem_use\`；由用户主动请求时才使用） |
 
 ## CLI 速查（常用检索）
 
 | 命令 | 用途 |
 |------|------|
-| \`claude-mem-lite search "query"\` | FTS5 全文搜索 |
-| \`claude-mem-lite search "err" --type bugfix\` | 按类型过滤 |
-| \`claude-mem-lite recall "file.mjs"\` | 文件相关记忆 |
-| \`claude-mem-lite recent 5\` | 最近 5 条 |
-| \`claude-mem-lite get 42,43\` | 按 ID 展开 |
-| \`claude-mem-lite timeline --anchor 42\` | 时间线上下文 |
+| \`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\` | 时间线上下文 |
 
 ## 质量门槛
 
@@ -89,6 +89,6 @@ MCP 层，按名 \`tools/call\` 仍可命中，但对 Claude Code 这类只读 t
 
 ## 卸载
 
-\`claude-mem-lite unadopt\` 精确移除 sentinel 段 + 本文件；其它 MEMORY.md 内容不动。
+\`node ~/.claude-mem-lite/cli.mjs unadopt\` 精确移除 sentinel 段 + 本文件；其它 MEMORY.md 内容不动。
 `;
 }

package/commands/adopt.md

@@ -57,4 +57,4 @@ session. After running `adopt`:
 
 Same caveat applies in reverse for `/unadopt`.
 
-!claude-mem-lite adopt $ARGUMENTS
+!node ~/.claude-mem-lite/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:
 
-    claude-mem-lite activity save \
+    node ~/.claude-mem-lite/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):
 
-    claude-mem-lite activity save \
+    node ~/.claude-mem-lite/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 `claude-mem-lite search <query>` via Bash
-- `/mem recent` or `/mem recent 20` → run `claude-mem-lite recent [N]` via Bash
-- `/mem recall <file>` → run `claude-mem-lite recall <file>` via Bash
-- `/mem timeline <id>` → run `claude-mem-lite timeline --anchor <id>` via Bash
+- `/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 save <text>` → call `mem_save` MCP tool with the text as content
-- `/mem stats` → run `claude-mem-lite stats` via Bash
-- `/mem get <ids>` → run `claude-mem-lite get <ids>` via Bash
+- `/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 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 `claude-mem-lite search <query>` via Bash
+- `/mem <query>` (no subcommand) → treat as search, run `node ~/.claude-mem-lite/cli.mjs search <query>` via Bash
 
-Use Bash commands first. For detailed data, use `claude-mem-lite get <id>` via Bash.
+Use Bash commands first. For detailed data, use `node ~/.claude-mem-lite/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.
 
-!claude-mem-lite unadopt $ARGUMENTS
+!node ~/.claude-mem-lite/cli.mjs unadopt $ARGUMENTS

package/hook.mjs

@@ -45,6 +45,7 @@ import {
 } from './hook-shared.mjs';
 import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObservation } from './hook-llm.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
+import { formatHookError } from './lib/native-binding-hint.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
 import { cleanupBroken, decayAndMarkIdle, boostAccessed } from './lib/maintain-core.mjs';
 import {
@@ -1439,9 +1440,13 @@ try {
     case 'update-check':     await checkForUpdate(); break;
   }
 } catch (err) {
-  // Always log fatal errors (ungated) with structured format
-  const ts = new Date().toISOString();
-  console.error(`[claude-mem-lite] [${ts}] [ERROR] ${event}: ${err.message}`);
+  // Log fatal errors (ungated) with structured format. ERR_DLOPEN_FAILED (an
+  // unloadable native DB binding, e.g. ABI-stale after a Node upgrade) is
+  // collapsed to one short, rate-limited rebuild hint instead of the raw
+  // multi-line NODE_MODULE_VERSION message on every fire — see
+  // lib/native-binding-hint.mjs.
+  const line = formatHookError(err, event, { runtimeDir: RUNTIME_DIR });
+  if (line) console.error(line);
 }
 
 process.exit(0);

package/lib/native-binding-hint.mjs

@@ -0,0 +1,71 @@
+// lib/native-binding-hint.mjs — friendly, rate-limited hint for an unloadable
+// native DB binding (better-sqlite3 ERR_DLOPEN_FAILED, e.g. a Node version
+// upgrade leaves the prebuilt .node ABI-stale).
+//
+// This is the SIBLING of the missing-dependency case handled in
+// scripts/hook-launcher.mjs. The two fail on different paths:
+//   • MISSING dependency (ERR_MODULE_NOT_FOUND) throws at IMPORT time, before
+//     hook.mjs runs — caught by the launcher.
+//   • UNLOADABLE binding (ERR_DLOPEN_FAILED) imports fine (better-sqlite3 loads
+//     its .node lazily at the first `new Database()`), then throws inside a hook
+//     handler — caught by hook.mjs's top-level dispatch try/catch. Pre-this,
+//     that catch logged the raw multi-line NODE_MODULE_VERSION message on EVERY
+//     hook fire. Here we collapse it to one short, actionable line, rate-limited
+//     per cooldown. The actual rebuild is the MCP server launch path's job
+//     (lib/binding-probe.mjs::ensureBetterSqlite3Working) — a hook must never
+//     run `npm rebuild` itself (2–5s timeout + concurrent-fire races).
+//
+// Pure node: imports + injectable now/runtimeDir so it unit-tests without the
+// hook dependency graph (no schema.mjs / better-sqlite3 import).
+
+import { join } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+
+export const NATIVE_BINDING_HINT_COOLDOWN_MS = 6 * 60 * 60 * 1000; // 6h
+const MARKER_NAME = 'native-binding-hint-last';
+
+/**
+ * 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.
+ *
+ * @param {string} runtimeDir Directory for the marker file
+ * @param {number} [now] Current epoch ms (injectable)
+ * @param {number} [cooldownMs] Suppression window
+ * @returns {boolean}
+ */
+export function nativeBindingHintDue(runtimeDir, now = Date.now(), cooldownMs = NATIVE_BINDING_HINT_COOLDOWN_MS) {
+  const marker = join(runtimeDir, MARKER_NAME);
+  try {
+    const last = Number(readFileSync(marker, 'utf8'));
+    if (Number.isFinite(last) && now - last < cooldownMs) return false;
+  } catch { /* no/invalid marker → due */ }
+  try {
+    if (!existsSync(runtimeDir)) mkdirSync(runtimeDir, { recursive: true });
+    writeFileSync(marker, String(now));
+  } catch { /* best-effort */ }
+  return true;
+}
+
+/**
+ * Single stderr line hook.mjs should log for a caught dispatch error, or null
+ * to stay silent (ERR_DLOPEN_FAILED still within cooldown). ERR_DLOPEN_FAILED →
+ * short rate-limited rebuild hint; everything else → the existing ungated
+ * structured ERROR line. Pass runtimeDir to enable rate-limiting (omit it to
+ * always format, e.g. in tests).
+ *
+ * @param {Error & {code?: string}} err
+ * @param {string} event Hook event name (stop / session-start / …)
+ * @param {{now?: number, runtimeDir?: string}} [opts]
+ * @returns {string | null}
+ */
+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;
+    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`;
+  }
+  return `[claude-mem-lite] [${ts}] [ERROR] ${event}: ${err && err.message}`;
+}

package/mem-cli.mjs

@@ -39,6 +39,7 @@ import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentT
 import { buildSearchFtsQuery, parseDateBounds, computePerSourceWindow, effectiveObsFtsQuery, searchSessionsFts, searchPromptsFts, normalizeCrossSourceScores, applyUserSort, applyTierFilter } from './lib/search-core.mjs';
 import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { countRecentHookErrors } from './lib/hook-telemetry.mjs';
+import { aggregateMetrics } from './lib/metrics.mjs';
 import {
   insertDeferred, listOpenWithOrdinal, dropDeferred,
   resolveDeferredIds, closeDeferredItems,
@@ -1154,6 +1155,13 @@ async function cmdStats(db, args) {
   out(`  Low-value (imp=1, never accessed, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`);
   out(`  Compressed: ${compressedCount.c}`);
   out(`  Hook errors (last 24h): ${hookErrors24h}${hookErrors24h > 0 ? `  ← tail ${join(DB_DIR, 'runtime/hook-errors')}` : ''}`);
+  // Tier-1 firing counters for ① file-intel + ② reread-guard (recorded by
+  // pre-tool-recall.js via lib/metrics.mjs; CLAUDE_MEM_METRICS=1 to enable).
+  const featAgg = aggregateMetrics(DB_DIR, 7);
+  const fiN = featAgg.file_intel?.count ?? 0;
+  const rrN = featAgg.reread_warn?.count ?? 0;
+  const metricsOn = process.env.CLAUDE_MEM_METRICS === '1';
+  out(`  Feature injections (7d): 📄 file-intel ${fiN} · 🔁 reread-warn ${rrN}${(!metricsOn && fiN + rrN === 0) ? '  (set CLAUDE_MEM_METRICS=1 to record)' : ''}`);
   if (noiseRatio > 0.6) out('  ⚠️ High noise ratio — consider running mem compress');
   out('');
   // Tier counts only live (uncompressed, non-superseded) observations — surface the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.0.0",
+  "version": "3.1.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",
@@ -79,6 +79,7 @@
     "lib/deferred-work.mjs",
     "lib/upgrade-banner.mjs",
     "lib/scrub-record.mjs",
+    "lib/native-binding-hint.mjs",
     "lib/import-jsonl.mjs",
     "cli/common.mjs",
     "cli/fts-check.mjs",

package/scripts/hook-launcher.mjs

@@ -9,10 +9,16 @@
 // launcher is defense-in-depth for similar future drift (corrupt download,
 // half-applied install, manual file deletion).
 //
-// Behavior: try-import the target entry. On ERR_MODULE_NOT_FOUND whose URL
-// points under the install dir, run `install.mjs repair` (rate-limited via a
-// 6h marker file under runtime/) and retry the import once. On any other
-// exception, re-throw so Node's default error surface is preserved.
+// Behavior: try-import the target entry. On ERR_MODULE_NOT_FOUND originating
+// from our install — either a missing relative module (e.url under the install
+// dir) or a missing bare dependency like better-sqlite3 (e.url is undefined and
+// the importer named in the message is under the install dir) — run
+// `install.mjs repair` (rate-limited via a 6h marker file under runtime/) and
+// retry the import once. If repair is unavailable or fails, degrade quietly:
+// these are best-effort memory hooks, so a broken/missing dependency emits one
+// clean recovery line and exits 0 rather than dumping a Node stack trace on
+// every fire. On any other (foreign) exception, re-throw so Node's default
+// error surface is preserved.
 //
 // HARD constraint: pure node: imports only. Importing anything from lib/ here
 // would defeat the entire purpose — the launcher must survive a broken
@@ -59,10 +65,33 @@ async function runEntry({ bustCache = false } = {}) {
   await import(url);
 }
 
+// Two ERR_MODULE_NOT_FOUND shapes reach here (both verified against Node 22):
+//   • missing relative module → e.url = file://<missing-path> (under install)
+//   • missing bare dependency (e.g. a half-installed better-sqlite3) → e.url is
+//     UNDEFINED and the message is `Cannot find package '<name>' imported from
+//     <importer>`. This is the shape that bricked the hooks: the old
+//     file://INSTALL_DIR prefix test never matched it in a dev-dir install, so
+//     a missing dependency was misread as a foreign error and re-thrown as a
+//     Node stack trace on every hook fire.
+// 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.
 function isLocalModuleErr(e) {
   if (!e || e.code !== 'ERR_MODULE_NOT_FOUND') return false;
-  const where = String(e.url || e.message || '');
-  return where.includes('.claude-mem-lite') || where.startsWith(`file://${INSTALL_DIR}`);
+  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'));
+}
+
+// Human-readable label for the "Detected broken install (<reason>)" line:
+// prefer the missing dependency/module name over a raw path fragment.
+function describeFailure(e) {
+  const pkg = /Cannot find package '([^']+)'/.exec(String(e.message || ''))?.[1];
+  if (pkg) return pkg;
+  if (e.url) return String(e.url).split('/').pop();
+  return String(e.message || 'unknown').split('/').slice(-2).join('/');
 }
 
 function recentHealAttempt() {
@@ -133,9 +162,14 @@ try {
   await runEntry();
 } catch (e) {
   if (!isLocalModuleErr(e)) throw e;
-  const reason = String(e.url || e.message).split('/').slice(-2).join('/');
-  const healed = await attemptHeal(reason);
-  if (!healed) throw e;
+  const healed = await attemptHeal(describeFailure(e));
+  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.
+    process.exit(0);
+  }
   try {
     await runEntry({ bustCache: true });
   } catch (retryErr) {
@@ -143,6 +177,6 @@ try {
       `[claude-mem-lite] Hook still failing after self-heal: ${retryErr.message}\n` +
       `[claude-mem-lite] Manual recovery: ${TARBALL_FALLBACK}\n`,
     );
-    process.exit(1);
+    process.exit(0);
   }
 }

package/scripts/pre-tool-recall.js

@@ -12,6 +12,7 @@ import { recordHookError } from '../lib/hook-telemetry.mjs';
 import { citeFactorClause } from '../scoring-sql.mjs';
 import { fileIntelFor } from '../lib/file-intel.mjs';
 import { shouldWarnReread, buildRereadWarning, readFileMeta } from '../lib/reread-guard.mjs';
+import { recordMetric } from '../lib/metrics.mjs';
 
 // CLAUDE_MEM_DIR matches schema.mjs / main CLI — one env var sandboxes the
 // whole system. CLAUDE_MEM_DB_PATH / CLAUDE_MEM_RUNTIME_DIR remain as
@@ -258,6 +259,7 @@ try {
               ].join('\n'),
             },
           }));
+          recordMetric(DATA_DIR, { event: 'reread_warn' }); // tier-1 firing counter (②)
         }
       }
       process.exit(0); // already recalled this file in-session
@@ -388,6 +390,9 @@ try {
     if (isRead && !FILE_INTEL_OFF) {
       try { fileIntelLine = fileIntelFor(filePath, { minTokens: FILE_INTEL_MIN_TOKENS }); } catch {}
     }
+    // Tier-1 firing counter (①). recordMetric no-ops unless CLAUDE_MEM_METRICS=1,
+    // so default users pay nothing; observers see counts in `doctor` / `stats`.
+    if (fileIntelLine) recordMetric(DATA_DIR, { event: 'file_intel' });
     const lines = [];
     // v2.34.6: Read mode uses 120-char truncation (Edit mode keeps the 240-char
     // cap from R3-UX). Rationale: Read is a one-shot nudge with 1 lesson max;

package/server-internals.mjs

@@ -14,7 +14,7 @@ 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):',
+  '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',
@@ -22,7 +22,7 @@ const INSTRUCTIONS_BASE = [
   '  claude-mem-lite get 42,43                   — full details by ID',
   '  claude-mem-lite timeline --anchor 42        — chronological context',
   '',
-  'MCP tools: mem_search, mem_recent, mem_save, mem_get, mem_recall, mem_timeline for programmatic access.',
+  '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).',
   'Search tips: short keywords (2-3 words), filter with obs_type when relevant.',
 ];

package/source-files.mjs

@@ -121,6 +121,10 @@ export const SOURCE_FILES = [
   // Statically imported by hook-llm, hook-handoff, hook-optimize, hook,
   // mem-cli; reached transitively from server.mjs and cli.mjs.
   'lib/scrub-record.mjs',
+  // Rate-limited friendly hint for an unloadable native DB binding
+  // (ERR_DLOPEN_FAILED). Statically imported by hook.mjs; ship it so the
+  // dispatch catch path resolves in installed/tarball runtimes.
+  'lib/native-binding-hint.mjs',
   // Cold-start backfill: parses ~/.claude/projects/<encoded>/<uuid>.jsonl
   // transcripts into user_prompts + observations. Dynamic-imported by
   // mem-cli.mjs::cmdImportJsonl; listed here so source-files-sync.test.mjs

package/tool-schemas.mjs

@@ -349,7 +349,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: claude-mem-lite search "<query>" [--type bugfix]',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs search "<query>" [--type bugfix]',
     inputSchema: memSearchSchema,
   },
   {
@@ -367,7 +367,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: claude-mem-lite recent [N]',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs recent [N]',
     inputSchema: memRecentSchema,
   },
   {
@@ -387,7 +387,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: claude-mem-lite timeline --anchor <ID> [--before N --after N]',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs timeline --anchor <ID> [--before N --after N]',
     inputSchema: memTimelineSchema,
   },
   {
@@ -407,7 +407,7 @@ export const tools = [
       '\n' +
       'On miss, response includes "Try: …" hint listing other sources the ID lives in.\n' +
       '\n' +
-      'Equivalent CLI: claude-mem-lite get <id>[,<id>,...] — accepts P#/S#/# prefix.',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs get <id>[,<id>,...] — accepts P#/S#/# prefix.',
     inputSchema: memGetSchema,
   },
   {
@@ -425,7 +425,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: claude-mem-lite delete <id>[,<id>,...] [--confirm]',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs delete <id>[,<id>,...] [--confirm]',
     inputSchema: memDeleteSchema,
     hidden: true,
   },
@@ -444,7 +444,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: claude-mem-lite save --type bugfix --lesson "..." "<content>"',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs save --type bugfix --lesson "..." "<content>"',
     inputSchema: memSaveSchema,
   },
   {
@@ -462,7 +462,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: claude-mem-lite stats [--project X] [--days 30]',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs stats [--project X] [--days 30]',
     inputSchema: memStatsSchema,
     hidden: true,
   },
@@ -481,7 +481,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: claude-mem-lite compress [--execute] [--age-days 90]  (preview is default)',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs compress [--execute] [--age-days 90]  (preview is default)',
     inputSchema: memCompressSchema,
     hidden: true,
   },
@@ -500,7 +500,7 @@ export const tools = [
       '  - After bulk imports or a long offline period\n' +
       '  - User asks for periodic maintenance / cleanup\n' +
       '\n' +
-      'Equivalent CLI: claude-mem-lite maintain scan --ops dedup,decay',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs maintain scan --ops dedup,decay',
     inputSchema: memMaintainSchema,
     hidden: true,
   },
@@ -519,7 +519,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: claude-mem-lite optimize [--run|--run-all] [--task re-enrich,normalize,cluster-merge,smart-compress] [--max N]  (preview is default)',
+      '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)',
     inputSchema: memOptimizeSchema,
     hidden: true,
   },
@@ -538,7 +538,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: claude-mem-lite registry <list|search|import|...> [args]',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs registry <list|search|import|...> [args]',
     inputSchema: memRegistrySchema,
     hidden: true,
   },
@@ -576,7 +576,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: claude-mem-lite update <id> [--title ...] [--lesson ...]',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs update <id> [--title ...] [--lesson ...]',
     inputSchema: memUpdateSchema,
     hidden: true,
   },
@@ -595,7 +595,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: claude-mem-lite export [--format jsonl] [--project X] [--limit 500]',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs export [--format jsonl] [--project X] [--limit 500]',
     inputSchema: memExportSchema,
     hidden: true,
   },
@@ -614,7 +614,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: claude-mem-lite recall "<file>" [--limit 10]',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs recall "<file>" [--limit 10]',
     inputSchema: memRecallSchema,
   },
   {
@@ -632,7 +632,7 @@ export const tools = [
       '  - After a crash, power loss, or manual DB edit\n' +
       '  - doctor / stats flags FTS integrity problems\n' +
       '\n' +
-      'Equivalent CLI: claude-mem-lite fts-check [--rebuild]',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs fts-check [--rebuild]',
     inputSchema: memFtsCheckSchema,
     hidden: true,
   },
@@ -651,7 +651,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: claude-mem-lite browse [--tier active] [--project X]',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs browse [--tier active] [--project X]',
     inputSchema: memBrowseSchema,
     hidden: true,
   },
@@ -670,7 +670,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: claude-mem-lite defer add "<title>" [--priority 1|2|3] [--detail "..."] [--files a.mjs,b.mjs]',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs defer add "<title>" [--priority 1|2|3] [--detail "..."] [--files a.mjs,b.mjs]',
     inputSchema: memDeferSchema,
   },
   {
@@ -687,7 +687,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: claude-mem-lite defer list [--project X] [--limit 10]',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs defer list [--project X] [--limit 10]',
     inputSchema: memDeferListSchema,
   },
   {
@@ -705,7 +705,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: claude-mem-lite defer drop <D#N|ordinal> --reason "..."',
+      'Equivalent CLI: node ~/.claude-mem-lite/cli.mjs defer drop <D#N|ordinal> --reason "..."',
     inputSchema: memDeferDropSchema,
   },
 ];