claude-mem-lite 3.12.1 → 3.13.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.12.1",
+      "version": "3.13.0",
       "source": "./",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF 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": "3.12.1",
+  "version": "3.13.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF 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/adopt-cli.mjs

@@ -1,25 +1,32 @@
-// Phase C (Invited-Memory plan, T11): CLI handlers for
-//   claude-mem-lite adopt [--all] [--force] [--dry-run] [--status]
-//   claude-mem-lite unadopt [--all]
+// CLAUDE.md-steering plan (v3.13): CLI handlers for
+//   claude-mem-lite adopt   [--all] [--force] [--dry-run] [--status] [--disable|--enable]
+//   claude-mem-lite unadopt [--all] [--force] [--dry-run] [--status]
 //
-// 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
+// adopt   = write the managed block into <cwd>/CLAUDE.md + drop
+//           <cwd>/.claude/plugin_claude_mem_lite.md, and migrate this project's
+//           legacy memory-dir sentinel away.
+// unadopt = remove the CLAUDE.md block + detail doc (and clean any legacy residue).
+//
+// The project path is needed to write CLAUDE.md, but the per-project memdir slug
+// (~/.claude/projects/<encoded>/) is a LOSSY encoding of the real cwd — it cannot
+// be decoded back to a filesystem path. So `--all` cannot adopt arbitrary projects;
+// it is redefined as a legacy-cleanup sweep (strip old memory-dir sentinels across
+// every memdir). New-scheme adoption happens per-project on SessionStart (cwd known).
 
 import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import {
-  memdirPath, writePluginSection, removePluginSection,
-  writePluginDoc, removePluginDoc,
-  isAdopted, hasPluginState, readMemoryIndex,
-  UserEditedError, BudgetExceededError,
+  memdirPath, removePluginSection, removePluginDoc,
+  isAdopted as memdirIsAdopted, hasPluginState,
 } from './memdir.mjs';
 import {
-  PLUGIN_SLUG, CURRENT_SENTINEL_VERSION, getIndexLine, getDetailDoc,
+  writeManaged, removeManaged, isAdopted as claudeMdIsAdopted,
+  needsRefresh, migrateLegacyMemoryDir, hasLegacyMemdirSentinel,
+  claudeMdPath, detailDocPath,
+} from './claudemd.mjs';
+import {
+  PLUGIN_SLUG, CURRENT_SENTINEL_VERSION, buildClaudeMdBlock, getDetailDoc,
 } from './adopt-content.mjs';
 
 function log(msg) { console.log(msg); }
@@ -56,7 +63,8 @@ function hasFlag(args, flag) { return Array.isArray(args) && args.includes(flag)
 // `rm ~/.claude-mem-lite/runtime/.auto-adopt-*`. Managed via
 // `claude-mem-lite adopt --disable` / `--enable`. silentAutoAdopt checks it
 // at entry and skips WITHOUT writing the runtime marker, so toggling
-// `--enable` re-arms auto-adopt on the next SessionStart.
+// `--enable` re-arms auto-adopt on the next SessionStart. Kept in the memdir
+// (not the project tree) so it survives `unadopt` cleaning out .claude/.
 const DISABLE_SENTINEL_BASENAME = '.mem-no-auto-adopt';
 
 export function disableSentinelPath(memdir) {
@@ -68,97 +76,98 @@ export function isAutoAdoptDisabled(memdir) {
 }
 
 /**
- * cmdAdopt — write sentinel section + plugin doc to memdir.
- * Exit code 1 on any hard failure; skipped (--all + UserEditedError) doesn't
- * fail the batch.
+ * cmdAdopt — write the CLAUDE.md managed block + detail doc for the current
+ * project, and migrate its legacy memory-dir sentinel away.
+ *
+ * `--all` does NOT adopt every project (their real paths are unrecoverable from
+ * the lossy memdir slug) — it sweeps the legacy memory-dir cleanup across all
+ * memdirs. `--status`/`--disable`/`--enable` as before.
  */
 export function cmdAdopt(args = []) {
   if (hasFlag(args, '--status')) return statusAll();
   if (hasFlag(args, '--disable')) return cmdDisable(args);
   if (hasFlag(args, '--enable')) return cmdEnable(args);
+  if (hasFlag(args, '--all')) return migrateAll(args);
 
-  const all = hasFlag(args, '--all');
   const force = hasFlag(args, '--force');
   const dryRun = hasFlag(args, '--dry-run');
+  const cwd = detectCwd();
 
-  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;
+  adoptOne(cwd, { force, dryRun });
 }
 
-function adoptOne(memdir, { force, dryRun, all }) {
-  const contentLine = getIndexLine();
+function adoptOne(cwd, { force, dryRun }) {
+  const block = buildClaudeMdBlock();
+  const doc = getDetailDoc();
   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)`);
+    log(`[adopt --dry-run] ${cwd}`);
+    log(`  CLAUDE.md block:  ${claudeMdPath(cwd)} (${block.length} chars, ${version})`);
+    log(`  detail doc:       ${detailDocPath(cwd, PLUGIN_SLUG)} (${doc.length} chars)`);
+    if (hasLegacyMemdirSentinel(cwd, PLUGIN_SLUG)) {
+      log(`  legacy migrate:   would strip memory-dir sentinel @ ${memdirPath(cwd)}`);
+    }
     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}`);
+    const mig = migrateLegacyMemoryDir(cwd, PLUGIN_SLUG, { force });
+    const r = writeManaged(cwd, { slug: PLUGIN_SLUG, version, block, doc });
+    const migNote = mig.action === 'removed' ? ' (+migrated legacy memdir)' : '';
+    log(`[adopt] ${cwd} → ${r.action}${migNote}`);
     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}`);
+    log(`[adopt] ${cwd} → error: ${e.message}`);
+    process.exitCode = 1;
     return { action: 'failed' };
   }
 }
 
 /**
- * silentAutoAdopt — plugin-mode first-run auto-adopt helper (v2.33.0+).
- *
- * Preconditions (caller must gate): CLAUDE_PLUGIN_ROOT set, MEM_NO_AUTO_ADOPT!=1,
- * first-attempt marker absent. This helper does NOT re-check those — it only
- * does the write + marker persistence. (v2.82.0: dropped MEM_QUIET_HOOKS gate;
- * quiet is a stdout control, not a side-effect control.)
- *
- * Behavior:
- *   - If `<memdir>/.mem-no-auto-adopt` exists: skip silently, do NOT write the
- *     runtime marker. This keeps `--enable` re-armable: deleting the disable
- *     sentinel lets the next SessionStart try again.
- *   - Else: writes plugin sentinel + detail doc to the memdir for `cwd`.
- *   - Writes a per-project first-attempt marker under `markerDir` so a later
- *     `/unadopt` is respected (no re-adopt loop).
- *   - Silent: never logs, never throws. Returns structured result.
+ * migrateAll — `claude-mem-lite adopt --all`: legacy-cleanup sweep. Strips the
+ * old memory-dir sentinel + detail doc from every memdir. Does NOT write any
+ * CLAUDE.md block (target paths are unrecoverable) — that happens per-project on
+ * the next SessionStart. Respects the foreign-content guard unless --force.
+ */
+function migrateAll(args) {
+  const force = hasFlag(args, '--force');
+  const dryRun = hasFlag(args, '--dry-run');
+  const dirs = listAllMemdirs();
+  if (dirs.length === 0) { log('[adopt --all] no memdirs found'); return; }
+
+  let removed = 0, absent = 0, skipped = 0;
+  for (const { projectSlug, memdir } of dirs) {
+    if (dryRun) {
+      const has = memdirIsAdopted(memdir, PLUGIN_SLUG);
+      const action = !has ? 'absent'
+        : (hasPluginState(memdir, PLUGIN_SLUG) || force) ? 'would-remove' : 'would-skip-foreign';
+      log(`[adopt --all --dry-run] ${projectSlug} → ${action}`);
+      if (action === 'would-remove') removed++;
+      else if (action === 'would-skip-foreign') skipped++;
+      else absent++;
+      continue;
+    }
+    const r = removePluginSection(memdir, PLUGIN_SLUG, { force });
+    if (r.action === 'removed') { removePluginDoc(memdir, PLUGIN_SLUG); removed++; }
+    else if (r.action === 'skipped-foreign') skipped++;
+    else absent++;
+  }
+  log('');
+  log(`[adopt --all] legacy memory-dir cleanup over ${dirs.length} project(s): ${removed} cleaned, ${skipped} skipped-foreign, ${absent} none.`);
+  log('[adopt --all] CLAUDE.md adoption is per-project — it runs automatically on each project\'s next SessionStart.');
+}
+
+/**
+ * silentAutoAdopt — SessionStart idempotent sync (migration vehicle).
  *
- * Returns { ok, action, reason } — caller uses for telemetry / debugLog only.
+ * Called every plugin-mode SessionStart (NOT gated by the one-shot marker, so
+ * existing users whose marker predates v3.13 still migrate). Order:
+ *   1. respect per-project `.mem-no-auto-adopt` opt-out → skip.
+ *   2. migrate legacy memory-dir sentinel away (idempotent; no-op once gone).
+ *   3. adopt the CLAUDE.md scheme if absent; else refresh if shipped content
+ *      drifted (unless CLAUDE_MEM_NO_TEMPLATE_REFRESH=1).
+ * Silent: never logs, never throws. Returns { ok, action, reason } for debugLog.
  */
 export function silentAutoAdopt({ cwd, markerDir, markerKey }) {
   const memdir = memdirPath(cwd);
@@ -166,27 +175,26 @@ export function silentAutoAdopt({ cwd, markerDir, markerKey }) {
     if (isAutoAdoptDisabled(memdir)) {
       return { ok: true, action: 'disabled', reason: 'disabled-by-sentinel' };
     }
-    if (isAdopted(memdir, PLUGIN_SLUG)) {
-      writeMarker(markerDir, markerKey);
-      return { ok: true, action: 'already-adopted' };
+    migrateLegacyMemoryDir(cwd, PLUGIN_SLUG);
+
+    const block = buildClaudeMdBlock();
+    const doc = getDetailDoc();
+    const version = CURRENT_SENTINEL_VERSION;
+
+    let action = 'already-adopted';
+    if (!claudeMdIsAdopted(cwd, PLUGIN_SLUG)) {
+      writeManaged(cwd, { slug: PLUGIN_SLUG, version, block, doc });
+      action = 'adopted';
+    } else if (process.env.CLAUDE_MEM_NO_TEMPLATE_REFRESH !== '1'
+        && needsRefresh(cwd, { slug: PLUGIN_SLUG, version, block, doc })) {
+      writeManaged(cwd, { slug: PLUGIN_SLUG, version, block, doc });
+      action = 'refreshed';
     }
-    writePluginSection(memdir, {
-      slug: PLUGIN_SLUG,
-      version: CURRENT_SENTINEL_VERSION,
-      contentLine: getIndexLine(),
-      force: false,
-    });
-    writePluginDoc(memdir, PLUGIN_SLUG, getDetailDoc());
-    writeMarker(markerDir, markerKey);
-    return { ok: true, action: 'adopted' };
+    if (markerDir && markerKey) writeMarker(markerDir, markerKey);
+    return { ok: true, action };
   } catch (e) {
-    // Budget exceeded, user-edited conflict, or FS error — write marker so we
-    // don't retry on every SessionStart. User can run /adopt --force manually.
-    try { writeMarker(markerDir, markerKey); } catch { /* marker best-effort */ }
-    const reason = e instanceof UserEditedError ? 'user-edited'
-      : e instanceof BudgetExceededError ? 'budget-exceeded'
-      : 'error';
-    return { ok: false, action: 'skipped', reason, err: e };
+    try { if (markerDir && markerKey) writeMarker(markerDir, markerKey); } catch { /* best-effort */ }
+    return { ok: false, action: 'skipped', reason: 'error', err: e };
   }
 }
 
@@ -202,13 +210,8 @@ export function hasAutoAdoptMarker(markerDir, markerKey) {
 
 /**
  * cmdDisable — `claude-mem-lite adopt --disable [--all]`.
- *
  * Writes `<memdir>/.mem-no-auto-adopt` so SessionStart auto-adopt skips this
- * project permanently. Idempotent: re-running on an already-disabled memdir is
- * a no-op. Does NOT remove an existing sentinel — pair with `unadopt` if you
- * want both. The two operations are deliberately separate:
- *   - `unadopt`      = "remove the contract now"
- *   - `adopt --disable` = "and don't auto-write it back"
+ * project permanently. Does NOT remove an existing block — pair with `unadopt`.
  */
 function cmdDisable(args) {
   const all = hasFlag(args, '--all');
@@ -216,10 +219,7 @@ function cmdDisable(args) {
     ? listAllMemdirs().map((m) => m.memdir)
     : [memdirPath(detectCwd())];
 
-  if (targets.length === 0) {
-    log('[adopt --disable] no memdirs found');
-    return;
-  }
+  if (targets.length === 0) { log('[adopt --disable] no memdirs found'); return; }
 
   let disabled = 0, already = 0;
   for (const memdir of targets) {
@@ -234,17 +234,13 @@ function cmdDisable(args) {
     log(`[adopt --disable] ${memdir} → disabled`);
     disabled++;
   }
-
   log('');
   log(`[adopt --disable] ${targets.length} target(s): ${disabled} newly disabled, ${already} already disabled`);
 }
 
 /**
- * cmdEnable — `claude-mem-lite adopt --enable [--all]`.
- *
- * Removes the `<memdir>/.mem-no-auto-adopt` sentinel so the next SessionStart
- * can auto-adopt again. Idempotent. Does NOT trigger an immediate adoption —
- * run plain `claude-mem-lite adopt` if you want that now.
+ * cmdEnable — `claude-mem-lite adopt --enable [--all]`. Removes the
+ * `.mem-no-auto-adopt` sentinel so the next SessionStart can auto-adopt again.
  */
 function cmdEnable(args) {
   const all = hasFlag(args, '--all');
@@ -252,10 +248,7 @@ function cmdEnable(args) {
     ? listAllMemdirs().map((m) => m.memdir)
     : [memdirPath(detectCwd())];
 
-  if (targets.length === 0) {
-    log('[adopt --enable] no memdirs found');
-    return;
-  }
+  if (targets.length === 0) { log('[adopt --enable] no memdirs found'); return; }
 
   let enabled = 0, absent = 0;
   for (const memdir of targets) {
@@ -269,56 +262,48 @@ function cmdEnable(args) {
     log(`[adopt --enable] ${memdir} → enabled`);
     enabled++;
   }
-
   log('');
   log(`[adopt --enable] ${targets.length} target(s): ${enabled} re-enabled, ${absent} not-disabled`);
 }
 
+/**
+ * statusAll — report the current project's new-scheme adoption, plus a sweep of
+ * how many memdirs still carry the legacy sentinel (i.e. await migration).
+ */
 function statusAll() {
+  const cwd = detectCwd();
+  const adoptedHere = claudeMdIsAdopted(cwd, PLUGIN_SLUG);
+  log('[adopt --status] current project:');
+  log(`  cwd:        ${cwd}`);
+  log(`  CLAUDE.md:  ${adoptedHere ? `✓ adopted (${CURRENT_SENTINEL_VERSION})` : '✗ not adopted'}`);
+  if (hasLegacyMemdirSentinel(cwd, PLUGIN_SLUG)) {
+    log('  legacy:     ⚠ memory-dir sentinel still present (migrates on next SessionStart, or run `adopt`)');
+  }
+
   const dirs = listAllMemdirs();
-  log('[adopt --status] scanning ~/.claude/projects/*/memory/');
-  if (dirs.length === 0) { log('  (no memdirs found)'); return; }
-  let adopted = 0, disabled = 0;
-  for (const { projectSlug, memdir } of dirs) {
-    const isAdoptedHere = isAdopted(memdir, PLUGIN_SLUG);
-    const isDisabledHere = isAutoAdoptDisabled(memdir);
-    if (isAdoptedHere) {
-      const idx = readMemoryIndex(memdir, PLUGIN_SLUG);
-      const suffix = isDisabledHere ? ' [auto-adopt disabled]' : '';
-      log(`  ✓ ${projectSlug} (${idx.version})${suffix}`);
-      adopted++;
-      if (isDisabledHere) disabled++;
-    } else if (isDisabledHere) {
-      log(`  ✗ ${projectSlug} (auto-adopt disabled, no sentinel)`);
-      disabled++;
-    }
+  let legacy = 0, disabled = 0;
+  for (const { memdir } of dirs) {
+    if (memdirIsAdopted(memdir, PLUGIN_SLUG)) legacy++;
+    if (isAutoAdoptDisabled(memdir)) disabled++;
   }
   log('');
-  log(`[adopt --status] ${adopted}/${dirs.length} adopted${disabled > 0 ? `, ${disabled} disabled` : ''}`);
+  log(`[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.');
 
-  // Gating snapshot — helps debug "why didn't auto-adopt fire?"
   const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ? 'set' : 'unset';
   const noAutoAdopt = process.env.MEM_NO_AUTO_ADOPT === '1' ? '1 (opt-out)' : 'unset';
   log('');
-  log('Auto-adopt gates (next SessionStart will fire only if both pass):');
-  log(`  CLAUDE_PLUGIN_ROOT  = ${pluginRoot}  (plugin-mode install required; npx stays opt-in)`);
+  log('Auto-adopt gates (next SessionStart fires only if these pass):');
+  log(`  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).');
 }
 
 /**
- * cmdUnadopt — precise removal of sentinel section + plugin doc.
- * Exit code stays 0: unadopt is idempotent; "absent" isn't an error.
- *
- * Flags:
- *   --all       Operate on every memdir under ~/.claude/projects/*\/memory/
- *   --status    Read-only: list currently-adopted memdirs (mirrors `adopt --status`).
- *   --dry-run   Preview what would be removed; no filesystem writes.
- *
- * Pre-fix history: unrecognized flags (e.g. `--status` extrapolated from `adopt --status`,
- * or `--dry-run` extrapolated from `adopt --dry-run`) were silently ignored and the
- * destructive default ran anyway, removing the sentinel block when the user expected
- * a read-only probe.
+ * cmdUnadopt — remove the CLAUDE.md managed block + detail doc for the current
+ * project, and clean any legacy memory-dir residue. `--all` sweeps the legacy
+ * memory-dir cleanup across every memdir (CLAUDE.md blocks for other projects
+ * can't be located from the lossy slug). Idempotent: exit code stays 0.
  */
 export function cmdUnadopt(args = []) {
   if (hasFlag(args, '--status')) return statusAll();
@@ -326,41 +311,21 @@ export function cmdUnadopt(args = []) {
   const all = hasFlag(args, '--all');
   const dryRun = hasFlag(args, '--dry-run');
   const force = hasFlag(args, '--force');
-  const targets = all
-    ? listAllMemdirs().map((m) => m.memdir)
-    : [memdirPath(detectCwd())];
 
-  if (targets.length === 0) {
-    log('[unadopt] no memdirs found');
-    return;
-  }
+  if (all) return migrateAll(['--all', ...(force ? ['--force'] : []), ...(dryRun ? ['--dry-run'] : [])]);
 
-  let removed = 0, absent = 0, skipped = 0;
-  for (const memdir of targets) {
-    if (dryRun) {
-      // Mirror the live foreign-content guard: a sentinel with no state sidecar would be
-      // skipped (not removed) unless --force, so dry-run must report it the same way.
-      const action = !isAdopted(memdir, PLUGIN_SLUG) ? 'absent'
-        : (hasPluginState(memdir, PLUGIN_SLUG) || force) ? 'would-remove'
-          : 'would-skip-foreign';
-      log(`[unadopt --dry-run] ${memdir} → ${action}`);
-      if (action === 'would-remove') removed++;
-      else if (action === 'would-skip-foreign') skipped++;
-      else absent++;
-      continue;
-    }
-    const r = removePluginSection(memdir, PLUGIN_SLUG, { force });
-    if (r.action === 'removed') { removePluginDoc(memdir, PLUGIN_SLUG); removed++; }
-    else if (r.action === 'skipped-foreign') skipped++;
-    else absent++;
-    log(`[unadopt] ${memdir} → ${r.action}`);
+  const cwd = detectCwd();
+  if (dryRun) {
+    const blockState = claudeMdIsAdopted(cwd, PLUGIN_SLUG) ? 'would-remove CLAUDE.md block + detail doc' : 'no CLAUDE.md block';
+    const legacy = hasLegacyMemdirSentinel(cwd, PLUGIN_SLUG) ? 'would-clean legacy memory-dir sentinel' : 'no legacy residue';
+    log(`[unadopt --dry-run] ${cwd}`);
+    log(`  ${blockState}`);
+    log(`  ${legacy}`);
+    return;
   }
 
-  if (skipped > 0) {
-    log('[unadopt] skipped-foreign = a sentinel block with no plugin state file (not proven plugin-written).');
-    log('[unadopt] pass --force to remove it anyway.');
-  }
-  log('');
-  const verb = dryRun ? 'would remove' : 'removed';
-  log(`[unadopt${dryRun ? ' --dry-run' : ''}] ${targets.length} target(s): ${removed} ${verb}, ${skipped} skipped-foreign, ${absent} absent`);
+  const r = removeManaged(cwd, PLUGIN_SLUG);
+  const mig = migrateLegacyMemoryDir(cwd, PLUGIN_SLUG, { force });
+  const migNote = mig.action === 'removed' ? ' (+cleaned legacy memdir)' : '';
+  log(`[unadopt] ${cwd} → ${r.action}${migNote}`);
 }

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/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

package/hook-shared.mjs

@@ -8,9 +8,11 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, readdir
 import { inferProject, debugCatch } from './utils.mjs';
 import { ensureDb, DB_DIR } from './schema.mjs';
 import { getClaudePath as getClaudePathShared, resolveModel as resolveModelShared, flattenForCLI as _flattenForCLI, detectMode as detectLLMMode, callHaiku } 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';
+// Phase D: invited-memory sentinel detection. memdir.mjs/claudemd.mjs only pull in
+// fs/path/os/crypto; adopt-content.mjs is pure strings. No circular deps —
+// neither imports hook-shared.
+import { memdirPath as _memdirPath, isAdopted as _isAdoptedMemdir } from './memdir.mjs';
+import { isAdopted as _isAdoptedClaudeMd } from './claudemd.mjs';
 import { PLUGIN_SLUG as _PLUGIN_SLUG } from './adopt-content.mjs';
 
 // ─── Constants ────────────────────────────────────────────────────────────────
@@ -38,14 +40,18 @@ 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)
+// Phase D (v2.32.1+) → v3.13: if the current project has adopted our steering,
+// the contract is already loaded at system-prompt authority — so hook +
+// MCP-instruction output can also go quiet. v3.13 moved that contract from the
+// memory-dir MEMORY.md sentinel to the project CLAUDE.md managed block, so check
+// the new scheme first and keep the legacy memdir sentinel as a fallback (an
+// un-migrated project stays quiet through the transition). 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);
+    return _isAdoptedClaudeMd(resolved, _PLUGIN_SLUG)
+      || _isAdoptedMemdir(_memdirPath(resolved), _PLUGIN_SLUG);
   } catch {
     return false;
   }

package/hook.mjs

@@ -63,7 +63,7 @@ import { detectMemOverride } from './lib/mem-override.mjs';
 import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection, pickHandoffToInject, extractUnfinishedSummary } from './hook-handoff.mjs';
 import { checkForUpdate, getCachedUpdateBanner, isUpdateCheckDue } from './hook-update.mjs';
 import { handleLLMOptimize } from './hook-optimize.mjs';
-import { silentAutoAdopt, hasAutoAdoptMarker } from './adopt-cli.mjs';
+import { silentAutoAdopt } from './adopt-cli.mjs';
 import { emitV270UpgradeBanner } from './lib/upgrade-banner.mjs';
 import { loadCiteBackForEpisode, extractCiteBackSignals, buildUnsavedBugfixHint, countUnsavedBugfixShape, buildCiteRecallNudge as libBuildCiteRecallNudge, nextCiteLowStreak } from './lib/cite-back-hint.mjs';
 // plugin-cache-guard.mjs loaded dynamically — pre-2.31.2 installs that auto-upgraded
@@ -1074,36 +1074,32 @@ async function handleSessionStart() {
     }
   } catch (e) { debugCatch(e, 'session-start-cache-heal'); }
 
-  // First-run auto-adopt (v2.33.0 plugin-mode → v2.82.1 install-mode-agnostic).
+  // Auto-adopt + migrate (v3.13 CLAUDE.md-steering). silentAutoAdopt is now an
+  // IDEMPOTENT per-session sync, so it runs on EVERY SessionStart — not gated by
+  // the one-shot RUNTIME_DIR marker. That gate is deliberately gone: existing
+  // users whose marker predates v3.13 must still get migrated (legacy memory-dir
+  // sentinel stripped, CLAUDE.md managed block written) on their next session.
+  // The sync short-circuits cheaply once a project is already on the new scheme.
   // ANY install path — `/plugin install`, `npm install -g`, `npx`, manual — is
-  // consent to integration. Writing the MEMORY.md sentinel once per project on
-  // first SessionStart avoids the opt-in friction that left ~zero users on
-  // auto-adopt (runtime-marker directory was empty machine-wide despite v2.33
-  // shipping ~5 weeks earlier — `install.mjs`-written hooks don't propagate
-  // ${CLAUDE_PLUGIN_ROOT}, so the v2.33.0 gate was a no-op for npm/manual
-  // installs, which is most of them). Scope is now:
+  // consent to integration. Scope:
   //   - gated by !MEM_NO_AUTO_ADOPT (explicit global escape hatch)
-  //   - per-project opt-out via `<memdir>/.mem-no-auto-adopt` sentinel
-  //     (managed by `claude-mem-lite adopt --disable / --enable`); checked
-  //     inside silentAutoAdopt so the helper is safe to call directly too.
-  //   - first-attempt marker persists in RUNTIME_DIR so a subsequent /unadopt
-  //     is respected (no re-adopt loop).
+  //   - per-project opt-out via `<memdir>/.mem-no-auto-adopt` sentinel (managed
+  //     by `claude-mem-lite adopt --disable / --enable`; checked inside
+  //     silentAutoAdopt).
+  //   - CLAUDE_MEM_NO_TEMPLATE_REFRESH=1 freezes the block against drift refresh.
   // Note v2.82.0: removed MEM_QUIET_HOOKS gate. That env var suppresses stdout
   // noise; it must NOT also disable side-effect work (PostToolUse writes the
-  // DB unconditionally — auto-adopt should follow the same rule).
-  // Failures (user-edited sentinel, budget exceeded, FS errors) are swallowed;
-  // the marker is still written so we don't retry on every SessionStart.
+  // DB unconditionally — auto-adopt follows the same rule). Failures are
+  // swallowed; the marker is still written for telemetry/back-compat.
   try {
     if (process.env.MEM_NO_AUTO_ADOPT !== '1') {
       const project = inferProject();
-      if (!hasAutoAdoptMarker(RUNTIME_DIR, project)) {
-        const cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-        const r = silentAutoAdopt({ cwd, markerDir: RUNTIME_DIR, markerKey: project });
-        if (r.ok) {
-          debugLog('DEBUG', 'session-start-auto-adopt', `action=${r.action} project=${project}`);
-        } else {
-          debugLog('DEBUG', 'session-start-auto-adopt', `skipped project=${project} reason=${r.reason}`);
-        }
+      const cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+      const r = silentAutoAdopt({ cwd, markerDir: RUNTIME_DIR, markerKey: project });
+      if (r.ok) {
+        debugLog('DEBUG', 'session-start-auto-adopt', `action=${r.action} project=${project}`);
+      } else {
+        debugLog('DEBUG', 'session-start-auto-adopt', `skipped project=${project} reason=${r.reason}`);
       }
     }
   } catch (e) { debugCatch(e, 'session-start-auto-adopt'); }

package/lib/startup-dashboard.mjs

@@ -109,5 +109,5 @@ function buildAdoptHint({ projectPath, stubs }) {
   // stubs.adopted === true/false lets tests assert both branches without touching FS.
   const adopted = stubs && 'adopted' in stubs ? stubs.adopted : isAdoptedHere(projectPath);
   if (adopted) return null;
-  return '🧷 Invited-memory 未启用：`claude-mem-lite adopt` 注入 MEMORY.md → 上下文省 ~40%，MCP 调用率提升；静音 `MEM_NO_ADOPT_HINT=1`';
+  return '🧷 Invited-memory 未启用：`claude-mem-lite adopt` 写入 CLAUDE.md 托管块（通常每会话自动）→ 上下文省 ~40%，MCP 调用率提升；静音 `MEM_NO_ADOPT_HINT=1`';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.12.1",
+  "version": "3.13.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF 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).",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -45,6 +45,7 @@
     "hook-precompact.mjs",
     "plugin-cache-guard.mjs",
     "memdir.mjs",
+    "claudemd.mjs",
     "adopt-content.mjs",
     "adopt-cli.mjs",
     "haiku-client.mjs",

package/server.mjs

@@ -143,7 +143,7 @@ const _quiet = effectiveQuiet();
 if (process.env.CLAUDE_MEM_QUIET_TRACE !== '0') {
   const reason = process.env.MEM_QUIET_HOOKS === '1'
     ? 'env:MEM_QUIET_HOOKS=1'
-    : _quiet ? 'adopted:MEMORY.md-sentinel' : 'none';
+    : _quiet ? 'adopted:steering' : 'none';
   const mode = _quiet ? 'BASE' : 'BASE+VERBOSE';
   process.stderr.write(`[mem] instructions: ${mode} reason=${reason}\n`);
 }
@@ -1715,7 +1715,7 @@ server.registerTool(
 // and direct MCP clients), but only the core tools appear in the `tools/list`
 // response. Hiding the maintenance/admin tools keeps Claude Code's startup
 // context small while preserving the contract that the plugin dogfoods (see
-// CLAUDE.md §Mem usage contract and adopt-content.mjs).
+// the CLAUDE.md managed block + adopt-content.mjs detail doc).
 // Surface counts as of v2.70.0: 9 core (mem_search/recent/timeline/get/save/
 // recall + mem_defer/mem_defer_list/mem_defer_drop) + 11 hidden (maintenance/
 // admin/specialized) = 20 registered; tests/tool-schemas.test.mjs is the

package/source-files.mjs

@@ -87,7 +87,9 @@ export const SOURCE_FILES = [
   'cli/activity.mjs',
   'server/fts-check.mjs',
   // v2.32 invited-memory: memdir primitives + adopt/unadopt CLI
+  // v3.13 CLAUDE.md-steering: claudemd.mjs project-tree managed block + migration
   'memdir.mjs',
+  'claudemd.mjs',
   'adopt-content.mjs',
   'adopt-cli.mjs',
   // P0 (v2.59.x): user-explicit "ignore memory" override detector. Lives