claude-mem-lite 6.24.0 → 6.25.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.24.0",
+      "version": "6.25.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.24.0",
+  "version": "6.25.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

@@ -237,6 +237,22 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
     repos/               # Shallow-cloned source repos
 ```
 
+## Upgrading to 6.25.0
+
+**Every session gets the same first line on a file-recall block again.** No schema-version
+change: 6.24.0 still opens the database after this release has.
+
+- **What changes.** Since 6.16.0 half of sessions got a plain statement of where the notes come
+  from instead of "system-injected context, continue your planned action", so the two could be
+  compared by how often the agent cited a lesson. On the maintainer's own sessions the comparison
+  found no difference it could detect, and a scan of the agent's replies found neither line
+  surfaced to the user, so the split is closed: unset now means the older line in every session.
+  `CLAUDE_MEM_RECALL_FRAMING=factual` keeps the plain statement; `=ab` restores the split.
+- **Also in this release:** when the data directory cannot be read, `doctor` says "not checked"
+  for what it could not look at and `status` names the directory, instead of reporting a missing
+  or empty store. `maintain execute --ops dedup` names the merge pairs it skips. Details in
+  CHANGELOG.md.
+
 ## Upgrading to 6.24.0
 
 **If you set `CLAUDE_CONFIG_DIR`, the installer, updates and hooks now use that directory, as
@@ -253,7 +269,8 @@ release has. Without `CLAUDE_CONFIG_DIR` nothing in this item changes.
   entries an older version wrote into `~/.claude/settings.json` stay there; if no other profile
   uses `~/.claude`, `env -u CLAUDE_CONFIG_DIR claude-mem-lite cleanup-hooks` removes them.
 - **Also in this release:** `npm install -g claude-mem-lite` and `npx` no longer install the
-  development toolchain (96 packages / 57 MB instead of 298 / 541 MB). A confirmed
+  development toolchain. As a dependency install it went from 298 packages / 541 MB to 96 / 57 MB;
+  after the release, `-g` and `npx` measured the same 96 packages. A confirmed
   `maintain execute --ops purge_stale` now deletes every row its preview counted in one run,
   behind one snapshot. `doctor` warns about a failing update check and about an
   `ANTHROPIC_BASE_URL` that ends in `/v1`. Details in CHANGELOG.md.
@@ -1234,7 +1251,7 @@ and names can change between releases.
 |----------|-------------|---------|
 | `CLAUDE_MEM_TASK_IMPERATIVE` | `on`/`1` injects the single most relevant lesson at prompt position under an imperative template. | _(off)_ |
 | `CLAUDE_MEM_SUBAGENT_INJECT` | Dispatch-time memory injection for subagents. | _(off)_ |
-| `CLAUDE_MEM_RECALL_FRAMING` | First line of a PreToolUse / PostToolUse recall block. `ab` gives each session one of two wordings, the older "system-injected context, continue your planned action" or a plain statement of source, so their cite-rates can be compared in one run (`benchmark/citation-live-replay.mjs --by-framing`); `legacy` / `factual` pin one. | `ab` |
+| `CLAUDE_MEM_RECALL_FRAMING` | First line of a PreToolUse / PostToolUse recall block. Unset or `legacy` = "system-injected context, continue your planned action"; `factual` = a plain statement of where the notes come from; `ab` = each session gets one of the two, for `benchmark/citation-live-replay.mjs --by-framing`. Any other value is `legacy`. | `legacy` |
 | `CLAUDE_MEM_SALIENCE` | Selects how the pre-edit lesson line asks for a response: unset = name a lesson's `#NN` only where it changed the edit; `verdict` = the pre-6.17 per-lesson `applied` / `n/a` verdict (the adoption row in CLAUDE.md and the detail doc keep the new wording, and since 6.17.1 the directive says it overrides them); `bind` / `bridge` = comprehension-bridge arms (`bridge` keeps the pre-6.17 verdict wording as its fallback; neither says it overrides the adopted text, so their measured wording stays fixed); `legacy` = no directive. | _(unset)_ |
 | `CLAUDE_MEM_EDGE_DECAY` | Enables decay of file↔observation edges. | _(off)_ |
 | `CLAUDE_MEM_EDGE_DECAY_K` | Edge-decay threshold when the flag above is on (clamped to ≥1). | `3` |

package/README.zh-CN.md

@@ -199,6 +199,35 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
     repos/               # 浅克隆的源代码仓库
 ```
 
+## 升级到 6.25.0
+
+**文件召回块的第一行，所有会话重新用同一种写法。** 没有 schema 版本变更：本版本打开过的数据库，6.24.0 仍能打开。
+
+- **变了什么。** 从 6.16.0 起，一半会话的第一行是说明笔记来源的事实陈述，另一半保留 "system-injected context,
+  continue your planned action"，用来比较 agent 引用教训的频率。在维护者自己的会话上，两种写法看不出差别，
+  按回复文本扫描，两组里 agent 也都没有把这一行当作可疑内容告诉用户，所以结束分组：
+  不设变量时，所有会话都用旧的那一行。
+  `CLAUDE_MEM_RECALL_FRAMING=factual` 保留事实陈述的写法，`=ab` 恢复分组。
+- **本版本还有：** 数据目录读不了时，`doctor` 对看不到的项目显示“not checked”，`status` 直接指出这个目录
+  无法访问，不再报成数据库缺失或为空。`maintain execute --ops dedup` 会列出跳过的合并对。详见 CHANGELOG.md。
+
+## 升级到 6.24.0
+
+**如果你设置了 `CLAUDE_CONFIG_DIR`，安装程序、更新和 hook 现在都使用这个目录，和 Claude Code 一致。**
+没有 schema 版本变更：本版本打开过的数据库，6.23.3 仍能打开。没设 `CLAUDE_CONFIG_DIR` 时，这一条不带来任何变化。
+
+- **受影响的是谁。** 设了 `CLAUDE_CONFIG_DIR` 时，Claude Code 把 `settings.json`、`plugins/` 和 `.claude.json`
+  都放在那个目录里，插件却一直用 `~/.claude` 和 `~/.claude.json`：`install` 把 hook 写到了 Claude Code 不读的
+  地方；有两个配置目录时，会话启动的整理步骤和 `self-update` 会清掉另一个配置目录的插件缓存，并改动它的
+  `.claude.json`。
+- **要做什么。** 用 npm 或 npx 安装的：在设好这个变量的情况下再运行一次 `claude-mem-lite install`，让 hook 写进
+  你的配置目录。插件安装不用做什么。旧版本写进 `~/.claude/settings.json` 的 hook 条目会留在那里；如果没有别的
+  配置目录在用 `~/.claude`，可以用 `env -u CLAUDE_CONFIG_DIR claude-mem-lite cleanup-hooks` 清掉。
+- **本版本还有：** `npm install -g claude-mem-lite` 和 `npx` 不再安装开发工具链。按依赖方式安装，从 298 个包 /
+  541 MB 降到 96 个包 / 57 MB；发布后实测 `-g` 和 `npx` 也是同样的 96 个包。确认执行的
+  `maintain execute --ops purge_stale` 现在一次运行就删掉预览里统计的全部行，只做一次快照。`doctor` 会对失败的
+  更新检查、以及以 `/v1` 结尾的 `ANTHROPIC_BASE_URL` 发出警告。详见 CHANGELOG.md。
+
 ## 升级到 6.23.1
 
 **如果你设置了 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`，后台 LLM 调用现在会发往那个网关。**

package/bash-utils.mjs

@@ -632,6 +632,28 @@ function withoutDiffHunks(text) {
 // Paths excluded from observation capture (ephemeral / virtual filesystems) — applied
 // uniformly to both command-parsed paths and direct file_path/path/filePath fields.
 
+// A line a test runner prints for one test (`# Subtest:` heads a failing one too): it carries the
+// test's name, not a summary.
+const PASSED_TEST_LINE_RE = /^[ \t]*(?:✔|✓|ok[ \t]+\d+[ \t]+-|# Subtest:)/;
+
+/**
+ * Whether test-runner output carries a red summary or failure banner (detectBashSignificance's
+ * veto on a green "0 fail" marker; D#179).
+ * @param {string} scan
+ * @returns {boolean}
+ */
+function hasRedTestSummary(scan) {
+  const lines = scan
+    .split('\n')
+    .filter((l) => !PASSED_TEST_LINE_RE.test(l))
+    .join('\n');
+  return (
+    /\b[1-9]\d*[ \t]+(?:fail|failed|failures|failing|errors?)\b(?=[ \t]*(?:$|[,;|(]|\.(?:[ \t]|$)|in[ \t]+\S))|^[ \t]*(?:ℹ|#)[ \t]*(?:fail|cancelled)[ \t]+[1-9]\d*[ \t]*$/im.test(
+      lines,
+    ) || /^[ \t]*(?:--- )?FAIL(?:ED)?(?::|[ \t]|$)/m.test(lines)
+  );
+}
+
 /**
  * Detect significance signals in a Bash command and its response.
  * Checks for errors, test runs, builds, git operations, and deployments.
@@ -675,12 +697,23 @@ export function detectBashSignificance(input, response) {
   // suites prints one summary each, and a node:test run whose failures were all timeouts says
   // "fail 0" next to "cancelled 1" (pre-tag defect review, item 7 F1). Red = a nonzero fail /
   // cancelled count in either summary form.
+  // D#179: a count-first red must sit where a summary puts it — end of line, or before `,` `;`
+  // `|` `(` `. ` or `in …` — on ONE line, and never on a line a runner prints for a PASSED test
+  // (node:test `✔ name (1ms)`, vitest / bun `✓ name`, TAP `ok 1 - name` and its `# Subtest:`),
+  // which carries the test's NAME. Matched anywhere and across newlines, a passing run whose test
+  // name or log said "3 failed" / "2 failed attempts" read red, and "want 2\nFAIL" read as
+  // "2 FAIL". `errors?` is red too (pytest "1 passed, 1 error", tsc "Found 1 error in …",
+  // eslint "(2 errors, 0 warnings)"). go / jest / vitest / shell-suite failures carry a
+  // case-sensitive FAIL / FAILED banner at line start ("--- FAIL:", "FAILED: 3 case(s)", pytest
+  // "FAILED test_x.py::…"), read on its own. The green marker still
+  // spans lines on purpose: made one-line, 17 of this machine's 77,819 recorded results flipped
+  // to errors, and 15 of them were passing batteries, file reads and reports that only ever
+  // matched "0\nFAIL" by accident; 2 were real failures (measured 2026-10-07, recounted by the
+  // pre-tag delta review).
   const hasGreenTestSummary =
     looksLikeError &&
     /\b0\s+(fail|failed|failures)\b|^[ \t]*(?:ℹ|#)[ \t]*fail[ \t]+0[ \t]*$/im.test(scan) &&
-    !/\b[1-9]\d*\s+(fail|failed|failures|failing)\b|^[ \t]*(?:ℹ|#)[ \t]*(?:fail|cancelled)[ \t]+[1-9]\d*[ \t]*$/im.test(
-      scan,
-    );
+    !hasRedTestSummary(scan);
   // NOTE: do not add `\bFAIL\s` here — with /i flag it would re-match the
   // very `0 fail\n` token green-summary is trying to exempt. A real test
   // failure produces "N fail" (N≥1) which never triggers hasGreenTestSummary,

package/hook-optimize.mjs

@@ -484,8 +484,8 @@ scope: ${SCOPE_PROMPT_LEGEND}`;
       // clampImportance floor it to 1 (kept visible, low-ranked) instead of hiding.
       // A compression keeper is never hidden: hiding it hides every member compressed into it
       // (the same rule NOT_COMPRESSION_KEEPER_SQL enforces on the maintenance writers). It falls
-      // through to the normal update instead: floored to importance 1 and stamped, so it is not
-      // re-sent. That update keeps its stored title and narrative in both scopes (keepStoredText).
+      // through instead: in narrow scope to the stamp-only write below (floored to importance 1
+      // and stamped, so it is not re-sent), in wide scope to the normal update.
       const isKeeper = !!db
         .prepare('SELECT 1 FROM observations WHERE compressed_into = ? LIMIT 1')
         .get(cand.id);
@@ -518,6 +518,31 @@ scope: ${SCOPE_PROMPT_LEGEND}`;
         processed++;
         continue;
       }
+      // A narrow 0 reply reaches this point only for a row that may not be hidden (a compression
+      // keeper, or an importance a person set). It judged the row worthless, so it is no basis for
+      // any of the row's text either: the stored title and narrative stay (D#207: 'Weekly summary:
+      // auth refactor' became 'Weekly summary', narrative 'x'), and so do type, lesson, concepts,
+      // facts, aliases and scope (D#268). Written instead: what hiding would have written bar the
+      // hide, i.e. the stamp, so the row is not re-sent, plus the importance floor below. Wide
+      // scope stays on the normal path: its rows are substantive by construction, so a 0 there
+      // reads as a misjudgment of importance, not of the row.
+      if (scoredZero && scope !== 'wide') {
+        const res = db
+          .prepare(
+            `UPDATE observations SET
+               importance = CASE WHEN importance_set_at IS NOT NULL THEN importance
+                                 ELSE MAX(?, COALESCE(NULLIF(importance, 0), 1)) END,
+               optimized_at = ?
+             WHERE id = ? AND ${liveObsFilterSql('')} AND optimized_at IS NULL`,
+          )
+          .run(clampImportance(parsed.importance), Date.now(), cand.id);
+        if (res.changes === 0) {
+          skipped++;
+          continue;
+        }
+        processed++;
+        continue;
+      }
 
       // Enrichment ("add a lesson") must not reclassify a specific type down to the generic
       // 'change' (lower TYPE_QUALITY + faster decay); keep the stored type on that downgrade.
@@ -558,13 +583,8 @@ scope: ${SCOPE_PROMPT_LEGEND}`;
       // For `narrow`, the truncate stays on LLM output but NOT on the preserve-on-empty
       // fallback — truncating the row's own stored narrative to buy nothing was the same
       // bug in miniature.
-      //
-      // A reply that scored the row 0 reaches this point only for a row that may not be hidden
-      // (a compression keeper, or an importance a person set). It judged the row worthless, so
-      // its title and narrative do not replace the stored ones either (D#207: 'Weekly summary:
-      // auth refactor' became 'Weekly summary', narrative 'x').
       const isWide = scope === 'wide';
-      const keepStoredText = isWide || scoredZero;
+      const keepStoredText = isWide;
       const title = keepStoredText ? cand.title : truncate(scrubSecrets(parsed.title || ''), 120);
       const narrative = keepStoredText
         ? cand.narrative
@@ -611,8 +631,8 @@ scope: ${SCOPE_PROMPT_LEGEND}`;
       // Narrow replaces title and narrative with model text, so an explicit save it rewrites (one
       // whose save-time enrich failed) moves to the re-enrich writer's id, as a cluster-merge
       // keeper does (D#146, D#138). Wide keeps the stored title and narrative (it fills the lesson
-      // and the side fields), so the row stays an explicit save, and so does a row whose stored
-      // text a 0 reply left in place. The writer's session row is best-effort.
+      // and the side fields), so the row stays an explicit save; a narrow 0 reply never gets here.
+      // The writer's session row is best-effort.
       let rewriteSessionId = null;
       if (!keepStoredText) {
         const cur = db.prepare('SELECT memory_session_id FROM observations WHERE id = ?').get(cand.id);

package/hook-shared.mjs

@@ -281,7 +281,8 @@ export const GC_PRESERVED_MARKER_PREFIXES = Object.freeze([
   // out. Both are version-keyed one-shot migration sentinels written by
   // scripts/setup.sh, and their gate is `! -f <marker>` — deleting one re-runs
   // its migration. `.mcp-dedup-v2.78` gates a block that removes
-  // mcpServers.mem / mcpServers["mem-lite"] from the user's ~/.claude.json with
+  // mcpServers.mem / mcpServers["mem-lite"] from the config home's .claude.json (one marker per
+  // .claude.json since D#270, the same prefix) with
   // a raw writeFileSync (no tmp+rename, no backup), which the repo's own test
   // documents as intentionally one-shot: "If a user later runs `claude mcp add
   // mem ...` themselves, the gate intentionally lets it stand." A 30-day sweep

package/hook-update.mjs

@@ -318,13 +318,28 @@ function shouldCheck(state) {
 // ── GitHub API ─────────────────────────────────────────────
 // Try releases/latest first, fallback to tags (some repos only use tags)
 export async function fetchLatestRelease() {
-  return (await lookupLatestRelease()).release;
+  const { release } = await lookupLatestRelease();
+  if (release) clearRecordedLookupFailure();
+  return release;
+}
+
+// repair looks up through fetchLatestRelease, so a lookup that succeeds there is evidence against
+// the failure doctor reports; without this the warning outlived the repair by a full check interval
+// (D#266). Only the two fields that decide whether doctor warns. lastCheck, latestVersion and
+// rateLimited belong to checkForUpdate (the background check and self-update): rateLimited picks
+// its interval (6 h, else 24 h), so clearing it here pushed the next check back by up to 18 h
+// (post-release review). No write when there is nothing to clear.
+function clearRecordedLookupFailure() {
+  const state = readState();
+  if (!state.lookupError && !state.lookupFailingSince) return;
+  saveState({ ...state, lookupError: null, lookupFailingSince: null });
 }
 
 // One lookup's outcome, returned rather than kept in module state: a module flag let a second
 // lookup running at the same time read the first one's 403 (D#260). `rateLimited` is THIS
-// lookup's refusal; the persisted flag is not that, since only a successful lookup clears it
-// (pre-tag review of cd9f1ab7). `error` says why there is no release, for doctor (D#255).
+// lookup's refusal; the persisted flag is not that, since only a successful checkForUpdate (the
+// background check or self-update) clears it (pre-tag review of cd9f1ab7). `error` says why there
+// is no release, for doctor (D#255).
 async function lookupLatestRelease() {
   const headers = {
     Accept: 'application/vnd.github+json',
@@ -905,25 +920,33 @@ export function recoverInterruptedSwaps(targetDir = INSTALL_DIR) {
   return recovered;
 }
 
+// A rollback swaps a file SET back just as the install swapped it in, so it holds the same
+// marker for the same reason (D#239 g). After the MED-5 smoke gate the loop has already cleared
+// it; after a throw inside the loop it is still set, and this call takes it over.
 function rollbackInstall(installed, backedUp, backupDir, targetDir) {
-  for (const relPath of installed.reverse()) {
-    try {
-      rmSync(join(targetDir, relPath), { recursive: true, force: true });
-    } catch {
-      /* best-effort */
+  markSwapStart();
+  try {
+    for (const relPath of installed.reverse()) {
+      try {
+        rmSync(join(targetDir, relPath), { recursive: true, force: true });
+      } catch {
+        /* best-effort */
+      }
     }
-  }
-  for (const relPath of backedUp.reverse()) {
-    const backupPath = join(backupDir, relPath);
-    const targetPath = join(targetDir, relPath);
-    try {
-      if (existsSync(backupPath)) {
-        mkdirSync(dirname(targetPath), { recursive: true });
-        renameSync(backupPath, targetPath);
+    for (const relPath of backedUp.reverse()) {
+      const backupPath = join(backupDir, relPath);
+      const targetPath = join(targetDir, relPath);
+      try {
+        if (existsSync(backupPath)) {
+          mkdirSync(dirname(targetPath), { recursive: true });
+          renameSync(backupPath, targetPath);
+        }
+      } catch (restoreErr) {
+        debugCatch(restoreErr, `installExtractedRelease-restore-${relPath}`);
       }
-    } catch (restoreErr) {
-      debugCatch(restoreErr, `installExtractedRelease-restore-${relPath}`);
     }
+  } finally {
+    clearSwapMarker();
   }
 }
 
@@ -1049,6 +1072,9 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
     }
 
     markSwapStart();
+    // Cleared here only when the loop finished. If a rename throws, the half-swapped tree keeps
+    // the marker through the catch below until rollbackInstall has put the old files back.
+    let swapped = false;
     try {
       for (const relPath of switchablePaths) {
         const stagedPath = join(stagingDir, relPath);
@@ -1070,8 +1096,9 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
         journalSwap(backupDir, backedUp, installed);
         renameSync(stagedPath, targetPath);
       }
+      swapped = true;
     } finally {
-      clearSwapMarker();
+      if (swapped) clearSwapMarker();
     }
 
     // MED-5: before discarding the rollback backup, prove the switched code boots.

package/install.mjs

@@ -99,7 +99,12 @@ import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/nat
 import { acquireLock } from './lib/proc-lock.mjs';
 import { atomicWriteFileSync, atomicCopyFileSync } from './lib/atomic-write.mjs';
 import { shellWord } from './cli-path.mjs';
-import { claudeConfigDir, claudeConfigDirFor, claudeStatePath } from './lib/data-paths.mjs';
+import {
+  claudeConfigDir,
+  claudeConfigDirFor,
+  claudeStatePath,
+  ignoredClaudeConfigDir,
+} from './lib/data-paths.mjs';
 import { isMemHook, isMemHookCommand, stripMemHooks, launcherEntryPath } from './lib/hook-prune.mjs';
 
 // Re-export for backward compatibility — tests/install-hook-scripts.test.mjs
@@ -1736,8 +1741,17 @@ async function status() {
     });
   }
 
-  // Database
-  if (existsSync(DB_PATH)) {
+  // Database. A data dir this process cannot enter reads as an empty one (D#199), and
+  // `exists: false` would be a guess — null says nobody could look.
+  const dataDirDenied = dataDirAccessError();
+  if (dataDirDenied) {
+    push(
+      'fail',
+      'database',
+      `Database: ${MEM_DATA_DIR} is not accessible (${dataDirDenied}) — Fix: ${dataDirAccessRemedy()}`,
+      { exists: null, error: dataDirDenied },
+    );
+  } else if (existsSync(DB_PATH)) {
     try {
       const Database = (await import('better-sqlite3')).default;
       const db = new Database(DB_PATH, { readonly: true });
@@ -1954,14 +1968,37 @@ async function doctor() {
     issues++;
   }
 
+  // A relative CLAUDE_CONFIG_DIR: Claude Code reads it against the directory it starts in, this
+  // code ignores it and uses ~/.claude, so hooks, settings and the plugin cache can sit in a home
+  // the host does not read (D#269). Followed only as an absolute path, on every face.
+  const ignoredConfigDir = ignoredClaudeConfigDir();
+  if (ignoredConfigDir !== null) {
+    dwarn(
+      `Claude Code config home: CLAUDE_CONFIG_DIR=${JSON.stringify(ignoredConfigDir)} is a relative path — Claude Code resolves it against the directory it starts in, claude-mem-lite uses ${claudeConfigDir()}`,
+    );
+    log('Set CLAUDE_CONFIG_DIR to an absolute path so both use the same directory.');
+  }
+
   const dataDirDenied = dataDirAccessError();
+  // D#199: a directory this process cannot ENTER or LIST reads as an empty one to
+  // existsSync/statSync, so the checks that look inside it said "no database yet" (✓), "DB 0.0MB"
+  // (✓) and "not found". Only those checks stand down, and only then: a readable directory that
+  // cannot be written (the usual 755 left by a `sudo` run) still reads correctly.
+  const readMode = fsConstants.R_OK | fsConstants.X_OK;
+  const dataDirUnreadable = dataDirDenied ? dataDirAccessError(MEM_DATA_DIR, readMode) : null;
   if (dataDirDenied) {
     fail(
-      `Data directory: ${MEM_DATA_DIR} is not accessible (${dataDirDenied}) — the checks below ` +
-        `read it as missing. Fix: ${dataDirAccessRemedy()}`,
+      `Data directory: ${MEM_DATA_DIR} is not accessible (${dataDirDenied}) — ` +
+        (dataDirUnreadable ? 'checks that read it say "not checked"' : 'it can be read but not written') +
+        `. Fix: ${dataDirAccessRemedy()}`,
     );
     issues++;
   }
+  const notCheckedDenied = (what, dir = MEM_DATA_DIR) =>
+    dwarn(`${what}: not checked — ${dir} is not accessible`);
+  // The code dir is the data dir in the default shape; under CLAUDE_MEM_DIR it is checked apart.
+  const codeIsDataDir = sameDir(INSTALL_DIR, MEM_DATA_DIR);
+  const codeDirDenied = codeIsDataDir ? dataDirUnreadable : dataDirAccessError(INSTALL_DIR, readMode);
 
   // Which code homes does this machine actually run? A machine can hold three
   // at once (plugin cache / ~/.claude-mem-lite / npm-global) and each owns its
@@ -2023,7 +2060,9 @@ async function doctor() {
   // too-new file is still a real number; a checkmark on it is not.
   let dbWriteBlocked = null;
   let dbUnusableHere = false;
-  if (!existsSync(DB_PATH)) {
+  if (dataDirUnreadable) {
+    notCheckedDenied('DB schema');
+  } else if (!existsSync(DB_PATH)) {
     ok('DB schema: no database yet — nothing to compare');
   } else if (rootProbes.length === 0) {
     // The fourth outcome the first cut had and did not print. The `fail` above already tells
@@ -2130,9 +2169,20 @@ async function doctor() {
       }
     }
   } else {
-    fail('server.mjs: missing');
-    fail('hook.mjs: missing');
-    issues += 2;
+    // A locked code dir reads as one with no code in it (D#199). In the default shape it IS the
+    // data dir, already a ✗ above; under CLAUDE_MEM_DIR it is not, and this is the only line.
+    if (codeDirDenied && codeIsDataDir) {
+      notCheckedDenied('Entry points', INSTALL_DIR);
+    } else if (codeDirDenied) {
+      fail(
+        `Entry points: ${INSTALL_DIR} is not accessible (${codeDirDenied}) — Fix: chmod u+rwx ${shellWord(INSTALL_DIR)}`,
+      );
+      issues++;
+    } else {
+      fail('server.mjs: missing');
+      fail('hook.mjs: missing');
+      issues += 2;
+    }
   }
 
   // Hook self-heal runtime: the launcher (scripts/hook-launcher.mjs) degrades a
@@ -2140,7 +2190,12 @@ async function doctor() {
   // fire. That silence is intentional but hides failure — it drops a breakage
   // marker so this check can surface the otherwise-invisible degraded state.
   const brokenMarker = join(MEM_RUNTIME_DIR, 'hook-launcher-broken');
-  if (existsSync(brokenMarker)) {
+  // The marker lives in the runtime dir, which is inside the data dir unless CLAUDE_MEM_RUNTIME_DIR
+  // moves it elsewhere.
+  const runtimeInDataDir = (resolve(MEM_RUNTIME_DIR) + sep).startsWith(resolve(MEM_DATA_DIR) + sep);
+  if (dataDirUnreadable && runtimeInDataDir) {
+    notCheckedDenied('Hook self-heal');
+  } else if (existsSync(brokenMarker)) {
     let detail = '';
     try {
       const b = JSON.parse(readFileSync(brokenMarker, 'utf8'));
@@ -2187,32 +2242,34 @@ async function doctor() {
   // check anywhere. Cheap probes only (DB file + .bak aggregate, no tree walk).
   // The budget itself is enforced by lib/db-backup on every new snapshot; this
   // check surfaces stores that predate the budget or exceed it between snapshots.
-  try {
-    const { listSnapshots, backupBudgetBytes } = await import('./lib/db-backup.mjs');
-    const dbFile = join(MEM_DATA_DIR, 'claude-mem-lite.db');
-    const dbBytes = existsSync(dbFile) ? statSync(dbFile).size : 0;
-    const snaps = listSnapshots(dbFile);
-    const backupBytes = snaps.reduce((s, x) => s + x.size, 0);
-    const mb = (n) => (n / (1024 * 1024)).toFixed(1);
-    // Warn threshold = the REAL eviction budget (pre-release review 2026-08-16) —
-    // warning below it promised an eviction enforceBackupBudget would never do.
-    if (backupBytes > backupBudgetBytes()) {
-      dwarn(
-        `Disk footprint: ${snaps.length} backup snapshot(s) hold ${mb(backupBytes)}MB, over the ${mb(backupBudgetBytes())}MB budget (CLAUDE_MEM_BACKUP_BUDGET_MB) — the next maintain/save snapshot evicts oldest snapshots past the 7d undo grace`,
-      );
-    } else {
-      ok(
-        `Disk footprint: DB ${mb(dbBytes)}MB, ${snaps.length} backup snapshot(s) ${mb(backupBytes)}MB (budget ${mb(backupBudgetBytes())}MB)`,
-      );
+  if (dataDirUnreadable) notCheckedDenied('Disk footprint');
+  else
+    try {
+      const { listSnapshots, backupBudgetBytes } = await import('./lib/db-backup.mjs');
+      const dbFile = join(MEM_DATA_DIR, 'claude-mem-lite.db');
+      const dbBytes = existsSync(dbFile) ? statSync(dbFile).size : 0;
+      const snaps = listSnapshots(dbFile);
+      const backupBytes = snaps.reduce((s, x) => s + x.size, 0);
+      const mb = (n) => (n / (1024 * 1024)).toFixed(1);
+      // Warn threshold = the REAL eviction budget (pre-release review 2026-08-16) —
+      // warning below it promised an eviction enforceBackupBudget would never do.
+      if (backupBytes > backupBudgetBytes()) {
+        dwarn(
+          `Disk footprint: ${snaps.length} backup snapshot(s) hold ${mb(backupBytes)}MB, over the ${mb(backupBudgetBytes())}MB budget (CLAUDE_MEM_BACKUP_BUDGET_MB) — the next maintain/save snapshot evicts oldest snapshots past the 7d undo grace`,
+        );
+      } else {
+        ok(
+          `Disk footprint: DB ${mb(dbBytes)}MB, ${snaps.length} backup snapshot(s) ${mb(backupBytes)}MB (budget ${mb(backupBudgetBytes())}MB)`,
+        );
+      }
+    } catch (e) {
+      // "Informational" was the reason this was silent, and silence is the one thing it must
+      // not be: the import above is of a sibling module, so the run where it fails is a broken
+      // install — doctor's entire audience. The line vanished with no trace, which reads
+      // identically to a check that was never written (R12 audit P3-7). Every other "I could
+      // not look" in this file has its own sentence; this is the same shape as the four.
+      dwarn('Disk footprint: check failed — ' + e.message);
     }
-  } catch (e) {
-    // "Informational" was the reason this was silent, and silence is the one thing it must
-    // not be: the import above is of a sibling module, so the run where it fails is a broken
-    // install — doctor's entire audience. The line vanished with no trace, which reads
-    // identically to a check that was never written (R12 audit P3-7). Every other "I could
-    // not look" in this file has its own sentence; this is the same shape as the four.
-    dwarn('Disk footprint: check failed — ' + e.message);
-  }
 
   // Plugin/hook lifecycle state
   //
@@ -2360,7 +2417,9 @@ async function doctor() {
   // and a check that reports on a thing you do not have is noise.
 
   // Database
-  if (existsSync(DB_PATH)) {
+  if (dataDirUnreadable) {
+    notCheckedDenied('Database');
+  } else if (existsSync(DB_PATH)) {
     try {
       const Database = (await import('better-sqlite3')).default;
       const db = new Database(DB_PATH, { readonly: true });
@@ -2493,20 +2552,38 @@ async function doctor() {
   // Update state
   try {
     const stateFile = join(MEM_DATA_DIR, 'runtime', 'update-state.json'); // runtime-dir:stays-put — installation identity
-    if (existsSync(stateFile)) {
+    // Dynamic, as elsewhere in doctor, so a hook-update that cannot load costs only these judgements.
+    let hookUpdate = null;
+    try {
+      hookUpdate = await import('./hook-update.mjs');
+    } catch {
+      /* cannot judge — report the recorded state as it stands */
+    }
+    // While checks are off neither the background check nor self-update looks up; only a repair
+    // does (README: a repair still runs), and since D#266 its successful lookup is the one thing
+    // that clears a failure recorded before they were turned off. Without this branch that failure
+    // stayed a warning, and a missing state file read "first run?". Say they are off instead.
+    const checksOff = hookUpdate?.updateCheckDisabledReason() ?? null;
+    if (checksOff) {
+      const why =
+        checksOff === 'CLAUDE_MEM_SKIP_UPDATE'
+          ? 'CLAUDE_MEM_SKIP_UPDATE is set'
+          : `${INSTALL_DIR} is a development install (a git checkout or symlinks)`;
+      ok(`Update state: not checked — ${why}`);
+    } else if (dataDirUnreadable) {
+      notCheckedDenied('Update state');
+    } else if (existsSync(stateFile)) {
       const state = JSON.parse(readFileSync(stateFile, 'utf8'));
       const parts = [];
       if (state.lastCheck) parts.push(`last check: ${state.lastCheck}`);
       if (state.latestVersion) parts.push(`latest: v${state.latestVersion}`);
       if (state.lastUpdate) parts.push(`last update: ${state.lastUpdate}`);
       // Judged against the version running now, like the banner (#35): in plugin mode
-      // nothing clears the cached flag once Claude Code has applied the update. Dynamic, as
-      // elsewhere in doctor, so a hook-update that cannot load costs only this judgement.
+      // nothing clears the cached flag once Claude Code has applied the update.
       if (state.updateAvailable) {
         let pending = true;
         try {
-          const { pendingCachedUpdate } = await import('./hook-update.mjs');
-          pending = pendingCachedUpdate(state) !== null;
+          if (hookUpdate) pending = hookUpdate.pendingCachedUpdate(state) !== null;
         } catch {
           /* cannot judge — report the cached flag as it stands */
         }
@@ -2525,6 +2602,11 @@ async function doctor() {
         log(
           'Newer releases cannot be detected until a lookup succeeds; self-update and repair use the same lookup.',
         );
+        // doctor sees only its own environment: a CLAUDE_MEM_SKIP_UPDATE set in Claude Code's
+        // settings `env` turns the checks off for the hooks but not here (post-release review).
+        log(
+          "If CLAUDE_MEM_SKIP_UPDATE is set in Claude Code's settings, background checks are off there; this record may be older, or from a run without it (a terminal self-update).",
+        );
       } else {
         ok(`Update state: ${parts.join(', ') || 'empty'}`);
       }
@@ -2596,6 +2678,8 @@ async function doctor() {
       ok(
         'Managed files: n/a (plugin-only install — code is served from the plugin cache, so ~/.claude-mem-lite holds data only)',
       );
+    } else if (codeDirDenied) {
+      notCheckedDenied('Managed files', INSTALL_DIR);
     } else if (r.devMode) {
       const parts = [];
       if (r.plainCount > 0) {
@@ -2690,6 +2774,8 @@ async function doctor() {
       : `claude-mem-lite self-update (or: node ${shellWord(join(INSTALL_DIR, 'cli.mjs'))} repair)`;
     if (skipScripts) {
       ok('Hook scripts: n/a (plugin-only install — hooks run from the plugin cache)');
+    } else if (codeDirDenied) {
+      notCheckedDenied('Hook scripts', INSTALL_DIR);
     } else if (!h.present) {
       issueWarn(
         `Hook scripts: ${join(INSTALL_DIR, 'scripts')} ` +
@@ -3600,15 +3686,30 @@ async function rebuildBinding() {
  * returns for a permission error and a live peer alike — as "Another install/repair is in
  * progress" and exited 0. Returns the error code, or null when accessible or absent.
  */
-function dataDirAccessError(dir = MEM_DATA_DIR) {
+function dataDirAccessError(
+  dir = MEM_DATA_DIR,
+  mode = fsConstants.R_OK | fsConstants.W_OK | fsConstants.X_OK,
+) {
   try {
-    accessSync(dir, fsConstants.R_OK | fsConstants.W_OK | fsConstants.X_OK);
+    accessSync(dir, mode);
     return null;
   } catch (e) {
     return e.code === 'ENOENT' ? null : e.code || 'EACCES';
   }
 }
 
+// Same directory however it is spelled (a trailing slash, a symlinked HOME). stat works on a
+// locked directory itself, so dev + inode decide; resolve() when either cannot be stat'ed.
+function sameDir(a, b) {
+  try {
+    const x = statSync(a);
+    const y = statSync(b);
+    return x.dev === y.dev && x.ino === y.ino;
+  } catch {
+    return resolve(a) === resolve(b);
+  }
+}
+
 const dataDirAccessRemedy = () =>
   `chmod u+rwx ${shellWord(MEM_DATA_DIR)} (or chown it back to your user if a sudo run created it)`;
 

package/lib/data-paths.mjs

@@ -44,6 +44,17 @@ export function claudeConfigDir() {
   return d && isAbsolute(d) ? d : join(homedir(), '.claude');
 }
 
+/**
+ * The CLAUDE_CONFIG_DIR value claudeConfigDir() does not follow (set, not empty, not absolute),
+ * else null. Claude Code resolves such a value against the directory it starts in (2.1.293), so
+ * the two can then use different config homes; doctor names it (D#269).
+ * @returns {string|null}
+ */
+export function ignoredClaudeConfigDir() {
+  const d = process.env.CLAUDE_CONFIG_DIR;
+  return d && !isAbsolute(d) ? d : null;
+}
+
 /**
  * The config home for a caller that may name a HOME: `<home>/.claude` when it does (tests and
  * fixtures pass one), else the host's own, claudeConfigDir().

package/lib/maintain-core.mjs

@@ -630,6 +630,10 @@ export function mergeDuplicates(db, groups, skipped = null) {
         continue;
       }
       if (!redirect.has(removeId)) redirect.set(removeId, keepId);
+      // D#200: a second, different keeper for the same row is a request that cannot also be
+      // honoured; say so. The same pair repeated verbatim merged as asked and stays quiet.
+      else if (redirect.get(removeId) !== keepId)
+        skip(keepId, removeId, `#${removeId} already merges into #${redirect.get(removeId)}`);
     }
   }
   if (redirect.size === 0) return 0;
@@ -666,8 +670,11 @@ export function mergeDuplicates(db, groups, skipped = null) {
   let merged = 0;
   for (const removeId of redirect.keys()) {
     const keeper = resolveKeeper(removeId);
-    if (keeper === removeId) continue; // cycle canonical: this row survives
     const keepId = redirect.get(removeId);
+    if (keeper === removeId) {
+      skip(keepId, removeId, `cycle: #${removeId} survives`); // cycle canonical: this row survives
+      continue;
+    }
     if (!isLive.get(keeper)) {
       skip(keepId, removeId, `no live row #${keeper}`); // keeper not live -> never orphan
       continue;

package/lib/recall-framing.mjs

@@ -1,4 +1,4 @@
-// lib/recall-framing.mjs — the first line of a PreToolUse / PostToolUse recall block, in two arms.
+// lib/recall-framing.mjs — the first line of a PreToolUse / PostToolUse recall block, in two wordings.
 //
 // The legacy line announces itself as "system-injected context, continue your planned
 // action". It was added in v2.40.0, modelled on the #7758 fix (a handoff injection misread
@@ -13,12 +13,21 @@
 //
 // PreToolUse is the best-cited face on record (56.2% over 7 days, 2026-09-27), so the wording
 // is not swapped on the documentation's say-so. The factual arm keeps that line's point as a
-// statement ("the tool call proceeds as planned") and the two arms run side by side, assigned
-// per SESSION, so one walk over one corpus compares them (doctrine rule 2: never diff two runs
-// taken at different times). benchmark/citation-live-replay.mjs `--by-framing` reads the arm
-// back from the injected text itself, which stays correct across the deploy boundary.
+// statement ("the tool call proceeds as planned"). From 6.16.0 to 6.24.x the two ran side by
+// side by default, assigned per SESSION, so one walk over one corpus compared them (doctrine rule
+// 2: never diff two runs taken at different times); `ab` still does that.
+// benchmark/citation-live-replay.mjs `--by-framing` reads the arm back from the injected text
+// itself, which stays correct across the deploy boundary.
 //
-// CLAUDE_MEM_RECALL_FRAMING = ab (default) | legacy | factual.
+// D#104 readout (2026-10-07, docs/audits/20261007-d104-d111-readout.md): no difference the
+// corpus can show. On ack-directive opus-5-5 sessions only, legacy cited 6/162 pretool pairs
+// (19 sessions) and factual 2/158 (22 sessions), session-level permutation p = 0.21; the
+// failure mode the doc names (the agent surfacing the block) matched no reply in the 20 legacy
+// and 22 factual sessions, by a pattern scan whose positive control is weak. A no-margin rule
+// passing at that n says nothing, so the incumbent stays: legacy is the default again and the
+// split is opt-in.
+//
+// CLAUDE_MEM_RECALL_FRAMING = legacy (default) | factual | ab. Any other value is legacy.
 
 const LEGACY_TAIL = 'system-injected context, continue your planned action:';
 // The substring classifyRecallFraming keys on. Part of the factual line only.
@@ -39,11 +48,11 @@ const FRAMING_LINE_RE = /^\[mem\] (?:PreToolUse|PostToolUse) recall — /;
  * @returns {'legacy'|'factual'}
  */
 export function recallFramingArm(sessionId, env = process.env) {
-  const mode = String(env.CLAUDE_MEM_RECALL_FRAMING || 'ab')
+  const mode = String(env.CLAUDE_MEM_RECALL_FRAMING || 'legacy')
     .trim()
     .toLowerCase();
-  if (mode === 'legacy' || mode === 'factual') return mode;
-  if (!sessionId) return 'legacy';
+  if (mode === 'factual') return mode;
+  if (mode !== 'ab' || !sessionId) return 'legacy';
   // FNV-1a, 32-bit: stable across processes and Node versions, unlike anything keyed on
   // object identity or Math.random.
   let h = 0x811c9dc5;

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.24.0",
+  "version": "6.25.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "6.24.0",
+      "version": "6.25.0",
       "os": [
         "darwin",
         "linux",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.24.0",
+  "version": "6.25.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).",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/scripts/post-tool-use.sh

@@ -28,10 +28,19 @@
 # to the key, so only that key's own value can satisfy it.
 # Deliberately NOT applied to the Node handoff at the tail: hook.mjs already self-guards
 # there, so a bash false positive could only lose data, never save work.
-case "$CLAUDE_CONFIG_DIR" in
-  /* | [A-Za-z]:[\\/]*) _mem_settings_file="${CLAUDE_CONFIG_DIR}/settings.json" ;;
-  *) _mem_settings_file="${HOME}/.claude/settings.json" ;;
-esac
+# "Absolute" as Node's path.isAbsolute reads it on this platform (D#269): a leading / anywhere,
+# and in a Windows shell (Git Bash, MSYS, Cygwin) also a leading \ (UNC, root of the drive) or a
+# drive letter and a slash. The same body sits in scripts/setup.sh.
+_mem_is_abs() {
+  case "$1" in /*) return 0 ;; esac
+  case "${OSTYPE:-}" in
+    msys* | cygwin*) case "$1" in \\* | [A-Za-z]:[\\/]*) return 0 ;; esac ;;
+  esac
+  return 1
+}
+_mem_config_home="${HOME}/.claude"
+_mem_is_abs "${CLAUDE_CONFIG_DIR:-}" && _mem_config_home="$CLAUDE_CONFIG_DIR"
+_mem_settings_file="$_mem_config_home/settings.json"
 _mem_plugin_disabled() {
   [[ -r "$_mem_settings_file" ]] || return 1
   local _settings

package/scripts/setup.sh

@@ -39,16 +39,44 @@ DB_DIR="$CODE_DIR"
 # Claude Code's config home, as lib/data-paths.mjs claudeConfigDir resolves it: an absolute
 # CLAUDE_CONFIG_DIR, else ~/.claude (a relative value is ignored). The plugin cache, settings.json
 # and .claude.json all live there; with the variable set, ~/.claude is another profile's.
-case "${CLAUDE_CONFIG_DIR:-}" in
-  /* | [A-Za-z]:[\\/]*)
-    CC_CONFIG_DIR="$CLAUDE_CONFIG_DIR"
-    CC_STATE_FILE="$CLAUDE_CONFIG_DIR/.claude.json"
-    ;;
-  *)
-    CC_CONFIG_DIR="$HOME/.claude"
-    CC_STATE_FILE="$HOME/.claude.json"
-    ;;
-esac
+# The defaults are spelled once: the default arm below and the marker keys after it both read them.
+CC_DEFAULT_CONFIG_DIR="$HOME/.claude"
+CC_DEFAULT_STATE_FILE="$HOME/.claude.json"
+# "Absolute" as Node's path.isAbsolute reads it on this platform (D#269): a leading / anywhere,
+# and in a Windows shell (Git Bash, MSYS, Cygwin) also a leading \ (UNC, root of the drive) or a
+# drive letter and a slash. The same body sits in scripts/post-tool-use.sh.
+_mem_is_abs() {
+  case "$1" in /*) return 0 ;; esac
+  case "${OSTYPE:-}" in
+    msys* | cygwin*) case "$1" in \\* | [A-Za-z]:[\\/]*) return 0 ;; esac ;;
+  esac
+  return 1
+}
+if _mem_is_abs "${CLAUDE_CONFIG_DIR:-}"; then
+  CC_CONFIG_DIR="$CLAUDE_CONFIG_DIR"
+  # Trailing slashes off, a bare / kept: the marker keys below read this as text, and `cfg/` must
+  # key the same file as `cfg` (post-release review).
+  while [[ "$CC_CONFIG_DIR" == */ && "$CC_CONFIG_DIR" != / ]]; do CC_CONFIG_DIR="${CC_CONFIG_DIR%/}"; done
+  CC_STATE_FILE="$CC_CONFIG_DIR/.claude.json"
+else
+  CC_CONFIG_DIR="$CC_DEFAULT_CONFIG_DIR"
+  CC_STATE_FILE="$CC_DEFAULT_STATE_FILE"
+fi
+# Steps 7 and 9 each settle a question about one file (.claude.json, settings.json) with a
+# one-shot marker in this data dir, which every CLAUDE_CONFIG_DIR profile shares, so the first
+# profile to start settled it for all of them (D#270). Key each marker by the file it gates. The
+# default files keep the bare names every existing install already has: renaming one re-runs it.
+# Not "is this ~/.claude": CLAUDE_CONFIG_DIR=~/.claude still moves .claude.json into ~/.claude.
+# Another spelling of a path (`cfg/`, `~/./.claude`, a symlinked dir) must key the same file: -ef
+# matches a default that exists, and any other path is hashed by its directory's physical path when
+# that directory exists (it does once Claude Code has run: the plugin runs from its plugins/). So
+# both callers pass the FILE, whose directory is the config dir itself.
+marker_suffix() {
+  [[ "$1" == "$2" || "$1" -ef "$2" ]] && return 0
+  local key="$1"
+  [[ -d "${1%/*}" ]] && key="$(cd "${1%/*}" && pwd -P)/${1##*/}"
+  printf -- '-%s' "$(printf '%s' "$key" | cksum | cut -d' ' -f1)"
+}
 RUNTIME_DIR="$CODE_DIR/runtime"
 if [[ -n "${CLAUDE_MEM_DIR:-}" || -n "${CLAUDE_MEM_RUNTIME_DIR:-}" ]] && [[ -f "$ROOT/lib/resolve-data-dir.mjs" ]]; then
   # shellcheck disable=SC2016  # node script single-quoted on purpose; path passed via env, not shell expansion
@@ -171,9 +199,9 @@ mkdir -p "$CODE_DIR/runtime"
 # resolved once at the top of this file.
 #
 # ONLY this marker follows the override. `.mcp-dedup-v2.78` and `.residue-warned-v2.55`
-# below are one-shot state about THIS MACHINE's install — a ~/.claude.json edit and a
-# settings.json warning, not state a hook hands to another component — so they stay under
-# CODE_DIR. Read lib/resolve-data-dir.mjs's MOVES/STAYS list before relocating either:
+# below are one-shot state about a CONFIG HOME — a .claude.json edit and a settings.json
+# warning, not state a hook hands to another component — so they stay under CODE_DIR, one per
+# file they gate. Read lib/resolve-data-dir.mjs's MOVES/STAYS list before relocating either:
 # moving a run-once marker re-runs what it gated.
 DEPS_FLAG="$RUNTIME_DIR/.deps-broken"
 
@@ -314,9 +342,10 @@ fi
 #    pre-v2.79.1 — extra node spawn + JSON parse on every SessionStart for a
 #    near-always no-op). Bump MCP_MIGRATION name to re-run cleanup in future
 #    versions; same shape as the .deps-broken self-heal pattern.
-# CODE_DIR/runtime, not RUNTIME_DIR: this marker gates a one-shot edit of ~/.claude.json,
-# which is machine state, not per-data-dir state. Relocating it would re-run that edit.
-MCP_MIGRATION="$CODE_DIR/runtime/.mcp-dedup-v2.78"
+# CODE_DIR/runtime, not RUNTIME_DIR: this marker gates a one-shot edit of the config home's
+# .claude.json, which is not per-data-dir state. Relocating it would re-run that edit. One per
+# .claude.json (marker_suffix above).
+MCP_MIGRATION="$CODE_DIR/runtime/.mcp-dedup-v2.78$(marker_suffix "$CC_STATE_FILE" "$CC_DEFAULT_STATE_FILE")"
 if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" && ! -f "$MCP_MIGRATION" ]]; then
   # shellcheck disable=SC2016  # node script single-quoted on purpose; CLAUDE_JSON passed via env, not shell expansion
   CLAUDE_JSON="$CC_STATE_FILE" node -e '
@@ -393,14 +422,14 @@ if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
 fi
 
 # 9. Residue detection (plugin mode only): warn once if legacy direct-install
-#    hooks remain in ~/.claude/settings.json. A user who installed via global
+#    hooks remain in the config home's settings.json. A user who installed via global
 #    `claude-mem-lite install` and later switched to the marketplace plugin
 #    will run every hook twice (direct settings.json hooks AND plugin hooks)
 #    until they run `claude-mem-lite uninstall` to clear the settings.json
 #    entries. /plugin uninstall does not touch settings.json.
-# CODE_DIR/runtime, same reason: the residue it warns about is stale hook entries in
-# ~/.claude/settings.json — one machine, one warning, regardless of where the data lives.
-RESIDUE_MARKER="$CODE_DIR/runtime/.residue-warned-v2.55"
+# CODE_DIR/runtime, same reason: the residue it warns about is stale hook entries in the config
+# home's settings.json — one warning per config home, regardless of where the data lives.
+RESIDUE_MARKER="$CODE_DIR/runtime/.residue-warned-v2.55$(marker_suffix "$CC_CONFIG_DIR/settings.json" "$CC_DEFAULT_CONFIG_DIR/settings.json")"
 if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" && ! -f "$RESIDUE_MARKER" ]]; then
   SETTINGS="$CC_CONFIG_DIR/settings.json"
   if [[ -f "$SETTINGS" ]]; then
@@ -438,7 +467,7 @@ if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" && ! -f "$RESIDUE_MARKER" ]]; then
     ' || true
   fi
   # Mark the warning as shown regardless of result — silence is fine if no
-  # residue, and the warning above is one-shot per data-dir.
+  # residue, and the warning above is one-shot per settings.json (RESIDUE_MARKER's key).
   touch "$RESIDUE_MARKER"
 fi