claude-mem-lite 6.29.2 → 6.30.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.29.2",
+      "version": "6.30.0",
       "source": "./",
       "homepage": "https://github.com/sdsrss/claude-mem-lite",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.29.2",
+  "version": "6.30.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -124,7 +124,7 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
   <br>Original behaviour and the measurements behind it via explicit keywords or FTS5 term overlap. **The `/clear` and `/compact` arm fires since v5.4.0** (R10-P1-1); before that it had never once written a row — `session_handoffs` on the maintainer's install held 4 `exit` rows and **0** `clear` rows. Two host facts settled it, both measured rather than assumed. (1) `Stop` runs at the end of every assistant *turn*, not once per session, and it deleted the session file that SessionStart reads to learn which session just ended — so the branch was unreachable, and mem sessions were minted per turn (58 prompts over 16 host sessions produced 56 mem sessions and 56 summary rows, 2026-09-07). (2) Claude Code **rotates its session id across `/clear`**: of 21 real transcripts, 12 carry a `/clear` command record, and in 12/12 that record's timestamp precedes its own file's first record by ~0.1s — the command is issued in the old session and replayed into a new file under a new id. So `Stop` no longer deletes the file, SessionStart asks the host's `source` (`startup`/`clear`/`compact`/`resume`) instead of guessing from the file, and the handoff's prompt lookup falls back to the unscoped set when the new session's id matches none. Revert path: `CLAUDE_MEM_LEGACY_STOP_UNLINK=1`
 - **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`. `hook-llm` routes non-memdir summary types through `persistHaikuSummary` so upgrades from observations→events are atomic. (v3.39: the `/lesson` and `/bug` slash commands were redirected from this events table to searchable **observations** — `mem_search` never read the events table, so explicit saves were unfindable; the events table remains the auto-capture activity log.)
+- **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`. `hook-llm` routes non-memdir summary types through `persistHaikuSummary` so upgrades from observations→events are atomic. (v3.39: the `/lesson` and `/claude-mem-lite:bug` slash commands were redirected from this events table to searchable **observations** — `mem_search` never read the events table, so explicit saves were unfindable; the events table remains the auto-capture activity log.)
 - **In-place observation updates** -- `mem_update` tool modifies existing observations atomically (field update + FTS text rebuild 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
@@ -165,7 +165,7 @@ is still outside it gets a message naming both sides of the mismatch instead of
 
 Plugin mode manages its own hooks/runtime. On session start it only **checks and reports** new claude-mem-lite versions; it does **not** self-overwrite plugin files in place. Update plugin-mode installs through Claude's plugin workflow.
 
-> **The plugin install is complete on its own** — hooks, MCP tools, and the bundled slash commands (`/mem`, `/lesson`, `/bug`, `/adopt`) all run from the plugin with no second step. The slash commands invoke the bundled CLI by an absolute path resolved from the plugin directory (`node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" <cmd>`), so they work without anything on your `PATH`. A global `claude-mem-lite` **shell** command (for running queries yourself in a terminal) is **optional** — `npm i -g claude-mem-lite` — and is a *separate* npm install: the plugin's auto-update does **not** refresh it, so re-run `npm i -g claude-mem-lite@latest` if you want that shell command kept in sync. You do **not** need it for the plugin to be fully functional.
+> **The plugin install is complete on its own** — hooks, MCP tools, and the bundled slash commands (`/mem`, `/lesson`, `/claude-mem-lite:bug`, `/adopt`) all run from the plugin with no second step. The slash commands invoke the bundled CLI by an absolute path resolved from the plugin directory (`node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" <cmd>`), so they work without anything on your `PATH`. A global `claude-mem-lite` **shell** command (for running queries yourself in a terminal) is **optional** — `npm i -g claude-mem-lite` — and is a *separate* npm install: the plugin's auto-update does **not** refresh it, so re-run `npm i -g claude-mem-lite@latest` if you want that shell command kept in sync. You do **not** need it for the plugin to be fully functional.
 
 > **Auto-adopt no longer adds its block to your project's `CLAUDE.md` (next release after 6.19.4).** On every SessionStart the plugin delivers its steering text — the trigger table that boosts Claude's proactive use of `mem_recall` / `mem_save`. In a git repository that does not already carry the block it keeps a managed block in `CLAUDE.local.md` at the repository root (Claude Code loads that file like `CLAUDE.md`, also in subagents that load project instructions; the built-in Explore and Plan agents load none) and adds the file to the repository's `.git/info/exclude` unless your ignore rules already cover it, so git does not list or commit it; you get a **one-time notice** the first time it is written. Claude Code reads instruction files before the plugin's startup hook runs, so the session that creates the file gets the text added to its context instead, once (its subagents do not see it). Where Claude Code reads an `AGENTS.md` as the project's instructions, it stops reading it once a `CLAUDE.md` or `CLAUDE.local.md` exists in the session's directory or above, so there nothing is written and the text is **injected** (subagents do not see it), with a one-time notice that names that `AGENTS.md`. With `CLAUDE_MEM_RULES_STEERING=1` the block goes to `.claude/rules/claude-mem-lite.md` at the repository root instead — excluded from git the same way, loaded by Claude Code as project instructions, also in subagents that load project instructions, and it leaves `AGENTS.md` loading — with its own one-time notice; it is not the default because in a pre-registered A/B it did not beat injection by the bar set in advance (`docs/audits/20261006-d212-ab.md`). Outside git, in a repository rooted at `$HOME`, where `CLAUDE.local.md` is tracked or a symbolic link, or where the repository root is an npm package that `npm publish` would ship it with (no `"private": true`, no `files` list leaving it out, and without one no `.npmignore` naming it), nothing is written and the text is **injected** into each session's context, with a one-time notice suggesting `/adopt` (not at `$HOME`). With the variable set, the same holds where the rules file cannot be written (a symbolic link on its path, a tracked or foreign file of that name, an npm package that would ship it). The notice beside an `AGENTS.md` names it, why there is no file, and the ways to a file that keep it loading, each only where it works: Project instructions = `claude-md-and-agents-md` in `/config`, after which `CLAUDE.local.md` is written (not where `CLAUDE.local.md` is refused too: a package root, or a file you removed), and `/adopt`, whose `CLAUDE.md` imports the `AGENTS.md` beside it (not offered when an `AGENTS.md` above that directory or in a subdirectory would stop loading). The detail file the block points at lives in the plugin's data directory, named with a `~/` path. `.git/info/exclude` is read by git only: docker build contexts, archives and other packagers can pick `CLAUDE.local.md` or the rules file up (a publishable npm package root does not keep `CLAUDE.local.md`: a block written before is taken out at the next session start; in a project whose `AGENTS.md` it would switch off, the block comes out and is injected, or, with `CLAUDE_MEM_RULES_STEERING=1`, moves to the rules file where that can be written). Earlier versions added the block to your project's own `<cwd>/CLAUDE.md` (a file that is normally committed) plus a `<cwd>/.claude/plugin_claude_mem_lite.md` detail file, unasked, in every project you opened; those projects keep the block, and the first session of this version refreshes it because the text changed — to move one to the local file, run `claude-mem-lite unadopt` there and commit the removal. Why not inject everywhere: in our sandbox evaluation (one project, Claude Opus 5.5) the agent made 1.5 proactive memory saves per 8-session run with injected steering against 5.25 with the block in `CLAUDE.local.md` or `CLAUDE.md`, and subagents never saw injected text. It applies regardless of install path (npm, npx, `/plugin`, manual); silence these notices with `MEM_NO_ADOPT_HINT=1`.
 >
@@ -684,9 +684,9 @@ have not allowed, and routing the same action through Bash would sidestep it.
 /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)
-/verify                    # Check memories against the current code; correct stale ones after you approve
+/lesson <text>             # Save a non-obvious lesson as a searchable observation
+/claude-mem-lite:bug <text>  # Log a known bug + repro steps as a searchable observation
+/claude-mem-lite:verify      # Check memories against the current code; correct stale ones after you approve
 ```
 
 ### Efficient Search Workflow
@@ -701,12 +701,10 @@ have not allowed, and routing the same action through Bash would sidestep it.
 
 Opt-in mechanism that installs a slug-scoped managed block into the project's
 own `CLAUDE.md` (plus an on-demand detail doc under `.claude/`) so Claude Code
-loads the plugin's MCP-tool triggers as **project instructions** — a higher
-instruction-following authority than MCP server instructions (which are framed
-as tool metadata). Claude Code loads `CLAUDE.md` and the memdir `MEMORY.md` at
-equal weight, so steering lives in `CLAUDE.md` (the canonical home for project
-instructions) rather than polluting `MEMORY.md`, which is reserved for the user's
-own memories. The pre-v3.13 scheme wrote into `MEMORY.md`; it is migrated away
+loads the plugin's MCP-tool triggers as **project instructions**, delivered in a
+message after the system prompt. Steering lives in `CLAUDE.md` (the canonical home
+for project instructions) rather than in the memdir `MEMORY.md`, which is reserved
+for the user's own memories. The pre-v3.13 scheme wrote into `MEMORY.md`; it is migrated away
 automatically on the next SessionStart.
 
 ```bash

package/README.zh-CN.md

@@ -95,7 +95,7 @@
 - **插件缓存 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`。`hook-llm` 通过 `persistHaikuSummary` 路由非 memdir 摘要，observations → events 升级路径是事务原子的。（v3.39：`/lesson`、`/bug` 斜杠命令已从此 events 表重定向到可搜索的 **observations**——`mem_search` 从不读 events 表，显式保存因此搜不到；events 表仍作自动捕获活动日志。）
+- **活动命名空间**（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`。`hook-llm` 通过 `persistHaikuSummary` 路由非 memdir 摘要，observations → events 升级路径是事务原子的。（v3.39：`/lesson`、`/claude-mem-lite:bug` 斜杠命令已从此 events 表重定向到可搜索的 **observations**——`mem_search` 从不读 events 表，显式保存因此搜不到；events 表仍作自动捕获活动日志。）
 
 ## 平台支持
 
@@ -129,7 +129,7 @@ v5.1.0 到 v6.1.0 之间，`package.json` 声明的是 `os: ["darwin", "linux"]`
 
 插件模式会管理自己的运行时与钩子。SessionStart 时它现在只会**检查并提示**新版本，不会直接覆盖插件目录中的文件。插件模式请通过 Claude 的插件更新流程完成升级。
 
-> **插件安装本身即完整** —— hooks、MCP 工具、以及捆绑的 slash 命令（`/mem`、`/lesson`、`/bug`、`/adopt`）全部从插件内运行，无需第二步。slash 命令以从插件目录解析出的绝对路径调用捆绑 CLI（`node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" <cmd>`），因此不依赖 `PATH` 上的任何东西。全局 `claude-mem-lite` **shell** 命令（用于你自己在终端里跑查询）是**可选**的 —— `npm i -g claude-mem-lite` —— 且是**独立**的 npm 安装：插件的自动更新**不会**刷新它，想保持同步就重新跑 `npm i -g claude-mem-lite@latest`。插件要完整工作**并不需要**它。
+> **插件安装本身即完整** —— hooks、MCP 工具、以及捆绑的 slash 命令（`/mem`、`/lesson`、`/claude-mem-lite:bug`、`/adopt`）全部从插件内运行，无需第二步。slash 命令以从插件目录解析出的绝对路径调用捆绑 CLI（`node "${CLAUDE_PLUGIN_ROOT}/cli.mjs" <cmd>`），因此不依赖 `PATH` 上的任何东西。全局 `claude-mem-lite` **shell** 命令（用于你自己在终端里跑查询）是**可选**的 —— `npm i -g claude-mem-lite` —— 且是**独立**的 npm 安装：插件的自动更新**不会**刷新它，想保持同步就重新跑 `npm i -g claude-mem-lite@latest`。插件要完整工作**并不需要**它。
 
 ### 方式二：npx（一行命令）
 
@@ -533,9 +533,9 @@ README 和 `docs/ARCHITECTURE.md` 都钉在它上面。）
 /mem timeline <query>      # 围绕匹配结果浏览时间线
 /mem browse                # 分层记忆仪表盘
 /mem <query>               # search 的简写
-/lesson <text>             # 保存非显而易见的经验到 events 表（v2.31.0）
-/bug <text>                # 记录已知 bug + 复现步骤到 events 表（v2.31.0）
-/verify                    # 对照当前代码核查记忆；你确认后才改正过期的记忆
+/lesson <text>             # 把非显而易见的经验存为可搜索的 observation
+/claude-mem-lite:bug <text>  # 把已知 bug + 复现步骤记为可搜索的 observation
+/claude-mem-lite:verify      # 对照当前代码核查记忆；你确认后才改正过期的记忆
 ```
 
 ### 高效搜索工作流
@@ -548,10 +548,11 @@ README 和 `docs/ARCHITECTURE.md` 都钉在它上面。）
 
 ### 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 权威。
+Opt-in 机制——在项目自己的 `CLAUDE.md` 里写入一个按 slug 限定的托管块（外加 `.claude/` 下
+按需读取的详情文档），让 Claude Code 把插件的 MCP 工具触发规则作为**项目指令**加载（在系统
+提示之后的一条消息里送达）。引导放在 `CLAUDE.md`（项目指令的正规位置），不去占用 memdir 里
+留给用户自己记忆的 `MEMORY.md`。v3.13 之前的方案写入
+`MEMORY.md`；下一次 SessionStart 会自动迁走。
 
 ```bash
 claude-mem-lite adopt              # 当前项目注入
@@ -566,16 +567,19 @@ claude-mem-lite unadopt            # 移除 CLAUDE.md 托管块和详情文档
 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` 详情文件（按需读取，不自动加载）。
+- `<cwd>/CLAUDE.md` 新增一段 `<!-- claude-mem-lite:begin v1 -->…<!-- claude-mem-lite:end -->`
+  包裹、带独立 `## claude-mem-lite — persistent memory` 标题的托管块，内含指向
+  `mem_recall` / `mem_save` / `mem_defer` 及其关键参数的触发表。只管理这一段，`CLAUDE.md`
+  其余内容原样保留，可与其他插件（如 `code-graph-mcp`）的托管块共存于同一文件。
+- 生成 `<cwd>/.claude/plugin_claude_mem_lite.md` 详情文件（不自动加载；`CLAUDE.md` 托管块
+  指向它时按需读取）。出货内容变化（版本升级或模板变更）时托管块自动刷新，除非设
+  `CLAUDE_MEM_NO_TEMPLATE_REFRESH=1`。
 - 保守 hook 层自动瘦身：MCP server instructions 去掉 `WHEN TO USE` 段，
   SessionStart 注入去掉 `File Lessons` / `Key Context`。`#ID` 引用与 `Recent`
   表保留，`mem_get` 仍可随时展开。
 
 **什么时候生效？**
-- MEMORY.md sentinel 和 hook 层瘦身（`File Lessons` / `Key Context` / lesson
+- `CLAUDE.md` 托管块和 hook 层瘦身（`File Lessons` / `Key Context` / lesson
   后缀）**下一次 SessionStart** 生效（adopt 的项目下任一新会话）。
 - MCP server instructions 是**服务启动时构建一次**，MCP 协议无 "push" 机制，
   所以 `WHEN TO USE` / `Decision rules` 两段的瘦身**只在 Claude Code 重启后**

package/adopt-cli.mjs

@@ -50,7 +50,7 @@ import {
   claudeMdPath,
   detailDocPath,
   addAgentsImports,
-  holdsOnlyOwnLines,
+  holdsOnlyPluginLines,
   straySentinelLines,
 } from './claudemd.mjs';
 import { PLUGIN_SLUG, CURRENT_SENTINEL_VERSION, buildClaudeMdBlock, getDetailDoc } from './adopt-content.mjs';
@@ -77,7 +77,9 @@ import {
   isSharedAncestor,
   samePath,
   localFileLinked,
+  userInstructionFiles,
 } from './lib/local-steering.mjs';
+import { CLI_INVOKE } from './cli-path.mjs';
 
 /**
  * Remove the auto-written local block (CLAUDE.local.md, or the D#212 rules file) for the project at
@@ -226,7 +228,7 @@ function adoptOne(cwd, { force, dryRun }) {
   const sharedNote = (verb) =>
     switchesOffBelow
       ? [
-          `  ⚠ ${claudeMdPath(cwd)} ${verb} Claude Code reading the AGENTS.md of every project below ${cwd} that has one; to steer one project, run adopt inside it instead${verb === 'stops' ? ' (`claude-mem-lite unadopt` here takes this back)' : ''}, or set Project instructions to claude-md-and-agents-md in /config`,
+          `  ⚠ ${claudeMdPath(cwd)} ${verb} Claude Code reading the AGENTS.md of every project below ${cwd} that has one; to steer one project, run adopt inside it instead${verb === 'stops' ? ` (\`${CLI_INVOKE} unadopt\` here takes this back)` : ''}, or set Project instructions to claude-md-and-agents-md in /config`,
         ]
       : [];
 
@@ -262,7 +264,12 @@ function adoptOne(cwd, { force, dryRun }) {
           : local.action === 'failed'
             ? ` (could not remove the block from ${local.path}, so sessions here load it twice)`
             : ` (+removed the block from ${local.path})`;
-    log(`[adopt] ${cwd} → ${r.action}${migNote}${localNote}${importNote}`);
+    // The block's disposition alone read "unchanged" over a rewritten detail doc (D#470).
+    const docNote =
+      r.action === 'unchanged' && r.docAction !== 'unchanged'
+        ? ` (+${r.docAction === 'created' ? 'wrote' : 'refreshed'} detail doc)`
+        : '';
+    log(`[adopt] ${cwd} → ${r.action}${docNote}${migNote}${localNote}${importNote}`);
     for (const line of elsewhere('stops')) log(line);
     for (const line of sharedNote('stops')) log(line);
     // The copy that could not come out loads beside CLAUDE.md: said, and not a success (R3-4).
@@ -373,13 +380,17 @@ export function silentAutoAdopt({ cwd, markerDir, markerKey }) {
     // cost most of the proactive memory writes (1.5 vs 5.25 per trajectory) and never reached
     // subagents (0/12). Inside a git work tree the block now goes to CLAUDE.local.md, which the
     // host loads like CLAUDE.md and info/exclude keeps out of commits (5.25 writes, 12/12).
-    const hasBlock = blockIn(cwd);
+    // managed-only loads no project CLAUDE.md either (code.claude.com/docs/en/memory): a block in
+    // one steers nothing, so the session goes on to the refused local file and injects, and the
+    // file stays as it is (v6.30.0 pre-tag defects review P2-2).
+    const managedOnly = userInstructionFiles() === 'managed-only';
+    const hasBlock = !managedOnly && blockIn(cwd);
     if (!hasBlock) {
       if (markerDir && markerKey) writeMarker(markerDir, markerKey);
       // A damaged sentinel line (`… --> (team note)`) leaves the block's text in CLAUDE.md, which
       // the host loads, while the block no longer parses: a copy written to CLAUDE.local.md or
       // injected here was a second one. Neither; `adopt` names the line and the fix (D#369 B14).
-      const stray = straySentinelLines(claudeMdPath(cwd), PLUGIN_SLUG);
+      const stray = managedOnly ? [] : straySentinelLines(claudeMdPath(cwd), PLUGIN_SLUG);
       if (stray.length > 0) return { ok: true, action: 'damaged', reason: 'stray-sentinel', lines: stray };
       const root = localSteeringRoot(cwd);
       if (root) {
@@ -387,7 +398,13 @@ export function silentAutoAdopt({ cwd, markerDir, markerKey }) {
         // loads the root's CLAUDE.md as an ancestor, so a block there already steers this
         // session; and an opt-out recorded for the root covers the file that lives there.
         if (!samePath(root, cwd)) {
-          if (blockIn(root)) return { ok: true, action: 'already-adopted', reason: 'root-claude-md' };
+          const above = managedOnly ? null : blockAbove(cwd, root);
+          if (above)
+            return {
+              ok: true,
+              action: 'already-adopted',
+              reason: samePath(above, root) ? 'root-claude-md' : 'ancestor-claude-md',
+            };
           // Off for the project means off here too: no file, no injected copy, no /adopt offer
           // (delta review P2-2; lib/quiet-scope.mjs mirrors it).
           if (isAutoAdoptDisabledFor(root)) return { ok: true, action: 'disabled', reason: 'root-disabled' };
@@ -421,7 +438,11 @@ export function silentAutoAdopt({ cwd, markerDir, markerKey }) {
           agentsMd: r.agentsMd,
         };
       }
-      return { ok: true, action: 'inject' };
+      // managed-only loads no project CLAUDE.md, so the hook does not offer /adopt (v6.30.0 pre-tag
+      // claims review P2-5; inside a git work tree the reason is local-managed-only).
+      return managedOnly
+        ? { ok: true, action: 'inject', reason: 'managed-only' }
+        : { ok: true, action: 'inject' };
     }
     dropLocalSteering(cwd, { atRootOnly: true, keepTracked: true });
     let action = 'already-adopted';
@@ -462,8 +483,8 @@ function syncAgentsImports(cwd) {
   // project below it, each asking to approve an import from outside its directory.
   if (isSharedAncestor(cwd)) return null;
   // The cheap check first: most CLAUDE.md files hold the user's own lines, and the full answer
-  // asks git.
-  if (!holdsOnlyOwnLines(claudeMdPath(cwd), PLUGIN_SLUG)) return null;
+  // asks git. Another plugin's managed block counts as plugin text, not the user's (D#220).
+  if (!holdsOnlyPluginLines(claudeMdPath(cwd), PLUGIN_SLUG)) return null;
   const agents = agentsMdForNewClaudeMd(cwd, PLUGIN_SLUG);
   if (!agents) return null;
   const imported =
@@ -501,6 +522,16 @@ function blockIn(dir) {
   }
 }
 
+// The nearest directory above `cwd`, up to and including `root`, whose CLAUDE.md carries the block:
+// the host loads it as an ancestor. `adopt` run in packages/ and a session in packages/web/src got a
+// root CLAUDE.local.md on top of packages/CLAUDE.md, the block twice (D#177(2)).
+function blockAbove(cwd, root) {
+  for (let d = dirname(cwd); ; d = dirname(d)) {
+    if (blockIn(d)) return d;
+    if (samePath(d, root) || dirname(d) === d) return null;
+  }
+}
+
 function writeMarker(markerDir, markerKey) {
   if (!existsSync(markerDir)) mkdirSync(markerDir, { recursive: true });
   const path = join(markerDir, `.auto-adopt-${markerKey}`);
@@ -620,9 +651,11 @@ function cmdEnable(args) {
 function localSteeringStatus(cwd) {
   const root = localSteeringRoot(cwd);
   const runs = autoAdoptRuns(cwd, root);
-  // CLAUDE.md first: where it carries the block, no local file is written and nothing is injected,
-  // in a git work tree or not (pre-tag delta review of the D#212 repairs, D11).
-  if (blockIn(cwd) || (root && blockIn(root))) {
+  // CLAUDE.md first: where it carries the block, no local file is written, in a git work tree or not
+  // (pre-tag delta review of the D#212 repairs, D11).
+  if (blockIn(cwd) || (root && !samePath(root, cwd) && blockAbove(cwd, root))) {
+    if (userInstructionFiles() === 'managed-only')
+      return '⚠ CLAUDE.md carries the block, but Project instructions is set to managed-only, which does not load it';
     const cur = root ? readLocalSteering(root, PLUGIN_SLUG) : null;
     if (cur === null || cur.body === null) return '— none: CLAUDE.md carries the block';
     const kept = localFileLinked(root, cur.path)
@@ -642,7 +675,7 @@ function localSteeringStatus(cwd) {
   }
   // Before "not a git work tree": with auto-adopt off nothing is injected either (R3-13).
   if (isAutoAdoptDisabledFor(cwd) || (root && isAutoAdoptDisabledFor(root)))
-    return '— none: auto-adopt is off for this project (`claude-mem-lite adopt --enable` turns it back on)';
+    return `— none: auto-adopt is off for this project (\`${CLI_INVOKE} adopt --enable\` turns it back on)`;
   if (process.env.MEM_NO_AUTO_ADOPT === '1')
     return '— none: MEM_NO_AUTO_ADOPT=1, so no local file is written';
   if (!root)
@@ -656,10 +689,10 @@ function localSteeringStatus(cwd) {
     const plan = planLocalSteering(root, PLUGIN_SLUG, cwd);
     const beside = plan.agentsMd ?? 'the AGENTS.md';
     if (plan.file === RULES_MD && plan.refusal === 'off')
-      return `${removed}; beside ${beside} a file comes back only with CLAUDE_MEM_RULES_STEERING=1 and then \`claude-mem-lite adopt --enable\``;
+      return `${removed}; beside ${beside} a file comes back only with CLAUDE_MEM_RULES_STEERING=1 and then \`${CLI_INVOKE} adopt --enable\``;
     if (plan.file === RULES_MD && plan.refusal)
       return `${removed}; beside ${beside}, ${rulesWhy(plan.refusal)}`;
-    return `${removed}; after \`claude-mem-lite adopt --enable\` the next session may write it again`;
+    return `${removed}; after \`${CLI_INVOKE} adopt --enable\` the next session may write it again`;
   }
   const plan = planLocalSteering(root, PLUGIN_SLUG, cwd);
   if (!plan.refusal)
@@ -671,7 +704,7 @@ function localSteeringStatus(cwd) {
     ways.settingGivesFile
       ? 'set Project instructions to claude-md-and-agents-md in /config and CLAUDE.local.md is written instead'
       : null,
-    ways.adoptImports ? 'run `claude-mem-lite adopt`, whose CLAUDE.md imports AGENTS.md' : null,
+    ways.adoptImports ? `run \`${CLI_INVOKE} adopt\`, whose CLAUDE.md imports AGENTS.md` : null,
   ].filter(Boolean);
   return `✗ not written: Claude Code stops reading ${plan.agentsMd ?? 'the AGENTS.md'} once a CLAUDE.local.md exists, and ${rulesWhy(plan.refusal)} (steering is injected at session start${alt.length ? `; ${alt.join(', or ')}` : ''})`;
 }
@@ -685,6 +718,9 @@ function currentLocalLine(root, cwd, cur, runs) {
     return `✓ ${cur.path} (behind a symbolic link; the plugin leaves it as it is)`;
   if (trackedByGit(root, rel)) return `✓ ${cur.path} (tracked by git; the plugin leaves it as it is)`;
   const plan = runs ? planLocalSteering(root, PLUGIN_SLUG, cwd) : null;
+  // Left in place under managed-only (writeLocalSteering, D#219), not removed.
+  if (plan?.refusal === 'managed-only')
+    return `⚠ ${cur.path} (auto-written, but CLAUDE.local.md ${LOCAL_REFUSAL_TEXT['managed-only']}; the steering is injected, and the file stays for when the setting changes)`;
   if (plan?.refusal) {
     const why =
       plan.file === LOCAL_MD
@@ -764,7 +800,7 @@ function statusAll() {
     `[adopt --status] scanned ${dirs.length} memdir(s): ${legacy} with legacy sentinel (await migration), ${disabled} auto-adopt-disabled.`,
   );
   if (legacy > 0)
-    log('[adopt --status] run `claude-mem-lite adopt --all` to sweep legacy memory-dir sentinels now.');
+    log(`[adopt --status] run \`${CLI_INVOKE} adopt --all\` to sweep legacy memory-dir sentinels now.`);
 
   const known = listKnownProjectDirs();
   let adoptedCount = 0;
@@ -773,7 +809,7 @@ function statusAll() {
     `[adopt --status] known projects (~/.claude.json): ${known.length} scanned, ${adoptedCount} with a CLAUDE.md managed block or partial residue (detail doc/state).`,
   );
   if (adoptedCount > 0)
-    log('[adopt --status] run `claude-mem-lite unadopt --all` to remove every CLAUDE.md block.');
+    log(`[adopt --status] run \`${CLI_INVOKE} unadopt --all\` to remove every CLAUDE.md block.`);
 
   const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ? 'set' : 'unset';
   const noAutoAdopt = process.env.MEM_NO_AUTO_ADOPT === '1' ? '1 (opt-out)' : 'unset';
@@ -783,7 +819,7 @@ function statusAll() {
     `  CLAUDE_PLUGIN_ROOT  = ${pluginRoot}  (any install path is consent; gate is the per-project opt-out below)`,
   );
   log(`  MEM_NO_AUTO_ADOPT   = ${noAutoAdopt}  (global escape hatch)`);
-  log('Per-project opt-out: `claude-mem-lite adopt --disable` (run --enable to re-arm).');
+  log(`Per-project opt-out: \`${CLI_INVOKE} adopt --disable\` (run --enable to re-arm).`);
 }
 
 /**
@@ -852,7 +888,7 @@ function unadoptAll(args) {
   if (failures > 0) process.exitCode = 1;
   if (projectDirs.length === 0) {
     log(
-      '[unadopt --all] no known projects found in ~/.claude.json — if a project was adopted but never opened in Claude Code, run `claude-mem-lite unadopt` from inside it.',
+      `[unadopt --all] no known projects found in ~/.claude.json — if a project was adopted but never opened in Claude Code, run \`${CLI_INVOKE} unadopt\` from inside it.`,
     );
   }
 }

package/adopt-content.mjs

@@ -73,7 +73,6 @@ export function getDetailDoc() {
 
 > 由 \`${CLI} adopt\` 生成、随版本自动刷新；卸载用 \`${CLI} unadopt\`。
 > 精炼触发表由 SessionStart 注入会话上下文（显式 \`${CLI} adopt\` 过的项目则写在 \`CLAUDE.md\` 的 \`claude-mem-lite\` 托管块里）；本文件是其展开。
-> 设计背景见 docs/CLAUDE-MD-STEERING-PLAN.md。
 
 > **本文下方所有命令写作 \`${CLI} <cmd>\`。** 该名字只在全局装过
 > （\`npm i -g claude-mem-lite\`）时才在 PATH 上；否则用等价的
@@ -159,7 +158,7 @@ PreToolUse hook 在你 Read / Edit / Write 文件前已自动 \`mem_recall\` 该
 
 | 场景 | CLI |
 |------|-----|
-| 清理过期记忆 | \`${CLI} maintain scan --ops purge_stale\` → \`maintain execute --ops purge_stale --confirm\`（删行必须 \`--confirm\`） |
+| 清理过期记忆 | \`${CLI} maintain scan\` 预览；清理本身交给用户启动的 \`/claude-mem-lite:update\` |
 | 深度优化（Haiku） | \`${CLI} optimize\`（默认 preview；\`--run\` 执行，\`--task re-enrich,normalize,cluster-merge,smart-compress\`） |
 | 压缩旧条目 | \`${CLI} compress\`（默认 preview；\`--execute\` 执行，\`--age-days N\`） |
 | FTS5 索引检查 / 重建 | \`${CLI} fts-check <check\\|rebuild>\` |

package/claudemd.mjs

@@ -2,9 +2,8 @@
 // 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
+// Why here and not memdir.mjs: steering belongs in CLAUDE.md (the canonical home
+// for project instructions) — seeding the memory-dir 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.
@@ -182,6 +181,31 @@ export function holdsOnlyOwnLines(p, slug) {
   }
 }
 
+// Another plugin's managed block: the same sentinel shape under any slug (code-graph-mcp writes
+// `<!-- code-graph-mcp:begin v2 -->` … `<!-- code-graph-mcp:end -->`). The backreference pairs a
+// begin with its own slug's end, so an unpaired line of one slug never closes another's block.
+const ANY_BLOCK_RE_G =
+  /<!-- ([a-z0-9][a-z0-9._-]*):begin v\d+ -->\r?\n(?:(?!<!-- \1:(?:begin|end))[\s\S])*?\r?\n<!-- \1:end -->/g;
+
+/**
+ * Whether the instructions file at `p` holds no line a person wrote: this plugin's blocks and
+ * imports, and other plugins' managed blocks. For "did plugin text alone switch AGENTS.md off"
+ * (D#220), never for deleting the file — another plugin's block is not ours to remove, and
+ * holdsOnlyOwnLines answers that question. False for a missing file.
+ * @param {string} p absolute path
+ * @param {string} slug
+ * @returns {boolean}
+ */
+export function holdsOnlyPluginLines(p, slug) {
+  try {
+    if (!existsSync(p)) return false;
+    const rest = readFileSync(p, 'utf8').replace(blockRegexG(slug), '').replace(ANY_BLOCK_RE_G, '');
+    return rest.trim() === '' || isOwnImportsOnly(rest, slug);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Put adopt's AGENTS.md imports at the top of <cwd>/CLAUDE.md (created if absent), unless the
  * marker is there already. `imports` are paths relative to `cwd` (`AGENTS.md`,
@@ -366,7 +390,8 @@ export function needsRefresh(cwd, { slug, version, block, doc }) {
  * 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)
+ * @returns {{action: 'created'|'updated'|'unchanged', docAction: 'created'|'updated'|'unchanged'}}
+ *   (block disposition, and the detail doc's)
  */
 export function writeManaged(cwd, { slug, version, block, doc }) {
   const { action } = writeBlockAt(claudeMdPath(cwd), { slug, version, block });
@@ -379,6 +404,7 @@ export function writeManaged(cwd, { slug, version, block, doc }) {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   const existingDoc = existsSync(dp) ? readFileSync(dp, 'utf8') : null;
   if (existingDoc !== docContent) atomicWrite(dp, docContent);
+  const docAction = existingDoc === null ? 'created' : existingDoc === docContent ? 'unchanged' : 'updated';
 
   // Only when what the sidecar records changed: it is committed alongside the block in a team
   // repo, and a fresh writtenAt on every re-run of `adopt` left a diff each time (E2E
@@ -394,7 +420,7 @@ export function writeManaged(cwd, { slug, version, block, doc }) {
   if (!(prev?.version === version && prev?.blockHash === blockHash && prev?.docHash === docHash)) {
     writeState(cwd, slug, { version, blockHash, docHash, writtenAt: new Date().toISOString() });
   }
-  return { action };
+  return { action, docAction };
 }
 
 /**

package/cli/activity.mjs

@@ -15,6 +15,7 @@ import { parseArgs, out, fail, rejectBareStringFlags } from './common.mjs';
 import { parseIntFlag, isNumericToken } from '../lib/cli-flags.mjs';
 import { snapshotDb } from '../lib/db-backup.mjs';
 import { isBlankText } from '../lib/blank-text.mjs';
+import { CLI_INVOKE } from '../cli-path.mjs';
 
 function formatActivityResults(rows) {
   if (!rows || rows.length === 0) return '(no events)';
@@ -31,7 +32,7 @@ function eventIdOf(token) {
 export async function cmdActivity(db, args) {
   const sub = args[0];
   if (!sub) {
-    fail('[mem] Usage: claude-mem-lite activity <save|search|recent|show|delete|promote> ...');
+    fail(`[mem] Usage: ${CLI_INVOKE} activity <save|search|recent|show|delete|promote> ...`);
     return;
   }
 
@@ -171,7 +172,7 @@ export async function cmdActivity(db, args) {
     // This command lets users prune them by ID without dropping to raw SQL.
     const idStr = positional.join(',').trim();
     if (!idStr) {
-      fail('[mem] Usage: claude-mem-lite activity delete <id1,id2,...> [--confirm]');
+      fail(`[mem] Usage: ${CLI_INVOKE} activity delete <id1,id2,...> [--confirm]`);
       return;
     }
     const tokens = idStr

package/cli/common.mjs

@@ -9,7 +9,8 @@
 // consistent.
 
 import { editDistance } from '../lib/edit-distance.mjs';
-import { neutralizeContextDelimiters, neutralizeSkillDelimiters } from '../format-utils.mjs';
+import { neutralizeContextDelimiters, neutralizeSkillDelimiters, truncate } from '../format-utils.mjs';
+import { CLI_INVOKE } from '../cli-path.mjs';
 
 // ─── Argument Parsing ────────────────────────────────────────────────────────
 
@@ -250,7 +251,7 @@ export function inertFilterFlagNotice(cmd, inert) {
   const verb = inert.length > 1 ? 'were' : 'was';
   return (
     `[mem] ${names} ${verb} ignored — \`${cmd}\` does not filter on ${inert.length > 1 ? 'them' : 'it'}, ` +
-    `so the results above are UNFILTERED. Run "claude-mem-lite help" for the flags this command reads.`
+    `so the results above are UNFILTERED. Run "${CLI_INVOKE} help" for the flags this command reads.`
   );
 }
 
@@ -596,11 +597,16 @@ export function obsFieldLabel(field) {
  * 2026-08-14 A4). Say what the rows are and what deletes them — and say nothing about
  * compression, which is a different sentinel with a different lifecycle.
  *
+ * purge_stale deletes only the queued rows older than its retain window (D#450), so the line
+ * also gives the number a purge at the default window deletes now.
+ *
  * @param {number} n stats.pendingPurge
+ * @param {number} due stats.pendingPurgeDue
+ * @param {number} retainDays the default retain window `due` was counted at
  * @returns {string} the full indented line, identical on both surfaces.
  */
-export function formatPendingPurgeLine(n) {
-  return `  Pending purge (idle-marked): ${n} (rows maintenance queued: hidden and still idle 7 days later, or queued by an earlier version — purge_stale deletes them)`;
+export function formatPendingPurgeLine(n, due, retainDays) {
+  return `  Pending purge (idle-marked): ${n} (rows maintenance queued: hidden and still idle 7 days later, or queued by an earlier version — purge_stale deletes those older than its retain window: ${due} at the default ${retainDays} days)`;
 }
 
 /**
@@ -642,3 +648,28 @@ export function formatProbeHints(probe) {
   if (probe.event?.length > 0) hints.push(`E#${probe.event.join(', E#')} (event)`);
   return hints;
 }
+
+/**
+ * The line under one side of a scan's Needs-review pair (D#461), from reviewRows: type, project,
+ * date, the lesson or that there is none, and the start of the narrative — enough to tell two rows
+ * with near-identical titles apart without `get`, which counts as an access.
+ * @param {{id: number, type?: string, project?: string, created_at_epoch?: number,
+ *   narrative?: string|null, lesson_learned?: string|null}|undefined} row
+ * @returns {string}
+ */
+export function formatReviewSide(row) {
+  if (!row) return '';
+  const flat = (v, n) =>
+    truncate(
+      String(v ?? '')
+        .replace(/\s+/g, ' ')
+        .trim(),
+      n,
+    );
+  const lesson =
+    row.lesson_learned && row.lesson_learned !== 'none'
+      ? `lesson: ${flat(row.lesson_learned, 100)}`
+      : 'no lesson';
+  const date = row.created_at_epoch ? new Date(row.created_at_epoch).toISOString().slice(0, 10) : '?';
+  return `#${row.id} ${row.type || '?'} · ${row.project} · ${date} · ${lesson} · ${flat(row.narrative, 120) || '(no narrative)'}`;
+}

package/cli/fts-check.mjs

@@ -3,12 +3,13 @@
 
 import { checkFTSIntegrity, rebuildFTS } from '../schema.mjs';
 import { parseArgs, out, fail } from './common.mjs';
+import { CLI_INVOKE } from '../cli-path.mjs';
 
 export function cmdFtsCheck(db, args) {
   const { positional } = parseArgs(args);
   const action = positional[0];
   if (!action) {
-    fail('[mem] Usage: claude-mem-lite fts-check <check|rebuild>');
+    fail(`[mem] Usage: ${CLI_INVOKE} fts-check <check|rebuild>`);
     return;
   }
   if (!['check', 'rebuild'].includes(action)) {

package/cli/verify-apply.mjs

@@ -23,12 +23,12 @@ import {
   markUndone,
 } from '../lib/verify-apply-core.mjs';
 import { parseArgs, out, fail, rejectBareStringFlags } from './common.mjs';
-import { shellWord } from '../cli-path.mjs';
+import { shellWord, CLI_INVOKE } from '../cli-path.mjs';
 
 const USAGE =
-  '[mem] Usage: claude-mem-lite verify-apply <proposals.json> [--project P]          (dry run)\n' +
-  '       claude-mem-lite verify-apply <proposals.json> [--project P] --apply --digest <d>\n' +
-  '       claude-mem-lite verify-apply --undo <backup.json>';
+  `[mem] Usage: ${CLI_INVOKE} verify-apply <proposals.json> [--project P]          (dry run)\n` +
+  `       ${CLI_INVOKE} verify-apply <proposals.json> [--project P] --apply --digest <d>\n` +
+  `       ${CLI_INVOKE} verify-apply --undo <backup.json>`;
 
 const SNIPPET_CONTEXT = 60;
 const BACKUP_DIR = join(DB_DIR, 'backups');

package/cli.mjs

@@ -338,8 +338,12 @@ if (cmd === '--version' || cmd === '-v' || cmd === '-V' || cmd === 'version') {
   if (best && bestDist <= 2) {
     process.stderr.write(`[mem] Did you mean: ${best}?\n`);
   } else {
+    // By path (D#462: the bare name is on PATH only after a global npm install). Imported here,
+    // not at the top: this entry takes no static local imports (D#26), and a module it cannot
+    // load leaves the old wording rather than no hint.
+    const { CLI_INVOKE } = await import('./cli-path.mjs').catch(() => ({ CLI_INVOKE: 'claude-mem-lite' }));
     process.stderr.write(
-      '[mem] Run "claude-mem-lite help" for CLI commands or "claude-mem-lite install" for setup\n',
+      `[mem] Run "${CLI_INVOKE} help" for CLI commands or "${CLI_INVOKE} install" for setup\n`,
     );
   }
   process.exitCode = 1;