claude-mem-lite 3.12.1 → 3.14.0

package/adopt-content.mjs

@@ -1,96 +1,139 @@
-// 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.
+// CLAUDE.md-steering plan (v3.13): content generators for the claude-mem-lite
+// managed block (written into <cwd>/CLAUDE.md) and its companion
+// <cwd>/.claude/plugin_claude_mem_lite.md detail doc. Kept separate from the
+// claudemd.mjs primitives so the strings are testable without side effects.
 //
-// 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.
+// Bumping CURRENT_SENTINEL_VERSION: pick the next vN. On the next SessionStart
+// needsRefresh() sees the version change and refreshes the block in place
+// (version bump = intended content change, so it overwrites rather than treating
+// the drift as a user edit). v1 = legacy memory-dir sentinel (now migrated away);
+// v2 = project-tree CLAUDE.md managed block.
 
 import { CLI_INVOKE } from './cli-path.mjs';
 
 export const PLUGIN_SLUG = 'claude-mem-lite';
-export const CURRENT_SENTINEL_VERSION = 'v1';
+export const CURRENT_SENTINEL_VERSION = 'v2';
 
 /**
- * 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.
+ * The concise managed block injected into <cwd>/CLAUDE.md (between the
+ * slug-scoped sentinels — those are added by claudemd.renderBlock, NOT here).
+ * Universal: the memory contract is the same for every project, so there is no
+ * per-project-type variation. Keep it tight (cheap always-loaded context); the
+ * full tables + rules live in the detail doc this block points to.
  */
-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)`';
+export function buildClaudeMdBlock() {
+  // Intentionally machine-stable: MCP tool names only, NO CLI_INVOKE (that
+  // resolves to an absolute path that differs per install — it would make this
+  // committed/refreshed block churn across machines). The robust CLI table lives
+  // in the detail doc (.claude/, gitignored).
+  return `## claude-mem-lite — 持久记忆 (persistent memory)
+
+PreToolUse hooks 在 Read/Edit/Write 前已自动 \`mem_recall\` 过往教训。下面是值得你主动发起的调用：
+
+| 时机 | 调用 |
+|------|------|
+| Edit/Write 前 | hook 已自动 recall；若注入了 \`#NN\` 教训，下次产出用户可见文字时引用 \`#NN\`（引用=采纳反馈，未引用会衰减） |
+| 解决非平凡 bug 后 | \`mem_save(type="bugfix", lesson_learned="<根因+修法>", importance=2)\` |
+| 非显然架构决策后 | \`mem_save(type="decision", lesson_learned="<约束+取舍>")\` |
+| 推迟到下个会话 | \`mem_defer({title, priority:1|2|3, detail})\`；修好时给 \`mem_save\` 加 \`closes_deferred=[N]\` |
+| 查过往工作 / 历史 | \`mem_search "关键词"\` · \`mem_recent\` · \`mem_timeline\` |
+
+完整工具+CLI 表、citation/decay 规则、save 纪律见 → \`.claude/plugin_claude_mem_lite.md\``;
 }
 
 /**
- * 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.
+ * Full detail doc rendered into `<cwd>/.claude/plugin_claude_mem_lite.md`.
+ * Not auto-loaded by Claude Code — the CLAUDE.md block points to it and Claude
+ * reads it on demand. claudemd.writeManaged() prepends the `managed-by` marker;
+ * this returns pure content.
  */
 export function getDetailDoc() {
-  return `# claude-mem-lite 插件契约
+  return `# claude-mem-lite 插件契约（完整）
+
+> 由 \`${CLI_INVOKE} adopt\` 生成、随版本自动刷新；卸载用 \`${CLI_INVOKE} unadopt\`。
+> 精炼触发表在项目 \`CLAUDE.md\` 的 \`claude-mem-lite\` 托管块里；本文件是其展开。
+> 设计背景见 docs/CLAUDE-MD-STEERING-PLAN.md。
 
-> 由 \`${CLI_INVOKE} adopt\` 生成；卸载用 \`${CLI_INVOKE} unadopt\`。
-> 设计背景见 docs/plans/2026-04-16-invited-memory-pattern.md。
+## 被动 recall（hook 已自动跑，你只需采纳）
 
-## 何时调用 MCP 工具
+PreToolUse hook 在你 Read / Edit / Write 文件前已自动 \`mem_recall\` 该文件：
+- **Read** 路径：asymmetric-quiet——最多 1 条 lesson、120 字符、要求带 \`lesson_learned\`。
+- **Edit / Write** 路径：decision-support——最多 3 条、240 字符、高重要度 bugfix/decision 即使无
+  lesson 也注入。
+- Read→Edit 同文件共享 cooldown（不重复注入正文），但 Read 注入后的首个 Edit 会把 lesson **ID**
+  以一行 ack 指令重新浮出。看到 \`#NN [bugfix] …\` 这类行时：**下次产出用户可见文字时引用 \`#NN\`**
+  （\`'#NN applied'\` 或 \`'#NN n/a — <理由>'\`）。纯工具回合不算；把 ID 记在工作记忆里，写回时引用。
+- 系统按会话追踪引用：未引用的 lesson 连续 3 个会话后 importance −1（地板 0），被引用的 +1（封顶 3）。
+  引用是给系统的反馈，不是合规仪式——注入池据此自调。
 
-以下 6 个核心 MCP 工具在 \`tools/list\` 中默认暴露，覆盖了契约的热路径：
-\`mem_search\` / \`mem_recent\` / \`mem_recall\` / \`mem_get\` / \`mem_save\` / \`mem_timeline\`。
+## 何时主动调用 MCP 工具
+
+\`tools/list\` 默认暴露 6 个核心工具 + 3 个 defer 工具：
+\`mem_search\` / \`mem_recent\` / \`mem_recall\` / \`mem_get\` / \`mem_save\` / \`mem_timeline\` +
+\`mem_defer\` / \`mem_defer_list\` / \`mem_defer_drop\`。
 
 | 时机 | 工具 | 关键参数 |
 |------|------|----------|
-| Edit / Write 前 | \`mem_recall\` | \`file="<路径>"\` —— 过往 bugfix 与教训 |
+| Edit / Write 前 | \`mem_recall\` | \`file="<路径>"\`（hook 通常已代劳） |
 | 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\` |
+| 解决非平凡 bug 后 | \`mem_save\` | \`type="bugfix", lesson_learned="<根因+修法>", importance=2\` |
+| 非显然架构决策后 | \`mem_save\` | \`type="decision", lesson_learned="<约束+取舍>"\` |
 | 上下文提到 #NN | \`mem_get\` | \`ids=[NN]\` |
 
-## Decision rules（替代多步 search）
-
-- "最近做了啥" → \`mem_recent\`
-- "<文件> 有哪些记忆" → \`mem_recall\`
-- "#NN 前后发生了啥" → \`mem_timeline\`
+## 必做契约（dogfood，本仓库尤其严格）
+
+- **解决非平凡 bug 后**（≠ typo / rename）**必须** \`mem_save(type="bugfix",
+  lesson_learned="<一行根因+一行修法>", importance=2)\`。判据：未来改同一文件的会话看到这条能否避坑？能→存。
+- **非显然架构决策后**（≠ 改名/挪代码）调 \`mem_save(type="decision",
+  lesson_learned="<约束+为何这样选+牺牲了什么>")\`。\`decision\` 命中率显著高于 \`change\`（当前遥测约
+  3:1，会漂移——用 \`${CLI_INVOKE} stats\` 实测，别套固定倍数）；方向稳健：一条好 decision 抵数条 change。
+  别注水：decision 只留给真权衡，不是风格选择。
+- **推迟到未来会话**（≠ 在途 todo、≠ 本 PR 跟进）调
+  \`mem_defer({title, priority:1|2|3, detail:"<约束+为何推迟>"})\`。
+  触发词：中文「下次/下个会话/不在本轮范围/留给下个会话」；en「next session / defer to next round /
+  out of scope for this PR / pick up later」。
+- 修掉 deferred 项时 **必须** 给 \`mem_save\` 加 \`closes_deferred=[N]\`（N 是 SessionStart
+  \`### Deferred Work\` banner 里的序号，或原始 id \`["D#42"]\`，混用 OK），让 carry-forward 链闭合。
+  若该项无需修（flaky/scope shift）改用 \`mem_defer_drop({id, reason})\`，reason 必填、作审计。
+- **不要为凑 schema 写 \`lesson_learned: 'none'\`**：写不出能复用的教训就留 NULL，接受低重要度观测。
+  Haiku 默认过于激进地填 "none"——手动 save 时覆盖它。
 
 ## 维护 / 管理类工具（走 CLI）
 
-v2.34.0 起，以下 11 个工具从 \`tools/list\` 中隐藏以缩小启动上下文；它们仍注册在
-MCP 层，按名 \`tools/call\` 仍可命中，但对 Claude Code 这类只读 tools/list 的
-调用方只走下面的 CLI 入口：
+以下工具从 \`tools/list\` 隐藏（缩小启动上下文）；仍注册在 MCP 层、按名 \`tools/call\` 可命中，
+但对 Claude Code 这类只读 tools/list 的调用方只走 CLI：
 
 | 场景 | CLI |
 |------|-----|
-| 清理过期记忆 | \`${CLI_INVOKE} maintain scan --ops purge_stale\` → \`maintain execute --ops purge_stale --confirm\`（execute 删行必须带 \`--confirm\`，否则只预览） |
-| 深度优化（Haiku） | \`${CLI_INVOKE} optimize\`（默认 preview；\`--run\` 执行，\`--task re-enrich,normalize,cluster-merge,smart-compress\` 选阶段） |
-| 压缩旧条目 | \`${CLI_INVOKE} compress\`（默认 preview；\`--execute\` 执行，\`--age-days N\` 改阈值） |
+| 清理过期记忆 | \`${CLI_INVOKE} maintain scan --ops purge_stale\` → \`maintain execute --ops purge_stale --confirm\`（删行必须 \`--confirm\`） |
+| 深度优化（Haiku） | \`${CLI_INVOKE} optimize\`（默认 preview；\`--run\` 执行，\`--task re-enrich,normalize,cluster-merge,smart-compress\`） |
+| 压缩旧条目 | \`${CLI_INVOKE} compress\`（默认 preview；\`--execute\` 执行，\`--age-days N\`） |
 | FTS5 索引检查 / 重建 | \`${CLI_INVOKE} fts-check [--rebuild]\` |
 | tier 分组浏览 | \`${CLI_INVOKE} browse [--tier active]\` |
 | 导出 JSON/JSONL | \`${CLI_INVOKE} export [--format jsonl]\` |
 | 统计总量 / 健康 | \`${CLI_INVOKE} stats [--days 30]\` |
-| 删除某条 | \`${CLI_INVOKE} delete <id>[,<id>]\` |
-| 更新某条 | \`${CLI_INVOKE} update <id> [--title ...]\` |
-| 列 / 搜索 / 导入 skill-agent registry | \`${CLI_INVOKE} registry <list\\|search\\|import>\` |
-| 按 registry 名载入 skill/agent | （MCP only：\`mem_use\`；由用户主动请求时才使用） |
+| 删除 / 更新某条 | \`${CLI_INVOKE} delete <id>[,<id>]\` · \`${CLI_INVOKE} update <id> [--title ...]\` |
+| skill-agent registry | \`${CLI_INVOKE} registry <list\\|search\\|import>\` |
 
 ## CLI 速查（常用检索）
 
 | 命令 | 用途 |
 |------|------|
-| \`${CLI_INVOKE} search "query"\` | FTS5 全文搜索 |
+| \`${CLI_INVOKE} search "query"\` | FTS5 全文搜索（默认排除低信号 \`Modified X\` 等；加 \`--include-noise\` 找文件变更记录） |
 | \`${CLI_INVOKE} search "err" --type bugfix\` | 按类型过滤 |
 | \`${CLI_INVOKE} recall "file.mjs"\` | 文件相关记忆 |
 | \`${CLI_INVOKE} recent 5\` | 最近 5 条 |
 | \`${CLI_INVOKE} get 42,43\` | 按 ID 展开 |
 | \`${CLI_INVOKE} timeline --anchor 42\` | 时间线上下文 |
 
-## 质量门槛
-
-- \`mem_save\` 的 \`lesson_learned\` 不要写 \`none\`——写不出教训就保持 NULL
-- \`decision\` 的命中率高于 \`change\`（当前遥测约 3:1，数值会漂移——用 \`${CLI_INVOKE} stats\` 实测，别套固定倍数）；方向稳健：一条好 decision 抵数条 change
-- 一般搜索跳过 \`obs_type\` 让系统自动路由；特定意图再过滤
-
-## 卸载
+## 卸载 / 关闭
 
-\`${CLI_INVOKE} unadopt\` 精确移除 sentinel 段 + 本文件；其它 MEMORY.md 内容不动。
+- \`${CLI_INVOKE} unadopt\`：移除 CLAUDE.md 托管块 + \`.claude/plugin_claude_mem_lite.md\`；
+  CLAUDE.md 里你自己的内容（sentinel 之外）不动。
+- 本项目永久关闭自动 adopt：\`${CLI_INVOKE} adopt --disable\`（\`--enable\` 重新武装）。
+- 全局禁用自动 adopt：环境变量 \`MEM_NO_AUTO_ADOPT=1\`。
+- 关闭版本漂移自动刷新（保留你对托管块的手改）：\`CLAUDE_MEM_NO_TEMPLATE_REFRESH=1\`。
 `;
 }

package/bash-utils.mjs

@@ -76,7 +76,14 @@ export function detectBashSignificance(input, response) {
   // Allow intervening global git options (`-C <path>`, `-c k=v`, `--no-pager`, …) between
   // `git` and the subcommand — `git -C /repo push` is the standard multi-repo/scripted form.
   const isGit = /\bgit\s+(?:(?:-[cC]\s+\S+|--?[\w-]+(?:=\S+)?)\s+)*(commit|merge|rebase|cherry-pick|push)\b/i.test(cmd);
-  const isDeploy = /\b(deploy|docker|kubectl|terraform)\b/i.test(cmd);
+  // Deploy + publish/release: the actual "ship". Package publish and GitHub
+  // release are rare, high-value events; without them a release session records
+  // the git push but not the publish that defines it. `npm run publish-*` is
+  // excluded (custom script, ambiguous) — only the direct publish verb counts.
+  const isDeploy = /\b(deploy|docker|kubectl|terraform)\b/i.test(cmd)
+    || /\b(?:npm|pnpm|yarn|bun|cargo)\s+publish\b/i.test(cmd)
+    || /\bgh\s+release\s+(?:create|edit|upload|delete)\b/i.test(cmd)
+    || /\btwine\s+upload\b/i.test(cmd);
   return {
     isError, isTest, isBuild, isGit, isDeploy,
     isSignificant: isError || isTest || isBuild || isGit || isDeploy,

package/claudemd.mjs

@@ -0,0 +1,244 @@
+// CLAUDE.md-steering plan (v3.13): claudemd.mjs — primitives for the
+// project-tree managed block at <cwd>/CLAUDE.md plus an on-demand detail doc
+// at <cwd>/.claude/plugin_<slug>.md.
+//
+// Why here and not memdir.mjs: Claude Code loads the project CLAUDE.md and the
+// memory-dir MEMORY.md at EQUAL weight, so steering belongs in CLAUDE.md (the
+// canonical home for project instructions) — seeding MEMORY.md just pollutes an
+// index meant for the user's own memories. This module mirrors the design
+// shipped by the sibling code-graph-mcp plugin (claude-plugin/scripts/adopt.js)
+// and the oh-my-claudecode versioned `<!-- :begin vN -->` managed-block pattern.
+//
+// The managed block is plugin-owned: it auto-refreshes when the shipped content
+// drifts (version bump or template change), UNLESS CLAUDE_MEM_NO_TEMPLATE_REFRESH=1.
+// User prose OUTSIDE the slug-scoped sentinel is never touched. The slug scope is
+// what keeps this independent from code-graph-mcp's own block in the same file.
+//
+// See docs/CLAUDE-MD-STEERING-PLAN.md for rationale + migration.
+
+import { readFileSync, writeFileSync, existsSync, renameSync, unlinkSync, mkdirSync, rmdirSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
+import { memdirPath, removePluginSection, removePluginDoc, isAdopted as memdirIsAdopted } from './memdir.mjs';
+
+// ─── Path helpers ────────────────────────────────────────────────────────────
+
+function slugSnake(slug) { return String(slug).replace(/[^a-zA-Z0-9]/g, '_'); }
+
+export function claudeMdPath(cwd) { return join(cwd, 'CLAUDE.md'); }
+function dotClaudeDir(cwd) { return join(cwd, '.claude'); }
+export function detailDocPath(cwd, slug) { return join(dotClaudeDir(cwd), `plugin_${slugSnake(slug)}.md`); }
+function stateFilePath(cwd, slug) { return join(dotClaudeDir(cwd), `.plugin_${slugSnake(slug)}_state.json`); }
+
+// First line of the detail doc — an invisible (in rendered markdown) marker that
+// lets us distinguish our generated copy from a user's same-named file.
+function managedByMarker(slug) { return `<!-- managed-by: ${slug} -->`; }
+
+// ─── Sentinel rendering & parsing ────────────────────────────────────────────
+
+function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+// Slug-scoped so stripping our block never disturbs another plugin's block
+// (e.g. code-graph-mcp's `<!-- code-graph-mcp:begin -->`) sitting in the same
+// CLAUDE.md. Matches any version vN+ for migration/idempotency. The separators
+// are `\r?\n` (not bare `\n`) so a CLAUDE.md re-saved with Windows CRLF endings
+// still matches — otherwise the block read as "absent" and a fresh LF copy got
+// appended every SessionStart, growing the file without bound (review C1/H2).
+function blockBody(esc) { return `<!-- ${esc}:begin (v\\d+) -->\\r?\\n([\\s\\S]*?)\\r?\\n<!-- ${esc}:end -->`; }
+function blockRegex(slug) { return new RegExp(blockBody(escapeRe(slug))); }
+function blockRegexG(slug) { return new RegExp(blockBody(escapeRe(slug)), 'g'); }
+
+function renderBlock(slug, version, body) {
+  return `<!-- ${slug}:begin ${version} -->\n${body}\n<!-- ${slug}:end -->`;
+}
+
+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 writeState(cwd, slug, state) {
+  const dir = dotClaudeDir(cwd);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  atomicWrite(stateFilePath(cwd, slug), JSON.stringify(state, null, 2) + '\n');
+}
+
+function clearState(cwd, slug) {
+  const p = stateFilePath(cwd, slug);
+  if (existsSync(p)) try { unlinkSync(p); } catch { /* best-effort */ }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Parse <cwd>/CLAUDE.md for our slug-scoped managed block.
+ * @returns {{ exists: boolean, version: string|null, body: string|null, raw: string }}
+ */
+export function readBlock(cwd, slug) {
+  const p = claudeMdPath(cwd);
+  if (!existsSync(p)) return { exists: false, version: null, body: null, raw: '' };
+  const raw = readFileSync(p, 'utf8');
+  const m = raw.match(blockRegex(slug));
+  if (!m) return { exists: true, version: null, body: null, raw };
+  // Normalize CRLF in the captured body so drift comparison (needsRefresh) is
+  // line-ending-agnostic — a CRLF-saved file matching the shipped LF content
+  // must NOT be seen as drifted and rewritten every session.
+  return { exists: true, version: m[1], body: m[2].replace(/\r\n/g, '\n'), raw };
+}
+
+/**
+ * Adopted under the new scheme = managed block present in CLAUDE.md AND the
+ * detail doc exists. Both must hold so a half-written state still self-heals.
+ */
+export function isAdopted(cwd, slug) {
+  const blk = readBlock(cwd, slug);
+  return blk.body !== null && existsSync(detailDocPath(cwd, slug));
+}
+
+/**
+ * Whether the installed block/doc has drifted from the shipped content — i.e.
+ * a version bump or a template edit means we should refresh. Returns true when
+ * the block is missing, the version differs, the block body differs, or the
+ * detail doc is missing / differs. The block is plugin-managed: drift is
+ * overwritten on refresh (opt out with CLAUDE_MEM_NO_TEMPLATE_REFRESH=1 at the
+ * caller). User content lives OUTSIDE the sentinel and is never compared.
+ */
+export function needsRefresh(cwd, { slug, version, block, doc }) {
+  const blk = readBlock(cwd, slug);
+  if (blk.body === null) return true;
+  if (blk.version !== version) return true;
+  if (blk.body !== block) return true;
+  const dp = detailDocPath(cwd, slug);
+  if (!existsSync(dp)) return true;
+  let cur;
+  try { cur = readFileSync(dp, 'utf8'); } catch { return true; }
+  return cur !== `${managedByMarker(slug)}\n${doc}`;
+}
+
+/**
+ * Write (insert-or-replace) the managed block in CLAUDE.md and the detail doc
+ * under .claude/, plus a state sidecar. Idempotent on the user-visible files:
+ * re-running with identical inputs leaves CLAUDE.md and the detail doc byte-for-
+ * byte unchanged (only the state sidecar's writtenAt updates).
+ *
+ * CLAUDE.md is created if absent. Only our slug-scoped region is rewritten;
+ * everything else in the file is preserved verbatim.
+ *
+ * @returns {{action: 'created'|'updated'|'unchanged'}} (block disposition)
+ */
+export function writeManaged(cwd, { slug, version, block, doc }) {
+  const p = claudeMdPath(cwd);
+  const raw = existsSync(p) ? readFileSync(p, 'utf8') : '';
+  const section = renderBlock(slug, version, block);
+  const m = raw.match(blockRegex(slug));
+
+  let next, action;
+  if (!m) {
+    if (raw.length === 0) next = section + '\n';
+    else if (raw.endsWith('\n\n')) next = raw + section + '\n';
+    else if (raw.endsWith('\n')) next = raw + '\n' + section + '\n';
+    else next = raw + '\n\n' + section + '\n';
+    action = 'created';
+  } else {
+    next = raw.replace(m[0], section);
+    action = next !== raw ? 'updated' : 'unchanged';
+  }
+  // H2: collapse any DUPLICATE same-slug blocks (keep the first, drop the rest).
+  // Defends against a CRLF-orphaned copy a pre-fix build may have appended, or a
+  // user paste — otherwise the extras would be invisible to refresh/unadopt.
+  let seen = 0;
+  const deduped = next.replace(blockRegexG(slug), (whole) => (seen++ === 0 ? whole : ''));
+  if (deduped !== next) {
+    next = deduped.replace(/\n{3,}/g, '\n\n');
+    if (action === 'unchanged') action = 'updated';
+  }
+  if (next !== raw) atomicWrite(p, next);
+
+  // Detail doc (marker on first line so unadopt/refresh can tell it apart from a
+  // user's same-named file).
+  const docContent = `${managedByMarker(slug)}\n${doc}`;
+  const dp = detailDocPath(cwd, slug);
+  const dir = dotClaudeDir(cwd);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const existingDoc = existsSync(dp) ? readFileSync(dp, 'utf8') : null;
+  if (existingDoc !== docContent) atomicWrite(dp, docContent);
+
+  writeState(cwd, slug, {
+    version,
+    blockHash: sha256(block),
+    docHash: sha256(doc),
+    writtenAt: new Date().toISOString(),
+  });
+  return { action };
+}
+
+/**
+ * Remove our managed block from CLAUDE.md (preserving all other content) and
+ * delete the detail doc + state sidecar. Best-effort removes an emptied
+ * .claude/ directory.
+ * @returns {{action: 'removed'|'absent'}}
+ */
+export function removeManaged(cwd, slug) {
+  const p = claudeMdPath(cwd);
+  let action = 'absent';
+  if (existsSync(p)) {
+    let raw = readFileSync(p, 'utf8');
+    // H2: loop so ALL same-slug blocks are removed, not just the first (a
+    // duplicate/CRLF-orphaned copy must not survive unadopt).
+    let m;
+    while ((m = raw.match(blockRegex(slug)))) {
+      const blockAtStart = m.index === 0;
+      let start = m.index;
+      let end = m.index + m[0].length;
+      if (raw[end] === '\n') end++;
+      if (start > 0 && raw.slice(0, start).endsWith('\n\n')) start--;
+      raw = raw.slice(0, start) + raw.slice(end);
+      raw = raw.replace(/\n{3,}/g, '\n\n');
+      if (blockAtStart) raw = raw.replace(/^\s+/, '');
+      action = 'removed';
+    }
+    if (action === 'removed') atomicWrite(p, raw);
+  }
+  const dp = detailDocPath(cwd, slug);
+  if (existsSync(dp)) try { unlinkSync(dp); } catch { /* best-effort */ }
+  clearState(cwd, slug);
+  // Drop an emptied .claude/ so unadopt leaves no trace (skips if it holds
+  // anything else — e.g. settings.local.json).
+  try {
+    const dir = dotClaudeDir(cwd);
+    if (existsSync(dir) && readdirSync(dir).length === 0) rmdirSync(dir);
+  } catch { /* best-effort */ }
+  return { action };
+}
+
+// ─── Legacy migration ────────────────────────────────────────────────────────
+
+/**
+ * One-time (idempotent) cleanup of the pre-v3.13 scheme: strip the slug-scoped
+ * sentinel from the project's memory-dir MEMORY.md and delete the memory-dir
+ * detail doc + state sidecar. Slug-scoped, so an adjacent code-graph-mcp block
+ * and all user prose survive byte-intact. Respects the foreign-content guard
+ * (a sentinel with no state sidecar is left in place) unless force=true.
+ *
+ * Absent legacy artifacts → harmless no-op, so this is safe to call every
+ * SessionStart.
+ *
+ * @returns {{action: 'removed'|'absent'|'skipped-foreign'}}
+ */
+export function migrateLegacyMemoryDir(cwd, slug, { force = false } = {}) {
+  const memdir = memdirPath(cwd);
+  const r = removePluginSection(memdir, slug, { force });
+  // M3: only delete the legacy detail doc when we actually removed OUR sentinel.
+  // On 'skipped-foreign' the sentinel is left in place (not provably plugin-
+  // written), so deleting its companion doc would leave a dangling pointer.
+  if (r.action === 'removed') removePluginDoc(memdir, slug);
+  return r;
+}
+
+/** True if the legacy memory-dir sentinel still exists for this project. */
+export function hasLegacyMemdirSentinel(cwd, slug) {
+  return memdirIsAdopted(memdirPath(cwd), slug);
+}

package/commands/adopt.md

@@ -1,60 +1,67 @@
 ---
 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."
+description: "Use when: user asks to increase claude-mem-lite's tool-invocation rate in the current project, or to (re)install the steering block. Writes a sentinel-wrapped managed block into <cwd>/CLAUDE.md plus a <cwd>/.claude/plugin_claude_mem_lite.md detail doc, and migrates away any legacy memory-dir sentinel. Runs automatically on SessionStart; use this to force it now. 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.
+Install the claude-mem-lite **steering block** into the current project's
+`CLAUDE.md` (the canonical home for project instructions — loaded by Claude Code
+at system-prompt authority). This replaces the pre-v3.13 scheme that seeded the
+project's memory-dir `MEMORY.md`; that polluted an index meant for the user's own
+memories, and `MEMORY.md` carries no more weight than `CLAUDE.md` anyway.
+
+This normally runs automatically on every SessionStart — invoke `/adopt` only to
+force it immediately (e.g. after editing the block out by hand).
 
 ## 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.
+1. **`<cwd>/CLAUDE.md`** — a concise `<!-- claude-mem-lite:begin v2 -->…<!-- :end -->`
+   managed block (trigger table → `mem_recall` / `mem_save` / `mem_defer`).
+   Slug-scoped: only this block is managed; the rest of your `CLAUDE.md` is
+   preserved verbatim. Auto-refreshes when the shipped content drifts.
+2. **`<cwd>/.claude/plugin_claude_mem_lite.md`** — the full contract (tool tables,
+   CLI cheatsheet, citation/decay + save discipline). First line is a
+   `<!-- managed-by: claude-mem-lite -->` marker. Not auto-loaded; the CLAUDE.md
+   block points to it and Claude reads it on demand.
+3. **`<cwd>/.claude/.plugin_claude_mem_lite_state.json`** — drift-tracking sidecar.
+
+It also **migrates** this project's legacy memory-dir sentinel away (strips the
+`claude-mem-lite:*` block from `MEMORY.md` and deletes the old memory-dir detail
+doc). Other plugins' blocks (e.g. `code-graph-mcp:*`) and your own prose survive.
 
 ## Flags
 
-- `--force` — overwrite a sentinel block that was manually edited
+- `--force` — also force-clean a legacy memory-dir block lacking a state sidecar
 - `--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
+- `--all` — legacy-cleanup sweep: strip the old memory-dir sentinel across **every**
+  project at once. (It does NOT write CLAUDE.md blocks for other projects — their
+  real paths can't be recovered from the encoded memdir slug; those adopt
+  per-project on each one's next SessionStart.)
+- `--status` — show this project's adoption + count of memdirs awaiting migration
+- `--disable` / `--enable` — per-project opt-out of automatic SessionStart adopt
 
-## Removal
+## Removal & opt-out
 
-`/unadopt` precisely removes the sentinel block + plugin doc + state file.
-User content outside the sentinel is preserved.
+- `/unadopt` removes the CLAUDE.md block + `.claude/` detail doc (your prose stays).
+- `claude-mem-lite adopt --disable` permanently stops auto-adopt for this project.
+- `MEM_NO_AUTO_ADOPT=1` disables auto-adopt globally.
+- `CLAUDE_MEM_NO_TEMPLATE_REFRESH=1` freezes the block against drift-refresh
+  (keeps your hand-edits to the managed block).
 
 ## 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.
-
-## Restart required for MCP trim to take effect
-
-The MCP server builds its instructions once at server boot and the protocol
-has no way to push updated instructions to an already-connected Claude Code
-session. After running `adopt`:
+UserPromptSubmit related-memory). Those remain as fallback. Post-adopt the MCP
+`WHEN TO USE` section + the `File Lessons` / `Key Context` sections auto-trim,
+since the CLAUDE.md block already carries the triggers at higher authority.
 
-- The **MEMORY.md sentinel** appears on the **next SessionStart** automatically.
-- Hook-layer trim (`File Lessons` / `Key Context` / lesson suffix) applies
-  on the next SessionStart.
-- MCP-instructions trim (`WHEN TO USE` / `Decision rules` sections) only
-  takes effect after Claude Code itself restarts (or at least re-attaches
-  the mem-lite MCP server). If you still see the verbose MCP instructions after
-  adopt, a `/exit` + fresh session is enough.
+## Restart caveat for the MCP-instructions trim
 
+The CLAUDE.md block + hook-layer trim apply on the **next SessionStart**. The MCP
+server builds its instructions once at boot, so the MCP-instructions trim
+(`WHEN TO USE` / `Decision rules`) only takes effect after Claude Code restarts
+(or re-attaches the mem-lite MCP server). A `/exit` + fresh session is enough.
 Same caveat applies in reverse for `/unadopt`.
 
 !node ${CLAUDE_PLUGIN_ROOT}/cli.mjs adopt $ARGUMENTS

package/commands/unadopt.md

@@ -1,30 +1,44 @@
 ---
 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."
+description: "Use when: user wants to remove the claude-mem-lite steering block from the current project (or sweep legacy memory-dir sentinels everywhere with --all). Removes the <cwd>/CLAUDE.md managed block + <cwd>/.claude/plugin_claude_mem_lite.md and cleans any legacy memory-dir residue. User content outside the sentinel is preserved. Benign no-op when not adopted."
 ---
 
 # /unadopt
 
-Remove the claude-mem-lite invited-memory sentinel from the current project's
-Claude Code memdir. Opposite of `/adopt`.
+Remove the claude-mem-lite steering block from the current project. 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.
+1. The `<!-- claude-mem-lite:begin vN --> … <!-- claude-mem-lite:end -->` managed
+   block from `<cwd>/CLAUDE.md`. Everything else in the file is preserved
+   byte-for-byte.
+2. `<cwd>/.claude/plugin_claude_mem_lite.md` detail doc.
+3. `<cwd>/.claude/.plugin_claude_mem_lite_state.json` sidecar (and an emptied
+   `.claude/` dir).
 
-Everything else in `MEMORY.md` is preserved byte-for-byte.
+It also cleans any leftover **legacy** memory-dir sentinel + detail doc for this
+project (slug-scoped — other plugins' blocks survive).
 
 ## Flags
 
-- `--all` — unadopt every memdir under `~/.claude/projects/*/memory/`
+- `--force` — also remove a legacy memory-dir block lacking a state sidecar
+- `--dry-run` — preview what would be removed; no writes
+- `--all` — legacy-cleanup sweep: strip the old memory-dir sentinel across every
+  project (CLAUDE.md blocks for other projects can't be located from the encoded
+  slug — `cd` into a project and run `/unadopt` there to remove its block).
+- `--status` — read-only adoption probe (mirrors `/adopt --status`)
+
+## Note: this does not stop auto-adopt
+
+`/unadopt` removes the block now, but the next SessionStart re-adopts unless you
+also disable it: `claude-mem-lite adopt --disable` (per-project) or
+`MEM_NO_AUTO_ADOPT=1` (global).
 
 ## 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.
+`Key Context`, MCP instructions `WHEN TO USE`) returns to verbose mode on the
+next session start.
 
 !node ${CLAUDE_PLUGIN_ROOT}/cli.mjs unadopt $ARGUMENTS