claude-mem-lite 3.91.0 → 3.93.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.91.0",
+      "version": "3.93.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.91.0",
+  "version": "3.93.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/README.md

@@ -823,6 +823,7 @@ benchmark and A/B harness are calibrated against — changing them invalidates t
 | `CLAUDE_MEM_ERROR_RECALL_BM25_MIN` | Relevance floor for the error-recall surface (memories injected after a failed Bash command). **Off by default.** Setting it to `10.5` (the calibrated value) makes the surface stay silent when its best-matching memory is not actually about the failure — the whole set is dropped, never trimmed row-by-row. **It is a real trade, not a free win:** measured on a live database at that threshold, injections fall ~37% and ~39% of firings go silent, concentrated in projects with few memories. Off by default because nothing shows the dropped rows were noise. Explore with `node benchmark/error-recall-suite.mjs --sweep`. | `0` (off) |
 | `CLAUDE_MEM_ERROR_RECALL_RERANK` | `off` restores the flat keyword ordering of the error-recall surface. **On by default**, and unlike the floor above it removes nothing: memories that share only the failed command's vocabulary are demoted below memories that mention the failure itself, and when a project has none of the latter the result is unchanged. Measured on a live database over 52 real failing commands × 15 projects: the lead memory matched no error term in 42.3% of firings before, 21.5% after, with the injected row count identical. | _(on)_ |
 | `CLAUDE_MEM_ERROR_RECALL_ON_FAILURE` | `off` stops the plugin from recalling memories when a Bash command **fails at the host level**. On by default. Claude Code delivers failed tool calls to a separate `PostToolUseFailure` hook event, so before this the surface only ever saw commands that exited `0` while printing error-ish text — a genuinely failing build recalled nothing. Denials from your own guardrails (sandbox, policy hooks, declined permission prompts) and commands you interrupted are never recalled for. | _(on)_ |
+| `CLAUDE_MEM_REGISTRY_CONFINE` | `off` lets registry enrichment read a resource whose `local_path` lies outside the managed data directory. **On by default.** Enrichment reads the file at `resources.local_path` and sends it to an LLM; the confinement check used to guard one of the four code paths that do this (`mem_registry(action="enrich")`) and not the other three, so `enrich <name>`, `enrich --all` and `import --enrich` read any path the row happened to hold. All four are gated now. Turn it off only if you deliberately registered resources outside `CLAUDE_MEM_DIR` and want them enriched; only `off` disables it — case-insensitively and ignoring surrounding whitespace — so a typo leaves the guard on. | _(on)_ |
 | `CLAUDE_MEM_UPS_IDENTIFIER_BYPASS` | `0` disables the bypass that lets an exact identifier match skip the score floors. | _(on)_ |
 | `CLAUDE_MEM_UPS_PROMPT_FALLBACK_LIMIT` | How many past-prompt rows the fallback arm may return. | `1` |
 | `MEM_COVERAGE_THRESHOLD` | Fraction of query terms a memory must cover to qualify (∈ [0,1]). | `0.4` |
@@ -894,6 +895,19 @@ Set by the tool or by the test harness. Setting these by hand is not supported:
 `CLAUDE_MEM_DB_PATH`, `CLAUDE_MEM_RUNTIME_DIR`, `MEM_DISABLE_SPAWN_LOG`.
 `CLAUDE_PLUGIN_ROOT` is set by Claude Code itself.
 
+The last two are worth one more sentence each, because they are the ones a harness reaches
+for. `CLAUDE_MEM_RUNTIME_DIR` relocates the runtime directory for hook-written state — markers,
+cooldowns, hook-error telemetry, the native-binding breakage marker, `metrics/`, episode
+buffers. Before v3.93.0 it was honoured by some readers and ignored by others, so setting it
+split the runtime rather than moving it. Installation-identity state (`install.lock`,
+`update-state.json`, update residue) deliberately stays under `CLAUDE_MEM_DIR`: two
+installers pointed at different override directories would otherwise each take their own
+lock and both proceed. **`CLAUDE_MEM_DB_PATH` still has the split shape**, and more narrowly
+than it looks: exactly ONE component reads it — `scripts/pre-tool-recall.js` — so setting it
+aims that single hook at one database and leaves the other four hook faces, the CLI and the
+MCP server on the default. Use `CLAUDE_MEM_DIR` — the only override
+every component respects, including the bash pre-filter — to isolate state.
+
 Three more are set by `vitest.config.mjs` / `tests/global-setup.mjs` and exist only to
 keep a test run off the live database: `CLAUDE_MEM_TEST_GUARD` (`1` arms the guard, `off`
 opts a test out), `CLAUDE_MEM_TEST_REALDIR` (the live data dir, captured before the suite

package/README.zh-CN.md

@@ -620,6 +620,7 @@ npm run benchmark:gate    # CI 门控：指标回退超过 5% 容差时失败
 | `MEM_QUIET_HOOKS` | 低噪声 hook。设为 `1` 时，SessionStart 注入去掉 `File Lessons` / `Key Context` 两节，`[mem] Related memories` 去掉 lesson 后缀，MCP server instructions 去掉 `WHEN TO USE` / `Decision rules` 两段。ID 与 `Recent` 表仍保留，`mem_get(ids=[…])` 可继续展开细节。适用于启用了 invited-memory adopt 流程或偏好最小化自动注入的用户。**v2.82.0 起此 env 不再阻挡 auto-adopt——如需关闭 auto-adopt 用 `MEM_NO_AUTO_ADOPT=1`。** | _(禁用)_ |
 | `MEM_NO_AUTO_ADOPT` | auto-adopt 全局关闭开关（v2.82.0+）。设为 `1` 阻止每次 SessionStart 在**所有**项目自动写入 `CLAUDE.md` 托管块。项目级关闭走 `claude-mem-lite adopt --disable`（写 `<memdir>/.mem-no-auto-adopt` 哨兵，存活于 marker 删除）。 | _(禁用)_ |
 | `MEM_NO_ADOPT_HINT` | 静音当前项目未 adopt 时 SessionStart 追加的那一行 "Invited-memory 未启用…" 提示。v2.82.1 起任何安装路径每次 SessionStart 都自动 adopt，所以该提示一般只在你显式 opt out（`MEM_NO_AUTO_ADOPT=1` 或 `claude-mem-lite adopt --disable`）的项目才会出现。 | _(禁用)_ |
+| `CLAUDE_MEM_REGISTRY_CONFINE` | 设为 `off` 允许 registry enrich 读取 `local_path` 位于托管数据目录之外的资源。**默认开启。** enrich 会读取 `resources.local_path` 指向的文件并发给 LLM；此前这道路径限制只接在四条读取路径中的一条（`mem_registry(action="enrich")`）上，`enrich <name>`、`enrich --all` 和 `import --enrich` 三条都是裸读。现在四条同门。仅当你确实把资源注册在 `CLAUDE_MEM_DIR` 之外并希望对其 enrich 时才关闭；只有精确值 `off` 会关闭它，拼错则守卫保持开启。 | _(开启)_ |
 
 ## 许可证
 

package/claudemd.mjs

@@ -16,7 +16,8 @@
 //
 // See docs/CLAUDE-MD-STEERING-PLAN.md for rationale + migration.
 
-import { readFileSync, writeFileSync, existsSync, renameSync, unlinkSync, mkdirSync, rmdirSync, readdirSync } from 'fs';
+import { readFileSync, existsSync, unlinkSync, mkdirSync, rmdirSync, readdirSync } from 'fs';
+import { atomicWriteFileSync as atomicWrite } from './lib/atomic-write.mjs';
 import { join } from 'path';
 import { createHash } from 'crypto';
 import { memdirPath, removePluginSection, removePluginDoc, isAdopted as memdirIsAdopted } from './memdir.mjs';
@@ -54,11 +55,13 @@ function renderBlock(slug, version, body) {
 
 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);
-}
+// `atomicWriteFileSync`, not a local temp+rename (audit 2026-09-02 P0-5). The local twin
+// renamed onto the PATH; when a project's CLAUDE.md is a symlink into a dotfiles repo
+// (chezmoi/stow/yadm) or a monorepo's shared root, that REPLACES the link with a regular
+// file — silently, on the first SessionStart, with no user-visible signal beyond a git
+// typechange. The shared writer lstats first and writes THROUGH to the real target. It has
+// been in this repo, shipped and used by install.mjs for ~/.claude/settings.json, since the
+// day that failure mode was first written down in its own docblock.
 
 function writeState(cwd, slug, state) {
   const dir = dotClaudeDir(cwd);

package/hash-utils.mjs

@@ -68,6 +68,18 @@ export function estimateJaccardFromMinHash(sig1, sig2) {
   if (sig1.length !== sig2.length) return 0;
   const numHashes = sig1.length / 8;
   if (numHashes === 0) return 0;
+  // NEGATIVE RESULT, kept so nobody re-proposes it (audit 2026-09-02 P2-13 suggested an
+  // "allocation-free comparison"). `slice()` does allocate two 8-char strings per band, and
+  // the caller is a full nested pair loop — ~125k pairs at the 500-row scan bound. A
+  // charCodeAt inner loop was written and measured against this form over all 124,750 pairs
+  // of a 500-title fixture: identical results (0 mismatches, so the rewrite was correct) and
+  // NO time difference — 0.77× / 1.08× / 1.03× across three passes, i.e. the first pass was
+  // slower and the rest were noise. V8 handles short slices well enough that the byte loop
+  // buys nothing, and the whole pass is 0.6 ms.
+  //
+  // So the slice form stays: it is the more readable of two equally fast implementations,
+  // and shipping the other would be churn with a performance claim behind it that the
+  // measurement does not support.
   let matches = 0;
   for (let i = 0; i < numHashes; i++) {
     const offset = i * 8;

package/hook-context.mjs

@@ -6,7 +6,8 @@
 // Handles adaptive time windows, token-budgeted selection, and legacy CLAUDE.md cleanup.
 
 import { basename, join } from 'path';
-import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { atomicWriteFileSync } from './lib/atomic-write.mjs';
 import {
   estimateTokens, truncate, typeIcon, fmtTime, inferProject,
   debugLog, neutralizeContextDelimiters,
@@ -351,16 +352,16 @@ export function cleanupClaudeMdLegacyBlock() {
 
   if (normalized === content) { dropMarker(); return; }
 
-  // Per-pid temp suffix so two concurrent first-run SessionStarts in the same
-  // project (e.g. two terminals) can't rename each other's half-written temp
-  // onto the user's tracked CLAUDE.md. Matches the idiom in hook-shared.mjs.
-  const tmp = claudeMdPath + `.mem-tmp-${process.pid}`;
+  // atomicWriteFileSync keeps the per-pid temp (two concurrent first-run SessionStarts in
+  // one project must not rename each other's half-written temp onto the user's tracked
+  // CLAUDE.md) AND adds the lstat the local twin lacked: renaming onto a symlink NAME
+  // replaces the link with a regular file, orphaning a dotfiles-managed CLAUDE.md
+  // (audit 2026-09-02 P0-5). Its temp lands beside the RESOLVED target, so the rename
+  // stays same-device even when the real file lives on another mount.
   try {
-    writeFileSync(tmp, normalized);
-    renameSync(tmp, claudeMdPath);
+    atomicWriteFileSync(claudeMdPath, normalized);
     dropMarker();
   } catch (e) {
-    try { unlinkSync(tmp); } catch {}
     debugLog('ERROR', 'cleanupClaudeMdLegacyBlock', `CLAUDE.md write failed: ${e.message}`);
     // Intentionally do NOT drop the marker on write failure — retry next session.
   }

package/hook-llm.mjs

@@ -1,8 +1,8 @@
 // claude-mem-lite: Background LLM workers for episode extraction and session summaries
 // Extracted from hook.mjs for testability and reduced complexity
 
-import { basename } from 'path';
-import { existsSync, readFileSync, unlinkSync, readdirSync } from 'fs';
+import { basename, join } from 'path';
+import { existsSync, readFileSync, unlinkSync, readdirSync, statSync } from 'fs';
 import {
   jaccardSimilarity, truncate, clampImportance, computeRuleImportance,
   inferProject, parseJsonFromLLM, scrubSecrets,
@@ -12,11 +12,11 @@ import {
 import { acquireLLMSlot, releaseLLMSlot } from './hook-semaphore.mjs';
 import { BG_LLM_TIMEOUT_MS } from './haiku-client.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
-import { getVocabulary, computeVector, vecTextForRow } from './tfidf.mjs';
-import { insertObservationRow, insertObservationFiles, insertObservationVector, normalizeScope, SCOPE_PROMPT_LEGEND } from './lib/observation-write.mjs';
+import { vecTextForRow } from './tfidf.mjs';
+import { insertObservationRow, insertObservationFiles, insertObservationVector, upsertObservationVector, normalizeScope, SCOPE_PROMPT_LEGEND } from './lib/observation-write.mjs';
 import { DEDUP_JACCARD_THRESHOLD, AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import {
-  RUNTIME_DIR, DEDUP_WINDOW_MS, RELATED_OBS_WINDOW_MS,
+  RUNTIME_DIR, DEDUP_WINDOW_MS, RELATED_OBS_WINDOW_MS, ORPHAN_EPISODE_AGE_MS,
   sessionFile, getSessionId, openDb, callLLM, sleep,
 } from './hook-shared.mjs';
 import { EVENT_TYPES, saveEvent } from './lib/activity.mjs';
@@ -26,6 +26,47 @@ import { OBS_TYPE_SET } from './lib/obs-types.mjs';
 
 import { DAY_MS } from './lib/time-constants.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
+import { recoverChildrenOf } from './lib/maintain-core.mjs';
+
+/**
+ * Retract a pre-saved observation this worker created moments ago, after the Haiku
+ * round-trip decided the row is not worth keeping.
+ *
+ * Three call sites used to be three DELETEs and only ONE of them had the guard (audit
+ * 2026-09-02 P0-6). Seconds pass between the pre-save and the LLM verdict, and in that
+ * window auto-dedup or `save --supersedes` can make the row a keeper or a tombstone:
+ *   - not live  -> not ours to hard-delete any more (a keeper may have absorbed it, and
+ *                  children can point at it through compressed_into). Leave it; the
+ *                  maintenance path deletes with recovery.
+ *   - live      -> still recover any children FIRST, the same order lib/delete-core.mjs
+ *                  uses, so nothing dangles behind a now-missing parent.
+ * Exported for a direct test only (no importer in production). Same call as `inertMarkerIds`
+ * in lib/patha-exclude-meter.mjs: the rule it encodes is one a review just caught missing on
+ * two of three sites, so it gets a test of its own rather than being reachable only through
+ * two mocked LLM workers.
+ * @returns {boolean} true when the row was actually removed
+ */
+export function retractPreSavedObs(db, obsId, where) {
+  // Liveness is checked BEFORE the recovery, not folded into the DELETE's WHERE. A first
+  // cut ran recoverChildrenOf unconditionally and let the guard live only on the DELETE:
+  // on the not-live branch the DELETE was then a no-op while the children had already been
+  // un-hidden, so a dedup that had legitimately folded #M into #N was silently undone and
+  // the debug line still said the row was "left in place" (true of #N, false of #M).
+  // Both statements run in one transaction so a crash between them cannot leave that state
+  // either; nesting under persistHaikuSummary's transaction is safe (better-sqlite3 uses
+  // savepoints).
+  return db.transaction(() => {
+    const live = db.prepare(
+      `SELECT 1 FROM observations WHERE id = ? AND ${liveObsFilterSql('')}`,
+    ).get(obsId);
+    if (!live) {
+      debugLog('DEBUG', 'llm-episode', `${where}: pre-saved obs #${obsId} no longer live — left in place`);
+      return false;
+    }
+    recoverChildrenOf(db, [obsId]);
+    return db.prepare('DELETE FROM observations WHERE id = ?').run(obsId).changes > 0;
+  })();
+}
 // T9: memdir-incompatible types live in the `events` table, not `observations`.
 // Set lookup is O(1) — authoritative source is lib/activity.mjs::EVENT_TYPES.
 const EVENT_TYPE_SET = new Set(EVENT_TYPES);
@@ -358,18 +399,10 @@ export function persistHaikuSummary(db, summary, ctx) {
 
     if (ctx.preSavedObsId) {
       const id = db.transaction(() => {
-        // Same live-row guard as the in-place upgrade (FLOW-7). If auto-dedup superseded
-        // or compressed the pre-saved row while this worker was in flight, that row is no
-        // longer ours to hard-delete — a keeper may have absorbed it, and children can
-        // point at it through compressed_into. Leave it to the maintenance path, which
-        // recovers children before deleting; the event still gets written either way.
-        const removed = db.prepare(
-          `DELETE FROM observations WHERE id = ? AND ${liveObsFilterSql('')}`,
-        ).run(ctx.preSavedObsId).changes;
-        if (removed === 0) {
-          debugLog('DEBUG', 'llm-episode',
-            `upgrade-delete: pre-saved obs #${ctx.preSavedObsId} no longer live — left in place`);
-        }
+        // Same live-row guard as the in-place upgrade (FLOW-7); the event gets written
+        // either way. Shared helper since audit 2026-09-02 P0-6 — this was the only one
+        // of the three retraction sites that carried the guard.
+        retractPreSavedObs(db, ctx.preSavedObsId, 'upgrade-delete');
         return insertEvent();
       })();
       return { table: 'events', id };
@@ -846,7 +879,7 @@ ${actionList}`;
         if (episode.savedId) {
           const ddb = openDb();
           if (ddb) {
-            try { ddb.prepare('DELETE FROM observations WHERE id = ?').run(episode.savedId); }
+            try { retractPreSavedObs(ddb, episode.savedId, 'low-value-discard'); }
             finally { ddb.close(); }
           }
         }
@@ -971,7 +1004,7 @@ ${actionList}`;
         if (episode.savedId) {
           const ddb = openDb();
           if (ddb) {
-            try { ddb.prepare('DELETE FROM observations WHERE id = ?').run(episode.savedId); }
+            try { retractPreSavedObs(ddb, episode.savedId, 'low-yield-change-drop'); }
             finally { ddb.close(); }
           }
         }
@@ -1076,18 +1109,13 @@ ${actionList}`;
           savedTable = 'observations';
           debugLog('DEBUG', 'llm-episode', `upgraded pre-saved obs #${savedId}`);
 
-          // Update TF-IDF vector with enriched content
-          try {
-            const vocab = getVocabulary(db);
-            if (vocab) {
-              const vecText = vecTextForRow({ title: obs.title, narrative: obs.narrative, concepts: conceptsText, lesson_learned: safe.lesson_learned, search_aliases: safe.search_aliases });
-              const vec = computeVector(vecText, vocab);
-              if (vec) {
-                db.prepare('INSERT OR REPLACE INTO observation_vectors (observation_id, vector, vocab_version, created_at_epoch) VALUES (?, ?, ?, ?)')
-                  .run(savedId, Buffer.from(vec.buffer), vocab.version, Date.now());
-              }
-            }
-          } catch (e) { debugCatch(e, 'handleLLMEpisode-vector'); }
+          // Update TF-IDF vector with enriched content. SQL + text derivation are
+          // lib/observation-write.mjs's (audit 2026-09-02 P1-4); `gate: false` keeps this
+          // path's prior behaviour, which never consulted vectorsEnabled().
+          upsertObservationVector(db, savedId, {
+            title: obs.title, narrative: obs.narrative, concepts: conceptsText,
+            lesson_learned: safe.lesson_learned, search_aliases: safe.search_aliases,
+          }, { gate: false, scope: 'handleLLMEpisode-vector' });
         }
       }
     } else {
@@ -1119,13 +1147,44 @@ ${actionList}`;
 export async function handleLLMSummary() {
   const parsed = parseInt(process.env.CLAUDE_MEM_FLUSH_TIMEOUT, 10);
   const flushTimeout = Number.isNaN(parsed) ? 15 : parsed;
-  for (let i = 0; i < flushTimeout; i++) {
-    try {
-      const files = readdirSync(RUNTIME_DIR).filter(f => f.startsWith('ep-flush-'));
-      if (files.length === 0) break;
-    } catch { break; }
-    debugLog('DEBUG', 'llm-summary', `waiting for flush files (${i + 1}/15)`);
+
+  // Wait for a DEFINED SET of flush files, not for "the directory is empty" (audit
+  // 2026-09-02 P1-7). RUNTIME_DIR is shared by every project on the machine, and the old
+  // predicate was `readdirSync(RUNTIME_DIR).some(f => f.startsWith('ep-flush-'))` — so:
+  //
+  //   • ONE crashed llm-episode worker leaves a file nothing will ever delete, and from
+  //     then on EVERY project's summary burns the full 15 s on every Stop until the next
+  //     maintain run sweeps it. Orphan cleanup lives behind a 24 h gate, so "until then"
+  //     is up to a day.
+  //   • A flush spawned by an unrelated project WHILE this summary is waiting extends the
+  //     wait, for work this summary will never read.
+  //
+  // The set is snapshotted at entry and filtered to files young enough to belong to a live
+  // worker. A file that appears after this point is somebody else's; a file older than
+  // ORPHAN_EPISODE_AGE_MS is nobody's. Both were previously indistinguishable from work in
+  // progress.
+  //
+  // Not narrowed to this project: the flush filename is `ep-flush-<ts>-<rand>.json` and
+  // carries no project. Widening it is a marker-format change with in-flight files during
+  // an upgrade, and the two filters above already remove the unbounded cases — what is left
+  // is a bounded overlap with genuinely concurrent work.
+  let pending;
+  try {
+    const cutoff = Date.now() - ORPHAN_EPISODE_AGE_MS;
+    pending = readdirSync(RUNTIME_DIR)
+      .filter((f) => f.startsWith('ep-flush-'))
+      .filter((f) => {
+        try { return statSync(join(RUNTIME_DIR, f)).mtimeMs >= cutoff; } catch { return false; }
+      });
+  } catch { pending = []; }
+
+  for (let i = 0; i < flushTimeout && pending.length > 0; i++) {
     await sleep(1000);
+    pending = pending.filter((f) => existsSync(join(RUNTIME_DIR, f)));
+    debugLog('DEBUG', 'llm-summary', `waiting for ${pending.length} flush file(s) (${i + 1}/${flushTimeout})`);
+  }
+  if (pending.length > 0) {
+    debugLog('DEBUG', 'llm-summary', `gave up waiting on ${pending.length} flush file(s) after ${flushTimeout}s: ${pending.join(', ')}`);
   }
 
   const db = openDb();

package/hook-optimize.mjs

@@ -16,15 +16,18 @@ import {
 import { callModelJSONAsync, BG_LLM_TIMEOUT_MS } from './haiku-client.mjs';
 import { acquireLLMSlot, releaseLLMSlot } from './hook-semaphore.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
-import { getVocabulary, computeVector, cosineSimilarity, vecTextForRow } from './tfidf.mjs';
+import { getVocabulary, computeVector, cosineSimilarity } from './tfidf.mjs';
 import { MERGE_JACCARD_LOW, AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { DB_DIR } from './schema.mjs';
 import { OBS_TYPE_SET } from './lib/obs-types.mjs';
-import { normalizeScope, SCOPE_PROMPT_LEGEND } from './lib/observation-write.mjs';
+import { normalizeScope, SCOPE_PROMPT_LEGEND, upsertObservationVector } from './lib/observation-write.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
+import { resolveRuntimeDir } from './lib/resolve-data-dir.mjs';
 
 import { DAY_MS } from './lib/time-constants.mjs';
-const RUNTIME_DIR = join(DB_DIR, 'runtime');
+// P1-14: same resolver as hook-shared.mjs — this was the second module that had never
+// heard of CLAUDE_MEM_RUNTIME_DIR, and a third hand-written copy of the join().
+const RUNTIME_DIR = resolveRuntimeDir(DB_DIR);
 
 // ─── Budget ─────────────────────────────────────────────────────────────────
 
@@ -49,30 +52,22 @@ export function distributeBudget(total = 15) {
 
 /**
  * Rebuild TF-IDF vector for an observation. Non-critical — swallows errors.
- * Exported for testing; also kept as the single source of vector-rebuild logic
- * for the optimize / re-enrich path to avoid drift with the hook-llm write path.
+ *
+ * The SQL, the text derivation and the vocab lookup are lib/observation-write.mjs's since
+ * audit 2026-09-02 P1-4; this is the optimize path's name for it. Accepts a legacy [parts]
+ * array OR an observation row (preferred — vecTextForRow gives the same field set the save
+ * path uses, so a rebuild matches the original write).
+ *
+ * `gate: false` preserves this path's behaviour exactly: it never checked
+ * `vectorsEnabled()`. That is a redundancy rather than a hole — `getVocabulary` returns
+ * null whenever the arm is off — but this refactor is not the place to decide it.
+ *
+ * The historical drift worth remembering: this copy wrote the column as `computed_at`
+ * instead of `created_at_epoch`, and its own catch swallowed the error until an experiment
+ * surfaced it. That is what a fifth copy of a statement buys.
  */
 export function rebuildVector(db, obsId, textPartsOrRow) {
-  try {
-    const vocab = getVocabulary(db);
-    if (!vocab) return;
-    // Accept a legacy [parts] array OR an observation row (preferred — single-source field set
-    // incl. lesson_learned/search_aliases via vecTextForRow, so rebuilds match the save path).
-    const text = Array.isArray(textPartsOrRow)
-      ? textPartsOrRow.filter(Boolean).join(' ')
-      : vecTextForRow(textPartsOrRow);
-    const vec = computeVector(text, vocab);
-    if (vec) {
-      // Bug #1 fix: column is `created_at_epoch`, not `computed_at`. Every other
-      // INSERT callsite (server.mjs, hook-llm.mjs, mem-cli.mjs) uses the correct
-      // name; this was the only drift, silently caught by the catch below until
-      // the R-7 experiment surfaced it.
-      db.prepare(`
-        INSERT OR REPLACE INTO observation_vectors (observation_id, vector, vocab_version, created_at_epoch)
-        VALUES (?, ?, ?, ?)
-      `).run(obsId, Buffer.from(vec.buffer), vocab.version, Date.now());
-    }
-  } catch (e) { debugCatch(e, 'optimize-vector'); }
+  upsertObservationVector(db, obsId, textPartsOrRow, { gate: false, scope: 'optimize-vector' });
 }
 
 // ─── Task 1: Re-enrich ─────────────────────────────────────────────────────
@@ -676,7 +671,19 @@ Return ONLY valid JSON:
       text: textField,
       lesson_learned: lessonLearned,
     });
-    db.transaction(() => {
+    const mergeApplied = db.transaction(() => {
+      // Re-check the keeper's liveness INSIDE the transaction (audit 2026-09-02 P0-3).
+      // findMergeCandidates selected live rows, but a Sonnet round-trip sits between that
+      // SELECT and this write (:617, BG_LLM_TIMEOUT_MS), and a concurrent SessionStart
+      // auto-dedup or `save --supersedes` can tombstone the keeper in that window. Pointing
+      // the other members at a tombstoned keeper is precisely the "buried behind a hidden
+      // parent" loss that mergeDuplicates' docblock enumerates (lib/maintain-core.mjs), and
+      // it is what that function's own isLive gate exists to prevent. Same predicate here.
+      const keeperLive = db.prepare(
+        `SELECT 1 FROM observations WHERE id = ? AND ${liveObsFilterSql('')}`
+      ).get(keeper.id);
+      if (!keeperLive) return false;
+
       // Snapshot the keeper's pre-merge row BEFORE overwriting it, so its original
       // full text survives as a recoverable compressed_into child (mirroring
       // compressGroup / recoverChildrenOf). The keeper is the cluster's most-
@@ -701,9 +708,16 @@ Return ONLY valid JSON:
 
       const otherIds = others.map(o => o.id);
       const ph = otherIds.map(() => '?').join(',');
-      db.prepare(`UPDATE observations SET compressed_into = ? WHERE id IN (${ph})`)
+      // Live guard on the members too: one already compressed into ANOTHER summary S during
+      // the LLM window would be re-pointed here, silently dropping a row out of S's child set.
+      db.prepare(`UPDATE observations SET compressed_into = ? WHERE id IN (${ph}) AND ${liveObsFilterSql('')}`)
         .run(keeper.id, ...otherIds);
+      return true;
     })();
+    if (!mergeApplied) {
+      debugLog('DEBUG', 'llm-optimize', `cluster-merge aborted: keeper #${keeper.id} no longer live`);
+      return { merged: false };
+    }
 
     rebuildVector(db, keeper.id, { title, narrative, concepts: conceptsText, lesson_learned: lessonLearned, search_aliases: keeper.search_aliases });
 
@@ -741,7 +755,11 @@ export function findSmartCompressCandidates(db, ageDays = 30, { project } = {})
   const stmt = db.prepare(`
     SELECT id, title, narrative, lesson_learned, project, type, created_at_epoch
     FROM observations
-    WHERE COALESCE(compressed_into, 0) = 0
+    -- liveObsFilterSql, not compressed_into alone (audit 2026-09-02 P0-3): auto-dedup losers
+    -- carry superseded_at with compressed_into=0 and match this predicate exactly (imp=1,
+    -- access 0, no lesson), so the narrower filter fed RETRACTED text to Sonnet and returned
+    -- it to live retrieval as a fresh "discovery" summary. Parity with findMergeCandidates.
+    WHERE ${liveObsFilterSql('')}
       AND COALESCE(importance, 1) = 1
       AND COALESCE(access_count, 0) = 0
       -- Never auto-compress a lesson-bearing row. Smart-compress sets compressed_into
@@ -903,7 +921,11 @@ JSON: {"title":"descriptive summary ≤120 chars","narrative":"comprehensive sum
 
       const obsIds = observations.map(o => o.id);
       const ph = obsIds.map(() => '?').join(',');
-      db.prepare(`UPDATE observations SET compressed_into = ? WHERE id IN (${ph})`)
+      // Live guard (audit 2026-09-02 P0-3): the candidate SELECT is separated from this write
+      // by a Sonnet round-trip, so a member may already be compressed into another summary or
+      // tombstoned. Re-pointing it here would silently remove a row from that summary's child
+      // set. Members that lost liveness stay where they are; the summary still lands.
+      db.prepare(`UPDATE observations SET compressed_into = ? WHERE id IN (${ph}) AND ${liveObsFilterSql('')}`)
         .run(sId, ...obsIds);
 
       return sId;

package/hook-shared.mjs

@@ -6,7 +6,9 @@ import { randomUUID } from 'crypto';
 import { join } from 'path';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, readdirSync, statSync, unlinkSync, chmodSync } from 'fs';
 import { inferProject, debugCatch } from './utils.mjs';
+import { CITE_RECALL_FILE_PREFIX } from './lib/cite-recall-path.mjs';
 import { ensureDbWithWalRecovery, DB_DIR } from './schema.mjs';
+import { resolveRuntimeDir } from './lib/resolve-data-dir.mjs';
 // Pure-`node:`/local module (it imports only binding-probe + native-binding-hint, and
 // neither imports this file) — no cycle.
 import { recordHookError } from './lib/hook-telemetry.mjs';
@@ -21,7 +23,11 @@ import { PLUGIN_SLUG as _PLUGIN_SLUG } from './adopt-content.mjs';
 import { DAY_MS } from './lib/time-constants.mjs';
 // ─── Constants ────────────────────────────────────────────────────────────────
 
-export const RUNTIME_DIR = join(DB_DIR, 'runtime');
+// P1-14: one resolver, so this module honours CLAUDE_MEM_RUNTIME_DIR like the five
+// standalone hook scripts already did. It did not, and hook.mjs / server.mjs /
+// hook-context.mjs / hook-episode.mjs all take RUNTIME_DIR from here — so the override
+// split the runtime dir in half instead of relocating it.
+export const RUNTIME_DIR = resolveRuntimeDir(DB_DIR);
 export const SCRIPT_PATH = process.argv[1];
 
 // Timing constants
@@ -104,18 +110,53 @@ export const ORPHAN_EPISODE_AGE_MS = 60 * 60 * 1000;
 // stale to any current episode) while leaving every active session's file untouched.
 export const ORPHAN_READS_AGE_MS = 24 * 60 * 60 * 1000;
 
-// Sweep stale `ep-flush-*` / `pending-*` (older than `ageMs`, default 1h) and
-// `reads-*.txt` (older than `readsAgeMs`, default 24h) files in `runtimeDir` by
-// mtime. Returns the number of files removed. fs-only — no DB / no network. Used by
+// `ep-<project>.json` — the LIVE episode buffer, one file per project — had no reclamation
+// path at all: it is excluded from both marker-GC lists below (correctly: it holds unflushed
+// observations, not cache) and `sweepOrphanEpisodeFiles` only ever matched `ep-flush-`.
+// A real install on 2026-09-02 held four of them for projects deleted months earlier, the
+// oldest 53 days (`ep-tmp--loop-testing-e2e.*.json`, 07-11).
+//
+// Leaving them is not neutral. `readEpisode` has no staleness gate, so `handleSessionStart`
+// unconditionally flushes whatever it finds (hook.mjs "Flush any leftover episode buffer") —
+// revisiting such a project injects months-old tool activity into today's memory stamped
+// with today's date. The stale buffer is not preserved data, it is data that will be
+// mis-dated the moment anyone touches the project again.
+//
+// 7 days, and the argument is that no LEGITIMATE state needs a buffer to live even one day:
+// `EPISODE_TIME_GAP_MS` is 5 min and `SESSION_EXPIRY_MS` is 12 h, so a buffer untouched for
+// 7 days outlived its owning session by an order of magnitude. The margin over 12 h is
+// deliberate slack for a laptop suspended across a long weekend, not a second threshold with
+// its own meaning. Considered and rejected: flushing on sweep instead of deleting — it would
+// re-date the content exactly the way the revisit path does, i.e. commit the defect on
+// purpose rather than by omission.
+//
+// Exported as of the pre-tag review for v3.92.0, on this constant's own stated rule ("export
+// it the day something needs it"): the sweep alone does NOT close the harm described above.
+// `handleSessionStart` flushes the leftover buffer in the FOREGROUND, and the sweeper runs
+// later, in a detached auto-maintain worker — so on the revisit itself the mis-dated flush
+// happens first and the sweeper then finds nothing. What the sweep delivers is dir-wide
+// reclamation of OTHER projects' abandoned buffers; the same-project revisit needs the same
+// threshold applied at the flush, which is `hook.mjs`'s importer of this symbol.
+// `bufferAgeMs` stays a parameter so a test can pin the sweep threshold without an import.
+export const STALE_EPISODE_BUFFER_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+// Sweep stale `ep-flush-*` / `pending-*` (older than `ageMs`, default 1h),
+// `reads-*.txt` (older than `readsAgeMs`, default 24h) and abandoned per-project episode
+// buffers `ep-<project>.json` (older than `bufferAgeMs`, default 7d) in `runtimeDir` by
+// mtime. `onSweep(name, kind)` is called before each unlink so a caller can log the one
+// deletion that discards content rather than residue ('buffer'); it is a callback rather
+// than a debugLog here because this module is imported by every hook entry point and stays
+// dependency-free. Returns the number of files removed. fs-only — no DB / no network. Used by
 // handleSessionStart auto-maintain to prevent the doctor "Stale temp files" warning
 // from accumulating across crashes; equivalent to the manual path in
 // `node install.mjs cleanup` but age-gated so concurrent in-flight workers / active
 // read sessions are never raced.
-export function sweepOrphanEpisodeFiles(runtimeDir, { ageMs = ORPHAN_EPISODE_AGE_MS, readsAgeMs = ORPHAN_READS_AGE_MS, now = Date.now() } = {}) {
+export function sweepOrphanEpisodeFiles(runtimeDir, { ageMs = ORPHAN_EPISODE_AGE_MS, readsAgeMs = ORPHAN_READS_AGE_MS, bufferAgeMs = STALE_EPISODE_BUFFER_AGE_MS, now = Date.now(), onSweep = () => {} } = {}) {
   let entries;
   try { entries = readdirSync(runtimeDir); } catch { return 0; }
   const cutoff = now - ageMs;
   const readsCutoff = now - readsAgeMs;
+  const bufferCutoff = now - bufferAgeMs;
   let count = 0;
   for (const f of entries) {
     // Crash residue: this runtime dir writes four families of temp name, each the middle
@@ -139,15 +180,22 @@ export function sweepOrphanEpisodeFiles(runtimeDir, { ageMs = ORPHAN_EPISODE_AGE
     const isCrashResidue = /\.(claim|collect|trim|tmp)-[^.]*$/.test(f);
     const isEpisode = f.startsWith('ep-flush-') || f.startsWith('pending-');
     const isReads = f.startsWith('reads-') && f.endsWith('.txt');
-    if (!isCrashResidue && !isEpisode && !isReads) continue;
+    // The live per-project buffer, on its own 7-day cutoff. `ep-flush-*` is also `ep-`-
+    // prefixed AND also ends in `.json`, so the exclusion is load-bearing, not defensive:
+    // without it a queued flush file would jump from the 1h cutoff to the 7d one.
+    const isStaleBuffer = f.startsWith('ep-') && !f.startsWith('ep-flush-') && f.endsWith('.json');
+    if (!isCrashResidue && !isEpisode && !isReads && !isStaleBuffer) continue;
     const full = join(runtimeDir, f);
     try {
       // Residue takes the short cutoff and a live tracker takes the 24h one, with no
       // tie-break needed: residue always APPENDS its suffix, so it never ends in `.txt`
       // and `isReads` is already false for it. (A `&& !isCrashResidue` tie-break was
       // written here first and no mutation could kill it — it was guarding a state the
-      // two predicates cannot both be in.)
-      if (statSync(full).mtimeMs < (isReads ? readsCutoff : cutoff)) {
+      // two predicates cannot both be in.) `isStaleBuffer` is in the same position: a
+      // residue name ends in `.tmp-<pid>`, never `.json`.
+      const fileCutoff = isReads ? readsCutoff : isStaleBuffer ? bufferCutoff : cutoff;
+      if (statSync(full).mtimeMs < fileCutoff) {
+        try { onSweep(f, isStaleBuffer ? 'buffer' : isReads ? 'reads' : isCrashResidue ? 'residue' : 'episode'); } catch { /* logging must never block the sweep */ }
         unlinkSync(full);
         count++;
       }
@@ -177,15 +225,17 @@ export const STALE_PROJECT_MARKER_AGE_MS = 30 * 24 * 60 * 60 * 1000;
 // Regenerated on demand; safe to lose at any time.
 export const GC_PROJECT_MARKER_PREFIXES = Object.freeze([
   'session-',                 // project → memory-session-id pointer
-  'cite-recall-',             // last session's cite-recall snapshot (nudge input)
+  CITE_RECALL_FILE_PREFIX,    // last session's cite-recall snapshot (nudge input)
   '.skill-cooldown-',         // suggestion throttle timestamp
   '.skill-reco-cooldown-',    // recommendation throttle timestamp
 ]);
 
 // Records of a completed side effect — never age out. `ep-`/`ep-flush-`/
-// `pending-`/`reads-` are absent from BOTH lists on purpose: the first holds
-// unflushed observations (data, not cache) and the rest already belong to
-// sweepOrphanEpisodeFiles on tighter cutoffs.
+// `pending-`/`reads-` are absent from BOTH lists on purpose: they all belong to
+// sweepOrphanEpisodeFiles, on three cutoffs of their own (1h residue / 24h reads /
+// 7d abandoned buffer). `ep-<project>.json` was the one with no cutoff at all until
+// audit P1-12 — it is still not marker-GC-able here, because 30 days of unflushed
+// observations is far past the point where flushing them would mis-date them.
 export const GC_PRESERVED_MARKER_PREFIXES = Object.freeze([
   '.auto-adopt-',
   '.deferred-block-migrated-',