claude-mem-lite 3.93.0 → 3.94.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.93.0",
+      "version": "3.94.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.93.0",
+  "version": "3.94.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

@@ -897,8 +897,9 @@ Set by the tool or by the test harness. Setting these by hand is not supported:
 
 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
+cooldowns, hook-error telemetry, the native-binding breakage marker, episode buffers.
+(`metrics/` is NOT in that set: it is a sibling of `runtime/` under the data dir and moves
+with `CLAUDE_MEM_DIR` only.) 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

package/cli/doctor.mjs

@@ -76,6 +76,7 @@ export async function cmdDoctor(db, args) {
       out(`  id_mix_other (fixture-style equality, info-only):  ${audit.id_mix_other}`);
       out(`  missing_mem_id (sdk_sessions w/ NULL after 5min):  ${audit.missing_mem_id}`);
       out(`  orphan_obs (observations w/o matching session):    ${audit.orphan_obs}`);
+      out(`  obs_importance_null (NULL importance, P3-14):      ${audit.obs_importance_null}`);
       if (audit.id_mix_other > 0 && audit.id_mix_uuid_shape === 0) {
         out('\n  Notes:');
         out('    • id_mix_other > 0 with uuid_shape=0 is typically benign — usually means insertSession({id:\'X\'}) test scaffold or pre-v30 data with non-UUID equal values. Does NOT drive failure.');
@@ -85,6 +86,7 @@ export async function cmdDoctor(db, args) {
         if (audit.id_mix_uuid_shape > 0) out('    • id_mix_uuid_shape > 0 — production v2.33.1 bug-pattern rows present. Investigate via SQL: SELECT * FROM sdk_sessions WHERE memory_session_id = content_session_id AND length(memory_session_id) = 36;');
         if (audit.missing_mem_id > 0) out('    • missing_mem_id rows are sessions whose mem-internal ID was never populated — likely SessionStart write that didn\'t reach Stop');
         if (audit.orphan_obs > 0) out('    • orphan_obs are observations referencing a sdk_sessions row that was deleted (FK CASCADE failed historically before v28)');
+        if (audit.obs_importance_null > 0) out('    • obs_importance_null rows read as importance 1 by the CLI/hook maintenance pass (COALESCE) and as "skip" by the MCP idle pass (bare `importance <= 1`), so they decay on one face and not the other. New rows cannot reach this state (lib/observation-write.mjs coerces nullish to 1); these predate that or were written around it. Fix: UPDATE observations SET importance = 1 WHERE importance IS NULL;');
       }
     }
     if (!audit.healthy) process.exitCode = 1;

package/hook-update.mjs

@@ -33,7 +33,7 @@ const INSTALL_DIR = CODE_DIR;  // ~/.claude-mem-lite/ (code)
 // DB_DIR), matching hook-shared RUNTIME_DIR and install.mjs doctor's read path.
 // Equal to INSTALL_DIR unless CLAUDE_MEM_DIR relocates the data dir.
 const STATE_DIR = DB_DIR;
-const STATE_FILE = join(STATE_DIR, 'runtime', 'update-state.json');
+const STATE_FILE = join(STATE_DIR, 'runtime', 'update-state.json'); // runtime-dir:stays-put — installation identity
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;       // 24 hours
 const FETCH_TIMEOUT_MS = 3000;                         // 3s network timeout
 // When rate-limited we got NO release data, so re-check sooner than the normal 24h
@@ -641,7 +641,7 @@ export async function verifyReleaseAuthenticity(extractedDir, assets, publicKey
 // hooks are best-effort, so losing one fire beats importing a mixed module graph.
 // Carries pid + ts because the launcher must never be muted permanently by an
 // updater that was killed mid-swap (it applies the same staleness bound).
-const SWAP_MARKER = join(STATE_DIR, 'runtime', 'swap-in-progress');
+const SWAP_MARKER = join(STATE_DIR, 'runtime', 'swap-in-progress'); // runtime-dir:stays-put — installation identity
 // Intent journal, written INSIDE the backup dir before each rename. On a hard kill
 // the backup dir survives (every normal exit deletes it) and this file says exactly
 // which paths were in flight, so the next entry can finish the rollback at the right
@@ -781,7 +781,7 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
   // holding the lock means an install is already in flight — skip rather than
   // race. Shared path with install.mjs so direct install + repair + auto-update
   // are mutually exclusive.
-  const release = acquireLock(join(STATE_DIR, 'runtime', 'install.lock'));
+  const release = acquireLock(join(STATE_DIR, 'runtime', 'install.lock')); // runtime-dir:stays-put — install lock serialises real installers
   if (!release) {
     debugLog('DEBUG', 'hook-update', 'installExtractedRelease: another install/update is in progress — skipping');
     return false;
@@ -1115,7 +1115,7 @@ function readState() {
 
 function saveState(state) {
   try {
-    const dir = join(STATE_DIR, 'runtime');
+    const dir = join(STATE_DIR, 'runtime'); // runtime-dir:stays-put — mkdir for update-state.json above
     mkdirSync(dir, { recursive: true });
     const tmpFile = STATE_FILE + `.tmp-${process.pid}`;
     writeFileSync(tmpFile, JSON.stringify(state, null, 2));

package/install.mjs

@@ -1791,7 +1791,7 @@ async function doctor() {
 
   // Update state
   try {
-    const stateFile = join(MEM_DATA_DIR, 'runtime', 'update-state.json');
+    const stateFile = join(MEM_DATA_DIR, 'runtime', 'update-state.json'); // runtime-dir:stays-put — installation identity
     if (existsSync(stateFile)) {
       const state = JSON.parse(readFileSync(stateFile, 'utf8'));
       const parts = [];
@@ -1951,8 +1951,12 @@ async function doctor() {
   try {
     // hook-update + the episode workers write runtime/ + staging under DB_DIR
     // (= MEM_DATA_DIR, env-aware), NOT the homedir code dir — scan there so doctor
-    // sees the real residue under relocation.
-    const runtimeDir = join(MEM_DATA_DIR, 'runtime');
+    // sees the real residue under relocation. MEM_RUNTIME_DIR rather than
+    // join(MEM_DATA_DIR,'runtime'): `pending-*` / `ep-flush-*` are written through
+    // hook-shared.mjs's override-aware RUNTIME_DIR, and `cleanup()` below deletes them from
+    // MEM_RUNTIME_DIR — v3.93.0 moved the deleter and left this scanner behind, so under the
+    // override doctor reported "none" while the cleanup it recommends removed files.
+    const runtimeDir = MEM_RUNTIME_DIR;
     let staleCount = 0;
     const stalePatterns = ['.update-staging-', '.update-backup-'];
     if (existsSync(MEM_DATA_DIR)) {
@@ -2560,7 +2564,7 @@ function bindingHostDir() {
 // two concurrent rebuilds can clobber the .node mid-compile. A live peer → report
 // and exit 0 (it is doing this very work), never race it.
 async function rebuildBinding() {
-  const release = acquireLock(join(MEM_DATA_DIR, 'runtime', 'install.lock'));
+  const release = acquireLock(join(MEM_DATA_DIR, 'runtime', 'install.lock')); // runtime-dir:stays-put — install lock serialises real installers
   if (!release) {
     // NOT exit 0: skipping is not healing. Callers key their state on the exit
     // code — a false success would let the launcher drop its cooldown and the
@@ -2609,7 +2613,7 @@ async function rebuildBinding() {
 // install/self-heal) holds it → skip rather than race into a torn install. Lock
 // path is shared with hook-update.installExtractedRelease (both env-aware).
 async function runLockedInstall() {
-  const release = acquireLock(join(MEM_DATA_DIR, 'runtime', 'install.lock'));
+  const release = acquireLock(join(MEM_DATA_DIR, 'runtime', 'install.lock')); // runtime-dir:stays-put — install lock serialises real installers
   if (!release) {
     console.log('[install] Another install/repair is in progress — skipping to avoid a torn write.');
     return;

package/lib/cite-back-hint.mjs

@@ -26,6 +26,7 @@ import { citeRecallPathFor } from './cite-recall-path.mjs';
 // One caliber for `#NN`. citation-tracker.mjs does NOT import this module, so the edge
 // is acyclic.
 import { citationIdRe } from './citation-tracker.mjs';
+import { envNumber } from './env-number.mjs';
 
 const MAX_FILES = 2;
 
@@ -207,8 +208,19 @@ export const CITE_NUDGE_SILENCE_AFTER = 3;
 // enough injection volume to judge). Shared by buildCiteRecallNudge (decide to
 // nag) and nextCiteLowStreak (decide to keep silencing).
 function ratioGateFires(data, env) {
-  const threshold = Number(env.CLAUDE_MEM_CITE_NUDGE_THRESHOLD) || 0.6;
-  const minInjected = Number(env.CLAUDE_MEM_CITE_NUDGE_MIN_INJECTED) || 5;
+  // `Number(x) || d` was NaN-safe but swallowed an explicit 0, and 0 is meaningful
+  // on BOTH knobs: threshold 0 means "never nag on ratio", min-injected 0 means "no
+  // volume requirement". Neither was reachable through the env before.
+  const threshold = envNumber(env.CLAUDE_MEM_CITE_NUDGE_THRESHOLD,
+    { name: 'CLAUDE_MEM_CITE_NUDGE_THRESHOLD', defaultValue: 0.6, min: 0, max: 1 });
+  // No `integer: true` here or on SILENCE_AFTER, deliberately. Both are consumed with
+  // `>=` against an integer counter, so a fractional bound works and `2.5` was a usable
+  // setting before this release; rejecting it would silently swap a working value for the
+  // default. `max: 1` on THRESHOLD is different and stays: `ratio` is
+  // recalled/injected.size and cannot exceed 1, so a bound there is the domain, not a
+  // preference. Same rule as lib/relevance-floor.mjs — read the bound off the consumer.
+  const minInjected = envNumber(env.CLAUDE_MEM_CITE_NUDGE_MIN_INJECTED,
+    { name: 'CLAUDE_MEM_CITE_NUDGE_MIN_INJECTED', defaultValue: 5, min: 0 });
   return typeof data?.injected === 'number'
     && typeof data?.ratio === 'number'
     && data.injected >= minInjected
@@ -234,9 +246,11 @@ export function buildCiteRecallNudge(project, runtimeDir, env = process.env) {
     const path = citeRecallPathFor(runtimeDir, project);
     const raw = readFileSync(path, 'utf8');
     const data = JSON.parse(raw);
-    const silenceAfter = env.CLAUDE_MEM_CITE_NUDGE_SILENCE_AFTER !== undefined
-      ? Number(env.CLAUDE_MEM_CITE_NUDGE_SILENCE_AFTER)
-      : CITE_NUDGE_SILENCE_AFTER;
+    // Garbage here used to become NaN, and `NaN >= silenceAfter` is false — so a
+    // typo turned the self-silencing OFF, the opposite of every other knob's failure
+    // direction and the one a user would never notice. 0 stays valid ("never silence").
+    const silenceAfter = envNumber(env.CLAUDE_MEM_CITE_NUDGE_SILENCE_AFTER,
+      { name: 'CLAUDE_MEM_CITE_NUDGE_SILENCE_AFTER', defaultValue: CITE_NUDGE_SILENCE_AFTER, min: 0 });
     // silenceAfter > 0 AND the project has ignored the nag that many times running.
     const silenced = silenceAfter > 0
       && typeof data.lowStreak === 'number'

package/lib/env-number.mjs

@@ -0,0 +1,105 @@
+// Numeric environment overrides with an explicit failure mode.
+//
+// The idiom this replaces — `Number(process.env.X || DEFAULT)` — has no failure
+// mode at all: `Number('abc')` is NaN, and NaN then propagates into whatever the
+// constant feeds. Nothing throws and nothing is logged, so the surface degrades
+// SILENTLY and in a direction that depends on the consumer. Measured on the six
+// UPS knobs (2026-09-04, node probe against the shipped consumers):
+//
+//   CLAUDE_MEM_UPS_MAX_RESULTS=abc          rows.slice(0, NaN) === []
+//                                           → the whole FTS injection face goes dark
+//   CLAUDE_MEM_UPS_PROMPT_FALLBACK_LIMIT=abc  `LIMIT ?` bound with NaN
+//                                           → SqliteError: datatype mismatch
+//   CLAUDE_MEM_UPS_TOP_MIN=abc              `Math.abs(rel) < NaN` is false
+//                                           → the set-level noise floor stops firing
+//   CLAUDE_MEM_UPS_OR_BM25_MIN=abc          `orFloor > 0` is false
+//                                           → the OR-fallback floor stops firing
+//
+// So one typo either silences the face or disables the gates that keep it quiet,
+// and the two are indistinguishable from outside. `lib/cli-flags.mjs` already
+// solved the same problem for CLI flags (warn once on stderr, fall back to the
+// documented default); this is that contract for the env side.
+//
+// `Number`, not `parseInt`: the floors here are written in scientific notation
+// (1e-5, 5e-6) and `parseInt('1e-5')` is 1 — a 100000x silent misparse, i.e. the
+// exact class of defect this module exists to remove.
+
+const DEFAULT_WARN = (msg) => {
+  // stderr is safe from every hook face: the host reads a command hook's stdout as
+  // its envelope and only surfaces stderr on a failure/blocked path, so a warning
+  // here can never corrupt an injection (lib/hook-stdout.mjs).
+  try { process.stderr.write(msg); } catch { /* never block on a warning */ }
+};
+
+/**
+ * Parse a numeric env override, falling back to `defaultValue` with a stderr
+ * warning on anything that is not a finite in-range number.
+ *
+ * Unset and empty-string both mean "not configured" and fall back SILENTLY —
+ * `CLAUDE_MEM_X=` is how a shell unsets a value it inherited, not a mistake.
+ *
+ * An explicit `0` is honoured whenever the range admits it. Which idiom swallowed a 0 is
+ * worth stating precisely, because a v3.94.0 draft got it backwards in two places:
+ *
+ *   Number(env.X || D)   with X='0'  ->  0   — SAFE. `process.env.X` is a STRING and
+ *                                             `'0'` is truthy; only `''` is falsy.
+ *   Number(env.X) || D   with X='0'  ->  D   — BROKEN. Parse first, then fall back.
+ *
+ * So the knobs that were unreachable at 0 are the parse-then-fallback ones,
+ * `CLAUDE_MEM_CITE_NUDGE_THRESHOLD` and `CLAUDE_MEM_CITE_NUDGE_MIN_INJECTED`
+ * (lib/cite-back-hint.mjs), NOT the folded UPS floors.
+ *
+ * Shape is decided by `Number` + `Number.isFinite` rather than a regex: that
+ * rejects trailing garbage ('2abc'), whitespace-only, and Infinity, while
+ * accepting the scientific-notation form the callers' own defaults use.
+ *
+ * @param {string|number|undefined|null} raw Raw env value (pass `env.NAME`, not the name).
+ * @param {object} opts
+ * @param {string} opts.name Env var name, for the warning text.
+ * @param {number} opts.defaultValue Value used when unset or invalid.
+ * @param {number} [opts.min=-Infinity] Inclusive lower bound.
+ * @param {number} [opts.max=Infinity] Inclusive upper bound.
+ * @param {boolean} [opts.integer=false] Reject non-integers (e.g. row caps, SQL LIMITs).
+ * @param {(msg: string) => void} [opts.warn] Test seam — defaults to process.stderr.write.
+ * @returns {number} A finite number in [min, max], or `defaultValue`.
+ */
+export function envNumber(raw, opts) {
+  const {
+    name, defaultValue, min = -Infinity, max = Infinity, integer = false,
+    warn = DEFAULT_WARN,
+  } = opts;
+
+  if (raw === undefined || raw === null) return defaultValue;
+  const str = String(raw).trim();
+  if (str === '') return defaultValue;
+
+  const n = Number(str);
+  const ok = Number.isFinite(n)
+    && (!integer || Number.isInteger(n))
+    && n >= min && n <= max;
+
+  if (!ok) {
+    const bound = describeRange(min, max, integer);
+    warn(`[mem] Invalid ${name}="${raw}" (${bound}); using default ${defaultValue}\n`);
+    return defaultValue;
+  }
+  return n;
+}
+
+/**
+ * Human-readable statement of what the value had to be. Split out so the warning
+ * text is derived from the SAME bounds the check used — a hand-written message
+ * drifts from its predicate on the first bound change.
+ *
+ * @param {number} min
+ * @param {number} max
+ * @param {boolean} integer
+ * @returns {string}
+ */
+function describeRange(min, max, integer) {
+  const kind = integer ? 'an integer' : 'a number';
+  if (min === -Infinity && max === Infinity) return `must be ${kind}`;
+  if (max === Infinity) return `must be ${kind} >= ${min}`;
+  if (min === -Infinity) return `must be ${kind} <= ${max}`;
+  return `must be ${kind} between ${min} and ${max}`;
+}

package/lib/hook-stdin.mjs

@@ -61,7 +61,13 @@ export const TOOL_INPUT_FILE_MAX_BYTES = 8 * 1024 * 1024;
  * @returns {{filePath: string, sessionId: string|null, toolName: string|null} | null}
  */
 export function salvageTruncatedHookEvent(prefix) {
-  const fp = prefix.match(/"file_path"\s*:\s*"((?:[^"\\]|\\.)*)"/);
+  // Bounded capture. Unbounded, an 8 MB prefix whose `file_path` string is never closed
+  // makes V8 exceed its regexp backtrack limit and THROW RangeError — measured at the cap by
+  // the v3.93.0 post-release review. The throw escapes the caller's catch into its top-level
+  // one, which still exits 0 but writes a `pre-recall:top` telemetry row: the same
+  // hook-error noise the caller split `pre-recall:json` away from. 4096 is far above any
+  // real path (PATH_MAX is 4096 on Linux, 1024 on macOS), so no reachable payload is lost.
+  const fp = prefix.match(/"file_path"\s*:\s*"((?:[^"\\]|\\.){0,4096})"/);
   if (!fp) return null;
   let filePath;
   // The captured group is still JSON-escaped (Windows paths arrive as `C:\\x`).

package/lib/hook-stdout.mjs

@@ -15,14 +15,79 @@
 // flushEpisode) and shipped surfaces that emit two envelopes, or an envelope
 // plus a raw block, on one stdout. Both shapes make JSON.parse throw, so:
 //
-//   • SessionStart / UserPromptSubmit / UserPromptExpansion — the plainText is
-//     injected verbatim, so the model receives `{"suppressOutput":true,…}` as
+// There are THREE channels, not one, and each event uses a different subset. Verified
+// against the 2.1.260 bundle, 2026-09-04 (minified names are rebuilt every release —
+// match on shape, not on the identifier):
+//
+//   • UserPromptSubmit / UserPromptExpansion — plain text becomes `additionalContext`
+//     and is injected verbatim, so the model receives `{"suppressOutput":true,…}` as
 //     literal escaped text and suppressOutput is never honoured.
-//   • every other event — the renderer returns [] for plain text, so BOTH
-//     receipts are dropped in silence.
+//   • SessionStart — NOT via additionalContext (see channel 1 below), but the runner's
+//     status-0 branch also emits a `hook_success` attachment whose `content` is
+//     `stdout.trim()`, and the attachment renderer turns that into a real message for
+//     SessionStart / UserPromptSubmit / UserPromptExpansion, prefixed
+//     `<hookName> hook success: `. So a stray envelope still reaches the model here —
+//     with a prefix rather than verbatim.
+//   • PreCompact — raw stdout becomes `newCustomInstructions` for the compaction
+//     summarizer (channel 2 below).
+//   • everything else — plain text is dropped in silence.
 //
 // So contributions are queued and written once. Callers keep their own gating
 // (RECEIPT_EVENTS, significance, etc.); this only owns the writing.
+//
+// ── THE THREE CHANNELS, and what each correction cost ────────────────────────────
+//
+// The original list had TWO bullets and named SessionStart as plain-text-injecting.
+// The v3.94.0 rewrite fixed that half and broke the other: it moved SessionStart into
+// "dropped in silence", which is false via channel 3. Caught by the v3.94.0 pre-tag
+// correctness review. Both errors have the same root — reading one channel and
+// generalising — which is why the channels are now enumerated rather than summarised.
+//
+// 1. **additionalContext.** The stdout classifier (`f8e` in 2.1.260, `Hxi` in 2.1.233)
+//    turns plain text into an injectable answer for exactly two events:
+//
+//      if (status === 0) { let N = (plainText ?? "").trim();
+//        return (event === "UserPromptSubmit" || event === "UserPromptExpansion") && N !== ""
+//          ? { answer: { hookSpecificOutput: { hookEventName: event, additionalContext: N } }, … }
+//          : { answer: {}, … } }
+//
+//    SessionStart's consumer reads `additionalContexts`, which comes off that empty
+//    `answer` — so on THIS channel SessionStart really does get nothing. hook.mjs
+//    SessionStart uses an envelope, so it does not depend on the finding either way.
+//
+// 3. **hook_success attachment.** Same status-0 branch, independent of the classifier:
+//
+//      if (ts.status === 0) { let ls = await bde(ts.stdout.trim(), …);
+//        yield { message: cn({ type: "hook_success", …, content: ls, … }), … } }
+//
+//    and the renderer:
+//
+//      case "hook_success":
+//        if (e.hookEvent !== "SessionStart" && e.hookEvent !== "UserPromptSubmit"
+//            && e.hookEvent !== "UserPromptExpansion") return [];
+//        if (e.content === "") return [];
+//        return [Te({ content: Ra(`${e.hookName} hook success: ${e.content}`), isMeta: !0 })];
+//
+// 2. There is a SECOND consumption channel, and it is raw stdout. The hook runner
+//    sets `result.output = status === 0 ? stdout : stderr` — the whole stdout, JSON
+//    or not, quite apart from the parsed `answer`. `executePreCompactHooks` uses THAT:
+//
+//      let v = results.filter(r => r.succeeded && !r.blocked && r.output.trim())
+//                     .map(r => r.output.trim());
+//      return { newCustomInstructions: v.length ? v.join("\n\n") : undefined, … }
+//
+//    and `newCustomInstructions` is passed as `customInstructions` into the compaction
+//    summarizer. `grep -abo '\.newCustomInstructions'` on 2.1.260 returns SIX read
+//    sites; a draft said four, which is what comes of counting the ones a single
+//    bounded grep happened to show. So hook-precompact.mjs writing a bare
+//    `<claude-mem-context>` block to stdout is not merely allowed — it is the ONLY
+//    correct form there. Routing it through this module would deliver the literal
+//    envelope JSON to the summarizer as its instructions. tests/precompact-stdout-shape
+//    pins that, so the "consistency" refactor cannot happen by accident.
+//
+// The general rule the two corrections share: "the host drops plain text" is a claim
+// about ONE channel. Before believing it for an event, find which field that event's
+// runner actually reads.
 
 let parts = [];
 let queuedEvent = null;

package/lib/maintain-core.mjs

@@ -351,7 +351,24 @@ export function decayAndMarkIdle(db, { projectFilter, baseParams, staleAge, opCa
     UPDATE observations SET compressed_into = ${COMPRESSED_PENDING_PURGE}
     WHERE id IN (
       SELECT id FROM observations
-      WHERE COALESCE(compressed_into, 0) = 0
+      -- liveObsFilterSql, not compressed_into alone (P3-13). This statement writes the
+      -- sentinel purgeStale hard-deletes, and deleting a RETIRED row destroys its
+      -- superseded_by column -- the redirect three functions in the Stop citation loop
+      -- follow to credit a #NN naming a corrected memory to its successor
+      -- (lib/citation-tracker.mjs redirectSupersededIds). 27 of 31 superseded rows on the
+      -- maintainer's DB carry one. An explicit delete still removes a tombstone, exactly
+      -- as with the lesson guard below.
+      --
+      -- ONLY the two PENDING_PURGE writers carry this (here and
+      -- search-scoring.runIdleCleanup). The decay arm below, boostAccessed, demotePinned
+      -- and cleanupBroken deliberately keep compressed_into alone: the first three move
+      -- only importance, which is inert on a row every read path already hides, so
+      -- exempting them would be churn plus a forecast change for no behavioural
+      -- difference. maintenanceStats' stale count mirrors THIS predicate and moved with it.
+      --
+      -- NB: no backticks anywhere in this block -- it sits inside a JS template literal,
+      -- where one terminates the string. A first draft did that and node --check failed.
+      WHERE ${liveObsFilterSql('')}
         AND COALESCE(importance, 1) = 1
         AND COALESCE(access_count, 0) = 0
         AND COALESCE(injection_count, 0) = 0
@@ -618,9 +635,14 @@ export function maintenanceStats(db, { projectFilter, baseParams, staleAge }) {
       -- lesson_learned guard mirrors decayAndMarkIdle (:188) / cleanupBroken (:153): those
       -- ops NEVER touch a lesson-bearing row ("lessons never auto-GC"), so the scan preview
       -- must exclude them too or it over-forecasts "Stale"/"Broken" vs what execute does.
+      -- superseded_at IS NULL mirrors the P3-13 guard added to decayAndMarkIdle's
+      -- mark-idle pass. It belongs ONLY on the stale count: boostable and pinned forecast
+      -- ops that were deliberately left touching tombstones, and forecasting an exemption
+      -- they do not have would break this parity in the other direction.
       COALESCE(SUM(CASE WHEN COALESCE(importance, 1) = 1 AND COALESCE(access_count, 0) = 0
                     AND COALESCE(injection_count, 0) = 0
                     AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
+                    AND superseded_at IS NULL
                     AND created_at_epoch < ? THEN 1 ELSE 0 END), 0) as stale,
       COALESCE(SUM(CASE WHEN (title IS NULL OR title = '') AND (narrative IS NULL OR narrative = '')
                     AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')

package/lib/observation-write.mjs

@@ -45,6 +45,35 @@ const OBS_DEFAULTS = {
   files_read: '[]', files_modified: '[]', search_aliases: null, importance: 1,
 };
 
+/**
+ * Column-level value normalization applied by BOTH write cores (insert and update).
+ *
+ * Today it holds exactly one rule, and it is a real one (audit P3-14). `importance` is
+ * `INTEGER DEFAULT 1` but NULLABLE, and the DEFAULT only applies when the column is
+ * OMITTED from the INSERT — it never is here, because the column list is fixed. So a
+ * caller passing `importance: null`, or `importance: undefined` as an OWN property (which
+ * skips the OBS_DEFAULTS lookup above), wrote a NULL. better-sqlite3 binds both to SQL
+ * NULL and throws on neither, so nothing upstream would have caught it.
+ *
+ * A NULL there is not cosmetic: the two maintenance faces disagree about what it means.
+ * `maintain-core.decayAndMarkIdle` reads `COALESCE(importance,1) = 1` and queues the row
+ * for purge; `search-scoring.runIdleCleanup` reads a bare `importance <= 1`, which is NULL
+ * (falsy) and skips it. Aligning those two predicates was rejected — the alignment that
+ * closes the gap is the one that makes the MCP face START purging — and a NOT NULL
+ * migration means rebuilding a table that carries FTS5 triggers, for a population measured
+ * at 0 rows. Making NULL unwritable at the two shared cores costs one function and leaves
+ * both read faces exactly as they are. `doctor --session-audit` reports any row that got
+ * in by another route.
+ *
+ * @param {string} col Column name.
+ * @param {*} value Value the caller supplied (or the default).
+ * @returns {*} Value to bind.
+ */
+function normalizeObsValue(col, value) {
+  if (col === 'importance' && (value === null || value === undefined)) return OBS_DEFAULTS.importance;
+  return value;
+}
+
 /**
  * Insert one observations row from a {column: value} map and return its id.
  * Omitted columns fall back to OBS_DEFAULTS (or NULL). The column list lives only
@@ -52,8 +81,8 @@ const OBS_DEFAULTS = {
  */
 export function insertObservationRow(db, fields) {
   const values = OBS_COLUMNS.map(c =>
-    Object.prototype.hasOwnProperty.call(fields, c) ? fields[c]
-      : (c in OBS_DEFAULTS ? OBS_DEFAULTS[c] : null)
+    normalizeObsValue(c, Object.prototype.hasOwnProperty.call(fields, c) ? fields[c]
+      : (c in OBS_DEFAULTS ? OBS_DEFAULTS[c] : null))
   );
   const placeholders = OBS_COLUMNS.map(() => '?').join(', ');
   const result = db
@@ -249,7 +278,12 @@ export function applyObsUpdate(db, id, fields) {
   for (const col of UPDATABLE_OBS_COLS) {
     if (fields[col] !== undefined) {
       updates.push(`${col} = ?`);
-      params.push(typeof fields[col] === 'string' ? scrubSecrets(fields[col]) : fields[col]);
+      // Same normalization as the insert core — an update is the OTHER way a NULL
+      // importance gets into the table, and a rule applied on one write path only is the
+      // shape this repo keeps paying for. `!== undefined` above lets an explicit null
+      // through, which is exactly the case normalizeObsValue catches.
+      const v = normalizeObsValue(col, fields[col]);
+      params.push(typeof v === 'string' ? scrubSecrets(v) : v);
     }
   }
   if (updates.length === 0) return [];

package/lib/relevance-floor.mjs

@@ -15,6 +15,8 @@
 // cache-busting query string reloads the FACE, not this module, so a load-time
 // constant here would have frozen at whatever the first import saw.
 
+import { envNumber } from './env-number.mjs';
+
 // Default reference corpus. Overridable per the historical UPS env name.
 // Module-private: exported by habit in the first cut, and knip correctly flagged it —
 // this project treats a new unused export as a defect to fix, not a baseline to carry.
@@ -25,7 +27,15 @@ const DEFAULT_FLOOR_REF_CORPUS = 584;
  * @returns {number}
  */
 function floorRefCorpus() {
-  return Number(process.env.CLAUDE_MEM_UPS_FLOOR_REF_CORPUS || DEFAULT_FLOOR_REF_CORPUS);
+  // min 0 and NOT min 2, which a first cut of this guard chose on the reasoning that
+  // maxIdf is 0 below n=2 so the ramp would divide by zero. `corpusFloorScale` already
+  // handles that: `ref <= 1` returns 1 and so does `!(refIdf > 0)`. A LOW reference is a
+  // supported setting — it is the documented way to pin the ramp OFF, which two cases in
+  // tests/user-prompt-search.test.mjs depend on — so min 2 turned a working knob into a
+  // silent fallback to 584 and unfired both gates. The only thing being screened here is
+  // the NaN that used to reach the comparison and make it silently false.
+  return envNumber(process.env.CLAUDE_MEM_UPS_FLOOR_REF_CORPUS,
+    { name: 'CLAUDE_MEM_UPS_FLOOR_REF_CORPUS', defaultValue: DEFAULT_FLOOR_REF_CORPUS, min: 0 });
 }
 
 /**

package/lib/resolve-data-dir.mjs

@@ -111,16 +111,26 @@ export function resolveDataDir(raw) {
  * the native-binding breakage marker, which is the self-heal trigger). The rule that
  * resolved them, stated so the next sweep does not overshoot:
  *
- *   MOVES with the override — state a HOOK writes and another component reads back:
- *   cross-hook injected-ids markers, skill/pre-recall cooldowns, hook-error telemetry,
- *   the native-binding breakage marker, `metrics/`, `ep-flush-*` / `pending-*` buffers,
- *   the shadow-recommendation log.
+ *   MOVES with the override — state a HOOK writes INTO THE RUNTIME DIR and another
+ *   component reads back: cross-hook injected-ids markers, skill/pre-recall cooldowns,
+ *   hook-error telemetry, the launcher's breakage/heal markers, the native-binding
+ *   breakage marker, `ep-flush-*` / `pending-*` buffers, the shadow-recommendation log.
  *
- *   STAYS under the data dir — state about the ONE REAL INSTALLATION: `install.lock`,
- *   `update-state.json`, `swap-in-progress`, and the `.update-staging-*` /
- *   `.update-backup-*` residue scan. These must NOT follow a per-harness override: the
- *   lock exists to serialise concurrent installers, and two installers pointed at
- *   different override directories would each take their own lock and both proceed.
+ *   STAYS under the data dir, for two DIFFERENT reasons — do not collapse them:
+ *     (a) state about the ONE REAL INSTALLATION — `install.lock`, `update-state.json`,
+ *         `swap-in-progress`, the `.update-staging-*` / `.update-backup-*` residue scan.
+ *         These must not follow a per-harness override: the lock exists to serialise
+ *         concurrent installers, and two installers pointed at different override
+ *         directories would each take their own lock and both proceed.
+ *     (b) state that was never under `runtime/` at all — `metrics/` is a SIBLING of it
+ *         (`lib/metrics.mjs` is `join(dbDir, 'metrics')`) and every caller passes the data
+ *         dir. A v3.93.0 draft of this list put it in the MOVES column, which is the one
+ *         error a reader following this docblock would act on: a sweep obeying it would
+ *         convert `recordMetric(DB_DIR, …)` to a runtime-relative path and re-open exactly
+ *         what that release closed. What was fixed there was `join(RUNTIME_DIR, '..')` —
+ *         an inverse derivation of the data dir that stopped equalling `DB_DIR` the moment
+ *         the override was honoured. Deriving one dir from the other is the defect; the
+ *         sink itself never moved.
  *
  * `tests/runtime-dir-single-home.test.mjs` sweeps for the defect FORM (a shipped module
  * building `join(…, 'runtime')` itself) with the stays-put sites as a named allowlist, so
@@ -137,6 +147,6 @@ export function resolveRuntimeDir(dataDir, env = process.env) {
   // turning a previously-working relative path into a throw would break isolation setups
   // in order to enforce tidiness. It is resolved against cwd instead, so the value is at
   // least absolute by the time anything writes to it.
-  if (raw === undefined || raw === null || raw === '') return join(dataDir, 'runtime');
+  if (raw === undefined || raw === null || raw === '') return join(dataDir, 'runtime'); // runtime-dir:stays-put — this IS the default branch of the rule
   return isAbsolute(raw) ? raw : resolve(raw);
 }

package/lib/save-observation.mjs

@@ -14,6 +14,10 @@
 import { jaccardSimilarity, scrubSecrets, computeMinHash, cjkBigrams, getCurrentBranch } from '../utils.mjs';
 import { DEDUP_JACCARD_THRESHOLD } from './dedup-constants.mjs';
 import { insertObservationRow, insertObservationFiles, insertObservationVector } from './observation-write.mjs';
+// The SAME predicate every read path uses. Imported rather than re-typed: a hand-written
+// `superseded_at IS NULL` here would drift from the read side on the next column change,
+// which is the mechanism behind this repo's recurring superseded-invariant failures.
+import { liveObsFilterSql } from './inject-search-core.mjs';
 // Imported, not injected: `allowStatuses` below is the POLICY this function exists to hold,
 // and a caller free to pass its own resolver could reinstate the one-way gate D#195 closed.
 import { resolveDeferredIds, closeDeferredItems } from './deferred-work.mjs';
@@ -193,11 +197,30 @@ export function saveObservation(db, params) {
     VALUES (?, ?, ?, ?, ?, 'active')
   `).run(sessionId, sessionId, project, now.toISOString(), now.getTime());
 
-  // Dedup window: 5-min, top-50 most-recent in project.
+  // Dedup window: 5-min, top-50 most-recent LIVE rows in project.
+  //
+  // `liveObsFilterSql` is load-bearing, not tidiness. Without it this window compared
+  // against retired rows and returned one of their ids to the caller as `existingId` —
+  // a tombstone no read path can reach, since every one of them filters on this same
+  // predicate. Concretely: save something wrong, retire it, save the correction inside
+  // five minutes, and the correction was refused as a duplicate OF THE ROW IT WAS
+  // CORRECTING (and, per D#201's short-circuit below, its supersession was dropped too).
+  // Measured 2026-09-04 on the live DB: 3 of the 31 superseded rows were retired 2.9 /
+  // 3.6 / 3.9 minutes after creation, so the window is exactly where this happens.
+  //
+  // hook-llm.mjs runs its own three-tier dedup over this table without the filter and is
+  // NOT the same defect. Two reasons, and they cover different tiers — worth saying, since
+  // a draft gave them as one undifferentiated pair:
+  //   * its 7d/3d LOW-SIGNAL tiers are MEANT to keep matching rows auto-compress retired
+  //     (that is what stops "Modified package.json" re-accumulating). Does not apply to
+  //     its Tier 1, which is this same 5-minute window with no live filter.
+  //   * it returns null rather than handing an id back to a caller, so nothing escapes.
+  //     THIS is the reason that covers Tier 1: the consequence there is one silently
+  //     dropped auto-save, not a caller told its correction duplicates a tombstone.
   const dedupCutoff = now.getTime() - DEDUP_WINDOW_MS;
   const recent = db.prepare(`
     SELECT id, title, text FROM observations
-    WHERE project = ? AND created_at_epoch > ?
+    WHERE project = ? AND created_at_epoch > ? AND ${liveObsFilterSql('')}
     ORDER BY created_at_epoch DESC LIMIT ?
   `).all(project, dedupCutoff, DEDUP_RECENT_LIMIT);
 

package/mem-cli.mjs

@@ -1326,7 +1326,7 @@ async function cmdStats(db, args) {
   out(`  Low-value (imp≤1, never used, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`);
   out(`  Low-signal titles (Modified/Error/Worked on…): ${lowSignalTitle.c} (${(lowSignalRatio * 100).toFixed(1)}%)`);
   out(`  Compressed: ${compressedCount.c}`);
-  out(`  Hook errors (last 24h): ${hookErrors24h}${hookErrors24h > 0 ? `  ← tail ${join(DB_DIR, 'runtime/hook-errors')}` : ''}`);
+  out(`  Hook errors (last 24h): ${hookErrors24h}${hookErrors24h > 0 ? `  ← tail ${join(resolveRuntimeDir(DB_DIR), 'hook-errors')}` : ''}`);
   // Hint threshold = the REAL eviction budget (pre-release review 2026-08-16: a
   // hardcoded 3×-DB heuristic promised an eviction that fires only past the budget).
   out(`  Disk: DB ${mb(dbBytes)}MB | ${snaps.length} backup snapshot(s) ${mb(backupBytes)}MB${backupBytes > backupBudgetBytes() ? `  ← over the ${mb(backupBudgetBytes())}MB backup budget; next maintain/save snapshot evicts oldest (>7d old)` : ''}`);

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.93.0",
+  "version": "3.94.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.93.0",
+      "version": "3.94.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.26.0",
         "better-sqlite3": "^12.6.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.93.0",
+  "version": "3.94.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",
@@ -128,6 +128,7 @@
     "lib/transcript-scan.mjs",
     "lib/ups-query.mjs",
     "lib/dedup-constants.mjs",
+    "lib/env-number.mjs",
     "lib/deferred-work.mjs",
     "lib/upgrade-banner.mjs",
     "lib/scrub-record.mjs",

package/schema.mjs

@@ -935,12 +935,25 @@ export function auditSessionConsistency(db, { graceMinutes = 5 } = {}) {
       SELECT 1 FROM sdk_sessions s WHERE s.memory_session_id = o.memory_session_id
     )
   `).get().c;
+  // Audit P3-14 backstop. `observations.importance` is INTEGER DEFAULT 1 but NULLABLE, and
+  // the two maintenance faces disagree about what NULL means: decayAndMarkIdle reads
+  // COALESCE(importance,1)=1 and queues the row for purge, runIdleCleanup reads a bare
+  // `importance <= 1` which is NULL and skips it. lib/observation-write.mjs now coerces
+  // nullish to 1 on both write cores, so no NEW row can be in that state; this counts the
+  // ones that got in another way — an old version, a hand-edited DB, a restored dump.
+  // Reported here rather than in its own command because `orphan_obs` above establishes
+  // that this audit already covers observation-level integrity, not only sessions.
+  const obsImportanceNull = db.prepare(
+    'SELECT COUNT(*) AS c FROM observations WHERE importance IS NULL'
+  ).get().c;
   return {
     id_mix_uuid_shape: idMixUuidShape,
     id_mix_other: idMixOther,
     missing_mem_id: missingMemId,
     orphan_obs: orphanObs,
-    healthy: idMixUuidShape === 0 && missingMemId === 0 && orphanObs === 0,
+    obs_importance_null: obsImportanceNull,
+    healthy: idMixUuidShape === 0 && missingMemId === 0 && orphanObs === 0
+      && obsImportanceNull === 0,
   };
 }
 

package/scripts/binding-probe-cli.mjs

@@ -102,7 +102,7 @@ if (first.ok) process.exit(0);
 // .node mid-compile.
 let lockPath;
 try {
-  lockPath = join(helpers.resolveDataDir(process.env.CLAUDE_MEM_DIR), 'runtime', 'install.lock');
+  lockPath = join(helpers.resolveDataDir(process.env.CLAUDE_MEM_DIR), 'runtime', 'install.lock'); // runtime-dir:stays-put — install lock serialises real installers
 } catch (e) {
   // resolveDataDir THROWS on a non-absolute CLAUDE_MEM_DIR. Unhandled, that
   // prints an 8-line rejection stack onto SessionStart stderr; one line is enough.

package/scripts/hook-launcher.mjs

@@ -39,13 +39,36 @@ const INSTALL_DIR = join(__dirname, '..');
 // non-absolute → default. Data-writing paths import that module and throw instead.
 const MEM_DIR = process.env.CLAUDE_MEM_DIR;
 const DATA_DIR = MEM_DIR && isAbsolute(MEM_DIR) ? MEM_DIR : join(homedir(), '.claude-mem-lite');
-const RUNTIME_DIR = join(DATA_DIR, 'runtime');
-const HEAL_MARKER = join(RUNTIME_DIR, 'hook-launcher-lastheal');
+// TWO runtime dirs, because this file writes BOTH classes of state and v3.93.0 shipped a
+// split by moving only doctor's READ side. `RUNTIME_DIR` is data-dir-relative and serves
+// `swap-in-progress`, which is installation identity and must NOT follow a per-harness
+// override (two installers pointed at different override dirs would each see no swap in
+// progress). `HOOK_RUNTIME_DIR` is override-aware and serves every marker another component
+// reads back — the launcher's own breakage/heal markers, which `install.mjs doctor` reads,
+// and the native-binding pair below. That second constant already existed here as
+// `NB_RUNTIME_DIR` and was applied to only half this file's markers.
+//
+// Inline `||`, not `lib/resolve-data-dir.mjs::resolveRuntimeDir`, and this is the single
+// declared exception in the tree: the launcher runs BEFORE the native binding is known to
+// work, so it imports only `node:` builtins on purpose — even a leaf lib module is a
+// resolution it declines to make on the path whose job is surviving a broken install. The
+// standalone hook scripts it mirrors (pre-tool-recall / pre-skill-bridge) honour the same
+// variable and write 78 of every 79 of these markers, so reading a different dir would mean
+// never healing. `resolveRuntimeDir` is the canonical rule (audit 2026-09-02 P1-14) and this
+// is NOT identical to it: the resolver additionally makes a RELATIVE override absolute
+// (`isAbsolute(raw) ? raw : resolve(raw)`), while this hands the relative value straight to
+// `fs`, which resolves it against cwd at call time rather than at module load. They agree on
+// unset, empty and absolute — the three cases that reach a real install. Keep the DEFAULTING
+// behaviour in step; do not read "identical" into the difference.
+// `tests/runtime-dir-single-home.test.mjs` asserts this file still carries the rule.
+const RUNTIME_DIR = join(DATA_DIR, 'runtime'); // runtime-dir:stays-put — serves swap-in-progress only; HOOK_RUNTIME_DIR carries the hook markers
+const HOOK_RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || RUNTIME_DIR;
+const HEAL_MARKER = join(HOOK_RUNTIME_DIR, 'hook-launcher-lastheal');
 const HEAL_COOLDOWN_MS = 6 * 60 * 60 * 1000;
 // Observable breakage state: written when the launcher degrades a broken install
 // to exit 0, cleared once the install is confirmed healthy. `doctor` reads it so
 // the intentional silence (no stack trace per fire) stays detectable. (#4/#8)
-const BROKEN_MARKER = join(RUNTIME_DIR, 'hook-launcher-broken');
+const BROKEN_MARKER = join(HOOK_RUNTIME_DIR, 'hook-launcher-broken');
 
 // ── Native-binding (ABI) self-heal ──────────────────────────────────────────
 // A stale better_sqlite3.node after a Node upgrade does NOT throw at import time
@@ -63,22 +86,9 @@ const BROKEN_MARKER = join(RUNTIME_DIR, 'hook-launcher-broken');
 // lib/hook-telemetry.mjs and lib/native-binding-hint.mjs); this heals from it at
 // SESSION-START only — never on the per-tool hot path, where an npm run would
 // stall the user's edit.
-// Marker dir mirrors the standalone hook scripts (pre-tool-recall /
-// pre-skill-bridge), which honor CLAUDE_MEM_RUNTIME_DIR — they write 78 of every
-// 79 of these markers, so reading a different dir would mean never healing.
-// The last hand-written copy of this rule, and it stays: this launcher runs BEFORE the
-// native binding is known to work, so it imports only `node:` builtins on purpose — even
-// `lib/resolve-data-dir.mjs` is a module resolution it declines to make on the path whose
-// job is to survive a broken install. `lib/resolve-data-dir.mjs::resolveRuntimeDir` is the
-// canonical rule (audit 2026-09-02 P1-14). It is NOT identical to it, and saying so was
-// wrong: the resolver additionally makes a RELATIVE override absolute (`isAbsolute(raw) ?
-// raw : resolve(raw)`), while this expression hands the relative value straight to `fs`,
-// which resolves it against cwd at call time instead of at module load. They agree on
-// unset, on empty and on an absolute override — the three cases that reach a real install.
-// Keep the DEFAULTING behaviour in step; do not read "identical" into the difference.
-const NB_RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || RUNTIME_DIR;
-const NB_BROKEN_MARKER = join(NB_RUNTIME_DIR, 'native-binding-broken');
-const NB_HEAL_MARKER = join(NB_RUNTIME_DIR, 'native-binding-lastheal');
+// Marker dir: HOOK_RUNTIME_DIR (see its definition above for why it is override-aware).
+const NB_BROKEN_MARKER = join(HOOK_RUNTIME_DIR, 'native-binding-broken');
+const NB_HEAL_MARKER = join(HOOK_RUNTIME_DIR, 'native-binding-lastheal');
 // Literal, not imported: the pure-`node:` charter above forbids importing lib/
 // here (this file must survive a broken install). Kept in sync with
 // lib/binding-probe.mjs::NATIVE_BINDING_REBUILD_CMD, which is the single home
@@ -225,7 +235,7 @@ function recentHealAttempt() {
 
 function recordHealAttempt() {
   try {
-    mkdirSync(RUNTIME_DIR, { recursive: true });
+    mkdirSync(HOOK_RUNTIME_DIR, { recursive: true });
     writeFileSync(HEAL_MARKER, String(Date.now()));
   } catch { /* best-effort */ }
 }
@@ -239,7 +249,7 @@ function clearHealMarker() {
 
 function recordBreakage(reason) {
   try {
-    mkdirSync(RUNTIME_DIR, { recursive: true });
+    mkdirSync(HOOK_RUNTIME_DIR, { recursive: true });
     writeFileSync(BROKEN_MARKER, JSON.stringify({ reason, ts: Date.now() }));
   } catch { /* best-effort */ }
 }
@@ -316,7 +326,7 @@ function healNativeBindingIfBroken() {
       if (Date.now() - statSync(NB_HEAL_MARKER).mtimeMs < HEAL_COOLDOWN_MS) return;
     } catch { /* no marker → not on cooldown */ }
     try {
-      mkdirSync(NB_RUNTIME_DIR, { recursive: true });
+      mkdirSync(HOOK_RUNTIME_DIR, { recursive: true });
       writeFileSync(NB_HEAL_MARKER, String(Date.now()));
     } catch { /* best-effort */ }
 

package/scripts/launch.mjs

@@ -76,7 +76,7 @@ try {
   // proceeds; a broken one defers to the peer instead of racing it).
   const { acquireLock } = await import('../lib/proc-lock.mjs');
   const { resolveDataDir } = await import('../lib/resolve-data-dir.mjs');
-  const lockPath = join(resolveDataDir(process.env.CLAUDE_MEM_DIR), 'runtime', 'install.lock');
+  const lockPath = join(resolveDataDir(process.env.CLAUDE_MEM_DIR), 'runtime', 'install.lock'); // runtime-dir:stays-put — install lock serialises real installers
   let release = null;
   for (let i = 0; i < 20 && !(release = acquireLock(lockPath)); i++) {
     await new Promise((r) => setTimeout(r, 500));

package/scripts/pre-tool-recall.js

@@ -39,6 +39,7 @@ import { neutralizeContextDelimiters } from '../format-utils.mjs';
 //
 // Import-free module, no runtime deps — nothing added to this script's load cost.
 import { queueHookContext, flushHookStdout } from '../lib/hook-stdout.mjs';
+import { envNumber } from '../lib/env-number.mjs';
 // P1-9: one bounded stdin reader. Import-free, like hook-stdout.mjs beside it.
 import { readHookStdin, TOOL_INPUT_FILE_MAX_BYTES, salvageTruncatedHookEvent } from '../lib/hook-stdin.mjs';
 // Recall queries the SAVE-path project, so this MUST produce the same string as the
@@ -176,16 +177,21 @@ const EDGE_DECAY_K = Math.max(1, Number.isNaN(EDGE_DECAY_K_RAW) ? 3 : EDGE_DECAY
 // dominated by legacy rows.
 const SCOPE_FILTER_ON = ['1', 'on', 'true', 'yes'].includes(
   String(process.env.CLAUDE_MEM_SCOPE_FILTER || '').toLowerCase());
-const FILE_INTEL_MIN_TOKENS = Math.max(1,
-  parseInt(process.env.CLAUDE_MEM_FILE_INTEL_MIN_TOKENS, 10) || 800);
+// `min: 1` replaces the old `Math.max(1, parseInt(…) || 800)`. The wrapper made the
+// clamp look like the whole story, but the `|| 800` inside it swallowed an explicit 0 —
+// `CLAUDE_MEM_FILE_INTEL_MIN_TOKENS=0` (a user asking for no floor) landed on 800, not on
+// 1. Same class as the UPS knobs; caught by the widened tree sweep in
+// tests/env-number.test.mjs once it learned the trailing-default shape.
+const FILE_INTEL_MIN_TOKENS = envNumber(process.env.CLAUDE_MEM_FILE_INTEL_MIN_TOKENS,
+  { name: 'CLAUDE_MEM_FILE_INTEL_MIN_TOKENS', defaultValue: 800, min: 1, integer: true });
 // Feature ② (repeated-read guard): when the agent does a FULL re-read of a file
 // it already read this session and the file is unchanged (mtime), nudge it to
 // reuse context instead of re-slurping. Read-only; only fires above the floor and
 // never on offset/limit paging. Default ON; CLAUDE_MEM_REREAD_GUARD=0 disables.
 const REREAD_GUARD_OFF = ['0', 'off', 'false', 'no'].includes(
   String(process.env.CLAUDE_MEM_REREAD_GUARD || '').toLowerCase());
-const REREAD_MIN_TOKENS = Math.max(1,
-  parseInt(process.env.CLAUDE_MEM_REREAD_MIN_TOKENS, 10) || 600);
+const REREAD_MIN_TOKENS = envNumber(process.env.CLAUDE_MEM_REREAD_MIN_TOKENS,
+  { name: 'CLAUDE_MEM_REREAD_MIN_TOKENS', defaultValue: 600, min: 1, integer: true });
 // Stale-cooldown GC moved to hook.mjs::handleSessionStart — running it on every
 // Edit cost 15-30 disk stats per call. SessionStart fires once at session boot,
 // which is enough to keep RUNTIME_DIR from growing unbounded.

package/scripts/user-prompt-search.js

@@ -23,6 +23,7 @@ import { recommendSkill } from '../registry-recommend.mjs';
 import { recordHookError } from '../lib/hook-telemetry.mjs';
 
 import { DAY_MS } from '../lib/time-constants.mjs';
+import { envNumber } from '../lib/env-number.mjs';
 // ─── Constants ──────────────────────────────────────────────────────────────
 
 // Telemetry sink (lib/hook-telemetry.mjs contract): env override for tests, else
@@ -48,7 +49,12 @@ const injectedIdsFileFor = (sessionId) =>
 // useRecent intent path is unaffected (it uses intent.limit=5 directly,
 // gated by explicit "before/previously/记得" prompts where breadth is the
 // point). Env override for projects that want broader recall or to A/B.
-const MAX_RESULTS = Number(process.env.CLAUDE_MEM_UPS_MAX_RESULTS || 3);
+// Integer, min 0. This value reaches `rows.slice(0, MAX_RESULTS)`, and 0 there means
+// "inject nothing" — a legitimate way to turn this face off, so it is accepted rather
+// than warned back up to 3 (falling back would INJECT for a user who asked for silence).
+// What is screened is NaN, which produced the same silence from a typo, unasked.
+const MAX_RESULTS = envNumber(process.env.CLAUDE_MEM_UPS_MAX_RESULTS,
+  { name: 'CLAUDE_MEM_UPS_MAX_RESULTS', defaultValue: 3, min: 0, integer: true });
 const LOOKBACK_MS = 60 * DAY_MS; // 60 days
 
 // v2.56.x: Past-similar-questions fallback row cap. Cut from 3 → 1 after
@@ -57,7 +63,11 @@ const LOOKBACK_MS = 60 * DAY_MS; // 60 days
 // Unlike the obs FTS path (TOP_REL_FLOOR + BM25 gates), prompt-fallback has no
 // quality gate — only BM25 ordering — so additional rows inflate noise without
 // improving signal. Env-overridable for projects that want broader prompt recall.
-const PROMPT_FALLBACK_LIMIT = Number(process.env.CLAUDE_MEM_UPS_PROMPT_FALLBACK_LIMIT || 1);
+// Integer, min 0: bound directly into a SQL `LIMIT ?`, where better-sqlite3 rejects a
+// non-integer outright (`SqliteError: datatype mismatch`). `LIMIT 0` is valid and means
+// "disable the prompt-fallback path", so 0 stays a usable setting.
+const PROMPT_FALLBACK_LIMIT = envNumber(process.env.CLAUDE_MEM_UPS_PROMPT_FALLBACK_LIMIT,
+  { name: 'CLAUDE_MEM_UPS_PROMPT_FALLBACK_LIMIT', defaultValue: 1, min: 0, integer: true });
 // Over-fetch factor for that cap. searchByUserPrompts filters rows in JS (cjkPrecisionOk)
 // AFTER the SQL LIMIT, so the LIMIT bounds reachability, not just output width — see the
 // comment at the query. These size the pool only; the function still returns at most
@@ -77,7 +87,10 @@ const PROMPT_FALLBACK_POOL_MAX = 25;
 // acts as a NULL-rel guard, not a real noise filter. The primary noise gate
 // is TOP_REL_FLOOR below, which drops the whole FTS set when the best match
 // is weak.
-const BM25_MIN_SCORE = Number(process.env.CLAUDE_MEM_UPS_BM25_MIN || 1e-5);
+// min 0, non-integer: a magnitude floor compared with `Math.abs(relevance) >= …`.
+// NaN here makes that comparison always false, i.e. it drops every row.
+const BM25_MIN_SCORE = envNumber(process.env.CLAUDE_MEM_UPS_BM25_MIN,
+  { name: 'CLAUDE_MEM_UPS_BM25_MIN', defaultValue: 1e-5, min: 0 });
 // CJK-weighted minimum length for the prompt. Catches medium-short Latin
 // prompts ("run tests", "fix bug now") that survive `shouldSkip`'s weaker 8-unit
 // floor but carry too few tokens to justify an FTS lookup.
@@ -92,7 +105,8 @@ const PROMPT_MIN_LENGTH = 15;
 // memory at least once, relax gates so short follow-ups still get recall.
 // Detection: injected-ids marker count > 0 within DEDUP_STALE_MS window.
 const FOLLOWUP_PROMPT_MIN_LENGTH = 8;
-const FOLLOWUP_BM25_MIN_SCORE = Number(process.env.CLAUDE_MEM_UPS_BM25_MIN_FOLLOWUP || 5e-6);
+const FOLLOWUP_BM25_MIN_SCORE = envNumber(process.env.CLAUDE_MEM_UPS_BM25_MIN_FOLLOWUP,
+  { name: 'CLAUDE_MEM_UPS_BM25_MIN_FOLLOWUP', defaultValue: 5e-6, min: 0 });
 
 // v2.34.3: top-|rel| sanity gate. BM25_MIN_SCORE filters per-row; this floor
 // gates the entire FTS set. Noise prompts ("today's date", "current time")
@@ -113,7 +127,18 @@ const FOLLOWUP_BM25_MIN_SCORE = Number(process.env.CLAUDE_MEM_UPS_BM25_MIN_FOLLO
 // through, but the top-|rel| gap is an absolute distribution separator —
 // lowering it in follow-up mode re-admits the 37..48 noise band that the
 // gate exists to drop.
-const TOP_REL_FLOOR = Number(process.env.CLAUDE_MEM_UPS_TOP_MIN || 50);
+// min 0, because 0 is a REAL value here: the documented seed-mode switch that kills both
+// absolute floors (see OR_TOP_BM25_FLOOR below).
+//
+// It has ALWAYS worked, and a first draft of this comment claimed otherwise on a false
+// premise worth recording: `process.env.X` is always a STRING, and `'0'` is truthy — only
+// `''` is falsy. So `Number(env || 50)` with `CLAUDE_MEM_UPS_TOP_MIN='0'` was already 0,
+// which is why `tests/user-prompt-search.test.mjs` has been green with `'0'` as runScript's
+// default. The idiom that genuinely swallows a 0 is the OTHER one — `Number(env.X) || D`,
+// parse first then fall back — which is what lib/cite-back-hint.mjs used. Caught by the
+// v3.94.0 pre-tag correctness review. What changed here is NaN screening, nothing else.
+const TOP_REL_FLOOR = envNumber(process.env.CLAUDE_MEM_UPS_TOP_MIN,
+  { name: 'CLAUDE_MEM_UPS_TOP_MIN', defaultValue: 50, min: 0 });
 
 // v2.43.x: OR-fallback raw BM25 magnitude floor. The composite TOP_REL_FLOOR
 // above gates on `bm25 × importance × type_quality × decay × noise_penalty`.
@@ -141,7 +166,8 @@ const TOP_REL_FLOOR = Number(process.env.CLAUDE_MEM_UPS_TOP_MIN || 50);
 // we piggy-back on it rather than introducing a second override env.
 const OR_TOP_BM25_FLOOR = TOP_REL_FLOOR === 0
   ? 0
-  : Number(process.env.CLAUDE_MEM_UPS_OR_BM25_MIN || 30);
+  : envNumber(process.env.CLAUDE_MEM_UPS_OR_BM25_MIN,
+    { name: 'CLAUDE_MEM_UPS_OR_BM25_MIN', defaultValue: 30, min: 0 });
 
 // ─── Corpus-size normalization of the absolute floors (v3.61.0) ─────────────
 //

package/search-scoring.mjs

@@ -316,7 +316,16 @@ export function runIdleCleanup(db) {
           -- the same guard-on-one-path shape the docblock below claims was consolidated.
           AND COALESCE(injection_count, 0) = 0
           AND type IN (${types})
-          AND created_at_epoch < ? AND COALESCE(compressed_into, 0) = 0
+          -- liveObsFilterSql, not compressed_into alone (P3-13), and the THIRD clause this
+          -- MCP twin has had to be brought level on (lesson guard, then injection_count in
+          -- audit P0-4, now this). A retired row's superseded_by column is the redirect the
+          -- Stop citation loop follows to credit a #NN naming a corrected memory; purgeStale
+          -- hard-deletes what this marks, and that destroys it. Same predicate, same
+          -- reasoning, as decayAndMarkIdle's mark-idle pass -- the two are twins and drift
+          -- here has cost data twice. The COMPRESSED_AUTO pass below deliberately does NOT
+          -- get it: -1 is not deletable by any path, so a tombstone reaching it loses nothing.
+          -- (No backticks: inside a JS template literal.)
+          AND created_at_epoch < ? AND ${liveObsFilterSql('')}
           -- Never auto-mark a lesson-bearing row for purge. This idle path is the
           -- MCP-server sibling of maintain-core.decayAndMarkIdle and must carry the
           -- SAME "lessons never auto-GC" guard; without it a lesson demoted to imp≤1

package/server.mjs

@@ -1570,8 +1570,12 @@ server.registerTool(
 // ─── Tool: mem_export ────────────────────────────────────────────────────────
 
 // In-process test seam (mirrors handleRecentForTest, #8743): threads an injected db
-// through the SAME body the registered handler runs. NOTE: a `project` arg is still
-// resolved via resolveProject() against the MODULE db, not the injected one.
+// through the SAME body the registered handler runs — INCLUDING the project resolution,
+// which uses `runExport`'s own `db` parameter. (A note here used to say the resolution ran
+// against the module db instead; it was false before this release too. Corrected while
+// rewriting the block below, since a stale note three lines above a rewrite is the one a
+// reader trusts.) This seam bypasses the zod layer, which is why `runExport` screens a
+// non-string `project` itself rather than relying on `memExportSchema`.
 export async function handleExportForTest(db, args) {
   return runExport(db, args);
 }
@@ -1592,14 +1596,24 @@ async function runExport(db, args) {
     toEpoch = new Date(d).getTime();
     if (isNaN(toEpoch)) throw new Error(`Invalid date_to: "${args.date_to}" (use ISO 8601 or YYYY-MM-DD)`);
   }
+  // Same policy as the two date checks: refuse rather than silently drop a filter.
+  //
+  // This replaces a `_resolveProjectShared(db, x) || x` fallback that could not do what
+  // its comment claimed. `resolveProject` returns a falsy value on exactly one input —
+  // a truthy NON-STRING, which it deliberately maps to null so that `true.includes('--')`
+  // stops crashing every project-filtered command at the root helper. Through MCP that
+  // input cannot arrive (`memExportSchema.project` is `z.string().optional()`, validated
+  // before the handler); through `handleExportForTest` it can. So the fallback's only
+  // reachable effect was to hand the non-string straight back, undoing that guard and
+  // trading a wide export for a bind error. Neither is the documented behaviour, and the
+  // other project-resolving sites (server.mjs:326/465, and every cmd* in mem-cli.mjs)
+  // carry no such fallback — this one was the outlier.
+  if (args.project !== undefined && args.project !== null && typeof args.project !== 'string') {
+    throw new Error(`Invalid project: expected a string, got ${typeof args.project}`);
+  }
   const { params, where } = buildExportWhere({
     includeCompressed: Boolean(args.include_compressed),
-    // `|| args.project`: buildExportWhere gates the predicate on TRUTHINESS, so a falsy
-    // resolution would DROP the project filter and export the whole store. The code this
-    // replaced pushed `project = ?` unconditionally, so an unresolvable name yielded zero
-    // rows — which is the safe direction, and the comment above is specifically about not
-    // letting a dropped filter widen the export.
-    project: args.project ? (_resolveProjectShared(db, args.project) || args.project) : null,
+    project: args.project ? _resolveProjectShared(db, args.project) : null,
     type: args.type || null,
     fromEpoch, toEpoch,
   });

package/source-files.mjs

@@ -250,6 +250,11 @@ export const SOURCE_FILES = [
   // hook-optimize.mjs, mem-cli.mjs, server.mjs, and the save/maintain cores;
   // missing it from the manifest would break those paths on auto-update.
   'lib/dedup-constants.mjs',
+  // Numeric env-override parsing with an explicit failure mode. Statically imported
+  // by scripts/user-prompt-search.js (a HOOK entry point — a missing manifest entry
+  // kills the UserPromptSubmit face outright on auto-update), lib/relevance-floor.mjs
+  // and lib/cite-back-hint.mjs.
+  'lib/env-number.mjs',
   // v2.70 deferred-work: carry-forward TODO primitives. Statically imported by
   // server.mjs (mem_defer family) and mem-cli.mjs (defer subcommand).
   'lib/deferred-work.mjs',