claude-mem-lite 3.93.1 → 3.95.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.93.1",
+      "version": "3.95.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.95.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);