claude-mem-lite 3.87.0 → 3.88.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.87.0",
+      "version": "3.88.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.87.0",
+  "version": "3.88.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

@@ -841,7 +841,7 @@ benchmark and A/B harness are calibrated against — changing them invalidates t
 |----------|-------------|---------|
 | `CLAUDE_MEM_NO_CITATION_TRACK` | `1` disables both the access-count bump and the decay loop — no citation bookkeeping at all. | _(enabled)_ |
 | `MEM_DISABLE_CITATION_DECAY` | `1` disables only the decay writes, keeping access-count bumps. | _(enabled)_ |
-| `CLAUDE_MEM_CITATION_ADOPTION_THRESHOLD` | Session cite-rate below which demotion is suppressed (promotion always proceeds). | `0.02` |
+| `CLAUDE_MEM_CITATION_ADOPTION_THRESHOLD` | **Removed — inert.** Tuned the per-project adoption gate, which is gone (D#204). Setting it warns on stderr and changes nothing. | _(n/a)_ |
 | `CLAUDE_MEM_NO_CITE_NUDGE` | `1` fully silences the cite-back nudge. | _(enabled)_ |
 | `CLAUDE_MEM_CITE_NUDGE_THRESHOLD` | Cite-rate below which the nudge fires. | `0.6` |
 | `CLAUDE_MEM_CITE_NUDGE_MIN_INJECTED` | Minimum injection volume before the ratio gate is judged at all. | `5` |

package/hook-context.mjs

@@ -9,7 +9,7 @@ import { basename, join } from 'path';
 import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'fs';
 import {
   estimateTokens, truncate, typeIcon, fmtTime, inferProject,
-  debugLog, debugCatch, neutralizeContextDelimiters,
+  debugLog, neutralizeContextDelimiters,
   DECAY_HALF_LIFE_BY_TYPE, DEFAULT_DECAY_HALF_LIFE_MS, notLowSignalTitleClause,
 } from './utils.mjs';
 import { STALE_SESSION_MS, FALLBACK_OBS_WINDOW_MS, RUNTIME_DIR, effectiveQuiet, isQuietHooks, KEY_CONTEXT_LIMIT } from './hook-shared.mjs';
@@ -86,8 +86,10 @@ export function computeAdaptiveWindows(db, project) {
 //
 // Both displaced rows lost their slot to the 3-per-type diversity cap. That is not a
 // three-way discrimination: the token budget does not bind on this corpus (651 of 2000 in
-// the widest arm's largest project) and the file-overlap `continue` below is UNREACHABLE
-// (D#197) — so the cap is currently the only gate that can fire.
+// the widest arm's largest project) and the file-overlap `continue` that used to sit in
+// the selector was UNREACHABLE and has since been deleted (D#197) — so the cap is
+// currently the only gate that can fire. ("below" until v3.88.0; there is nothing below
+// any more, and a reader who went looking found the sentence outliving its referent.)
 //
 // 200 is ~2x the largest pool observed (107). The ruler CANNOT distinguish 200 from 500
 // on this corpus — every bound >= the largest pool is one arm, identical in both
@@ -196,7 +198,6 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
     ...scoredSess.map(s => ({ ...s, _kind: 'sess' })),
   ].sort((a, b) => b.valueDensity - a.valueDensity);
 
-  const selectedFiles = new Set();
   const selectedTypes = new Map(); // type → count for diversity constraint
 
   for (const c of allCandidates) {
@@ -208,20 +209,32 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
       if (typeCount >= 3) continue;
     }
 
-    // Diversity penalty: reduce value for file overlap with already-selected
-    if (c._kind === 'obs' && c.files_modified) {
-      let cFiles;
-      try { cFiles = JSON.parse(c.files_modified || '[]'); } catch (e) { debugCatch(e, 'budgetSelect-parseFiles'); cFiles = []; }
-      if (cFiles.length > 0 && selectedFiles.size > 0) {
-        const overlap = cFiles.filter(f => selectedFiles.has(f)).length;
-        const overlapRatio = overlap / cFiles.length;
-        const penalizedValue = c.valueDensity * (1 - 0.3 * overlapRatio);
-        if (penalizedValue < 0.001) continue;
-      }
-      for (const f of cFiles) selectedFiles.add(f);
-    }
-
-    // Commit type diversity counter after both gates pass
+    // D#197: a "Diversity penalty: reduce value for file overlap" block used to sit
+    // here. It is gone, and the deletion is behaviour-preserving, because it reduced
+    // nothing. Two independent reasons, both verified rather than reasoned about:
+    //
+    //  (1) Its `penalizedValue` was a local read by exactly one `continue`. Order was
+    //      already fixed upstream by the raw-valueDensity sort and this greedy loop
+    //      never re-sorts — so the comment's promise could not happen at all.
+    //  (2) That `continue` was unreachable. penalizedValue >= 0.7 * valueDensity, and
+    //      valueDensity = value / sqrt(cost) with value > 0.5 (recency > 1 x
+    //      TYPE_QUALITY min 0.5 x impBoost >= 1.0 x lessonBoost >= 1.0) and cost >= 1
+    //      — estimateTokens('') returns 1, checked, so there is no zero-cost row that
+    //      would drive valueDensity to 0 and make it fire. Triggering needed a title
+    //      costing > 122500 tokens. Measured over the 2027 live rows carrying
+    //      files_modified: zero zero-cost rows, minimum valueDensity 0.1147 (80x the
+    //      trigger), longest title 171 chars = 43 tokens by this code's own
+    //      estimateTokens (ceil(ascii/4) + ceil(cjk/1.5)). A first version of this line
+    //      said 49, which is 3.5 chars/token — a rate nothing here uses.
+    //
+    // With both gone `selectedFiles` had no reader left, so the Set and its
+    // JSON.parse went with it. Type diversity above is the only diversity constraint
+    // that was ever live, which is why the counter below no longer says "both gates".
+    //
+    // Real overlap down-weighting, if wanted, belongs in the sort key — a ranking
+    // change owing an A/B, not a revival of this block. tests/hook-context.test.mjs
+    // pins the current unpenalized order and asserts its own discriminator, so a
+    // penalty that reached the ordering turns red instead of landing silently.
     if (c._kind === 'obs' && c.type) {
       selectedTypes.set(c.type, (selectedTypes.get(c.type) || 0) + 1);
     }

package/hook-memory.mjs

@@ -31,8 +31,11 @@ const MEMORY_LOOKBACK_MS = 60 * DAY_MS; // 60 days
  * × 3.0 cite = 6.75; worst = 0.5 change × 1.0 no-lesson × 0.6 importance × 0.2 noise ×
  * 0.4 cite = 0.024, i.e. a **281× DECLARED range**. That is an upper bound off the factor
  * tables, not a measurement: `citeFactor = 0.4` requires `uncited_streak >= 3`, and
- * citation-decay resets the streak at 3 after demoting importance, so the steady state is
- * bounded by [0,2] (scoring-sql.mjs, citeFactorJs docblock). Measured 2026-09-01 over the
+ * citation-decay rolls the streak over to 0 when it reaches 3, so the steady state is
+ * bounded by [0,2] (scoring-sql.mjs, citeFactorJs docblock). That rollover used to be
+ * paired with an `importance - 1`; D#179/D#198 removed the importance write, and the
+ * bound is unaffected because it was always the streak reset that produced it.
+ * Measured 2026-09-01 over the
  * 2284 rows that clear `liveObsFilterSql` — the one predicate in the WHERE of BOTH SELECTs
  * below — 0 are at streak >= 3, and recomputing the factor per row gives a REALISED range
  * of 0.1125 … 6.750: a **60.0× spread** (81 rows hit the full best case, 0 the full worst).
@@ -513,9 +516,13 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
  * projects on this machine the importance=3 population ALONE exceeds 50 — so every
  * importance=2 lesson in those projects was structurally unreachable, and a
  * citation-decay demotion 3->2 EVICTED a row from the pool instead of down-ranking it.
- * That eviction loop is the risk D#172 was filed on; raising the bound above any
- * plausible per-project population is what closes it, because a 3->2 demotion then only
- * changes the row's score multiplier, which is what the decay design intends.
+ * That eviction loop is the risk D#172 was filed on, and raising the bound above any
+ * plausible per-project population is what closed it. The second half of that sentence
+ * is now moot from the other end too: D#179/D#198 stopped citation-decay writing
+ * `importance` at all, so there is no 3->2 walk left for the bound to have to absorb.
+ * The bound still matters on its own terms — it is what makes importance=2 rows
+ * reachable here — but it is no longer the only thing standing between a citation and
+ * an eviction.
  *
  * COUNT THE POPULATION WITH THE POOL'S OWN FILTER. Those figures are
  * `liveObsFilterSql` + the `importance >= 2` + non-empty-lesson gates, i.e. what the query
@@ -527,14 +534,17 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
  * in lib/citation-tracker.mjs. Re-measure with `node benchmark/imperative-pool-replay.mjs
  * --population`, never with a bare `SELECT ... WHERE importance = 3`.
  *
- * 3->2 IS NOW A DOWN-RANK; 2->1 IS STILL AN EVICTION. The pool gate is
- * `COALESCE(importance, 1) >= 2`, so a row demoted to the IMPORTANCE_FLOOR of 1 leaves
- * this face's reach until some other face cites it back up. Widening the bound is also
- * what first makes importance=2 rows reachable here (56 of projects--mem's 383 eligible),
- * so it creates the injections that can walk one down to 1. Measured exposure: of the
- * picks the widening newly surfaces, one is importance=2 — `score = importance x overlap`
- * keeps importance=3 rows ahead nearly always — so this is a known small edge, not a
- * closed loop.
+ * THE EVICTION EDGE IS CLOSED FROM THE OTHER END, AND NOT BY THIS BOUND. The pool gate is
+ * `COALESCE(importance, 1) >= 2`, so a row at 1 is out of this face's reach — that part is
+ * unchanged. What changed is that nothing in the citation loop can put it there any more:
+ * D#179/D#198 deleted the `importance` write from BOTH branches of `applyCitationDecay`
+ * along with `IMPORTANCE_FLOOR` itself, so neither a 3->2 down-rank nor a 2->1 eviction can
+ * originate from a citation. This paragraph used to read "3->2 IS NOW A DOWN-RANK; 2->1 IS
+ * STILL AN EVICTION" and cite that constant; it survived the deletion because the paragraph
+ * immediately above it was the one rewritten (pre-tag review v3.88.0, correctness S3).
+ * What can still move a row to 1 is ordinary maintenance — `demotePinned` writes 1 on a
+ * heavily-injected uncited row with no lesson, and `decayAndMarkIdle` walks `imp - 1` on a
+ * never-accessed never-injected row — so the edge exists, it just is not citation-driven.
  *
  * MEASURED, and reproducible: `node benchmark/imperative-pool-replay.mjs`. Over 373 real
  * user prompts replayed against their OWN project's live corpus (85 produced a candidate

package/hook.mjs

@@ -1004,10 +1004,14 @@ async function handleStop() {
             // marker. They are added to the decay set ONLY where they were
             // actually cited (below), never as bare denominator: the block
             // re-renders the same fixed top-10 unconditionally, so an uncited
-            // render says nothing about relevance — and since keyObs gates on
-            // `importance >= 2`, one demotion evicts the common importance-2 row
-            // from Key Context for good. v3.66.0 fed them in as denominator and
-            // that made the block eat its own contents.
+            // render says nothing about relevance. v3.66.0 fed them in as
+            // denominator and that made the block eat its own contents.
+            // The policy used to rest on a second ground as well — "since keyObs
+            // gates on `importance >= 2`, one demotion evicts the common
+            // importance-2 row from Key Context for good" — which D#179/D#198
+            // retired: this loop no longer writes `importance`, so no citation
+            // miss can evict anything. The first ground is untouched and is why
+            // the policy stays.
             const keyCtxIds = extractInjectedFromKeyContext({
               runtimeDir: RUNTIME_DIR, project, sessionId: ccSessionId,
             });

package/lib/citation-tracker.mjs

@@ -830,13 +830,14 @@ export function extractAllInjected(transcriptPath, opts = {}) {
  *   changed the top-1 in 3 of 78. The bound is now IMPERATIVE_POOL_BACKSTOP = 5000,
  *   documented there as an OOM backstop and not a relevance gate.
  *
- *   A 3->2 demotion is a down-rank again. A 2->1 demotion is still an EVICTION, because
- *   the pool gate is `>= 2` and IMPORTANCE_FLOOR is 1 — and widening is what first makes
- *   importance=2 rows reachable by this face at all, so it creates the injections that can
- *   walk one there. Measured exposure is one row; see the constant's docblock. `subagent`
- *   shares that pool and inherits both halves. Still open in D#172: admitting `subagent`
- *   to the denominator, which is a separate decision needing the receiver-attributed cites
- *   merged asymmetrically.
+ *   The demotion half of that paragraph is now MOOT rather than merely improved:
+ *   D#179/D#198 stopped this loop writing `importance` at all, so neither a 3->2 nor a
+ *   2->1 walk can happen through decay and the pool gate `>= 2` is no longer something
+ *   citations move a row across. The widening still matters on its own terms — it is
+ *   what makes importance=2 rows reachable by this face — but the eviction risk it used
+ *   to carry is gone with the writes. `subagent` shares that pool. Still open in D#172:
+ *   admitting `subagent` to the denominator, which is a separate decision needing the
+ *   receiver-attributed cites merged asymmetrically.
  */
 const DECAY_EXCLUDED_SURFACES = new Set();
 
@@ -906,21 +907,32 @@ export const DECAY_DENOMINATOR_SURFACES = ATTACHMENT_SURFACES.filter((f) => !DEC
  *   FOUR of the five are 3->2 down-ranks (#8597, #8847 with cited_count 56, #8948,
  *   #10246). THE FIFTH WAS AN EVICTION and the first draft of this note said there were
  *   none: at 2026-08-25 18:00Z, #10716 sat at importance = 2, so its next miss would take
- *   it to IMPORTANCE_FLOOR = 1 — under the `COALESCE(importance, 1) >= 2` gate in
+ *   it to the floor of 1 (`IMPORTANCE_FLOOR`, a constant this loop no longer has — see the
+ *   correction two paragraphs down) — under the `COALESCE(importance, 1) >= 2` gate in
  *   rankImperativeCandidates, which is the candidate pool of the very face being
  *   admitted. IMPERATIVE_POOL_BACKSTOP closed the 3->2 eviction in v3.82.0 and 2->1 was
  *   always documented as still evicting; writing "down-ranks, not evictions" required
  *   assuming the marginal population was all importance = 3, which one query refutes.
  *   Count it before repeating it.
  *
- *   THAT ROW IS NO LONGER IN THAT STATE, AND THE REASON IS THIS LOOP (D#179). #10716 now
- *   reads importance 3 / uncited_streak 0 / demoted_at cleared, promoted by the session
- *   that WROTE THIS PARAGRAPH: `#10716` occurs 21 times in that session's assistant text,
- *   extractCitationsFromTranscript scans assistant text for `#NN`, and applyCitationDecay
- *   promotes on a hit. Discussing a memory is indistinguishable from applying it here.
- *   Anything in this file that quotes live decay STATE is therefore perturbed by being
- *   written down; quote it with a timestamp, and prefer the structural claim (the marginal
- *   population is not all importance = 3) to the row that demonstrated it.
+ *   THAT ROW WAS NO LONGER IN THAT STATE, AND AT THE TIME THE REASON WAS THIS LOOP (D#179).
+ *   #10716 read importance 3 / uncited_streak 0 / demoted_at cleared, promoted by the
+ *   session that WROTE THIS PARAGRAPH: `#10716` occurs 21 times in that session's assistant
+ *   text, extractCitationsFromTranscript scans assistant text for `#NN`, and at that time
+ *   applyCitationDecay raised `importance` on a hit. Discussing a memory was
+ *   indistinguishable from applying it.
+ *
+ *   CORRECTED (v3.88.0, D#179/D#198): that mechanism is gone. Neither branch of this loop
+ *   writes `importance` any more, so citing a row cannot promote it HERE and the specific
+ *   self-promotion described above can no longer occur. Two things still hold and are the
+ *   reason the paragraph is kept rather than deleted. The general warning stands — anything
+ *   in this file quoting live decay STATE is perturbed by being written down, since the
+ *   loop still writes `cited_count`, `uncited_streak`, `demoted_at` and the session
+ *   columns on a citation — so quote it with a timestamp and prefer the structural claim
+ *   (the marginal population is not all importance = 3) to the row that demonstrated it.
+ *   And a citation can still reach `importance` by a SECOND path this loop does not own:
+ *   `bumpCitationAccess` credits `access_count`, and the `boost` maintain op raises
+ *   `importance` by 1 above `access_count > 3` (D#206, open).
  *
  *   Cross-crediting — a main-face id the main thread never cited but a subagent did — is
  *   3 pairs. The denominator giving 0.25% is DISTINCT (session,id) across the five decay
@@ -1170,54 +1182,40 @@ export function hasMainThreadAssistantText(transcriptPath) {
   return false;
 }
 
-const IMPORTANCE_CAP = 3;
-// Demote floor = 1, NOT 0. Both passive injection surfaces exclude importance 0
-// (pre-tool-recall.js requires >=2, user-prompt-search.js requires >=1), so a row
-// demoted to 0 can never be re-injected → never re-cited → never recovers: a one-way
-// burial that silently hides lesson-bearing rows the "lessons never auto-GC" guards
-// (maintain decayAndMarkIdle + compress-core) protect on every other path. Floor 1
-// keeps a decayed row on the >=1 surface with a citation-recovery path. Genuine noise
-// still sinks via maintain's PENDING_PURGE pipeline, which keys on compressed_into
-// (not importance) over injection_count=0 rows — a disjoint population from these
-// injected-but-uncited rows — so noise GC is unaffected.
-const IMPORTANCE_FLOOR = 1;
+// IMPORTANCE_CAP (3) and IMPORTANCE_FLOOR (1) lived here until D#179/D#198 took
+// `importance` out of this loop entirely; both are gone rather than kept unused.
+// The reasoning behind the FLOOR is preserved because it is the sharpest statement
+// of why decay must not move this column at all: both passive injection surfaces
+// exclude importance 0 (pre-tool-recall.js requires >= 2, user-prompt-search.js
+// requires >= 1), so a row demoted to 0 could never be re-injected -> never
+// re-cited -> never recover. The floor bounded that one-way burial at the bottom
+// of the scale; it could do nothing about the same mechanism one step up, where
+// a 3 -> 2 evicts a row from the `>= 3` tier arm of the Key Context pool. Genuine
+// noise still sinks via maintain's PENDING_PURGE pipeline, which keys on
+// compressed_into (not importance) over injection_count = 0 rows.
 const UNCITED_STREAK_THRESHOLD = 3;
 
-// Adoption-rate gate (P5 ②). A project's cite-rate is SUM(cited_count) /
-// SUM(decay_seen_count) over its non-superseded observations: of every decay
-// resolution this project has ever produced, what fraction were citations.
-// Below ADOPTION_THRESHOLD with at least ADOPTION_MIN_SEEN resolutions on record,
-// the project has demonstrably not adopted the #NN convention, so we suppress
-// DEMOTION (never promotion) — see the construct-validity note on
-// applyCitationDecay. MIN_SEEN keeps the gate dormant for low-data projects so
-// the established behavior is preserved until there's enough signal to judge.
-const ADOPTION_THRESHOLD = 0.02;
-const ADOPTION_MIN_SEEN = 8;
-
-/**
- * Compute a project's citation-adoption snapshot: total citations vs total decay
- * resolutions on record, and their ratio. Read-only; safe to call before the
- * decay transaction (the gate decision is made on the pre-mutation snapshot).
- *
- * @param {import('better-sqlite3').Database} db
- * @param {string} project
- * @returns {{cited: number, seen: number, rate: number}}
- */
-export function computeCitationAdoption(db, project) {
-  const empty = { cited: 0, seen: 0, rate: 0 };
-  if (!db || !project) return empty;
-  try {
-    const row = db.prepare(`
-      SELECT COALESCE(SUM(cited_count), 0)       AS cited,
-             COALESCE(SUM(decay_seen_count), 0)  AS seen
-        FROM observations
-       WHERE project = ? AND superseded_at IS NULL
-    `).get(project);
-    const cited = row?.cited || 0;
-    const seen = row?.seen || 0;
-    return { cited, seen, rate: seen > 0 ? cited / seen : 0 };
-  } catch (e) { debugCatch(e, 'computeCitationAdoption'); return empty; }
-}
+// The adoption-rate gate (P5 ②) lived here, with computeCitationAdoption feeding
+// it and a streak CAP as its other half. All three are gone — D#204.
+//
+// It suppressed the demote branch in a project whose cite-rate was ~0 over enough
+// resolutions, on the reasoning that such a project has not adopted the `#NN`
+// convention and a demotion there is a false negative it could never earn back.
+// That reasoning was entirely about `importance`, which D#179 removed from this
+// loop. What was left behind was inverted: the suppressed path capped
+// uncited_streak at threshold-1 and so never returned to 0 without a citation,
+// pinning those projects' rows at citeFactor 0.5x permanently, while an adopting
+// project's rolled back to 1.0x every third resolution. The gate written to be
+// gentler on non-adopting projects had become the only thing punishing them.
+//
+// The cap's stated purpose — keep the streak from climbing unbounded into the
+// citeFactor floor — is served by the rollover itself, and served better, since
+// the rollover also recovers. One path for every project.
+//
+// CLAUDE_MEM_CITATION_ADOPTION_THRESHOLD tuned the gate. It is now inert, and
+// warned about rather than silently ignored (see applyCitationDecay): a setting
+// that is accepted but means nothing is worse than one that is unsupported.
+let adoptionThresholdWarned = false;
 
 /**
  * D#61: a lesson injected live and then superseded mid-session (auto-dedup /
@@ -1264,8 +1262,49 @@ export function redirectSupersededIds(db, project, ids) {
  * Apply the citation-feedback loop for one session: for each injected obs id,
  * decide cited vs uncited and mutate importance/streak/cited_count per spec.
  *
- * - cited: importance += 1 (cap 3), cited_count += 1, streak = 0.
- * - uncited: streak += 1; if it reaches 3, importance -= 1 (floor 1, IMPORTANCE_FLOOR), streak = 0.
+ * - cited: cited_count += 1, streak = 0, demoted_at cleared.
+ * - uncited: streak += 1; if it reaches 3, streak = 0 and demoted_at is stamped.
+ *
+ * D#179 / D#198 — THIS LOOP NO LONGER WRITES `importance`, on any branch.
+ * `importance` was carrying two jobs at once: a relevance prior AND a
+ * pool-admission gate. Every injection surface gates on it — `>= 1` or `>= 2` on
+ * the prompt faces, and hook-context's Key Context tier arms use `>= 1 / >= 2 /
+ * >= 3` — so a decay-driven 3 -> 2 was not a down-rank, it removed the row from
+ * the candidate POPULATION. That is the D#172 shape, confirmed on the imperative
+ * pool (v3.82.0) and then on the Key Context pool, where 45 of ~106 pool rows sat
+ * in the band where one demotion is an eviction (D#198).
+ *
+ * The ranking half of the loop is unaffected and was never the problem:
+ * cited_count and uncited_streak still feed citeFactorClause, a BOUNDED
+ * [0.4, 3.0] pure multiplier. So the feedback loop still responds to observed
+ * agent behaviour — it just does so by re-ranking within the population instead
+ * of by changing who is in it. Given that no available signal separates "acted on
+ * this lesson" from "wrote about this lesson" (D#179; a release-note session
+ * promotes exactly the rows it discusses, and the mention/application split
+ * measured on the live corpus is not a bound in either direction), a bounded rank
+ * shift is the right cost for a mis-read citation. An eviction is not.
+ *
+ * NOT covered by this change, and stated so nobody reads it as "citations can no
+ * longer move importance": `bumpCitationAccess` credits `access_count`, and the
+ * `boost` maintain op lifts `importance + 1` above `access_count > 3`. That is a
+ * SECOND, independent citation -> importance path (obs #10911, D#206).
+ *
+ * Scope it correctly — an earlier version of this paragraph said "for any `#NN` in
+ * assistant text", which has been false since v3.84.0 (f9a9eae). The credit is gated
+ * on `buildCitationRelevanceSet`: the id must have been injected on one of the five
+ * attachment faces, or by Key Context, or into a subagent, or typed by the user. A
+ * bare mention of an id you were never shown credits nothing, and the revert switch
+ * is CLAUDE_MEM_CITATION_RELEVANCE_GATE=off. What the gate does NOT ask is whether
+ * you acted on the lesson — an injected id named only in prose is still credited —
+ * which is why the path is open rather than closed.
+ *
+ * Measured before deciding to leave it (2026-09-02, live DB + 98 transcripts): 52
+ * rows are currently boost-eligible; 25 of them are cited nowhere in the corpus, and
+ * at most 3 could have crossed `access_count > 3` on citations even under an upper
+ * bound that ignores the gate entirely. So the path is real and its effect is small.
+ * It is untouched here because `access_count` has other writers (explicit recall /
+ * get / timeline) and is also an input to noisePenaltyClause, so changing it is a
+ * different decision with a different blast radius.
  * - per-(session, obs) idempotent via last_decided_session_id; re-running for
  *   the same session is a no-op (Stop hook may fire more than once).
  * - cross-project IDs are silently ignored by the WHERE clause.
@@ -1277,13 +1316,17 @@ export function redirectSupersededIds(db, project, ids) {
  *   2. (cite-back) the agent edited a file a prior lesson #NN had warned about —
  *      unioned into citedIds by the Stop handler before this call.
  * Signal 2 was added because signal 1 alone penalizes projects that act on a
- * lesson without typing its id. Even so, both are proxies. For a project that has
- * never cited anything (cite-rate below ADOPTION_THRESHOLD over ≥ADOPTION_MIN_SEEN
- * resolutions), demotion is suppressed: absent any positive signal we cannot
- * distinguish "useless lesson" from "useful lesson in a project that doesn't use
- * the #NN convention," and a false demotion is the costlier error. The gate trades
- * missed demotions (stale lessons linger) for avoided false demotions. Promotion
- * is never gated — a single citation lifts the project's rate and re-enables decay.
+ * lesson without typing its id. Even so, both are proxies, and nothing available
+ * separates "acted on this lesson" from "wrote about this lesson".
+ *
+ * That imprecision used to be answered with a per-project adoption gate that
+ * suppressed demotion where the cite-rate was ~0. It is gone (D#204), because the
+ * cost it was insuring against — losing `importance`, i.e. dropping out of the
+ * candidate pool — is gone too (D#179). What the proxies can still get wrong is
+ * bounded on its own: a mis-read citation moves citeFactorClause within
+ * [0.4, 3.0] and nothing else. The uncited streak rolls over at
+ * UNCITED_STREAK_THRESHOLD in every project, so a lesson in a project that never
+ * types `#NN` is not driven monotonically downward — it oscillates and recovers.
  *
  * @param {import('better-sqlite3').Database} db
  * @param {string} project
@@ -1303,16 +1346,22 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
   injected = redirectSupersededIds(db, project, injected);
   cited = redirectSupersededIds(db, project, cited);
 
-  // Adoption gate (snapshot taken before any mutation this run). Suppress only
-  // demotion; promotion always proceeds. Threshold overridable via env.
-  const adoption = computeCitationAdoption(db, project);
-  const envThreshold = Number.parseFloat(process.env.CLAUDE_MEM_CITATION_ADOPTION_THRESHOLD);
-  const adoptionThreshold = Number.isFinite(envThreshold) && envThreshold >= 0 ? envThreshold : ADOPTION_THRESHOLD;
-  const suppressDemotion = adoption.seen >= ADOPTION_MIN_SEEN && adoption.rate < adoptionThreshold;
+  // D#204: the adoption gate is gone. Its env override is still READ, once, only
+  // to say out loud that it no longer does anything — the alternative is a
+  // setting a user can configure and watch have no effect.
+  if (!adoptionThresholdWarned && process.env.CLAUDE_MEM_CITATION_ADOPTION_THRESHOLD !== undefined) {
+    adoptionThresholdWarned = true;
+    try {
+      process.stderr.write(
+        '[claude-mem-lite] CLAUDE_MEM_CITATION_ADOPTION_THRESHOLD is set but no longer has any effect — '
+        + 'the citation-decay adoption gate was removed (D#204). Unset it.\n'
+      );
+    } catch (e) { debugCatch(e, 'adoption-threshold-warn'); }
+  }
 
   const selectStmt = db.prepare(
-    // superseded_at IS NULL: mirror computeCitationAdoption + the 4 injection SELECTs so a
-    // row superseded mid-session (injected live, then auto-dedup supersedes it before this
+    // superseded_at IS NULL: mirror the 4 injection SELECTs so a row superseded
+    // mid-session (injected live, then auto-dedup supersedes it before this
     // decay resolves) is not decayed/streaked/mutated — defense-in-depth parity.
     'SELECT id, importance, uncited_streak, last_decided_session_id, last_cited_session_id FROM observations WHERE id = ? AND project = ? AND superseded_at IS NULL'
   );
@@ -1341,8 +1390,7 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
   // list would silently renumber if a clause were ever reordered.
   const updatePromote = db.prepare(`
     UPDATE observations
-       SET importance = MIN(@cap, COALESCE(importance, 1) + 1),
-           cited_count = cited_count + 1,
+       SET cited_count = cited_count + 1,
            uncited_streak = 0,
            demoted_at = NULL,
            last_decided_session_id = @session,
@@ -1361,22 +1409,16 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
            decay_seen_count = decay_seen_count + 1
      WHERE id = ?
   `);
-  // Suppressed (non-adopting) projects never demote, so uncited_streak would grow
-  // UNBOUNDED — and citeFactorClause penalizes -0.25*streak (floor 0.4), pinning every
-  // memory at the ranking floor with no recovery path. Cap at UNCITED_STREAK_THRESHOLD-1
-  // to hold the [0, threshold-1] steady state the scoring header asserts (in an adopting
-  // project the streak resets to 0 on demote, so the STORED value never exceeds 2).
-  const updateStreakCapped = db.prepare(`
-    UPDATE observations
-       SET uncited_streak = MIN(uncited_streak + 1, ?),
-           last_decided_session_id = ?,
-           decay_seen_count = decay_seen_count + 1
-     WHERE id = ?
-  `);
+  // D#179/D#198: this branch no longer touches `importance`. It is the STREAK
+  // ROLLOVER: at UNCITED_STREAK_THRESHOLD the streak resets to 0 and the moment
+  // is stamped in demoted_at. The name and the returned `demoted` counter are
+  // kept because both are load-bearing for callers and citation-stats; what
+  // changed is that the rollover is now a bookkeeping event, not a change of
+  // population membership. Resetting the streak (rather than pinning it) is what
+  // holds citeFactorClause's documented [0, threshold-1] steady state.
   const updateDemote = db.prepare(`
     UPDATE observations
-       SET importance = MAX(?, COALESCE(importance, 1) - 1),
-           uncited_streak = 0,
+       SET uncited_streak = 0,
            last_decided_session_id = ?,
            demoted_at = ?,
            decay_seen_count = decay_seen_count + 1
@@ -1403,7 +1445,7 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
         // decay_seen_count and the funnel's injected_n (cite-rate would read N/2, not N/1).
         const firstResolution = !decidedThisSession;
         updatePromote.run({
-          cap: IMPORTANCE_CAP, session: sessionId, seenInc: firstResolution ? 1 : 0, id,
+          session: sessionId, seenInc: firstResolution ? 1 : 0, id,
         });
         promoted++;
         if (firstResolution) touched++;
@@ -1413,15 +1455,12 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
         if (decidedThisSession) continue;
         touched++;
         const nextStreak = (row.uncited_streak || 0) + 1;
-        // Demote only when the streak is up AND the project has demonstrably
-        // adopted citations. A non-adopting project advances the streak (idempotent
-        // bookkeeping) but never loses importance — see construct-validity note.
-        if (nextStreak >= UNCITED_STREAK_THRESHOLD && !suppressDemotion) {
-          updateDemote.run(IMPORTANCE_FLOOR, sessionId, Date.now(), id);
+        // D#204: one path for every project. The rollover both bounds the streak
+        // (so citeFactorClause cannot sink toward its floor) and lets it recover
+        // to 0 without requiring a citation.
+        if (nextStreak >= UNCITED_STREAK_THRESHOLD) {
+          updateDemote.run(sessionId, Date.now(), id);
           demoted++;
-        } else if (suppressDemotion) {
-          // Never-demoting project: cap the streak so cite_factor can't sink to floor.
-          updateStreakCapped.run(UNCITED_STREAK_THRESHOLD - 1, sessionId, id);
         } else {
           updateStreakOnly.run(sessionId, id);
         }

package/lib/deferred-work.mjs

@@ -119,6 +119,55 @@ export function dropDeferred(db, id, reason) {
   return { changed: r.changes };
 }
 
+/**
+ * Reasons that mean "this item was FIXED", for which `defer drop` is the wrong
+ * verb — dropping loses the closed_by_obs_id link that `save --closes-deferred`
+ * would have written, and leaves the row indistinguishable from a genuinely
+ * rejected one (D#195; v3.86.0 dropped six fixed items this way).
+ *
+ * Deliberately a POSITIVE pattern for the fixed-shape, not a stop-list of
+ * rejection wordings: the set of ways to say "no longer relevant" is open-ended,
+ * the set of ways to say "done" is small. Advisory only — the drop still
+ * succeeds, so a false positive costs one line of output.
+ */
+// `closed` and `landed` are here because of the six real v3.86.0 mis-drops this
+// hint exists to prevent: their reason was "closed this round; fix + mutation-
+// verified binding test landed", which an earlier draft anchored on `fixed` and
+// `closed by` and therefore MISSED — the motivating case fell through its own
+// predicate. Bare `fix` is deliberately NOT here: "waiting for an upstream fix"
+// is a legitimate rejection and carries no veto word in English.
+const DROP_REASON_FIXED_RE = /\b(fixed|implemented|shipped|resolved|done|closed|landed)\b|修复|已实现|已完成|完成了|已发布|已解决/i;
+
+/**
+ * Negative-sense veto, applied to the WHOLE reason before the positive pattern.
+ *
+ * A lookbehind cannot do this job: the sense-carrying word is not adjacent to the
+ * keyword. "等待上游修复" (waiting for an upstream fix) puts 游 immediately before
+ * 修复, so `(?<![待未需])修复` still fires on it — measured, which is why the
+ * predicate is two-stage rather than one clever pattern. Suppression is the safe
+ * direction here: a missed hint costs nothing, a wrong hint trains the reader to
+ * ignore the line.
+ */
+// `wontfix` is spelled with no boundary after `wont`, so a plain `won'?t\b` misses the
+// single most common English way of writing this rejection and the hint then fires on
+// "resolved as wontfix" — the positive arm's `resolved` winning over a veto that never
+// ran. Matched explicitly rather than by loosening the boundary, which would also admit
+// `wonton`. (pre-tag review v3.88.0, correctness N4)
+const DROP_REASON_NOT_YET_RE = /\bwon'?tfix\b|\b(not|won'?t|cannot|can'?t|unable|pending|todo|blocked|waiting|obsolete|superseded|duplicate|irrelevant|refuted)\b|待|未|尚|需|无法|暂不|过时|重复|取代/i;
+
+/**
+ * @param {string} reason The drop reason about to be recorded.
+ * @returns {string|null} Advisory hint, or null when the reason does not look
+ *          like a completion.
+ */
+export function formatDropReasonHint(reason) {
+  if (typeof reason !== 'string') return null;
+  if (DROP_REASON_NOT_YET_RE.test(reason)) return null;
+  if (!DROP_REASON_FIXED_RE.test(reason)) return null;
+  return '⚠ that reason reads like the item was FIXED — prefer `save --closes-deferred D#<id>`, '
+    + 'which records status=done plus the closing observation id. `drop` records a rejection.';
+}
+
 /**
  * Fetch full deferred_work rows by raw id — ANY status, input order preserved,
  * missing ids omitted. This is the read half of the D# surface: `defer list`
@@ -161,6 +210,11 @@ export function formatDeferredDetail(row) {
   if (row.created_at_epoch) lines.push(`created: ${new Date(row.created_at_epoch).toISOString()}`);
   if (row.status === 'dropped' && row.drop_reason) lines.push(`drop_reason: ${row.drop_reason}`);
   if (row.status === 'done' && row.closed_by_obs_id) lines.push(`closed_by: #${row.closed_by_obs_id}`);
+  // D#195: a row re-closed out of 'dropped' keeps its drop_reason. Render it under
+  // a distinct label rather than dropping it from the view — the mis-drop is the
+  // part a later reader needs, and a `drop_reason:` line on a done row would read
+  // as a contradiction.
+  if (row.status === 'done' && row.drop_reason) lines.push(`previously_dropped: ${row.drop_reason}`);
   return lines.join('\n');
 }
 
@@ -258,18 +312,31 @@ export function formatDeferredSearchTrailer(rows, invokeHint) {
 
 /**
  * Resolve mixed ordinal (int) + raw-id ("D#<n>") tokens to real deferred_work
- * ids, validated against caller project + status='open'.
+ * ids, validated against caller project + an allowed status set.
  *
  * - bare integer N → ordinal-within-project (uses same ROW_NUMBER as listOpenWithOrdinal)
- * - "D#<n>" string → raw deferred_work.id; must belong to caller project AND be open
+ * - "D#<n>" string → raw deferred_work.id; must belong to caller project AND
+ *   carry an allowed status
+ *
+ * `allowStatuses` defaults to open-only, which is the DROP verb's policy and the
+ * historical behaviour of every caller. The CLOSE verb (`save --closes-deferred`)
+ * passes `['open', 'dropped']` per D#195: dropping an item that was actually
+ * fixed used to be a one-way gate, permanently losing the closed_by_obs_id link.
+ * 'done' is never allowed under either policy — re-closing would overwrite an
+ * existing obs link with a different one.
+ *
+ * Ordinals stay open-only under every policy: the ROW_NUMBER that defines them
+ * is computed over open rows, so a dropped row simply has no ordinal to name.
+ * Reaching one requires the explicit `D#<n>` form.
  *
  * @param {Database} db
  * @param {string} project Caller project (FK guard)
  * @param {Array<number|string>} tokens Mixed input
+ * @param {{allowStatuses?: string[]}} [opts]
  * @returns {number[]} Real deferred_work ids in input order
  * @throws {Error} On unresolvable input — error message names the offending token
  */
-export function resolveDeferredIds(db, project, tokens) {
+export function resolveDeferredIds(db, project, tokens, { allowStatuses = ['open'] } = {}) {
   if (!Array.isArray(tokens)) throw new Error('tokens must be an array');
   // Pre-load open list once for ordinal resolution (ROW_NUMBER snapshot stable
   // within this call so [1, 2] resolves consistently).
@@ -300,10 +367,11 @@ export function resolveDeferredIds(db, project, tokens) {
       if (row.project !== project) {
         throw new Error(`D#${id} belongs to project "${row.project}", not "${project}"`);
       }
-      if (row.status !== 'open') {
+      if (!allowStatuses.includes(row.status)) {
         // Verb-neutral: resolveDeferredIds is shared by close (save --closes-deferred)
         // AND drop (mem_defer_drop), so "cannot close" mis-described the drop path.
-        throw new Error(`D#${id} status is "${row.status}" — only 'open' items can be closed or dropped`);
+        const allowed = allowStatuses.map(s => `'${s}'`).join(' or ');
+        throw new Error(`D#${id} status is "${row.status}" — only ${allowed} items are accepted here`);
       }
     } else {
       throw new Error(`invalid token type ${typeof t} — expected D#N or integer ordinal`);
@@ -327,7 +395,7 @@ export function resolveDeferredIds(db, project, tokens) {
  * @param {Database} db
  * @param {number[]} ids Already-resolved real ids (use resolveDeferredIds first)
  * @param {number} closingObsId observations.id that proves closure
- * @throws {Error} If any id is not currently open (lookup-based safety net)
+ * @throws {Error} If any id is neither 'open' nor 'dropped' (lookup-based safety net)
  */
 export function closeDeferredItems(db, ids, closingObsId) {
   if (!Array.isArray(ids) || ids.length === 0) return;
@@ -337,17 +405,22 @@ export function closeDeferredItems(db, ids, closingObsId) {
   // Defense-in-depth: even if caller already validated via resolveDeferredIds,
   // re-check status here (caller may have done resolution earlier in the same
   // transaction without holding a lock).
+  //
+  // D#195: 'dropped' is closable. drop_reason is intentionally NOT cleared — the
+  // row's history is what makes a mis-drop auditable, and formatDeferredDetail
+  // renders it as `previously_dropped:` once the status is 'done'. 'done' stays
+  // excluded so a second close cannot overwrite an existing closed_by_obs_id.
   const stmt = db.prepare(`
     UPDATE deferred_work
     SET status='done', closed_at_epoch=?, closed_by_obs_id=?
-    WHERE id=? AND status='open'
+    WHERE id=? AND status IN ('open', 'dropped')
   `);
   const now = Date.now();
   const tx = db.transaction((idList) => {
     for (const id of idList) {
       const r = stmt.run(now, closingObsId, id);
       if (r.changes !== 1) {
-        throw new Error(`closeDeferredItems: id ${id} was not in 'open' status (changes=${r.changes})`);
+        throw new Error(`closeDeferredItems: id ${id} was not in a closable status ('open' or 'dropped') (changes=${r.changes})`);
       }
     }
   });

package/lib/events-injection.mjs

@@ -20,9 +20,20 @@
 // row is never mis-attributed to an observation id (which would let citation decay
 // mutate an unrelated observation sharing that id). Events carry no citation columns,
 // so they inject as reference-only — reachability, not decay bookkeeping.
+//
+// D#202: that paragraph was true of the faces it names and FALSE of the one it does
+// not. `scripts/pre-tool-recall.js` renders its own merged obs+event rows and used a
+// bare `#` for both, so nearly half of that channel's injected rows (44.9%, measured
+// over 4227 firings) were event ids entering the observation decay denominator —
+// exactly the mis-attribution this prefix exists to prevent. The invariant was stated
+// here while the face that broke it lived elsewhere and was not enumerated. The prefix
+// is now a shared constant (lib/injected-ids.mjs, a leaf so the hot PreToolUse path
+// need not pull this file's search-core chain) and
+// tests/pretool-event-id-namespace.test.mjs sweeps both renderers.
 
 import { searchEventsFts } from './search-core.mjs';
 import { neutralizeContextDelimiters } from '../format-utils.mjs';
+import { EVENT_ID_PREFIX } from './injected-ids.mjs';
 
 const DEFAULT_LIMIT = 3;
 const DEFAULT_MIN_IMPORTANCE = 2;
@@ -98,7 +109,7 @@ export function renderInjectableEvent(row) {
   // hook-llm.mjs behind `if (EVENT_TYPE_SET.has(summary.type))`), so it carries no
   // injection markers and is intentionally NOT defanged — mirrors the un-defanged
   // `[type]` for observations. If an unvalidated event writer is ever added, defang it.
-  const head = `E#${row.id} [${row.type}] ${title}`;
+  const head = `${EVENT_ID_PREFIX}${row.id} [${row.type}] ${title}`;
   if (row.lesson_learned) {
     const lesson = neutralizeContextDelimiters(row.lesson_learned.trim().slice(0, LESSON_MAX));
     if (lesson) return `${head} — ${lesson}`;

package/lib/injected-ids.mjs

@@ -95,6 +95,23 @@ export function injectedIdKey(id, src = 'obs') {
   return src === 'evt' ? `E${id}` : String(id);
 }
 
+/**
+ * DISPLAY prefix for an event id rendered into an injected line, as opposed to
+ * `injectedIdKey` above, which namespaces the same id inside the marker FILE.
+ * Two forms of one convention: the marker key is `E<id>` (no `#`, it is not
+ * citable text), the rendered token is `E#<id>` (the `#` is what makes an id
+ * look like an id to a reader).
+ *
+ * It lives in this leaf module — rather than beside either renderer — because
+ * D#202 was exactly the two renderers not agreeing. lib/events-injection.mjs
+ * had the `E#` convention and a header explaining it; scripts/pre-tool-recall.js
+ * rendered its own merged obs+event rows with a bare `#`, putting 44.9% of that
+ * channel's ids into the observation citation-decay denominator. Importing from
+ * here also keeps the hot PreToolUse path off events-injection.mjs's
+ * search-core.mjs dependency chain.
+ */
+export const EVENT_ID_PREFIX = 'E#';
+
 /**
  * Runtime-dir FILE NAME for the SessionStart Key Context marker: the obs ids
  * ACTUALLY rendered into the <claude-mem-context> File Lessons / Key Context

package/lib/maintain-core.mjs

@@ -265,8 +265,10 @@ export function recoverOrphanedChildren(db, { projectFilter = '', baseParams = [
   `).run(...baseParams).changes;
 }
 
-// Heal lesson-bearing rows that citation-decay buried at importance 0 under the old
-// IMPORTANCE_FLOOR=0 (fixed in citation-tracker.mjs → floor 1). All passive injection
+// Heal lesson-bearing rows that citation-decay buried at importance 0 back when its floor
+// was 0. That loop was later given a floor of 1, and as of D#179/D#198 it does not write
+// `importance` on any branch at all — so this op no longer has an active producer and only
+// drains the historical backlog. Keep it: nothing else lifts a stranded 0. All passive injection
 // surfaces exclude importance 0 (pre-tool-recall >=2, user-prompt-search >=1, memory-context
 // >=1), so a lesson demoted there is invisible AND — being injection_count>0 by construction
 // — sits in no GC queue either (decayAndMarkIdle only marks injection_count=0 rows): stranded

package/lib/save-observation.mjs

@@ -18,6 +18,31 @@ import { insertObservationRow, insertObservationFiles, insertObservationVector }
 const DEDUP_WINDOW_MS = 5 * 60 * 1000;
 const DEDUP_RECENT_LIMIT = 50;
 
+/** Human-readable cause per `supersedeSkipped` reason (D#201). */
+const SUPERSEDE_SKIP_CAUSE = {
+  'malformed-id': 'not a positive integer id',
+  'no-such-observation': 'no observation with that id',
+  'other-project': 'belongs to a different project',
+  'already-superseded': 'already superseded (no-op)',
+  'duplicate-save': 'the save deduped, so nothing was superseded',
+};
+
+/**
+ * Render the D#201 warning for requested-but-not-superseded ids. Lives here
+ * rather than in either face so the CLI and the MCP tool cannot word it
+ * differently or, more to the point, so one of them cannot quietly stop
+ * rendering it.
+ *
+ * @param {Array<{id: any, reason: string}>} [skipped]
+ * @returns {string|null} null when nothing was skipped
+ */
+export function formatSupersedeSkipped(skipped) {
+  if (!Array.isArray(skipped) || skipped.length === 0) return null;
+  const parts = skipped.map(({ id, reason }) =>
+    `#${id} (${SUPERSEDE_SKIP_CAUSE[reason] || reason})`);
+  return `⚠ --supersedes: ${parts.length} id(s) NOT superseded — ${parts.join(', ')}.`;
+}
+
 /**
  * Save a new observation if it isn't a near-duplicate of one saved within the
  * last 5 minutes (Jaccard similarity > 0.7 on title or content).
@@ -32,8 +57,18 @@ const DEDUP_RECENT_LIMIT = 50;
  * @param {string[]} [params.files=[]]            File paths to attach (junction table).
  * @param {string|null} [params.lesson_learned]   Caller validates ≤500 chars.
  * @param {Date}   [params.now]                   Override for tests.
- * @returns {{ kind: 'duplicate', existingId: number, project: string, type: string }
- *          | { kind: 'saved', id: number, type: string, project: string, title: string, lessonCaptured: boolean }}
+ * Both result shapes carry `supersededIds` (what was actually tombstoned) and
+ * `supersedeSkipped` (requested but NOT tombstoned, each with a `reason`:
+ * `malformed-id` | `no-such-observation` | `other-project` |
+ * `already-superseded` | `duplicate-save`). Callers MUST surface a non-empty
+ * `supersedeSkipped` — that is the whole point of D#201; dropping it puts the
+ * silent failure back.
+ *
+ * @returns {{ kind: 'duplicate', existingId: number, project: string, type: string,
+ *             supersededIds: number[], supersedeSkipped: Array<{id: any, reason: string}> }
+ *          | { kind: 'saved', id: number, type: string, project: string, title: string,
+ *              lessonCaptured: boolean, supersededIds: number[],
+ *              supersedeSkipped: Array<{id: any, reason: string}> }}
  */
 export function saveObservation(db, params) {
   const now = params.now instanceof Date ? params.now : new Date();
@@ -83,12 +118,42 @@ export function saveObservation(db, params) {
     ORDER BY created_at_epoch DESC LIMIT ?
   `).all(project, dedupCutoff, DEDUP_RECENT_LIMIT);
 
+  // Requested supersession targets, normalized. Declared BEFORE the dedup
+  // short-circuit because that path reports on them too.
+  // Self-reference is filtered inside the transaction, once the new id exists.
+  //
+  // D#201: the tokens that DON'T survive normalization are kept, not dropped.
+  // A caller who names an id and gets no supersession has to be told which id
+  // and why — the previous shape reported "requested 4, superseded 0" and
+  // "requested nothing" identically, so a mistyped or wrong-table id read as a
+  // clean success. `malformed-id` is the pre-query class; the DB-level classes
+  // are decided inside the transaction.
+  const rawSupersedes = Array.isArray(params.supersedes) ? params.supersedes : [];
+  const requestedSupersedes = [...new Set(
+    rawSupersedes.map(Number).filter((n) => Number.isInteger(n) && n > 0)
+  )];
+  const malformedSupersedes = rawSupersedes
+    .filter((t) => { const n = Number(t); return !(Number.isInteger(n) && n > 0); })
+    .map((t) => ({ id: t, reason: 'malformed-id' }));
+
   const dupMatch = recent.find((r) =>
     jaccardSimilarity(r.title, safeTitle) > DEDUP_JACCARD_THRESHOLD ||
     jaccardSimilarity(r.text || '', safeContent) > DEDUP_JACCARD_THRESHOLD
   );
   if (dupMatch) {
-    return { kind: 'duplicate', existingId: dupMatch.id, project, type };
+    // D#201: a dedup short-circuit swallows the requested supersession too — you
+    // write a correction, it reads as a near-duplicate of something saved in the
+    // last 5 minutes, and the rows you meant to retire stay live. Same sentence
+    // as the ineligible-id case ("requested, did not happen, no trace"), so it
+    // reports through the same channel rather than staying quiet.
+    return {
+      kind: 'duplicate', existingId: dupMatch.id, project, type,
+      supersededIds: [],
+      supersedeSkipped: [
+        ...malformedSupersedes,
+        ...requestedSupersedes.map((id) => ({ id, reason: 'duplicate-save' })),
+      ],
+    };
   }
 
   // FTS-indexed text field includes title + content + lesson + CJK bigrams,
@@ -99,13 +164,6 @@ export function saveObservation(db, params) {
   const bigramText = cjkBigrams(indexText);
   const textField = bigramText ? safeContent + ' ' + bigramText : safeContent;
 
-  // Requested supersession targets, normalized before the transaction opens.
-  // Self-reference is filtered inside, once the new id exists.
-  const requestedSupersedes = [...new Set(
-    (Array.isArray(params.supersedes) ? params.supersedes : [])
-      .map(Number).filter((n) => Number.isInteger(n) && n > 0)
-  )];
-
   // Atomic: observation row + observation_files junction + observation_vectors
   // (TF-IDF) + supersession tombstones. Vector write is best-effort — vocab may be
   // uninitialized on a fresh DB; failure must not roll back the observation.
@@ -139,6 +197,7 @@ export function saveObservation(db, params) {
     // Write-the-correction and retire-its-predecessors is one unit or neither.
     const ids = requestedSupersedes.filter((n) => n !== savedId);
     let supersededIds = [];
+    const skipped = [];
     if (ids.length > 0) {
       const ph = ids.map(() => '?').join(',');
       const eligible = db.prepare(
@@ -150,11 +209,30 @@ export function saveObservation(db, params) {
           .run(now.getTime(), savedId, ...eligible);
         supersededIds = eligible;
       }
+      // D#201: classify the difference instead of discarding it. One extra
+      // SELECT, and only when something actually failed to land — the happy
+      // path (every id eligible) skips it entirely.
+      const landed = new Set(eligible);
+      const missed = ids.filter((n) => !landed.has(n));
+      if (missed.length > 0) {
+        const ph3 = missed.map(() => '?').join(',');
+        const rows = new Map(db.prepare(
+          `SELECT id, project, superseded_at FROM observations WHERE id IN (${ph3})`
+        ).all(...missed).map((r) => [r.id, r]));
+        for (const n of missed) {
+          const row = rows.get(n);
+          // Order matters: a row can be BOTH foreign-project and already
+          // superseded, and "it isn't yours" is the more actionable of the two.
+          if (!row) skipped.push({ id: n, reason: 'no-such-observation' });
+          else if (row.project !== project) skipped.push({ id: n, reason: 'other-project' });
+          else skipped.push({ id: n, reason: 'already-superseded' });
+        }
+      }
     }
 
-    return { savedId, supersededIds };
+    return { savedId, supersededIds, skipped };
   });
-  const { savedId, supersededIds } = saveTx();
+  const { savedId, supersededIds, skipped } = saveTx();
 
   return {
     kind: 'saved',
@@ -164,5 +242,9 @@ export function saveObservation(db, params) {
     title: safeTitle,
     lessonCaptured: Boolean(safeLesson),
     supersededIds,
+    // D#201: requested-but-not-superseded, with a reason each. Malformed tokens
+    // are prepended because they were rejected before the query and so carry the
+    // caller's ORIGINAL token (which may not even be a number) rather than an id.
+    supersedeSkipped: [...malformedSupersedes, ...skipped],
   };
 }

package/mem-cli.mjs

@@ -55,7 +55,7 @@ import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
 import { isNativeBindingError, healAndReexec } from './lib/binding-probe.mjs';
 import { CLI_PATH, CLI_INVOKE } from './cli-path.mjs';
 import { parseArgs, out, outVerbatim, fail, relativeTime, fmtDateShort, parseIdToken, formatProbeHints, rejectBareStringFlags, resolvePositionalAlias, suggestUnknownFlags, OBS_TIME_FIELDS, formatObsFieldValue, obsFieldLabel, formatPendingPurgeLine } from './cli/common.mjs';
-import { saveObservation } from './lib/save-observation.mjs';
+import { saveObservation, formatSupersedeSkipped } from './lib/save-observation.mjs';
 import { normalizeScope, insertObservationVector, applyObsUpdate } from './lib/observation-write.mjs';
 import { EXPORT_COLUMNS_SQL } from './lib/export-columns.mjs';
 import { recallByFile } from './lib/recall-core.mjs';
@@ -80,7 +80,7 @@ const SURFACE_LABELS = {
 };
 import { aggregateMetrics, readMetrics } from './lib/metrics.mjs';
 import {
-  insertDeferred, listOpenWithOrdinal, dropDeferred,
+  insertDeferred, listOpenWithOrdinal, dropDeferred, formatDropReasonHint,
   resolveDeferredIds, closeDeferredItems,
   getDeferredByIds, formatDeferredDetail,
   searchDeferredWork, formatDeferredSearchTrailer,
@@ -955,8 +955,13 @@ function cmdSave(db, args) {
   let supersedesIds = null;
   if (flags.supersedes !== undefined && flags.supersedes !== false) {
     const raw = String(flags.supersedes);
-    supersedesIds = raw.split(',').map(t => t.trim()).filter(Boolean)
-      .map(t => parseInt(t, 10)).filter(n => Number.isInteger(n) && n > 0);
+    // Tokens go through UNPARSED so saveObservation's classifier — not parseInt — decides
+    // what is malformed. parseInt is lenient in the one direction that costs data: it read
+    // `1abc` as 1, so a typo (`875x` for `8754`) tombstoned an unrelated observation and
+    // printed a clean `Superseded: #1.` Worse, the token vanished before saveObservation
+    // saw it, which made the `malformed-id` class D#201 added unreachable from the CLI —
+    // the exact face whose silence motivated D#201. Number() rejects `1abc` as NaN.
+    supersedesIds = raw.split(',').map((t) => t.trim()).filter(Boolean);
     if (supersedesIds.length === 0) {
       fail('[mem] --supersedes requires at least one positive observation id (e.g. --supersedes 8754,8771)');
       return;
@@ -984,7 +989,11 @@ function cmdSave(db, args) {
       // the deferred row has transitioned out of 'open'.
       if (r.kind === 'duplicate') return r;
       if (closesTokens) {
-        closesIds = resolveDeferredIds(db, project, closesTokens);
+        // D#195: the close verb accepts a 'dropped' row and converts it to
+        // 'done'. `defer drop` used on an item that was actually fixed was
+        // otherwise a one-way gate, permanently losing the obs link. Kept in
+        // sync with the same policy in server.mjs mem_save.
+        closesIds = resolveDeferredIds(db, project, closesTokens, { allowStatuses: ['open', 'dropped'] });
         closeDeferredItems(db, closesIds, r.id);
       }
       return r;
@@ -1000,6 +1009,10 @@ function cmdSave(db, args) {
 
   if (result.kind === 'duplicate') {
     out(`[mem] Skipped: similar to existing #${result.existingId}. Use "claude-mem-lite get ${result.existingId}" to review.`);
+    // D#201: the dedup swallowed the requested supersession too — say so here,
+    // because this branch returns before the note below is ever reached.
+    const dupSkip = formatSupersedeSkipped(result.supersedeSkipped);
+    if (dupSkip) out(`[mem] ${dupSkip}`);
     return;
   }
 
@@ -1015,6 +1028,10 @@ function cmdSave(db, args) {
   const enrichNote = shouldQueueSaveEnrich(result) && queueSaveEnrich(result.id)
     ? ' (background enrichment queued)' : '';
   out(`[mem] Saved #${result.id} [${result.type}] "${truncate(result.title, 80)}" (project: ${result.project})${lessonNote}${closedNote}${supersededNote}${enrichNote}${buildLessonNudge({ type: result.type, id: result.id, lessonCaptured: result.lessonCaptured, surface: 'cli' })}`);
+  // D#201: on its OWN line, after the success line. Appending it to the success
+  // string would put a warning inside a sentence that reads as "done".
+  const skipNote = formatSupersedeSkipped(result.supersedeSkipped);
+  if (skipNote) out(`[mem] ${skipNote}`);
 }
 
 // ─── cmdDefer (sub-dispatch: add | list | drop) ──────────────────────────────
@@ -1149,6 +1166,12 @@ function cmdDeferDrop(db, args) {
   if (noop.length > 0) {
     out(`[mem] No-op (not in 'open' status): ${noop.map(id => `D#${id}`).join(', ')}`);
   }
+  // D#195 (c): catch the mis-drop at the moment it happens, not months later
+  // when the ledger can no longer tell a fixed item from a rejected one.
+  if (dropped.length > 0) {
+    const hint = formatDropReasonHint(reason);
+    if (hint) out(`[mem] ${hint}`);
+  }
 }
 
 // N-1: Quality-focused stats for R-2 A/B baseline.
@@ -2540,10 +2563,19 @@ function cmdCitationStats(db, args) {
      LIMIT 20
   `).all();
 
+  // D#179/D#198, second half: the sibling `demoted` caption below was re-worded when the
+  // decay loop stopped writing `importance`, and this one was not — the same "the copy I
+  // fixed was not the only copy" shape the batch's own sweeps exist to prevent. Gating on
+  // `importance >= 3` made the section structurally empty for anything the loop produces:
+  // a row cited in ten sessions now has cited_count = 10 and whatever importance it was
+  // saved with, so the section degenerated into "rows that were already at 3" under a
+  // caption reading "promoted". The discriminator is now the pair the promote branch
+  // actually writes (`cited_count + 1`, `uncited_streak = 0`); `importance` is still
+  // SELECTed and printed, so a reader can see it is unrelated.
   const promoted = db.prepare(`
     SELECT id, project, type, title, importance, cited_count
       FROM observations
-     WHERE importance >= 3 AND cited_count >= 1
+     WHERE cited_count >= 1 AND COALESCE(uncited_streak, 0) = 0
        AND ${liveObsFilterSql('')}
   ORDER BY cited_count DESC
      LIMIT 10
@@ -2665,19 +2697,23 @@ function cmdCitationStats(db, args) {
     }
   }
   out('');
-  out('Active decay queue (uncited_streak >= 2, next miss → demote):');
+  out('Active decay queue (uncited_streak >= 2, next miss → rollover):');
   if (decayQueue.length === 0) out('  (none)');
   for (const r of decayQueue) {
     out(`  #${r.id} [${r.type}] ${(r.title || '').slice(0, 60)}   imp=${r.importance} streak=${r.uncited_streak}`);
   }
   out('');
-  out('Recently promoted (importance=3, cited_count >= 1):');
+  out('Recently cited (cited_count >= 1, streak reset; importance unaffected):');
   if (promoted.length === 0) out('  (none)');
   for (const r of promoted) {
     out(`  #${r.id} [${r.type}] ${(r.title || '').slice(0, 60)}   cited ${r.cited_count}x`);
   }
   out('');
-  out(`Recently demoted (last ${days}d, importance ↓):`);
+  // D#179/D#198: demoted_at now stamps the UNCITED-STREAK ROLLOVER, which no
+  // longer lowers importance. The old label ("importance ↓") would describe a
+  // write that stopped happening while the column beside it kept printing the
+  // row's unchanged value — a caption contradicting its own table.
+  out(`Recently rolled over (last ${days}d, uncited streak reset; importance unaffected):`);
   if (demoted.length === 0) out('  (none)');
   for (const r of demoted) {
     const ago = Math.round((Date.now() - r.demoted_at) / DAY_MS);

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.87.0",
+  "version": "3.88.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.87.0",
+      "version": "3.88.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.87.0",
+  "version": "3.88.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",

package/scoring-sql.mjs

@@ -185,11 +185,21 @@ export function notLowSignalTitleClause(alias = 'o') {
 //
 // Closes the citation-decay → ranking loop. The Stop hook citation-decay
 // already maintains cited_count (Promote on cite) and uncited_streak (bump on
-// uncited; reset on cite or demote-at-3). Before A1, both columns affected
+// uncited; reset on cite or rollover-at-3). Before A1, both columns affected
 // only the importance ±1 dial — through `(0.5 + 0.5·importance)` that's a
 // ≤2× swing and saturates fast. This factor lets ranking respond directly to
 // observed agent behavior on the obs itself.
 //
+// D#179/D#198 made this factor the ONLY thing citation-decay feeds: that loop
+// no longer writes `importance` at all. The reason is that importance is not a
+// ranking dial — every injection surface gates candidacy on it, so moving it
+// changed WHO IS IN the pool rather than where they ranked. This clause is the
+// right home for the signal precisely because it is bounded and pure-ranking:
+// a mis-read citation costs at most a 3.0× / 0.4× rank shift and can never
+// evict a row. (A second, independent citation → importance path still exists
+// via bumpCitationAccess → access_count → the `boost` maintain op; see obs
+// #10911. It is out of this clause's scope and is NOT closed.)
+//
 // Formula: clamp(0.4, 3.0, 1 + 0.2·cited_count − 0.25·uncited_streak)
 // Distribution:
 //   cited=0, streak=0  → 1.0  (fresh obs, neutral)

package/scripts/pre-tool-recall.js

@@ -8,7 +8,7 @@ import { existsSync, readFileSync, mkdirSync } from 'fs';
 import { basename, join } from 'path';
 import { resolveDataDir } from '../lib/resolve-data-dir.mjs';
 import { atomicWriteFileSync } from '../lib/atomic-write.mjs';
-import { injectedIdsFileName, injectedIdKey } from '../lib/injected-ids.mjs';
+import { injectedIdsFileName, injectedIdKey, EVENT_ID_PREFIX } from '../lib/injected-ids.mjs';
 import { liveObsFilterSql } from '../lib/inject-search-core.mjs';
 import { buildNotLowSignalSql } from '../lib/low-signal-patterns.mjs';
 import { recordHookError } from '../lib/hook-telemetry.mjs';
@@ -660,17 +660,36 @@ try {
     if (fileIntelLine) lines.push(neutralizeContextDelimiters(fileIntelLine));
     if (hasLessons) {
       lines.push(`[mem] Lessons for ${fname}:`);
+      // D#202: this block merges TWO TABLES and rendered both with a bare `#NN`.
+      // lib/events-injection.mjs already established the `E#` prefix for exactly
+      // this reason, and its header even enumerates the extractors the prefix
+      // protects — FYI, memory-context, error-recall. It does not name THIS face,
+      // which is the one that was breaking the invariant.
+      //
+      // Measured on the live metrics log (4227 `pretool_recall` firings,
+      // 2026-07-18 -> 2026-09-02): 44.9% of the rows injected here are
+      // event-sourced and 40.2% of firings inject events only. Two costs:
+      //   * a reader cannot tell which table to follow an id into — a
+      //     `--supersedes` or `mem_get` on one fails for no visible reason;
+      //   * load-bearing: extractInjectedFromPreToolUse reads these ids into the
+      //     citation-decay DENOMINATOR, and applyCitationDecay resolves them
+      //     against `observations` alone, so an event id colliding with a live
+      //     SAME-PROJECT observation streaked or promoted an unrelated memory.
+      //     198 of 5476 injectable events (3.6%) sit in that position.
+      // The `E#` prefix closes the second by construction: INJECTED_ROW_RE
+      // anchors `#` after at most six spaces, so `E#` cannot match it.
       for (const r of allRows) {
+        const idTag = `${r.src === 'evt' ? EVENT_ID_PREFIX : '#'}${r.id}`;
         if (r.lesson_learned) {
           const lesson = r.lesson_learned.length > LESSON_MAX
             ? r.lesson_learned.slice(0, LESSON_MAX - 3) + '...'
             : r.lesson_learned;
-          lines.push(`  #${r.id} [${r.type}] ${neutralizeContextDelimiters(lesson)}`);
+          lines.push(`  ${idTag} [${r.type}] ${neutralizeContextDelimiters(lesson)}`);
         } else {
           const title = (r.title || '').length > LESSON_MAX
             ? r.title.slice(0, LESSON_MAX - 3) + '...'
             : (r.title || '');
-          lines.push(`  #${r.id} [${r.type}] ${neutralizeContextDelimiters(title)}`);
+          lines.push(`  ${idTag} [${r.type}] ${neutralizeContextDelimiters(title)}`);
         }
       }
       // v2.98 salience: Edit/Write is the action point — close the block with an

package/server.mjs

@@ -50,7 +50,7 @@ import { ensureRegistryDb, collectRegistryStats, listResourcesRanked, formatRegi
 import { IMPORT_STRING_FIELDS, importResource, removeResource, reindexResources } from './lib/registry-core.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { probeOtherSources as probeIdSources, bucketIdTokens, splitDeferredTokens } from './lib/id-routing.mjs';
-import { saveObservation } from './lib/save-observation.mjs';
+import { saveObservation, formatSupersedeSkipped } from './lib/save-observation.mjs';
 import { applyObsUpdate } from './lib/observation-write.mjs';
 import { EXPORT_COLUMNS_SQL } from './lib/export-columns.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
@@ -58,7 +58,7 @@ import { recallByFile } from './lib/recall-core.mjs';
 import { fetchRecent } from './lib/recent-core.mjs';
 import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import {
-  insertDeferred, listOpenWithOrdinal, dropDeferred,
+  insertDeferred, listOpenWithOrdinal, dropDeferred, formatDropReasonHint,
   resolveDeferredIds, closeDeferredItems,
   getDeferredByIds, formatDeferredDetail,
   searchDeferredWork, formatDeferredSearchTrailer,
@@ -853,7 +853,9 @@ server.registerTool(
         // Resolve INSIDE tx + after dedup check so duplicate replays don't throw on
         // already-closed items. Mirrors mem-cli.mjs cmdSave shape.
         if (args.closes_deferred && args.closes_deferred.length > 0) {
-          closesIds = resolveDeferredIds(db, project, args.closes_deferred);
+          // D#195: 'dropped' is closable by the close verb (kept in sync with
+          // mem-cli.mjs cmdSave — same policy, both faces).
+          closesIds = resolveDeferredIds(db, project, args.closes_deferred, { allowStatuses: ['open', 'dropped'] });
           closeDeferredItems(db, closesIds, r.id);
         }
         return r;
@@ -869,7 +871,10 @@ server.registerTool(
     }
 
     if (result.kind === 'duplicate') {
-      return { content: [{ type: 'text', text: `Skipped: similar to existing #${result.existingId} in project "${project}". Use mem_get(ids=[${result.existingId}]) to review.` }] };
+      // D#201: this branch returns before the note below, so it renders its own.
+      const dupSkip = formatSupersedeSkipped(result.supersedeSkipped);
+      const dupText = `Skipped: similar to existing #${result.existingId} in project "${project}". Use mem_get(ids=[${result.existingId}]) to review.`;
+      return { content: [{ type: 'text', text: dupSkip ? `${dupText}\n${dupSkip}` : dupText }] };
     }
 
     const lessonNote = result.lessonCaptured ? ` 💡lesson captured` : '';
@@ -884,7 +889,10 @@ server.registerTool(
     // every save) — fill-only-empty, so an agent acting on the nudge still wins.
     const enrichNote = shouldQueueSaveEnrich(result) && queueSaveEnrich(result.id)
       ? ' (background enrichment queued)' : '';
-    return { content: [{ type: 'text', text: `Saved as observation #${result.id} [${result.type}] in project "${project}".${lessonNote}${closedNote}${supersededNote}${enrichNote}${nudge}` }] };
+    // D#201: on its own line rather than inside the success sentence.
+    const skipNote = formatSupersedeSkipped(result.supersedeSkipped);
+    const savedText = `Saved as observation #${result.id} [${result.type}] in project "${project}".${lessonNote}${closedNote}${supersededNote}${enrichNote}${nudge}`;
+    return { content: [{ type: 'text', text: skipNote ? `${savedText}\n${skipNote}` : savedText }] };
   })
 );
 
@@ -960,7 +968,11 @@ server.registerTool(
     if (r.changed === 0) {
       return { content: [{ type: 'text', text: `D#${realId} was not in 'open' status — drop is a no-op.` }] };
     }
-    return { content: [{ type: 'text', text: `Dropped D#${realId} in project "${project}". Reason: ${args.reason}` }] };
+    // D#195 (c): same advisory as the CLI's `defer drop`, so an agent reaching
+    // this through MCP gets the same steer toward `mem_save(closes_deferred)`.
+    const hint = formatDropReasonHint(args.reason);
+    const dropText = `Dropped D#${realId} in project "${project}". Reason: ${args.reason}`;
+    return { content: [{ type: 'text', text: hint ? `${dropText}\n${hint}` : dropText }] };
   })
 );