claude-mem-lite 2.31.1 → 2.32.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.31.1",
+      "version": "2.32.1",
       "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.1",
+  "version": "2.32.1",
   "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/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');

package/hook-shared.mjs

@@ -8,6 +8,10 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from '
 import { inferProject, debugCatch } from './utils.mjs';
 import { ensureDb, DB_DIR } from './schema.mjs';
 import { getClaudePath as getClaudePathShared, resolveModel as resolveModelShared } from './haiku-client.mjs';
+// Phase D: invited-memory sentinel detection. memdir.mjs only pulls in fs/path/os/crypto;
+// adopt-content.mjs is pure strings. No circular deps — memdir doesn't import hook-shared.
+import { memdirPath as _memdirPath, isAdopted as _isAdopted } from './memdir.mjs';
+import { PLUGIN_SLUG as _PLUGIN_SLUG } from './adopt-content.mjs';
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
@@ -24,6 +28,33 @@ export const DEDUP_WINDOW_MS = 5 * 60 * 1000;            // 5 min (title dedup)
 export const RELATED_OBS_WINDOW_MS = 7 * 86400000;       // 7 days
 export const FALLBACK_OBS_WINDOW_MS = RELATED_OBS_WINDOW_MS; // same window
 
+// Phase A (v2.31.3+): MEM_QUIET_HOOKS=1 drops descriptive hook/MCP-instruction
+// bodies (File Lessons / Key Context headers, MCP WHEN-TO-USE & decision rules,
+// related-memory lesson suffix). Intended for users who adopted invited-memory
+// (MEMORY.md sentinel) or who otherwise want minimal hook noise. Function form
+// (not const) so modules importing at load time still respect later env sets
+// in-process, and tests can toggle per-call. See docs/plans/2026-04-16-invited-memory-pattern.md.
+export function isQuietHooks() {
+  return process.env.MEM_QUIET_HOOKS === '1';
+}
+
+// Phase D (v2.32.1+): if the current project has adopted our invited-memory
+// sentinel, MEMORY.md already carries the triggers at system-prompt authority
+// — so hook + MCP-instruction output can also go quiet. isQuietHooks (env)
+// remains an independent, stronger override.
+export function isAdoptedHere(cwd) {
+  try {
+    const resolved = cwd || process.env.CLAUDE_PROJECT_DIR || process.env.PWD || process.cwd();
+    return _isAdopted(_memdirPath(resolved), _PLUGIN_SLUG);
+  } catch {
+    return false;
+  }
+}
+
+export function effectiveQuiet(cwd) {
+  return isQuietHooks() || isAdoptedHere(cwd);
+}
+
 // Handoff system constants
 export const HANDOFF_EXPIRY_CLEAR = 6 * 3600000;                // 6 hours (covers lunch/meeting breaks)
 export const HANDOFF_EXPIRY_EXIT = 7 * 24 * 60 * 60 * 1000;   // 7 days

package/hook-update.mjs

@@ -196,6 +196,7 @@ const SOURCE_FILES = [
   'cli.mjs', 'server.mjs', 'server-internals.mjs', 'tool-schemas.mjs',
   'hook.mjs', 'hook-shared.mjs', 'hook-llm.mjs', 'hook-memory.mjs', 'skip-tools.mjs',
   'hook-semaphore.mjs', 'hook-episode.mjs', 'hook-context.mjs', 'hook-handoff.mjs', 'hook-update.mjs',
+  'hook-optimize.mjs', 'plugin-cache-guard.mjs',
   'haiku-client.mjs', 'utils.mjs', 'schema.mjs', 'package.json', 'package-lock.json', 'skill.md',
   'registry.mjs', 'registry-scanner.mjs', 'registry-indexer.mjs',
   'registry-retriever.mjs', 'resource-discovery.mjs',
@@ -289,6 +290,13 @@ export function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR) {
     // Post-update: prune old plugin cache versions (keep latest 3)
     try { prunePluginCache(); } catch (e) { debugCatch(e, 'prunePluginCache'); }
 
+    // Post-update: clear cache hooks.json in every remaining version. Claude Code
+    // runtime reads plugin hooks from cache, not marketplace source — leaving populated
+    // cache hooks.json alongside install.mjs-written settings.json causes double firing.
+    // Inline impl (no import of plugin-cache-guard.mjs — this module must run even when
+    // the guard module is absent on disk, e.g. auto-upgrading from pre-2.31.2).
+    try { clearCacheHookResidue(); } catch (e) { debugCatch(e, 'clearCacheHookResidue'); }
+
     debugLog('DEBUG', 'hook-update', `Auto-update: switched ${installed.length} paths`);
     return true;
   } catch (err) {
@@ -348,6 +356,33 @@ function copyReleaseIntoStaging(sourceDir, stagingDir) {
   debugLog('DEBUG', 'hook-update', `Auto-update staged ${copied} source files`);
 }
 
+// ── Cache hook residue clearing ────────────────────────────
+// Inline (does not import plugin-cache-guard.mjs) so hook-update.mjs keeps working
+// even if plugin-cache-guard.mjs is missing on disk in degraded installs.
+export function clearCacheHookResidue() {
+  const cacheBase = join(homedir(), '.claude', 'plugins', 'cache', 'sdsrss', 'claude-mem-lite');
+  if (!existsSync(cacheBase)) return 0;
+  let cleared = 0;
+  for (const ver of readdirSync(cacheBase)) {
+    const p = join(cacheBase, ver, 'hooks', 'hooks.json');
+    if (!existsSync(p)) continue;
+    try {
+      const h = JSON.parse(readFileSync(p, 'utf8'));
+      if (!h.hooks || Object.keys(h.hooks).length === 0) continue;
+      writeFileSync(p, JSON.stringify({
+        description: h.description || 'claude-mem-lite hooks',
+        _note: `Auto-cleared by hook-update.mjs post-install — prevents double hook registration (cache ver: ${ver})`,
+        hooks: {},
+      }, null, 2) + '\n');
+      cleared++;
+    } catch { /* ignore single bad entry */ }
+  }
+  if (cleared > 0) {
+    debugLog('DEBUG', 'hook-update', `Cache hooks residue cleared in ${cleared} version(s)`);
+  }
+  return cleared;
+}
+
 // ── Plugin Cache Pruning ──────────────────────────────────
 const PLUGIN_CACHE_KEEP = 3;
 

package/hook.mjs

@@ -32,7 +32,16 @@ import { searchRelevantMemories } from './hook-memory.mjs';
 import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection, extractUnfinishedSummary } from './hook-handoff.mjs';
 import { checkForUpdate } from './hook-update.mjs';
 import { handleLLMOptimize } from './hook-optimize.mjs';
-import { clearPluginCacheHooks, hasInstallManagedHooks } from './plugin-cache-guard.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.
+let _cacheGuardCache = null;
+async function loadCacheGuard() {
+  if (_cacheGuardCache !== null) return _cacheGuardCache;
+  try { _cacheGuardCache = await import('./plugin-cache-guard.mjs'); }
+  catch { _cacheGuardCache = {}; }
+  return _cacheGuardCache;
+}
 import { SKIP_TOOLS, SKIP_PREFIXES } from './skip-tools.mjs';
 import { getVocabulary } from './tfidf.mjs';
 
@@ -402,9 +411,12 @@ async function handleSessionStart() {
   // re-populate cache/<ver>/hooks/hooks.json, reintroducing duplicate hook
   // registration alongside install.mjs-managed settings.json entries. Silently
   // clear — gated by hasInstallManagedHooks to avoid breaking plugin-only users.
+  // Dynamic-import fallback: if plugin-cache-guard.mjs is missing (pre-2.31.2
+  // auto-upgrade install), skip self-heal instead of crashing the entire hook.
   try {
-    if (hasInstallManagedHooks()) {
-      const cleared = clearPluginCacheHooks({
+    const guard = await loadCacheGuard();
+    if (guard.hasInstallManagedHooks && guard.hasInstallManagedHooks()) {
+      const cleared = guard.clearPluginCacheHooks({
         reason: 'Auto-healed by hook.mjs session-start — install.mjs-managed hooks active in settings.json',
       });
       if (cleared.length > 0) {

package/install.mjs

@@ -224,6 +224,10 @@ async function install() {
     'lib/plan-reader.mjs',
     'lib/git-state.mjs',
     'lib/startup-dashboard.mjs',
+    // v2.32 (invited-memory): memdir primitives + adopt/unadopt CLI.
+    'memdir.mjs',
+    'adopt-content.mjs',
+    'adopt-cli.mjs',
   ];
 
   if (IS_DEV) {
@@ -807,6 +811,25 @@ async function install() {
     log('No existing database — will be created on first use');
   }
 
+  // 7b. Dogfood auto-adopt (invited-memory, Phase C T13).
+  // Only fires when install.mjs is running from the claude-mem-lite source repo
+  // itself (detected via git remote match). In npm/npx flows PROJECT_DIR is a
+  // cache dir with no git metadata, so this is a no-op for end users.
+  // --no-adopt override respected.
+  if (!flags.has('--no-adopt')) {
+    try {
+      const remote = execFileSync('git', ['-C', PROJECT_DIR, 'config', '--get', 'remote.origin.url'], { encoding: 'utf8', stdio: 'pipe' }).trim();
+      const isDogfood = /github\.com[:/]sdsrss\/claude-mem-lite(\.git)?$/i.test(remote);
+      if (isDogfood) {
+        const { cmdAdopt } = await import('./adopt-cli.mjs');
+        cmdAdopt([]);
+        ok('Invited-memory: auto-adopt for claude-mem-lite dogfood repo');
+      }
+    } catch {
+      // Not a git repo, or git missing — silent skip (this is the normal npm path).
+    }
+  }
+
   // 8. Disable old claude-mem plugin
   if (settings.enabledPlugins?.['claude-mem@thedotmack'] !== undefined) {
     settings.enabledPlugins['claude-mem@thedotmack'] = false;
@@ -851,6 +874,10 @@ async function uninstall() {
   const settings = readSettings();
   cleanupMemHooksFromSettings(settings);
 
+  // 2b. Uninstall does NOT auto-unadopt — an adopted project may be in active use
+  // by the user in other Claude Code sessions. Tell them the command instead.
+  log('Invited-memory: adopt state preserved. Run `claude-mem-lite unadopt --all` to remove sentinel sections.');
+
   // 3. Clean plugin registry entries conservatively (avoid deleting other plugins
   // from the same marketplace publisher)
   const pluginsDir = join(homedir(), '.claude', 'plugins');

package/mem-cli.mjs

@@ -14,6 +14,7 @@ import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { optimizePreview, optimizeRun } from './hook-optimize.mjs';
 import { buildSessionContextLines } from './hook-context.mjs';
+import { cmdAdopt, cmdUnadopt } from './adopt-cli.mjs';
 import { basename } from 'path';
 import { readFileSync } from 'fs';
 
@@ -2058,6 +2059,17 @@ Commands:
     --files (plural, comma-split) preferred; --file (singular) kept for back-compat.
     Use /lesson or /bug slash commands for faster capture (T8).
 
+  adopt                 Inject claude-mem-lite sentinel line into this project's
+                        ~/.claude/projects/<encoded>/memory/MEMORY.md so Claude Code
+                        auto-loads it as user-memory (higher instruction authority).
+    --all               Adopt every project under ~/.claude/projects/*/memory/
+    --force             Overwrite a sentinel block that was manually edited
+    --dry-run           Print intended writes without touching disk
+    --status            List adopted projects + version
+
+  unadopt               Precise removal of the sentinel block + plugin_claude_mem_lite.md.
+    --all               Unadopt every project
+
 DB: ${DB_PATH}`);
 }
 
@@ -2336,6 +2348,11 @@ export async function run(argv) {
     return;
   }
 
+  // adopt / unadopt do pure filesystem work on ~/.claude/projects/<encoded>/memory/ —
+  // no DB needed. Route them before ensureDb() so an unbootable DB doesn't block.
+  if (cmd === 'adopt') { cmdAdopt(cmdArgs); return; }
+  if (cmd === 'unadopt') { cmdUnadopt(cmdArgs); return; }
+
   let db;
   try {
     db = ensureDb();

package/memdir.mjs

@@ -0,0 +1,252 @@
+// Phase B (Invited-Memory plan): memdir.mjs — primitives for the per-project
+// Claude Code memdir at ~/.claude/projects/<encoded>/memory/.
+//
+// The public API lets a plugin install a single sentinel-wrapped line into
+// MEMORY.md (auto-loaded by Claude Code into the system prompt) plus an
+// on-demand `plugin_<slug>.md` detail file. Writes are idempotent, hash-guarded
+// against manual user edits, and capped by a 180-line budget so the injection
+// block never gets truncated by Claude Code's 200-line MEMORY.md cap.
+//
+// See docs/plans/2026-04-16-invited-memory-pattern.md for rationale.
+
+import { readFileSync, writeFileSync, existsSync, renameSync, unlinkSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { createHash } from 'crypto';
+
+const MEMORY_LINE_BUDGET = 180;
+const SECTION_HEADER = '## 插件契约';
+
+export class UserEditedError extends Error {
+  constructor(message) { super(message); this.name = 'UserEditedError'; }
+}
+
+export class BudgetExceededError extends Error {
+  constructor(message) { super(message); this.name = 'BudgetExceededError'; }
+}
+
+// ─── Path helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Mirror Claude Code's project-path encoding: every non-alphanumeric char
+ * is replaced with "-". Lossy by design — the encoded path is a directory
+ * slug, not a reversible encoding. Ground truth fixture:
+ *   /mnt/data_ssd/dev/projects/mem → -mnt-data-ssd-dev-projects-mem
+ * Memory ref: #7687 ("Claude Code mangles EVERY non-alphanumeric char").
+ */
+export function encodeProjectPath(absPath) {
+  return String(absPath).replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+/**
+ * Absolute path to the project's memdir. Caller runs mkdir-p as needed.
+ */
+export function memdirPath(projectCwd) {
+  return join(homedir(), '.claude', 'projects', encodeProjectPath(projectCwd), 'memory');
+}
+
+function memoryFile(memdir) { return join(memdir, 'MEMORY.md'); }
+
+function slugSnake(slug) {
+  return String(slug).replace(/[^a-zA-Z0-9]/g, '_');
+}
+
+function docFile(memdir, slug) {
+  return join(memdir, `plugin_${slugSnake(slug)}.md`);
+}
+
+function stateFile(memdir, slug) {
+  return join(memdir, `.plugin_${slugSnake(slug)}_state.json`);
+}
+
+// ─── Sentinel rendering & parsing ────────────────────────────────────────────
+
+function sentinelRegex(slug) {
+  // Escape regex metacharacters in the slug. In practice plugin slugs are
+  // [a-z0-9-], but guard against '.', '+' etc. from arbitrary other plugins.
+  const esc = slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(
+    `<!-- ${esc}:begin (v\\d+) -->\\s*\\n([\\s\\S]*?)<!-- ${esc}:end -->`,
+  );
+}
+
+function renderSentinel(slug, version, contentLine) {
+  return [
+    `<!-- ${slug}:begin ${version} -->`,
+    SECTION_HEADER,
+    contentLine,
+    `<!-- ${slug}:end -->`,
+  ].join('\n');
+}
+
+function canonicalBody(contentLine) {
+  // Must match what sentinelRegex captures in match[2]: everything between
+  // "begin X -->\n" and "<!-- X:end -->". That's SECTION_HEADER + '\n' +
+  // contentLine + '\n'.
+  return `${SECTION_HEADER}\n${contentLine}\n`;
+}
+
+function sha256(s) { return createHash('sha256').update(s).digest('hex'); }
+
+function atomicWrite(path, content) {
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, content);
+  renameSync(tmp, path);
+}
+
+function readState(memdir, slug) {
+  const p = stateFile(memdir, slug);
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+function writeState(memdir, slug, state) {
+  atomicWrite(stateFile(memdir, slug), JSON.stringify(state, null, 2) + '\n');
+}
+
+function clearState(memdir, slug) {
+  const p = stateFile(memdir, slug);
+  if (existsSync(p)) try { unlinkSync(p); } catch { /* best-effort */ }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Parse MEMORY.md for the plugin's sentinel block.
+ * @returns {{ exists: boolean, raw: string, lineCount: number,
+ *   section: string|null, body: string|null, version: string|null }}
+ */
+export function readMemoryIndex(memdir, slug) {
+  const path = memoryFile(memdir);
+  if (!existsSync(path)) {
+    return { exists: false, raw: '', lineCount: 0, section: null, body: null, version: null };
+  }
+  const raw = readFileSync(path, 'utf8');
+  const m = raw.match(sentinelRegex(slug));
+  const lineCount = raw.length === 0 ? 0 : raw.split('\n').length;
+  if (!m) return { exists: true, raw, lineCount, section: null, body: null, version: null };
+  return { exists: true, raw, lineCount, section: m[0], body: m[2], version: m[1] };
+}
+
+/**
+ * Insert-or-update the plugin's sentinel block in MEMORY.md, writing a
+ * state sidecar alongside it.
+ *
+ * Idempotent: rewriting identical inputs is a no-op (returns action='unchanged').
+ *
+ * @param {string} memdir Absolute path to the memory directory.
+ * @param {object} opts
+ * @param {string} opts.slug Plugin slug (e.g. 'claude-mem-lite').
+ * @param {string} opts.version Contract version, e.g. 'v1'.
+ * @param {string} opts.contentLine Single-line index entry (≤150 chars).
+ * @param {boolean} [opts.force=false] Override UserEditedError.
+ * @returns {{action: 'created'|'updated'|'unchanged'}}
+ *
+ * @throws {BudgetExceededError} when MEMORY.md has > 180 lines AND we'd be
+ *   adding a new section (updates to an existing sentinel are always allowed).
+ * @throws {UserEditedError} when the sentinel exists but its body hash doesn't
+ *   match the last hash we wrote (detected via the state sidecar). Also thrown
+ *   when a sentinel exists without any state file — treated as foreign content.
+ */
+export function writePluginSection(memdir, { slug, version, contentLine, force = false }) {
+  if (!existsSync(memdir)) mkdirSync(memdir, { recursive: true });
+  const path = memoryFile(memdir);
+  const raw = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const match = raw.match(sentinelRegex(slug));
+
+  const freshSection = renderSentinel(slug, version, contentLine);
+  const freshHash = sha256(canonicalBody(contentLine));
+
+  if (!match) {
+    // Insert: enforce the 180-line budget so we never get truncated at 200.
+    const existingLines = raw.length === 0 ? 0 : raw.split('\n').length;
+    if (existingLines > MEMORY_LINE_BUDGET) {
+      throw new BudgetExceededError(
+        `MEMORY.md has ${existingLines} lines (> ${MEMORY_LINE_BUDGET}); refuse to add new sentinel section for ${slug}.`,
+      );
+    }
+    // Assemble with one blank line before our section for readability.
+    let next;
+    if (raw.length === 0) {
+      next = freshSection + '\n';
+    } else if (raw.endsWith('\n\n')) {
+      next = raw + freshSection + '\n';
+    } else if (raw.endsWith('\n')) {
+      next = raw + '\n' + freshSection + '\n';
+    } else {
+      next = raw + '\n\n' + freshSection + '\n';
+    }
+    atomicWrite(path, next);
+    writeState(memdir, slug, { version, bodyHash: freshHash, writtenAt: new Date().toISOString() });
+    return { action: 'created' };
+  }
+
+  // Update path: hash-guard against user edits via state sidecar.
+  if (!force) {
+    const state = readState(memdir, slug);
+    if (!state) {
+      throw new UserEditedError(
+        `${slug} sentinel found without plugin state file — treating as foreign content. Pass force=true to re-adopt.`,
+      );
+    }
+    const currentHash = sha256(match[2]);
+    if (state.bodyHash !== currentHash) {
+      throw new UserEditedError(
+        `${slug} sentinel body was modified since last write (hash mismatch). Pass force=true to overwrite.`,
+      );
+    }
+  }
+
+  const next = raw.replace(match[0], freshSection);
+  const changed = next !== raw;
+  if (changed) atomicWrite(path, next);
+  writeState(memdir, slug, { version, bodyHash: freshHash, writtenAt: new Date().toISOString() });
+  return { action: changed ? 'updated' : 'unchanged' };
+}
+
+/**
+ * Remove the plugin's sentinel block plus its state sidecar. External content
+ * in MEMORY.md is preserved.
+ * @returns {{action: 'removed'|'absent'}}
+ */
+export function removePluginSection(memdir, slug) {
+  clearState(memdir, slug);
+  const path = memoryFile(memdir);
+  if (!existsSync(path)) return { action: 'absent' };
+  const raw = readFileSync(path, 'utf8');
+  const match = raw.match(sentinelRegex(slug));
+  if (!match) return { action: 'absent' };
+
+  // Delete the match plus a trailing newline + a preceding blank line so we
+  // don't leave a stranded paragraph gap.
+  let start = match.index;
+  let end = match.index + match[0].length;
+  if (raw[end] === '\n') end++;
+  if (start > 0 && raw.slice(0, start).endsWith('\n\n')) start--;
+  const next = raw.slice(0, start) + raw.slice(end);
+  atomicWrite(path, next);
+  return { action: 'removed' };
+}
+
+/**
+ * Whether this memdir has our sentinel. Body edits don't demote the adoption —
+ * users who hand-tweak the contract line still count as adopted.
+ */
+export function isAdopted(memdir, slug) {
+  if (!existsSync(memdir)) return false;
+  const { section } = readMemoryIndex(memdir, slug);
+  return section !== null;
+}
+
+// ─── Plugin detail doc IO ────────────────────────────────────────────────────
+
+export function writePluginDoc(memdir, slug, markdown) {
+  if (!existsSync(memdir)) mkdirSync(memdir, { recursive: true });
+  atomicWrite(docFile(memdir, slug), markdown);
+}
+
+export function removePluginDoc(memdir, slug) {
+  const path = docFile(memdir, slug);
+  if (!existsSync(path)) return;
+  try { unlinkSync(path); } catch { /* best-effort */ }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.31.1",
+  "version": "2.32.1",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {
@@ -35,6 +35,9 @@
     "hook-context.mjs",
     "hook-handoff.mjs",
     "hook-update.mjs",
+    "memdir.mjs",
+    "adopt-content.mjs",
+    "adopt-cli.mjs",
     "haiku-client.mjs",
     "registry.mjs",
     "registry-retriever.mjs",
@@ -66,6 +69,8 @@
     "commands/memory.md",
     "commands/update.md",
     "commands/tools.md",
+    "commands/adopt.md",
+    "commands/unadopt.md",
     "hooks/hooks.json",
     "scripts/launch.mjs",
     "scripts/setup.sh",
@@ -85,6 +90,9 @@
     "better-sqlite3": "^12.6.2",
     "zod": "^4.3.6"
   },
+  "overrides": {
+    "hono": ">=4.12.14"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^4.0.18",

package/scripts/user-prompt-search.js

@@ -167,6 +167,10 @@ function readStdin() {
 
 // ─── Format Output ──────────────────────────────────────────────────────────
 
+// Phase A (v2.31.3+): drop lesson suffix when MEM_QUIET_HOOKS=1; users on invited-memory
+// path can mem_get the ID for full detail.
+const QUIET_HOOKS = process.env.MEM_QUIET_HOOKS === '1';
+
 function formatResults(rows) {
   if (!rows || rows.length === 0) return null;
 
@@ -174,7 +178,7 @@ function formatResults(rows) {
   for (const r of rows) {
     const icon = typeIcon(r.type);
     const title = truncate(r.title || '', 70);
-    const lesson = r.lesson_learned ? ` — ${truncate(r.lesson_learned, 50)}` : '';
+    const lesson = !QUIET_HOOKS && r.lesson_learned ? ` — ${truncate(r.lesson_learned, 50)}` : '';
     lines.push(`#${r.id} ${icon} ${title}${lesson}`);
   }
   return lines.join('\n');

package/server-internals.mjs

@@ -5,6 +5,54 @@ import { debugCatch, COMPRESSED_AUTO, COMPRESSED_PENDING_PURGE, OBS_BM25 } from
 import { BASE_STOP_WORDS } from './stop-words.mjs';
 import { porterStem } from './tfidf.mjs';
 
+// ─── MCP Server Instructions Builder ───────────────────────────────────────
+// Phase A (v2.31.3+): when quiet=true, drops WHEN-TO-USE proactive-trigger and
+// Decision-rules sections; keeps the irreducible CLI/MCP tool list. Intended
+// for users who adopted invited-memory (MEMORY.md sentinel carries the same
+// triggers at higher authority). Default false preserves v2.31.2 behavior.
+
+const INSTRUCTIONS_BASE = [
+  'Long-term memory across sessions. Hooks auto-inject context; CLI preferred for explicit queries.',
+  '',
+  'CLI (via Bash):',
+  '  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',
+  '  claude-mem-lite recent 5                    — latest observations',
+  '  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.',
+  'mem_save: Save non-obvious insights (bugfix lessons, architecture decisions).',
+  'Search tips: short keywords (2-3 words), filter with obs_type when relevant.',
+];
+
+const INSTRUCTIONS_VERBOSE = [
+  '',
+  'WHEN TO USE (proactive triggers during coding):',
+  '  • About to Edit/Write a file → mem_recall(file="path") FIRST — past bugfixes & lessons',
+  '  • Test failure or error → mem_search(query="error keywords", obs_type="bugfix")',
+  '  • Before refactoring → mem_search(query="module-name", obs_type="refactor") for past decisions',
+  '  • Starting new feature → mem_search(query="feature area") for prior art & patterns',
+  '  • After fixing a tricky bug → mem_save(type="bugfix", lesson_learned="root cause & fix")',
+  '  • After architecture decision → mem_save(type="decision", lesson_learned="rationale")',
+  '  • Hook-injected context mentions #ID → mem_get(ids=[ID]) for full details',
+  '',
+  'Decision rules (use INSTEAD OF multi-step search):',
+  '  • "what happened recently?" → mem_recent (NOT search with empty query)',
+  '  • "what do we know about file.mjs?" → mem_recall (NOT grep + manual search)',
+  '  • "show me around observation #42" → mem_timeline (NOT mem_get + manual navigation)',
+  '  • "clean up old/duplicate memories" → mem_maintain (NOT manual mem_delete loop)',
+  '  • "is the search index healthy?" → mem_fts_check (NOT manual COUNT queries)',
+  '  • "overview of memory tiers" → mem_browse (NOT mem_search + manual grouping)',
+  '  • "export for backup" → mem_export (NOT manual SELECT queries)',
+];
+
+export function buildServerInstructions(quiet = false) {
+  if (quiet) return INSTRUCTIONS_BASE.join('\n');
+  return [...INSTRUCTIONS_BASE, ...INSTRUCTIONS_VERBOSE].join('\n');
+}
+
 // ─── Search Re-ranking Helpers ────────────────────────────────────────────
 
 /**

package/server.mjs

@@ -8,7 +8,8 @@ import { jaccardSimilarity, truncate, typeIcon, sanitizeFtsQuery, relaxFtsQueryT
 import { extractCjkLikePatterns } from './nlp.mjs';
 import { resolveProject as _resolveProjectShared } from './project-utils.mjs';
 import { ensureDb, DB_PATH, REGISTRY_DB_PATH, checkFTSIntegrity, rebuildFTS } from './schema.mjs';
-import { reRankWithContext, markSuperseded, extractPRFTerms, expandQueryByConcepts, autoBoostIfNeeded, runIdleCleanup } from './server-internals.mjs';
+import { reRankWithContext, markSuperseded, extractPRFTerms, expandQueryByConcepts, autoBoostIfNeeded, runIdleCleanup, buildServerInstructions } from './server-internals.mjs';
+import { effectiveQuiet } from './hook-shared.mjs';
 import { computeTier, TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
 import { memSearchSchema, memRecentSchema, memTimelineSchema, memGetSchema, memDeleteSchema, memSaveSchema, memStatsSchema, memCompressSchema, memMaintainSchema, memOptimizeSchema, memUpdateSchema, memExportSchema, memRecallSchema, memFtsCheckSchema, memRegistrySchema, memBrowseSchema, memUseSchema, tools as TOOL_DEFS } from './tool-schemas.mjs';
 
@@ -105,41 +106,7 @@ const RECENCY_HALF_LIFE_MS = DEFAULT_DECAY_HALF_LIFE_MS;
 
 const server = new McpServer(
   { name: 'claude-mem-lite', version: PKG_VERSION },
-  {
-    instructions: [
-      'Long-term memory across sessions. Hooks auto-inject context; CLI preferred for explicit queries.',
-      '',
-      'CLI (via Bash):',
-      '  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',
-      '  claude-mem-lite recent 5                    — latest observations',
-      '  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.',
-      'mem_save: Save non-obvious insights (bugfix lessons, architecture decisions).',
-      'Search tips: short keywords (2-3 words), filter with obs_type when relevant.',
-      '',
-      'WHEN TO USE (proactive triggers during coding):',
-      '  • About to Edit/Write a file → mem_recall(file="path") FIRST — past bugfixes & lessons',
-      '  • Test failure or error → mem_search(query="error keywords", obs_type="bugfix")',
-      '  • Before refactoring → mem_search(query="module-name", obs_type="refactor") for past decisions',
-      '  • Starting new feature → mem_search(query="feature area") for prior art & patterns',
-      '  • After fixing a tricky bug → mem_save(type="bugfix", lesson_learned="root cause & fix")',
-      '  • After architecture decision → mem_save(type="decision", lesson_learned="rationale")',
-      '  • Hook-injected context mentions #ID → mem_get(ids=[ID]) for full details',
-      '',
-      'Decision rules (use INSTEAD OF multi-step search):',
-      '  • "what happened recently?" → mem_recent (NOT search with empty query)',
-      '  • "what do we know about file.mjs?" → mem_recall (NOT grep + manual search)',
-      '  • "show me around observation #42" → mem_timeline (NOT mem_get + manual navigation)',
-      '  • "clean up old/duplicate memories" → mem_maintain (NOT manual mem_delete loop)',
-      '  • "is the search index healthy?" → mem_fts_check (NOT manual COUNT queries)',
-      '  • "overview of memory tiers" → mem_browse (NOT mem_search + manual grouping)',
-      '  • "export for backup" → mem_export (NOT manual SELECT queries)',
-    ].join('\n'),
-  },
+  { instructions: buildServerInstructions(effectiveQuiet()) },
 );
 
 // Track MCP request activity for idle-time cleanup (see idle timer below)