claude-mem-lite 2.31.2 → 2.32.2

package/.claude-plugin/marketplace.json

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

package/README.md

@@ -92,6 +92,7 @@ The original sends **everything to the LLM and hopes it filters well**. claude-m
 - **Prompt-time memory injection** -- UserPromptSubmit hook automatically searches and injects relevant past observations with recency and importance weighting
 - **Smart skill invocation** -- Auto-loaded and searched managed skills/agents include portable `~` paths with `Read()` guidance; native plugin skills recommend `Skill("full:name")`; prevents `Skill()` misuse for managed resources that aren't registered with Claude Code's native handler
 - **Dual injection dedup** -- `user-prompt-search.js` and `handleUserPrompt` coordinate via temp file to prevent duplicate memory injection
+- **Plugin cache hook self-heal** -- Claude Code runtime reads plugin hooks from `~/.claude/plugins/cache/<mp>/<plugin>/<ver>/hooks/hooks.json`, not from the marketplace source. When `install.mjs`-managed `settings.json` hooks coexist with a stale cache `hooks.json` (e.g. from a previous marketplace install or a plugin auto-update), the runtime registers hooks twice → every session start / user prompt fires twice. `install.mjs` and `hook-update.mjs` now clear cache `hooks.json` in every version dir, and `hook.mjs session-start` self-heals on every session (gated by `hasInstallManagedHooks` so plugin-only users are not affected). `install.mjs status` reports cache pollution state (since v2.31.1/2.31.2).
 - **Result-dedup cooldown** -- User-prompt memory injection uses result-overlap detection (>80% ID overlap → skip) instead of time-based cooldown, allowing topic switches within seconds while preventing redundant injections
 - **OR query fallback** -- When AND-joined FTS5 queries return zero results, automatically relaxes to OR-joined queries for broader recall (applied in both user-prompt-search and hook-memory paths)
 - **Configurable LLM model** -- Switch between Haiku (fast/cheap) and Sonnet (deeper analysis) via `CLAUDE_MEM_MODEL` env var
@@ -101,6 +102,9 @@ The original sends **everything to the LLM and hopes it filters well**. claude-m
 - **LLM concurrency control** -- File-based semaphore limits background workers to 2 concurrent LLM calls, preventing resource contention
 - **stdin overflow protection** -- Hook input truncated at 256KB with regex-based action salvage for oversized tool outputs
 - **Cross-session handoff** -- Captures session state (request, completed work, next steps, key files) on `/clear` or `/exit`, then injects context when the next session detects continuation intent via explicit keywords or FTS5 term overlap
+- **Git-SHA continuation anchor** (v2.31.0) -- Handoff rows include `git_sha_at_handoff`; any handoff matching the current `HEAD` counts as continuation regardless of TTL. Code state is a stronger continuation signal than wall-clock time
+- **Startup dashboard** (v2.31.0) -- SessionStart hook aggregates `git status` + `~/.claude/tasks/*.json` + `~/.claude/plans/*.md` + most-recent exit handoff + recent event count into a single structured block injected via `hookSpecificOutput.additionalContext`
+- **Activity namespace** (v2.31.0) -- Dedicated `events` table + FTS5 for non-memdir types (`bugfix`, `lesson`, `bug`, `discovery`, `refactor`, `feature`, `observation`, `decision`) that don't compete with `WHAT_NOT_TO_SAVE` semantics on the observations table. CLI: `claude-mem-lite activity save|search|recent|show`. Slash commands: `/lesson`, `/bug`. `hook-llm` routes non-memdir summary types through `persistHaikuSummary` so upgrades from observations→events are atomic
 - **In-place observation updates** -- `mem_update` tool modifies existing observations atomically (field update + FTS text rebuild + vector re-computation in one transaction), preserving original IDs and references
 - **Bulk export** -- `mem_export` tool exports observations as JSON or JSONL, with project/type/date filtering and 1000-row pagination cap with batch guidance
 - **FTS integrity management** -- `mem_fts_check` tool verifies FTS5 index health or rebuilds indexes on demand, useful after database recovery or when search results seem wrong
@@ -235,6 +239,8 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
 /mem timeline <query>      # Browse timeline around a match
 /mem browse                # Tier-grouped memory dashboard
 /mem <query>               # Shorthand for search
+/lesson <text>             # Save a non-obvious lesson to the events table (v2.31.0)
+/bug <text>                # Log a known bug + repro steps to the events table (v2.31.0)
 ```
 
 ### Efficient Search Workflow
@@ -245,6 +251,48 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
 3. mem_get(ids=[12345, 12346])      -> full details
 ```
 
+### Invited Memory (v2.32+)
+
+Opt-in mechanism that installs a single sentinel-wrapped line into the project's
+memdir (`~/.claude/projects/<encoded>/memory/MEMORY.md`) so Claude Code loads
+the plugin's MCP-tool triggers as **user-memory** — a higher instruction-following
+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 --dry-run    # preview without writing
+claude-mem-lite unadopt            # remove cleanly
+```
+
+Slash commands `/adopt` and `/unadopt` wrap the same CLI.
+
+**What adoption changes:**
+- A `<!-- claude-mem-lite:begin v1 -->…<!-- claude-mem-lite:end -->` block is
+  added to `MEMORY.md` under a `## 插件契约` header, containing one ≤150-char
+  line pointing at `mem_recall` / `mem_save` with their key arguments.
+- A `plugin_claude_mem_lite.md` detail file is written (not auto-loaded; read
+  on demand when the MEMORY.md pointer surfaces in context).
+- Post-adopt the conservative hook layer auto-trims: MCP server instructions
+  drop the `WHEN TO USE` section, SessionStart injection drops the `File Lessons`
+  / `Key Context` sections. `#ID` references and the `Recent` table still fire
+  so `mem_get` remains reachable.
+
+**Safety:**
+- Hash-guarded: editing the sentinel body yourself blocks automatic rewrites
+  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.
+- 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.
+
+See `docs/plans/2026-04-16-invited-memory-pattern.md` for the full design
+(including the reusable template other plugins can follow).
+
 ## Database Schema
 
 Five core tables with FTS5 virtual tables for search:
@@ -523,6 +571,8 @@ 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)_ |
 
 ## License
 

package/README.zh-CN.md

@@ -94,6 +94,10 @@
 - **LLM 并发控制** -- 基于文件的信号量将后台 worker 限制为 2 个并发 LLM 调用，防止资源争用
 - **stdin 溢出保护** -- Hook 输入在 256KB 处截断，对超大工具输出使用正则挽救关键信息
 - **跨会话交接** -- 在 `/clear` 或 `/exit` 时捕获会话状态（请求、已完成工作、后续步骤、关键文件），下次会话检测到继续意图时自动注入上下文（支持显式关键词和 FTS5 术语重叠匹配）
+- **插件缓存 hook 自愈** -- Claude Code runtime 从 `~/.claude/plugins/cache/<mp>/<plugin>/<ver>/hooks/hooks.json` 读取插件 hook，而非 marketplace 源。当 `install.mjs` 写入 `settings.json` 的 hooks 与残留 cache `hooks.json` 同时存在（例如曾装过 marketplace 版本，或插件被 Claude Code 自动升级重建 cache），runtime 会注册两套 hook → 每次 SessionStart / UserPromptSubmit 都触发两份。`install.mjs` 和 `hook-update.mjs` 现在会清理每个 cache 版本目录下的 `hooks.json`；`hook.mjs session-start` 每次启动自愈（通过 `hasInstallManagedHooks` 门控，不影响纯插件模式用户）；`install.mjs status` 会报告 cache 污染状况（自 v2.31.1 / v2.31.2 起）。
+- **Git-SHA 延续锚点**（v2.31.0）-- handoff 记录包含 `git_sha_at_handoff` 字段，任何匹配当前 `HEAD` 的 handoff 都视为延续会话，不受 TTL 限制。代码状态比时钟时间更能反映上下文延续。
+- **启动面板**（v2.31.0）-- SessionStart hook 将 `git status` + `~/.claude/tasks/*.json` + `~/.claude/plans/*.md` + 最近 /exit 交接 + 最近事件数聚合为一个结构化块，通过 `hookSpecificOutput.additionalContext` 注入。
+- **活动命名空间**（v2.31.0）-- 为非 memdir 类型（`bugfix` / `lesson` / `bug` / `discovery` / `refactor` / `feature` / `observation` / `decision`）启用独立的 `events` 表 + FTS5，与 observations 表的 `WHAT_NOT_TO_SAVE` 语义解耦。CLI：`claude-mem-lite activity save|search|recent|show`；斜杠命令：`/lesson`、`/bug`。`hook-llm` 通过 `persistHaikuSummary` 路由非 memdir 摘要，observations → events 升级路径是事务原子的。
 
 ## 平台支持
 
@@ -222,6 +226,8 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
 /mem timeline <query>      # 围绕匹配结果浏览时间线
 /mem browse                # 分层记忆仪表盘
 /mem <query>               # search 的简写
+/lesson <text>             # 保存非显而易见的经验到 events 表（v2.31.0）
+/bug <text>                # 记录已知 bug + 复现步骤到 events 表（v2.31.0）
 ```
 
 ### 高效搜索工作流
@@ -232,6 +238,44 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
 3. mem_get(ids=[12345, 12346])      -> 完整详情
 ```
 
+### Invited Memory（邀请式记忆，v2.32+）
+
+Opt-in 机制——向项目 memdir（`~/.claude/projects/<encoded>/memory/MEMORY.md`）
+注入单行 sentinel 包围的插件契约，Claude Code 会把它作为 **user-memory** 加载
+到系统提示——比 MCP server instructions（被框定为 tool metadata）具有更高的
+instruction-following 权威。
+
+```bash
+claude-mem-lite adopt              # 当前项目注入
+claude-mem-lite adopt --all        # 扫描 ~/.claude/projects/* 全部注入
+claude-mem-lite adopt --status     # 列出所有已 adopt 的项目 + 版本号
+claude-mem-lite adopt --dry-run    # 只打印不写入
+claude-mem-lite unadopt            # 精确移除
+```
+
+Slash 命令 `/adopt` 和 `/unadopt` 是上述 CLI 的包装。
+
+**Adopt 后会发生什么：**
+- `MEMORY.md` 新增一段 `<!-- claude-mem-lite:begin v1 -->…<!-- claude-mem-lite:end -->`
+  包裹的 `## 插件契约`，含一行 ≤150 字符、指向 `mem_recall` / `mem_save` 关键参数
+  的动作锚条目。
+- 生成 `plugin_claude_mem_lite.md` 详情文件（按需读取，不自动加载）。
+- 保守 hook 层自动瘦身：MCP server instructions 去掉 `WHEN TO USE` 段，
+  SessionStart 注入去掉 `File Lessons` / `Key Context`。`#ID` 引用与 `Recent`
+  表保留，`mem_get` 仍可随时展开。
+
+**安全性：**
+- Hash 守护：你手动改了 sentinel 段 → 下一次 adopt 报 `UserEditedError`，
+  除非显式 `--force`。
+- 预算门：MEMORY.md 已 >180 行时拒绝新增（避开 Claude Code 200 行截断）。
+- `install` 只在从 claude-mem-lite 源码仓库运行时 auto-adopt（靠 git remote 判别）；
+  其它用户需显式调用。
+- 保守 hook 层源码永不删——条件瘦身仅基于 sentinel 存在性做 runtime 判断，
+  未 adopt 的项目仍看完整 verbose 输出。
+
+完整设计见 `docs/plans/2026-04-16-invited-memory-pattern.md`（含其它插件
+可复用的模板）。
+
 ## 数据库结构
 
 五张核心表 + FTS5 虚拟表用于搜索：
@@ -500,6 +544,8 @@ 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 的情况下也能静音。 | _(禁用)_ |
 
 ## 许可证
 

package/adopt-cli.mjs

@@ -0,0 +1,166 @@
+// Phase C (Invited-Memory plan, T11): CLI handlers for
+//   claude-mem-lite adopt [--all] [--force] [--dry-run] [--status]
+//   claude-mem-lite unadopt [--all]
+//
+// adopt = write sentinel section into MEMORY.md + drop plugin_claude_mem_lite.md
+// unadopt = precise sentinel removal + doc cleanup
+// --all  = scan every project under ~/.claude/projects/*/memory/
+// --force = override UserEditedError
+// --dry-run = print intent without writing
+// --status = list all adopted projects + versions
+
+import { existsSync, readdirSync, statSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import {
+  memdirPath, writePluginSection, removePluginSection,
+  writePluginDoc, removePluginDoc,
+  isAdopted, readMemoryIndex,
+  UserEditedError, BudgetExceededError,
+} from './memdir.mjs';
+import {
+  PLUGIN_SLUG, CURRENT_SENTINEL_VERSION, getIndexLine, getDetailDoc,
+} from './adopt-content.mjs';
+
+function log(msg) { console.log(msg); }
+
+function detectCwd() {
+  return process.env.CLAUDE_PROJECT_DIR || process.env.PWD || process.cwd();
+}
+
+function projectsRoot() {
+  return join(homedir(), '.claude', 'projects');
+}
+
+function listAllMemdirs() {
+  const base = projectsRoot();
+  if (!existsSync(base)) return [];
+  const out = [];
+  for (const name of readdirSync(base)) {
+    const memdir = join(base, name, 'memory');
+    try {
+      if (existsSync(memdir) && statSync(memdir).isDirectory()) {
+        out.push({ projectSlug: name, memdir });
+      }
+    } catch { /* ignore entries we can't stat */ }
+  }
+  return out;
+}
+
+function hasFlag(args, flag) { return Array.isArray(args) && args.includes(flag); }
+
+/**
+ * cmdAdopt — write sentinel section + plugin doc to memdir.
+ * Exit code 1 on any hard failure; skipped (--all + UserEditedError) doesn't
+ * fail the batch.
+ */
+export function cmdAdopt(args = []) {
+  if (hasFlag(args, '--status')) return statusAll();
+
+  const all = hasFlag(args, '--all');
+  const force = hasFlag(args, '--force');
+  const dryRun = hasFlag(args, '--dry-run');
+
+  const targets = all
+    ? listAllMemdirs().map((m) => m.memdir)
+    : [memdirPath(detectCwd())];
+
+  if (targets.length === 0) {
+    log('[adopt] no memdirs to adopt (use without --all for current project)');
+    return;
+  }
+
+  let created = 0, updated = 0, unchanged = 0, skipped = 0, failed = 0;
+  for (const memdir of targets) {
+    const r = adoptOne(memdir, { force, dryRun, all });
+    if (r.action === 'created') created++;
+    else if (r.action === 'updated') updated++;
+    else if (r.action === 'unchanged') unchanged++;
+    else if (r.action === 'skipped') skipped++;
+    else if (r.action === 'dry-run') unchanged++;
+    else failed++;
+  }
+
+  log('');
+  log(`[adopt] ${targets.length} target(s): ${created} created, ${updated} updated, ${unchanged} unchanged, ${skipped} skipped, ${failed} failed`);
+  if (failed > 0) process.exitCode = 1;
+}
+
+function adoptOne(memdir, { force, dryRun, all }) {
+  const contentLine = getIndexLine();
+  const version = CURRENT_SENTINEL_VERSION;
+
+  if (dryRun) {
+    log(`[adopt --dry-run] ${memdir}`);
+    log(`  MEMORY.md line: ${contentLine}`);
+    log(`  detail file:    plugin_claude_mem_lite.md (${getDetailDoc().length} chars)`);
+    return { action: 'dry-run' };
+  }
+
+  try {
+    const r = writePluginSection(memdir, { slug: PLUGIN_SLUG, version, contentLine, force });
+    writePluginDoc(memdir, PLUGIN_SLUG, getDetailDoc());
+    log(`[adopt] ${memdir} → ${r.action}`);
+    return r;
+  } catch (e) {
+    if (e instanceof UserEditedError && all) {
+      log(`[adopt] ${memdir} → skipped (user-edited; pass --force to override)`);
+      return { action: 'skipped' };
+    }
+    if (e instanceof UserEditedError) {
+      log(`[adopt] ${memdir} → refused: ${e.message}`);
+      log('[adopt] pass --force to overwrite, or edit/uninstall manually.');
+      return { action: 'failed' };
+    }
+    if (e instanceof BudgetExceededError) {
+      log(`[adopt] ${memdir} → failed: ${e.message}`);
+      return { action: 'failed' };
+    }
+    log(`[adopt] ${memdir} → error: ${e.message}`);
+    return { action: 'failed' };
+  }
+}
+
+function statusAll() {
+  const dirs = listAllMemdirs();
+  log('[adopt --status] scanning ~/.claude/projects/*/memory/');
+  if (dirs.length === 0) { log('  (no memdirs found)'); return; }
+  let adopted = 0;
+  for (const { projectSlug, memdir } of dirs) {
+    if (isAdopted(memdir, PLUGIN_SLUG)) {
+      const idx = readMemoryIndex(memdir, PLUGIN_SLUG);
+      log(`  ✓ ${projectSlug} (${idx.version})`);
+      adopted++;
+    }
+  }
+  log('');
+  log(`[adopt --status] ${adopted}/${dirs.length} adopted`);
+}
+
+/**
+ * cmdUnadopt — precise removal of sentinel section + plugin doc.
+ * Exit code stays 0: unadopt is idempotent; "absent" isn't an error.
+ */
+export function cmdUnadopt(args = []) {
+  const all = hasFlag(args, '--all');
+  const targets = all
+    ? listAllMemdirs().map((m) => m.memdir)
+    : [memdirPath(detectCwd())];
+
+  if (targets.length === 0) {
+    log('[unadopt] no memdirs found');
+    return;
+  }
+
+  let removed = 0, absent = 0;
+  for (const memdir of targets) {
+    const r = removePluginSection(memdir, PLUGIN_SLUG);
+    removePluginDoc(memdir, PLUGIN_SLUG);
+    if (r.action === 'removed') removed++;
+    else absent++;
+    log(`[unadopt] ${memdir} → ${r.action}`);
+  }
+
+  log('');
+  log(`[unadopt] ${targets.length} target(s): ${removed} removed, ${absent} absent`);
+}

package/adopt-content.mjs

@@ -0,0 +1,75 @@
+// Phase C (Invited-Memory plan, T10): Content generators for the
+// claude-mem-lite sentinel line and its companion plugin_claude_mem_lite.md
+// detail doc. Kept separate so the strings are testable without side effects
+// and can evolve without touching memdir.mjs primitives.
+//
+// Bumping CURRENT_SENTINEL_VERSION: pick the next vN and update
+// docs/plans/2026-04-16-invited-memory-pattern.md so installs do a version-
+// bump replace instead of treating the old content as a user edit.
+
+export const PLUGIN_SLUG = 'claude-mem-lite';
+export const CURRENT_SENTINEL_VERSION = 'v1';
+
+/**
+ * One-line entry injected into MEMORY.md's sentinel section. Must stay ≤150
+ * chars so it clears Claude Code's 200-line MEMORY.md cap with headroom.
+ */
+export function getIndexLine() {
+  return '- [claude-mem-lite](plugin_claude_mem_lite.md) — Edit 前 `mem_recall(file=…)`；bugfix 后 `mem_save(type="bugfix", lesson_learned, importance=2)`';
+}
+
+/**
+ * Full detail doc rendered into `memdir/plugin_claude_mem_lite.md`. Not
+ * auto-loaded by Claude Code — the MEMORY.md index line points to it and
+ * Claude reads it on demand when the injected hint suggests relevance.
+ */
+export function getDetailDoc() {
+  return `# claude-mem-lite 插件契约
+
+> 由 \`claude-mem-lite adopt\` 生成；卸载用 \`claude-mem-lite unadopt\`。
+> 设计背景见 docs/plans/2026-04-16-invited-memory-pattern.md。
+
+## 何时调用 MCP 工具
+
+| 时机 | 工具 | 关键参数 |
+|------|------|----------|
+| Edit / Write 前 | \`mem_recall\` | \`file="<路径>"\` —— 过往 bugfix 与教训 |
+| Test failure / error | \`mem_search\` | \`query="<错误关键词>", obs_type="bugfix"\` |
+| Refactor 前 | \`mem_search\` | \`query="<模块>", obs_type="refactor"\` |
+| 新功能起手 | \`mem_search\` | \`query="<功能区域>"\` —— 找 prior art |
+| Bugfix 解决后 | \`mem_save\` | \`type="bugfix", lesson_learned="<根因+修法>", importance=2\` |
+| 架构决策后 | \`mem_save\` | \`type="decision", lesson_learned="<取舍理由>", importance=2\` |
+| 上下文提到 #NN | \`mem_get\` | \`ids=[NN]\` |
+
+## Decision rules（替代多步 search）
+
+- "最近做了啥" → \`mem_recent\`
+- "<文件> 有哪些记忆" → \`mem_recall\`
+- "#NN 前后发生了啥" → \`mem_timeline\`
+- "清理过期记忆" → \`mem_maintain\`
+- "FTS 索引健康吗" → \`mem_fts_check\`
+- "按 tier 浏览" → \`mem_browse\`
+- "备份导出" → \`mem_export\`
+
+## 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\` | 时间线上下文 |
+
+## 质量门槛
+
+- \`mem_save\` 的 \`lesson_learned\` 不要写 \`none\`——写不出教训就保持 NULL
+- \`decision\` 命中率 72.7% vs \`change\` 16.5%——一条好 decision ≈ 20 条 change
+- 一般搜索跳过 \`obs_type\` 让系统自动路由；特定意图再过滤
+
+## 卸载
+
+\`claude-mem-lite unadopt\` 精确移除 sentinel 段 + 本文件；其它 MEMORY.md 内容不动。
+`;
+}

package/commands/adopt.md

@@ -0,0 +1,44 @@
+---
+name: adopt
+description: "Use when: user asks to increase claude-mem-lite's tool-invocation rate in the current project, or wants to install the invited-memory sentinel so Claude Code auto-loads the contract as user-memory. Writes a single sentinel-wrapped line to ~/.claude/projects/<encoded>/memory/MEMORY.md plus a plugin_claude_mem_lite.md detail file. Run /unadopt to remove."
+---
+
+# /adopt
+
+Install the **invited-memory** sentinel into the current project's Claude Code
+memdir (`~/.claude/projects/<encoded>/memory/`). The sentinel line carries the
+MCP-tool triggers (`mem_recall` / `mem_save`) at system-prompt authority
+(framed as "user's auto-memory") so Claude Code is more likely to call them
+proactively than when those same triggers live in MCP server instructions.
+
+## What it writes
+
+1. **`MEMORY.md`** — ONE sentinel-wrapped line under a `## 插件契约` header.
+   Idempotent: re-running replaces the block only if the version bumped.
+2. **`plugin_claude_mem_lite.md`** — Detailed contract (CLI cheatsheet +
+   MCP decision rules). Not auto-loaded; Claude reads it on demand when the
+   MEMORY.md pointer surfaces in context.
+3. **`.plugin_claude_mem_lite_state.json`** — Sidecar with sentinel body hash
+   for user-edit detection.
+
+## Flags
+
+- `--force` — overwrite a sentinel block that was manually edited
+- `--dry-run` — print intended writes without touching disk
+- `--all` — adopt every memdir under `~/.claude/projects/*/memory/`
+- `--status` — list all adopted projects with their sentinel versions
+
+## Removal
+
+`/unadopt` precisely removes the sentinel block + plugin doc + state file.
+User content outside the sentinel is preserved.
+
+## Conservative layer still active
+
+Adoption does NOT remove the hook-based injection (SessionStart context,
+UserPromptSubmit related-memory). Those remain as fallback for older Claude
+Code versions. Post-adopt the MCP `WHEN TO USE` section + the `File Lessons` /
+`Key Context` sections auto-trim since the sentinel line already carries the
+triggers at higher authority.
+
+!claude-mem-lite adopt $ARGUMENTS

package/commands/bug.md

@@ -0,0 +1,57 @@
+---
+name: bug
+description: "Use when: logging a known bug + repro steps you can't fix right now. Writes to the mem events table (NOT memdir). Skip for bugs you're actively fixing in the current turn — just fix them."
+---
+
+# /bug
+
+Record a known bug + reproduction steps. Writes to the mem `events` table
+with `event_type='bug'`. Does NOT touch memdir. Useful for bugs you can't
+fix immediately but want future sessions (or yourself after `/clear`) to
+know about and avoid re-investigating.
+
+## When to use
+
+- Bug is known but fix is blocked (waiting on upstream, needs discussion).
+- Bug is intermittent / race condition; you want a repro recipe recorded.
+- Edge case affecting only part of users; not priority now but must not
+  be silently re-discovered.
+
+Don't use for bugs you're actively fixing in the current turn — just fix
+them. Use `/lesson` afterward if there's a non-obvious root cause worth
+recording.
+
+## Arguments
+
+- Positional text: short bug description.
+- `--file <path>` or `--files f1,f2,...`: affected files. Triggers
+  pre-tool-recall warning when these files are edited later.
+- `--repro "step1; step2; step3"`: reproduction steps, semicolon-separated.
+- `--severity low|med|high`: maps to importance `1|2|3`. Default `med`.
+
+## Execution
+
+Map severity to importance:
+
+- `low` → importance 1
+- `med` → importance 2 (default)
+- `high` → importance 3
+
+Build the body as `<description>\n\nRepro:\n<repro-steps>` (or just
+`<description>` if `--repro` is absent).
+
+Run via Bash:
+
+    claude-mem-lite activity save \
+      --type bug \
+      --title "<first 60 chars of description>" \
+      --body "<body>" \
+      [--file <path> | --files f1,f2,...] \
+      --importance <1|2|3>
+
+Confirm to user with: `Bug logged: activity #<id>`.
+
+## Examples
+
+- `/bug intermittent test flake when DB is under load --repro "run pnpm test -- --retry=0; fails ~1 in 20 runs when CPU is busy"`.
+- `/bug --file src/auth.mjs --severity high "session refresh drops the X-Forwarded-For header"` — no repro steps, just a high-severity note.

package/commands/lesson.md

@@ -0,0 +1,53 @@
+---
+name: lesson
+description: "Use when: capturing a non-obvious lesson/gotcha/workaround after a tricky fix or surprising behavior. Writes to the mem events table (NOT memdir). Skip for typos, renames, or user-preference rules."
+---
+
+# /lesson
+
+Record a lesson / gotcha / workaround. Writes to the mem `events` table
+with `event_type='lesson'`. Does NOT touch memdir — so lessons never end up
+in the L1 system-prompt memory section and do not conflict with the
+`WHAT_NOT_TO_SAVE` semantics sdscc enforces.
+
+## When to use
+
+After you (or the user) solve a tricky bug or discover a non-obvious behavior:
+
+- "you need to call X before Y or the test hangs"
+- "don't use this import path — it shadows the real module"
+- "the API returns null when you pass empty string, even though docs say it throws"
+
+Don't use for trivial fixes (typos, renames), for rules that belong in memdir
+(user preferences, project-wide conventions), or for general project notes
+(use `/mem:memory` or `mem_save` instead).
+
+## Arguments
+
+- Positional text: the lesson description (what went wrong + root cause + fix).
+- `--file <path>`: scope to a specific file. The lesson will surface via
+  pre-tool-recall the next time the file is opened via Edit/Write.
+- `--files f1,f2,f3`: comma-separated list for multiple files.
+- `--importance <1|2|3>`: default `2`. Use `3` for critical lessons you always
+  want surfaced; `1` for minor gotchas.
+
+## Execution
+
+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 \
+      --type lesson \
+      --title "<first 60 chars of text>" \
+      --body "<full text>" \
+      [--file <path> | --files f1,f2,...] \
+      --importance <1|2|3>
+
+Confirm to user with: `Lesson saved: activity #<id>`.
+
+## Examples
+
+- `/lesson fix a bug now` — stores a short lesson for the current project; no file scope.
+- `/lesson --file src/auth.mjs "session cookies must be httpOnly or the e2e tests bleed across browsers"` — file-scoped.
+- `/lesson --files src/a.mjs,src/b.mjs --importance 3 "both modules share a cache via WeakMap; clearing one invalidates the other"` — multi-file, high importance.

package/commands/unadopt.md

@@ -0,0 +1,30 @@
+---
+name: unadopt
+description: "Use when: user wants to remove the invited-memory sentinel from the current project (or all projects with --all). Cleans MEMORY.md sentinel block + plugin_claude_mem_lite.md + state sidecar. User content outside the sentinel is preserved. Benign no-op on never-adopted memdirs."
+---
+
+# /unadopt
+
+Remove the claude-mem-lite invited-memory sentinel from the current project's
+Claude Code memdir. Opposite of `/adopt`.
+
+## What it removes
+
+1. The `<!-- claude-mem-lite:begin vN --> ... <!-- claude-mem-lite:end -->`
+   block from `MEMORY.md` (plus the preceding `## 插件契约` header line it owns).
+2. `plugin_claude_mem_lite.md` detail file.
+3. `.plugin_claude_mem_lite_state.json` sidecar.
+
+Everything else in `MEMORY.md` is preserved byte-for-byte.
+
+## Flags
+
+- `--all` — unadopt every memdir under `~/.claude/projects/*/memory/`
+
+## Aftermath
+
+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

package/hook-context.mjs

@@ -8,7 +8,7 @@ import {
   debugLog, debugCatch,
   DECAY_HALF_LIFE_BY_TYPE, DEFAULT_DECAY_HALF_LIFE_MS, notLowSignalTitleClause,
 } from './utils.mjs';
-import { STALE_SESSION_MS, FALLBACK_OBS_WINDOW_MS } from './hook-shared.mjs';
+import { STALE_SESSION_MS, FALLBACK_OBS_WINDOW_MS, effectiveQuiet } from './hook-shared.mjs';
 import { extractUnfinishedSummary } from './hook-handoff.mjs';
 
 /**
@@ -315,18 +315,25 @@ export function buildSessionContextLines(db, project, now = new Date(), currentC
       keyContext.push(`- [${o.type || 'discovery'}] ${truncate(clean, 80)} (#${o.id})${lesson}`);
     }
 
-    if (fileLessons.length > 0) {
+    // Phase A (QUIET_HOOKS) + Phase D (adopted sentinel): drop descriptive
+    // File Lessons / Key Context sections when the user has opted into low-noise
+    // hooks OR adopted invited-memory (MEMORY.md sentinel carries the triggers
+    // at higher system-prompt authority). The Recent table still fires so #IDs
+    // remain reachable via mem_get.
+    const quiet = effectiveQuiet();
+    if (fileLessons.length > 0 && !quiet) {
       summaryLines.push('### File Lessons');
       summaryLines.push(...fileLessons.slice(0, 5));
       summaryLines.push('');
     }
-    if (keyContext.length > 0) {
+    if (keyContext.length > 0 && !quiet) {
       summaryLines.push('### Key Context');
       summaryLines.push(...keyContext.slice(0, 5));
       summaryLines.push('');
     }
-  } else if (!latestSummary) {
-    // Fallback: no summary AND no key observations — show recent activity
+  } else if (!latestSummary && !effectiveQuiet()) {
+    // Fallback: no summary AND no key observations — show recent activity.
+    // Skipped under QUIET_HOOKS since the Recent table already carries titles.
     const recentObs = (observations.length >= 3 ? observations : fallbackObs).slice(0, 3);
     if (recentObs.length > 0) {
       summaryLines.push('### Recent Activity');