claude-mem-lite 3.93.1 → 3.94.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.93.1",
+      "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.1",
+  "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/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/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-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/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/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.93.1",
+  "version": "3.94.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.93.1",
+      "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.1",
+  "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/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',