claude-mem-lite 2.81.0 → 2.83.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.81.0",
+      "version": "2.83.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.81.0",
+  "version": "2.83.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -138,7 +138,7 @@ 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`.
+> **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)
 
@@ -281,9 +281,11 @@ authority than MCP server instructions (which are framed as tool metadata).
 ```bash
 claude-mem-lite adopt              # install for current project
 claude-mem-lite adopt --all        # install for every project under ~/.claude/projects/
-claude-mem-lite adopt --status     # list adopted projects + sentinel versions
+claude-mem-lite adopt --status     # list adopted/disabled projects + current gating snapshot
 claude-mem-lite adopt --dry-run    # preview without writing
-claude-mem-lite unadopt            # remove cleanly
+claude-mem-lite adopt --disable    # opt out of auto-adopt for current project (writes .mem-no-auto-adopt sentinel)
+claude-mem-lite adopt --enable     # re-arm auto-adopt for current project (deletes the sentinel)
+claude-mem-lite unadopt            # remove sentinel + doc (runtime marker stays to honor the explicit removal)
 ```
 
 Slash commands `/adopt` and `/unadopt` wrap the same CLI.
@@ -313,8 +315,12 @@ Slash commands `/adopt` and `/unadopt` wrap the same CLI.
   unless you pass `--force`.
 - Budget-gated: refuses to insert when MEMORY.md is already >180 lines, so
   Claude Code's 200-line MEMORY.md cap won't truncate the block.
-- `install` only auto-adopts when run from the claude-mem-lite source repo
-  itself (detected via git remote match); other users must opt in explicitly.
+- **Auto-adopt fires on the first SessionStart per project for any install
+  path (v2.82.1+).** Per-project opt-out: `claude-mem-lite adopt --disable`
+  (writes a durable `<memdir>/.mem-no-auto-adopt` sentinel that survives marker
+  deletion / plugin reinstalls). Global opt-out: `MEM_NO_AUTO_ADOPT=1`.
+  Pre-v2.82.1 the `CLAUDE_PLUGIN_ROOT` gate left auto-adopt unreachable for
+  every `install.mjs`-written hook (the common path) — see CHANGELOG v2.82.1.
 - The fallback hook layer is never removed from source — conditional trim is
   runtime-gated on sentinel presence, so projects without adoption get the
   full verbose output.
@@ -614,8 +620,9 @@ npm run benchmark:gate    # CI gate: fails if metrics regress beyond 5% toleranc
 | `CLAUDE_MEM_DIR` | Custom data directory. All databases, runtime files, and managed resources are stored here. | `~/.claude-mem-lite/` |
 | `CLAUDE_MEM_MODEL` | LLM model for background calls (episode extraction, session summaries). Accepts `haiku` or `sonnet`. | `haiku` |
 | `CLAUDE_MEM_DEBUG` | Enable debug logging (`1` to enable). | _(disabled)_ |
-| `MEM_QUIET_HOOKS` | Low-noise hooks. `1` drops the `File Lessons` / `Key Context` sections from SessionStart injection, the lesson suffix from `[mem] Related memories`, and the `WHEN TO USE` / `Decision rules` blocks from MCP server instructions. IDs and the `Recent` table still surface so `mem_get(ids=[…])` remains reachable. Intended for users running the invited-memory adopt path or who otherwise want minimal auto-injection. | _(disabled)_ |
-| `MEM_NO_ADOPT_HINT` | Silences the one-line "Invited-memory 未启用：`claude-mem-lite adopt`…" hint that SessionStart appends when the current project hasn't been adopted. The hint self-clears once `adopt` runs; set this env to suppress it without adopting. | _(disabled)_ |
+| `MEM_QUIET_HOOKS` | Low-noise hooks. `1` drops the `File Lessons` / `Key Context` sections from SessionStart injection, the lesson suffix from `[mem] Related memories`, and the `WHEN TO USE` / `Decision rules` blocks from MCP server instructions. IDs and the `Recent` table still surface so `mem_get(ids=[…])` remains reachable. Intended for users running the invited-memory adopt path or who otherwise want minimal auto-injection. **Since v2.82.0 this env no longer gates auto-adopt — use `MEM_NO_AUTO_ADOPT=1` for that.** | _(disabled)_ |
+| `MEM_NO_AUTO_ADOPT` | Global opt-out for auto-adopt (v2.82.0+). `1` prevents the first-SessionStart auto-write of the invited-memory sentinel across **all** projects. For per-project opt-out use `claude-mem-lite adopt --disable` instead (writes a durable `<memdir>/.mem-no-auto-adopt` sentinel that survives marker deletion). | _(disabled)_ |
+| `MEM_NO_ADOPT_HINT` | Silences the one-line "Invited-memory 未启用：`claude-mem-lite adopt`…" hint that SessionStart appends when the current project hasn't been adopted. Since v2.82.1 auto-adopt fires on first SessionStart for any install path, so this hint typically surfaces only when you've explicitly opted out (`MEM_NO_AUTO_ADOPT=1` or `claude-mem-lite adopt --disable`). | _(disabled)_ |
 
 ## License
 

package/README.zh-CN.md

@@ -148,7 +148,7 @@ node install.mjs install
 1. **安装依赖** -- `npm install --omit=dev`（编译原生 `better-sqlite3`）
 2. **注册 MCP 服务器** -- `mem-lite` 服务器，包含 20 个工具（9 个核心通过 `tools/list` 暴露 + 11 个隐藏但可调；完整表见 Usage 段）。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`。
+> **首次 SessionStart 自动 adopt（v2.82.1+）。** 插件会自动向该项目 memdir 写入**邀请式 memory 哨兵**（一条提升 Claude 主动调用 `mem_recall` / `mem_save` 的 system-authority 指针），**任何安装路径都生效**（npm、npx、`/plugin`、手动），**无需再手动跑 `/adopt`**。项目级关闭：`claude-mem-lite adopt --disable`（重新启用用 `--enable`）。全局关闭：`export MEM_NO_AUTO_ADOPT=1`。手动 `/adopt` 仍保留用于编辑后重写或 `--all` 批量场景。
 3. **配置钩子** -- `PostToolUse`、`PreToolUse`、`SessionStart`、`Stop`、`UserPromptSubmit` 生命周期钩子
 4. **创建数据目录** -- `~/.claude-mem-lite/`（隐藏目录），存放数据库、运行时和托管资源文件
 5. **自动迁移** -- 自动检测 `~/.claude-mem/`（原版 claude-mem）或 `~/claude-mem-lite/`（v0.5 前的非隐藏目录），将数据库和运行时文件迁移到 `~/.claude-mem-lite/`，原目录保持不变
@@ -263,9 +263,11 @@ instruction-following 权威。
 ```bash
 claude-mem-lite adopt              # 当前项目注入
 claude-mem-lite adopt --all        # 扫描 ~/.claude/projects/* 全部注入
-claude-mem-lite adopt --status     # 列出所有已 adopt 的项目 + 版本号
+claude-mem-lite adopt --status     # 列出已 adopt / 已禁用项目 + 当前 gate 快照
 claude-mem-lite adopt --dry-run    # 只打印不写入
-claude-mem-lite unadopt            # 精确移除
+claude-mem-lite adopt --disable    # 当前项目关闭 auto-adopt（写 .mem-no-auto-adopt 哨兵）
+claude-mem-lite adopt --enable     # 当前项目重新启用 auto-adopt（删哨兵）
+claude-mem-lite unadopt            # 精确移除 sentinel + 详情文档（runtime marker 保留以尊重显式撤销）
 ```
 
 Slash 命令 `/adopt` 和 `/unadopt` 是上述 CLI 的包装。
@@ -291,8 +293,11 @@ Slash 命令 `/adopt` 和 `/unadopt` 是上述 CLI 的包装。
 - Hash 守护：你手动改了 sentinel 段 → 下一次 adopt 报 `UserEditedError`，
   除非显式 `--force`。
 - 预算门：MEMORY.md 已 >180 行时拒绝新增（避开 Claude Code 200 行截断）。
-- `install` 只在从 claude-mem-lite 源码仓库运行时 auto-adopt（靠 git remote 判别）；
-  其它用户需显式调用。
+- **任何安装路径首次 SessionStart 自动 adopt（v2.82.1+）。** 项目级关闭：
+  `claude-mem-lite adopt --disable`（写 `<memdir>/.mem-no-auto-adopt` 哨兵，
+  存活于 marker 删除 / 插件重装）。全局关闭：`export MEM_NO_AUTO_ADOPT=1`。
+  v2.82.1 前因 `CLAUDE_PLUGIN_ROOT` gate 与 `install.mjs` 写出的 hook 命令
+  不匹配，auto-adopt 实质 5 周零触发——见 CHANGELOG v2.82.1。
 - 保守 hook 层源码永不删——条件瘦身仅基于 sentinel 存在性做 runtime 判断，
   未 adopt 的项目仍看完整 verbose 输出。
 
@@ -575,8 +580,9 @@ npm run benchmark:gate    # CI 门控：指标回退超过 5% 容差时失败
 | `CLAUDE_MEM_DIR` | 自定义数据目录。所有数据库、运行时文件和托管资源均存储在此。 | `~/.claude-mem-lite/` |
 | `CLAUDE_MEM_MODEL` | 后台 LLM 调用模型（Episode 提取、会话总结、调度）。可选 `haiku` 或 `sonnet`。 | `haiku` |
 | `CLAUDE_MEM_DEBUG` | 启用调试日志（设为 `1` 启用）。 | _(禁用)_ |
-| `MEM_QUIET_HOOKS` | 低噪声 hook。设为 `1` 时，SessionStart 注入去掉 `File Lessons` / `Key Context` 两节，`[mem] Related memories` 去掉 lesson 后缀，MCP server instructions 去掉 `WHEN TO USE` / `Decision rules` 两段。ID 与 `Recent` 表仍保留，`mem_get(ids=[…])` 可继续展开细节。适用于启用了 invited-memory adopt 流程或偏好最小化自动注入的用户。 | _(禁用)_ |
-| `MEM_NO_ADOPT_HINT` | 静音当前项目未 adopt 时 SessionStart 追加的那一行 "Invited-memory 未启用…" 提示。一旦运行 `adopt` 该提示自动消失；此 env 让偏好保守层的用户在不 adopt 的情况下也能静音。 | _(禁用)_ |
+| `MEM_QUIET_HOOKS` | 低噪声 hook。设为 `1` 时，SessionStart 注入去掉 `File Lessons` / `Key Context` 两节，`[mem] Related memories` 去掉 lesson 后缀，MCP server instructions 去掉 `WHEN TO USE` / `Decision rules` 两段。ID 与 `Recent` 表仍保留，`mem_get(ids=[…])` 可继续展开细节。适用于启用了 invited-memory adopt 流程或偏好最小化自动注入的用户。**v2.82.0 起此 env 不再阻挡 auto-adopt——如需关闭 auto-adopt 用 `MEM_NO_AUTO_ADOPT=1`。** | _(禁用)_ |
+| `MEM_NO_AUTO_ADOPT` | auto-adopt 全局关闭开关（v2.82.0+）。设为 `1` 阻止首次 SessionStart 在**所有**项目自动写入邀请式 memory 哨兵。项目级关闭走 `claude-mem-lite adopt --disable`（写 `<memdir>/.mem-no-auto-adopt` 哨兵，存活于 marker 删除）。 | _(禁用)_ |
+| `MEM_NO_ADOPT_HINT` | 静音当前项目未 adopt 时 SessionStart 追加的那一行 "Invited-memory 未启用…" 提示。v2.82.1 起任何安装路径首次 SessionStart 都自动 adopt，所以该提示一般只在你显式 opt out（`MEM_NO_AUTO_ADOPT=1` 或 `claude-mem-lite adopt --disable`）的项目才会出现。 | _(禁用)_ |
 
 ## 许可证
 

package/adopt-cli.mjs

@@ -9,7 +9,7 @@
 // --dry-run = print intent without writing
 // --status = list all adopted projects + versions
 
-import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync } from 'fs';
+import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import {
@@ -49,6 +49,24 @@ function listAllMemdirs() {
 
 function hasFlag(args, flag) { return Array.isArray(args) && args.includes(flag); }
 
+// ─── Per-project auto-adopt opt-out sentinel ─────────────────────────────────
+// `<memdir>/.mem-no-auto-adopt` is the durable, project-scoped escape hatch.
+// Survives marker deletion, sentinel removal, and plugin reinstalls — that's
+// the point: "user said no for this project" should not be reversible by
+// `rm ~/.claude-mem-lite/runtime/.auto-adopt-*`. Managed via
+// `claude-mem-lite adopt --disable` / `--enable`. silentAutoAdopt checks it
+// at entry and skips WITHOUT writing the runtime marker, so toggling
+// `--enable` re-arms auto-adopt on the next SessionStart.
+const DISABLE_SENTINEL_BASENAME = '.mem-no-auto-adopt';
+
+export function disableSentinelPath(memdir) {
+  return join(memdir, DISABLE_SENTINEL_BASENAME);
+}
+
+export function isAutoAdoptDisabled(memdir) {
+  return existsSync(disableSentinelPath(memdir));
+}
+
 /**
  * cmdAdopt — write sentinel section + plugin doc to memdir.
  * Exit code 1 on any hard failure; skipped (--all + UserEditedError) doesn't
@@ -56,6 +74,8 @@ function hasFlag(args, flag) { return Array.isArray(args) && args.includes(flag)
  */
 export function cmdAdopt(args = []) {
   if (hasFlag(args, '--status')) return statusAll();
+  if (hasFlag(args, '--disable')) return cmdDisable(args);
+  if (hasFlag(args, '--enable')) return cmdEnable(args);
 
   const all = hasFlag(args, '--all');
   const force = hasFlag(args, '--force');
@@ -122,14 +142,18 @@ function adoptOne(memdir, { force, dryRun, all }) {
 }
 
 /**
- * silentAutoAdopt — plugin-mode first-run auto-adopt helper (v2.33.0).
+ * silentAutoAdopt — plugin-mode first-run auto-adopt helper (v2.33.0+).
  *
  * Preconditions (caller must gate): CLAUDE_PLUGIN_ROOT set, MEM_NO_AUTO_ADOPT!=1,
- * MEM_QUIET_HOOKS!=1, first-attempt marker absent. This helper does NOT re-check
- * those — it only does the write + marker persistence.
+ * first-attempt marker absent. This helper does NOT re-check those — it only
+ * does the write + marker persistence. (v2.82.0: dropped MEM_QUIET_HOOKS gate;
+ * quiet is a stdout control, not a side-effect control.)
  *
  * Behavior:
- *   - Writes plugin sentinel + detail doc to the memdir for `cwd`.
+ *   - If `<memdir>/.mem-no-auto-adopt` exists: skip silently, do NOT write the
+ *     runtime marker. This keeps `--enable` re-armable: deleting the disable
+ *     sentinel lets the next SessionStart try again.
+ *   - Else: writes plugin sentinel + detail doc to the memdir for `cwd`.
  *   - Writes a per-project first-attempt marker under `markerDir` so a later
  *     `/unadopt` is respected (no re-adopt loop).
  *   - Silent: never logs, never throws. Returns structured result.
@@ -139,6 +163,9 @@ function adoptOne(memdir, { force, dryRun, all }) {
 export function silentAutoAdopt({ cwd, markerDir, markerKey }) {
   const memdir = memdirPath(cwd);
   try {
+    if (isAutoAdoptDisabled(memdir)) {
+      return { ok: true, action: 'disabled', reason: 'disabled-by-sentinel' };
+    }
     if (isAdopted(memdir, PLUGIN_SLUG)) {
       writeMarker(markerDir, markerKey);
       return { ok: true, action: 'already-adopted' };
@@ -173,20 +200,110 @@ export function hasAutoAdoptMarker(markerDir, markerKey) {
   return existsSync(join(markerDir, `.auto-adopt-${markerKey}`));
 }
 
+/**
+ * cmdDisable — `claude-mem-lite adopt --disable [--all]`.
+ *
+ * Writes `<memdir>/.mem-no-auto-adopt` so SessionStart auto-adopt skips this
+ * project permanently. Idempotent: re-running on an already-disabled memdir is
+ * a no-op. Does NOT remove an existing sentinel — pair with `unadopt` if you
+ * want both. The two operations are deliberately separate:
+ *   - `unadopt`      = "remove the contract now"
+ *   - `adopt --disable` = "and don't auto-write it back"
+ */
+function cmdDisable(args) {
+  const all = hasFlag(args, '--all');
+  const targets = all
+    ? listAllMemdirs().map((m) => m.memdir)
+    : [memdirPath(detectCwd())];
+
+  if (targets.length === 0) {
+    log('[adopt --disable] no memdirs found');
+    return;
+  }
+
+  let disabled = 0, already = 0;
+  for (const memdir of targets) {
+    if (!existsSync(memdir)) mkdirSync(memdir, { recursive: true });
+    const path = disableSentinelPath(memdir);
+    if (existsSync(path)) {
+      log(`[adopt --disable] ${memdir} → already-disabled`);
+      already++;
+      continue;
+    }
+    writeFileSync(path, JSON.stringify({ disabledAt: new Date().toISOString() }) + '\n');
+    log(`[adopt --disable] ${memdir} → disabled`);
+    disabled++;
+  }
+
+  log('');
+  log(`[adopt --disable] ${targets.length} target(s): ${disabled} newly disabled, ${already} already disabled`);
+}
+
+/**
+ * cmdEnable — `claude-mem-lite adopt --enable [--all]`.
+ *
+ * Removes the `<memdir>/.mem-no-auto-adopt` sentinel so the next SessionStart
+ * can auto-adopt again. Idempotent. Does NOT trigger an immediate adoption —
+ * run plain `claude-mem-lite adopt` if you want that now.
+ */
+function cmdEnable(args) {
+  const all = hasFlag(args, '--all');
+  const targets = all
+    ? listAllMemdirs().map((m) => m.memdir)
+    : [memdirPath(detectCwd())];
+
+  if (targets.length === 0) {
+    log('[adopt --enable] no memdirs found');
+    return;
+  }
+
+  let enabled = 0, absent = 0;
+  for (const memdir of targets) {
+    const path = disableSentinelPath(memdir);
+    if (!existsSync(path)) {
+      log(`[adopt --enable] ${memdir} → absent`);
+      absent++;
+      continue;
+    }
+    try { unlinkSync(path); } catch { /* best-effort */ }
+    log(`[adopt --enable] ${memdir} → enabled`);
+    enabled++;
+  }
+
+  log('');
+  log(`[adopt --enable] ${targets.length} target(s): ${enabled} re-enabled, ${absent} not-disabled`);
+}
+
 function statusAll() {
   const dirs = listAllMemdirs();
   log('[adopt --status] scanning ~/.claude/projects/*/memory/');
   if (dirs.length === 0) { log('  (no memdirs found)'); return; }
-  let adopted = 0;
+  let adopted = 0, disabled = 0;
   for (const { projectSlug, memdir } of dirs) {
-    if (isAdopted(memdir, PLUGIN_SLUG)) {
+    const isAdoptedHere = isAdopted(memdir, PLUGIN_SLUG);
+    const isDisabledHere = isAutoAdoptDisabled(memdir);
+    if (isAdoptedHere) {
       const idx = readMemoryIndex(memdir, PLUGIN_SLUG);
-      log(`  ✓ ${projectSlug} (${idx.version})`);
+      const suffix = isDisabledHere ? ' [auto-adopt disabled]' : '';
+      log(`  ✓ ${projectSlug} (${idx.version})${suffix}`);
       adopted++;
+      if (isDisabledHere) disabled++;
+    } else if (isDisabledHere) {
+      log(`  ✗ ${projectSlug} (auto-adopt disabled, no sentinel)`);
+      disabled++;
     }
   }
   log('');
-  log(`[adopt --status] ${adopted}/${dirs.length} adopted`);
+  log(`[adopt --status] ${adopted}/${dirs.length} adopted${disabled > 0 ? `, ${disabled} disabled` : ''}`);
+
+  // Gating snapshot — helps debug "why didn't auto-adopt fire?"
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ? 'set' : 'unset';
+  const noAutoAdopt = process.env.MEM_NO_AUTO_ADOPT === '1' ? '1 (opt-out)' : 'unset';
+  log('');
+  log('Auto-adopt gates (next SessionStart will fire only if both pass):');
+  log(`  CLAUDE_PLUGIN_ROOT  = ${pluginRoot}  (plugin-mode install required; npx stays opt-in)`);
+  log(`  MEM_NO_AUTO_ADOPT   = ${noAutoAdopt}  (global escape hatch)`);
+  log('Per-project opt-out: `claude-mem-lite adopt --disable` (run --enable to re-arm).');
 }
 
 /**

package/hook-memory.mjs

@@ -2,6 +2,7 @@
 // Search past observations for relevant memories to inject as context at user-prompt time.
 
 import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, truncate, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords } from './utils.mjs';
+import { citeFactorJs } from './scoring-sql.mjs';
 import { recordMetric } from './lib/metrics.mjs';
 import { DB_DIR } from './schema.mjs';
 
@@ -163,6 +164,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     const selectStmt = db.prepare(`
       SELECT o.id, o.type, o.title, o.subtitle, o.narrative, o.importance, o.lesson_learned, o.project,
              o.created_at_epoch, o.files_modified,
+             o.cited_count, o.uncited_streak,
              ${OBS_BM25} as relevance,
              ${noisePenaltyClause('o')} as noise_penalty
       FROM observations_fts
@@ -200,6 +202,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     try {
       const crossStmt = db.prepare(`
         SELECT o.id, o.type, o.title, o.subtitle, o.narrative, o.importance, o.lesson_learned, o.project,
+               o.cited_count, o.uncited_streak,
                ${OBS_BM25} as relevance,
                ${noisePenaltyClause('o')} as noise_penalty
         FROM observations_fts
@@ -241,6 +244,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
         const crossProjectPenalty = r.project === project ? 1.0 : crossPenalty;
         const orFallbackPenalty = r._or ? 0.4 : 1.0;
         const noisePenalty = typeof r.noise_penalty === 'number' ? r.noise_penalty : 1.0;
+        const citeFactor = citeFactorJs(r);
         return {
           ...r,
           score: Math.abs(r.relevance)
@@ -249,7 +253,8 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
             * (r.importance >= 2 ? 1.0 : 0.6)
             * crossProjectPenalty
             * orFallbackPenalty
-            * noisePenalty,
+            * noisePenalty
+            * citeFactor,
         };
       })
       .sort((a, b) => b.score - a.score);

package/hook.mjs

@@ -61,7 +61,7 @@ import { checkForUpdate } from './hook-update.mjs';
 import { handleLLMOptimize } from './hook-optimize.mjs';
 import { silentAutoAdopt, hasAutoAdoptMarker } from './adopt-cli.mjs';
 import { emitV270UpgradeBanner } from './lib/upgrade-banner.mjs';
-import { loadCiteBackForEpisode } from './lib/cite-back-hint.mjs';
+import { loadCiteBackForEpisode, buildUnsavedBugfixHint } from './lib/cite-back-hint.mjs';
 // plugin-cache-guard.mjs loaded dynamically — pre-2.31.2 installs that auto-upgraded
 // from an older hook-update.mjs SOURCE_FILES (which did not list this module) would
 // crash on static import. Degrade gracefully to no-op when the module is absent.
@@ -181,8 +181,6 @@ function flushEpisode(episode, hookEventName = 'PostToolUse') {
     if (RECEIPT_EVENTS.has(hookEventName)) {
       try {
         const entries = episode.entries || [];
-        const hasError = entries.some(e => e.isError);
-        const hasEdit = entries.some(e => EDIT_TOOLS.has(e.tool));
         const toolCounts = {};
         for (const e of entries) toolCounts[e.tool] = (toolCounts[e.tool] || 0) + 1;
         const toolSummary = Object.entries(toolCounts)
@@ -191,16 +189,14 @@ function flushEpisode(episode, hookEventName = 'PostToolUse') {
           .map(([t, n]) => `${t}×${n}`)
           .join(', ');
         const lines = [`[mem] episode flushed: ${entries.length} entries (${toolSummary})`];
-        if (hasError && hasEdit && entries.length >= 3) {
-          const editFiles = entries.filter(e => EDIT_TOOLS.has(e.tool)).flatMap(e => e.files || []);
-          const uniqueFiles = [...new Set(editFiles)].slice(0, 3);
-          const filesHint = uniqueFiles.length > 0 ? ` (${uniqueFiles.join(', ')})` : '';
-          lines.push(`[mem] 💡 error→fix pattern${filesHint} — consider: mem_save(type="bugfix", lesson_learned="<root cause + fix>")`);
-        }
+        // v2.83: error→fix nudge lifted to lib/cite-back-hint.mjs::buildUnsavedBugfixHint
+        // so the wording (count + "Save now" verb) stays in sync with cite-back.
+        const bugfixHint = buildUnsavedBugfixHint(episode);
+        if (bugfixHint) lines.push(bugfixHint);
         // v2.81: cite-back hint — fires when this episode edits a file that
         // PreToolUse:Read/Edit nudged earlier in the same session. Precision
         // signal (we know the file was warned about); orthogonal to the
-        // error→fix pattern above and may co-fire.
+        // bugfix-shape nudge above and may co-fire.
         const citeBack = loadCiteBackForEpisode(episode, RUNTIME_DIR);
         if (citeBack) lines.push(citeBack);
         process.stdout.write(JSON.stringify({
@@ -652,22 +648,27 @@ async function handleSessionStart() {
     }
   } catch (e) { debugCatch(e, 'session-start-cache-heal'); }
 
-  // v2.33.0: plugin-mode first-run auto-adopt. /plugin install IS consent to
-  // integration — writing the MEMORY.md sentinel once per project on first
-  // SessionStart avoids the opt-in friction. Scope is narrow:
-  //   - gated by CLAUDE_PLUGIN_ROOT (npm/npx installs stay opt-in)
-  //   - gated by !MEM_NO_AUTO_ADOPT (explicit escape hatch)
-  //   - gated by !MEM_QUIET_HOOKS (quiet = no side-effects semantics)
+  // First-run auto-adopt (v2.33.0 plugin-mode → v2.82.1 install-mode-agnostic).
+  // ANY install path — `/plugin install`, `npm install -g`, `npx`, manual — is
+  // consent to integration. Writing the MEMORY.md sentinel once per project on
+  // first SessionStart avoids the opt-in friction that left ~zero users on
+  // auto-adopt (runtime-marker directory was empty machine-wide despite v2.33
+  // shipping ~5 weeks earlier — `install.mjs`-written hooks don't propagate
+  // ${CLAUDE_PLUGIN_ROOT}, so the v2.33.0 gate was a no-op for npm/manual
+  // installs, which is most of them). Scope is now:
+  //   - gated by !MEM_NO_AUTO_ADOPT (explicit global escape hatch)
+  //   - per-project opt-out via `<memdir>/.mem-no-auto-adopt` sentinel
+  //     (managed by `claude-mem-lite adopt --disable / --enable`); checked
+  //     inside silentAutoAdopt so the helper is safe to call directly too.
   //   - first-attempt marker persists in RUNTIME_DIR so a subsequent /unadopt
   //     is respected (no re-adopt loop).
+  // Note v2.82.0: removed MEM_QUIET_HOOKS gate. That env var suppresses stdout
+  // noise; it must NOT also disable side-effect work (PostToolUse writes the
+  // DB unconditionally — auto-adopt should follow the same rule).
   // Failures (user-edited sentinel, budget exceeded, FS errors) are swallowed;
   // the marker is still written so we don't retry on every SessionStart.
   try {
-    if (
-      process.env.CLAUDE_PLUGIN_ROOT
-      && process.env.MEM_NO_AUTO_ADOPT !== '1'
-      && process.env.MEM_QUIET_HOOKS !== '1'
-    ) {
+    if (process.env.MEM_NO_AUTO_ADOPT !== '1') {
       const project = inferProject();
       if (!hasAutoAdoptMarker(RUNTIME_DIR, project)) {
         const cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();

package/lib/cite-back-hint.mjs

@@ -41,15 +41,60 @@ export function buildCiteBackHint(episode, cooldown) {
 
   if (matches.length === 0) return null;
 
-  const lines = ['[mem] 💡 Cite-back: you edited file(s) that received PreToolUse lessons this session.'];
+  // B1 (v2.83): leader line carries explicit counts (file count + total lesson
+  // count) and a directive verb. Pre-v2.83 wording "if you fixed it" was
+  // routinely treated as advisory and ignored — cite-recall data showed the
+  // hint firing without follow-up `/lesson` calls. §10 Specificity binds:
+  // numeric framing is measurably harder to dismiss than a hedged hint.
+  const totalLessons = matches.reduce((sum, m) => sum + m.ids.length, 0);
+  const lines = [
+    `[mem] ⚠ Cite-back: edited ${matches.length} file(s) with ${totalLessons} prior lesson(s) this session. Save now if any was the root cause:`,
+  ];
   for (const m of matches) {
     const fname = basename(m.file);
     const idList = m.ids.map(id => `#${id}`).join(', ');
-    lines.push(`  • ${fname} ← ${idList} — if you fixed it: /lesson --file ${fname} "<root cause + fix>"`);
+    lines.push(`  • ${fname} ← ${idList} — /lesson --file ${fname} "<root cause + fix>"`);
   }
   return lines.join('\n');
 }
 
+// B1 (v2.83): structured per-episode "tricky fix just happened" detector. Lifts
+// the inline error→fix nudge that used to live in hook.mjs flushEpisode into
+// the lib so all save-prompt hints share one home + the same wording rules.
+//
+// Detection (mirrors pre-v2.83 hook.mjs:194 heuristic):
+//   • has at least one entry with isError=true
+//   • has at least one entry using an edit tool
+//   • entries.length >= 3 (rules out single-typo fixes that don't need a lesson)
+// Returns null when any condition fails or when no edited files are recoverable
+// from the entry list (defensive — episodes flushed mid-tool can have empties).
+const MIN_BUGFIX_ENTRIES = 3;
+const MAX_DISPLAY_FILES = 3;
+
+export function buildUnsavedBugfixHint(episode) {
+  if (!episode) return null;
+  const entries = episode.entries;
+  if (!Array.isArray(entries) || entries.length < MIN_BUGFIX_ENTRIES) return null;
+
+  let hasError = false;
+  let hasEdit = false;
+  const editedFiles = new Set();
+  for (const e of entries) {
+    if (!e) continue;
+    if (e.isError) hasError = true;
+    if (EDIT_TOOLS.has(e.tool)) {
+      hasEdit = true;
+      for (const f of e.files || []) editedFiles.add(f);
+    }
+  }
+  if (!hasError || !hasEdit || editedFiles.size === 0) return null;
+
+  const files = [...editedFiles];
+  const displayed = files.slice(0, MAX_DISPLAY_FILES).map(f => basename(f));
+  const firstFname = basename(files[0]);
+  return `[mem] ⚠ Unsaved bugfix-shape: error+edit across ${files.length} file(s) in ${entries.length} entries (${displayed.join(', ')}). Save now if it was a real fix: /lesson --file ${firstFname} "<root cause + fix>"`;
+}
+
 // Path scheme MUST mirror scripts/pre-tool-recall.js cooldownPathFor() — drift
 // silently zeros cite-back across the release. Pinned by tests/cite-back-hint.test.mjs
 // 'sanitizes the sessionId the same way pre-tool-recall.js does'.

package/package.json

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

package/scoring-sql.mjs

@@ -126,3 +126,52 @@ export function noisePenaltyClause(alias = 'o') {
 export function notLowSignalTitleClause(alias = 'o') {
   return buildNotLowSignalSql(alias);
 }
+
+// ─── Cite-history factor (A1, v2.83) ────────────────────────────────────────
+//
+// Closes the citation-decay → ranking loop. The Stop hook citation-decay
+// already maintains cited_count (Promote on cite) and uncited_streak (bump on
+// uncited; reset on cite or demote-at-3). Before A1, both columns affected
+// only the importance ±1 dial — through `(0.5 + 0.5·importance)` that's a
+// ≤2× swing and saturates fast. This factor lets ranking respond directly to
+// observed agent behavior on the obs itself.
+//
+// Formula: clamp(0.4, 3.0, 1 + 0.2·cited_count − 0.25·uncited_streak)
+// Distribution:
+//   cited=0, streak=0  → 1.0  (fresh obs, neutral)
+//   cited=5, streak=0  → 2.0
+//   cited≥10, streak=0 → 3.0  (capped — one viral obs can't dominate)
+//   cited=0, streak=2  → 0.5
+//   cited=0, streak=3+ → 0.4  (floored; citation-decay resets streak at 3
+//                              after demoting importance, so steady-state
+//                              streak is bounded by [0,2])
+//
+// Disjoint from noisePenaltyClause: noise penalty uses
+// `injection_count vs access_count` (passive inject vs any access);
+// cite_factor uses `cited_count vs uncited_streak` — same-source signal
+// maintained only by the citation-decay loop. Both apply multiplicatively;
+// order doesn't affect ORDER BY relevance ASC.
+export const CITE_FACTOR_MIN = 0.4;
+export const CITE_FACTOR_MAX = 3.0;
+export const CITE_FACTOR_PER_CITE = 0.2;
+export const CITE_FACTOR_PER_STREAK = 0.25;
+
+export function citeFactorClause(alias = 'o') {
+  const a = alias ? `${alias}.` : '';
+  return `(
+    MAX(${CITE_FACTOR_MIN},
+      MIN(${CITE_FACTOR_MAX},
+        1.0
+          + ${CITE_FACTOR_PER_CITE} * COALESCE(${a}cited_count, 0)
+          - ${CITE_FACTOR_PER_STREAK} * COALESCE(${a}uncited_streak, 0)
+      )
+    )
+  )`;
+}
+
+export function citeFactorJs(row) {
+  const cited = (row && typeof row.cited_count === 'number') ? row.cited_count : 0;
+  const streak = (row && typeof row.uncited_streak === 'number') ? row.uncited_streak : 0;
+  const raw = 1.0 + CITE_FACTOR_PER_CITE * cited - CITE_FACTOR_PER_STREAK * streak;
+  return Math.max(CITE_FACTOR_MIN, Math.min(CITE_FACTOR_MAX, raw));
+}

package/scripts/pre-tool-recall.js

@@ -16,6 +16,12 @@ import { recordHookError } from '../lib/hook-telemetry.mjs';
 const DATA_DIR = process.env.CLAUDE_MEM_DIR || join(homedir(), '.claude-mem-lite');
 const DB_PATH = process.env.CLAUDE_MEM_DB_PATH || join(DATA_DIR, 'claude-mem-lite.db');
 const RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || join(DATA_DIR, 'runtime');
+// A3 (v2.83): cross-hook dedup window — must mirror DEDUP_STALE_MS in
+// scripts/prompt-search-utils.mjs. UPS writes
+// `runtime/.claude-mem-injected-<project>` after each inject; we read it to
+// drop IDs the agent already saw in this 5-min window. Standalone fast-path
+// (#8447) so we inline the constant rather than importing the helper.
+const CROSS_HOOK_DEDUP_MS = 5 * 60 * 1000;
 // v2.33.1: cooldown path is session-scoped so same-file-twice within one
 // session never re-injects (was: global file, 5-min window). Cross-session:
 // fresh file, fresh nudges — this is intended. No session_id → fall back to
@@ -58,6 +64,50 @@ function entryTimestamp(v) {
   return 0;
 }
 
+// A3 (v2.83): cross-hook injected-IDs store. UPS writes
+// `runtime/.claude-mem-injected-<project>` with {ids, ts, count}. We read
+// inside the staleness window, filter overlaps from PreToolUse output, then
+// merge back so the next UPS sees what we emitted too.
+function crossHookInjectedFile(project) {
+  return join(RUNTIME_DIR, `.claude-mem-injected-${project}`);
+}
+
+function readCrossHookInjected(project) {
+  try {
+    const raw = readFileSync(crossHookInjectedFile(project), 'utf8');
+    const { ids, ts } = JSON.parse(raw);
+    if (!ts || Date.now() - ts > CROSS_HOOK_DEDUP_MS) return new Set();
+    if (!Array.isArray(ids)) return new Set();
+    return new Set(ids.map(String));
+  } catch { return new Set(); }
+}
+
+function mergeCrossHookInjected(project, newIds) {
+  if (!newIds || newIds.length === 0) return;
+  try {
+    mkdirSync(RUNTIME_DIR, { recursive: true });
+    const file = crossHookInjectedFile(project);
+    let prev = { ids: [], ts: 0, count: 0 };
+    try {
+      const raw = readFileSync(file, 'utf8');
+      const parsed = JSON.parse(raw);
+      // Within the staleness window: union. Outside: replace (fresh session).
+      if (parsed.ts && Date.now() - parsed.ts < CROSS_HOOK_DEDUP_MS) {
+        prev = parsed;
+      }
+    } catch { /* fresh file */ }
+    const ids = [...new Set([
+      ...(Array.isArray(prev.ids) ? prev.ids.map(String) : []),
+      ...newIds.map(String),
+    ])];
+    writeFileSync(file, JSON.stringify({
+      ids,
+      ts: Date.now(),
+      count: (prev.count || 0) + 1,
+    }));
+  } catch { /* silent — dedup is best-effort */ }
+}
+
 function writeCooldown(cooldownPath, data, isSessionScoped) {
   try {
     mkdirSync(RUNTIME_DIR, { recursive: true });
@@ -228,10 +278,20 @@ try {
       `).all(project, cutoff, `%"${fnameEscaped}"%`, `%"${filePathEscaped}"%`);
     } catch { /* events table may not exist on pre-v2.31 DBs — silent */ }
 
+    // A3 (v2.83): cross-hook dedup. UPS may have already injected some of
+    // these obs ids this prompt — re-emitting wastes the PreToolUse slot
+    // (and inflates context). Drop ids found in the cross-hook injected file
+    // inside the staleness window; keep file-cooldown unchanged (the same
+    // file might also re-warrant a different lesson next session).
+    const crossHookSeen = readCrossHookInjected(project);
+    const dedupedRows = crossHookSeen.size > 0
+      ? [...rows, ...eventRows].filter(r => !crossHookSeen.has(String(r.id)))
+      : [...rows, ...eventRows];
+
     // Merge: observations first (they carry richer lesson_learned), then events.
     // Edit/Write caps at 3 total; Read caps at 1 (single most-actionable hit).
     const mergeCap = isRead ? 1 : 3;
-    const allRows = [...rows, ...eventRows].slice(0, mergeCap);
+    const allRows = dedupedRows.slice(0, mergeCap);
 
     // v2.31 T2: emit JSON with hookSpecificOutput.additionalContext so the message
     // reliably renders across CC variants (sdscc drops plain-text stdout from PreToolUse).
@@ -291,6 +351,11 @@ try {
     // file. Empty array on no-lesson branches keeps the schema uniform.
     cooldown[filePath] = { ts: now, lessonIds: allRows.map(r => r.id) };
     writeCooldown(cooldownPath, cooldown, isSessionScoped);
+    // A3 (v2.83): merge our newly-emitted IDs into the cross-hook injected
+    // file so the next UPS prompt skips them too. Always write, even on
+    // empty allRows, so the file's ts stays fresh for the no-op case where
+    // we'd otherwise drift outside the dedup window.
+    mergeCrossHookInjected(project, allRows.map(r => r.id));
   } catch (e) {
     // Silent failure — never block editing, but record for self-observation.
     recordHookError('pre-recall:query', e, RUNTIME_DIR, { filePath });

package/scripts/user-prompt-search.js

@@ -5,6 +5,7 @@
 
 import { ensureDb, DB_DIR, REGISTRY_DB_PATH } from '../schema.mjs';
 import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, OBS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, notLowSignalTitleClause, noisePenaltyClause, stripPrivate } from '../utils.mjs';
+import { citeFactorClause } from '../scoring-sql.mjs';
 import { cjkPrecisionOk } from '../nlp.mjs';
 import { writeFileSync, readFileSync, existsSync, renameSync } from 'fs';
 import { join } from 'path';
@@ -216,6 +217,11 @@ function searchByFts(db, queryText, project, limit, typeFilter) {
   // v26 P0: noise penalty shrinks relevance magnitude for obs with high
   // inject:access ratio (auto-injected often, never cited/opened). See
   // docs/p0-injection-noise-baseline.txt.
+  // A1 (v2.83): cite_factor closes the citation-decay → ranking loop. Obs the
+  // assistant cited in past sessions (cited_count > 0) get boosted; obs with
+  // accumulating uncited_streak get dampened upstream of importance-decay.
+  // Disjoint signal from noise_penalty (which uses injection_count vs
+  // access_count) — see scoring-sql.mjs::citeFactorClause for the math.
   const sql = `
     SELECT o.id, o.type, o.title, o.lesson_learned,
            ${OBS_BM25} as bm25_raw,
@@ -223,7 +229,8 @@ function searchByFts(db, queryText, project, limit, typeFilter) {
              * (1.0 + EXP(-0.693 * (? - o.created_at_epoch) / ${TYPE_DECAY_CASE}))
              * ${TYPE_QUALITY_CASE}
              * (0.5 + 0.5 * COALESCE(o.importance, 1))
-             * ${noisePenaltyClause('o')} as relevance
+             * ${noisePenaltyClause('o')}
+             * ${citeFactorClause('o')} as relevance
     FROM observations_fts
     JOIN observations o ON o.id = observations_fts.rowid
     WHERE observations_fts MATCH ?