claude-mem-lite 3.82.0 → 3.83.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.82.0",
+      "version": "3.83.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.82.0",
+  "version": "3.83.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

@@ -827,7 +827,8 @@ benchmark and A/B harness are calibrated against — changing them invalidates t
 | `CLAUDE_MEM_AUTO_DEEP` | `0` disables automatic deep-search escalation (one Haiku call rewriting a weak query into keyword/concept/HyDE variants). Explicit `deep: true` still works. | _(auto)_ |
 | `CLAUDE_MEM_AUTO_DEEP_CLI` | `0` disables the same auto-escalation on the CLI path only. | _(auto)_ |
 | `CLAUDE_MEM_VECTORS` | `1` re-enables the persisted TF-IDF vector arm (off by default; also needs a vector rebuild via `maintain`). | _(off)_ |
-| `CLAUDE_MEM_SCOPE_FILTER` | `1` stops environment-scoped observations from firing on file-triggered recall. They stay reachable via search. | _(off)_ |
+| `CLAUDE_MEM_SCOPE_FILTER` | `1` stops environment-scoped observations from firing on file-triggered recall. They stay reachable via search. **Leave it off**: on the face it gates, `environment` is not the low-relevance class its premise assumes — it cites at least as well as `project` (47.5% vs 44.3%, intervals overlapping), and an earlier measurement left 173 recall groups empty with it on. | _(off)_ |
+| `CLAUDE_MEM_READS_CARRY` | An episode flush collects `reads-<project>.txt` only when it will actually save an observation, so a flush that records nothing no longer discards the Read paths it swept up (42.2% of the paths a flush consumed, measured over 1122 transcripts). `0` restores the pre-v3.83.0 behaviour. | _(on)_ |
 
 ### Citation tracking and feedback
 
@@ -840,6 +841,7 @@ benchmark and A/B harness are calibrated against — changing them invalidates t
 | `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` |
 | `CLAUDE_MEM_CITE_NUDGE_SILENCE_AFTER` | Consecutive low-cite sessions before the nudge goes quiet; `0` = never silence. | `3` |
+| `CLAUDE_MEM_SUBAGENT_DECAY` | The `subagent` injection face feeds the decay loop: memories handed to a dispatched agent enter the denominator, and the citation that agent makes in its own transcript counts as the numerator. `0` returns the face to metered-but-never-decaying (v3.77–v3.82). | _(on)_ |
 | `CLAUDE_MEM_METRICS` | `1` records feature-injection counters surfaced by `claude-mem-lite stats`. | _(off)_ |
 
 ### Background work

package/hook-episode.mjs

@@ -314,17 +314,75 @@ const RESEARCH_ENTRY_THRESHOLD = 8;
  *     2026-08    20/ 193  10.4%   >=8:  0
  *     lifetime reaching >=8: 81
  *
- * For three consecutive months this field fed the threshold at a real rate. It collapsed in
- * 2026-05 and the cause is NOT identified. That regime break is the single most useful fact
- * here, because it is direct evidence for the conclusion rather than against it: the
- * reachable input is the episode BOUNDARY, not the threshold and not the field, and the
- * boundary demonstrably moved once already.
+ * For three consecutive months this field fed the threshold at a real rate. The break is
+ * sharp: 2026-05-08 reads 11%, 05-09 onward reads 0.
+ *
+ * "THE REACHABLE INPUT IS THE EPISODE BOUNDARY" WAS WRONG — D#174 investigated it and the
+ * boundary never moved. One query falsifies the whole family of boundary explanations:
+ * measure the SIBLING column the same producer writes. `files_modified` is non-empty on
+ * 85-98% of rows every month from 2026-02 through 2026-08, averaging 2.0-2.6 paths, and it
+ * does not so much as dip across the break — while `files_read` goes 60% -> 1%. Episodes
+ * still carry ~2 edits each; they just stopped carrying reads. A smaller boundary would have
+ * taken both columns down together. Consistent with that, nothing in this repo changed at the
+ * break: zero commits on 05-08/05-09, scripts/post-tool-use.sh byte-identical from 03-29 to
+ * 05-24, hooks/hooks.json byte-identical from 04-22 to 05-10, and EPISODE_BUFFER_SIZE /
+ * EPISODE_TIME_GAP_MS / isRelatedToEpisode untouched since 2026-02-11.
+ *
+ * WHAT ACTUALLY SET THE RATE (probed, not read): a flush consumed reads-<project>.txt
+ * unconditionally but only PERSISTED it when the episode was significant
+ * (flushEpisodeGroup saves on `isSignificant`, and unlinks the flush file otherwise). So a
+ * buffered-but-insignificant flush — a successful `npm test` on its own, say — swallowed every
+ * Read accumulated since the previous flush and wrote none of them anywhere. Measured in a
+ * sandbox: seed 2 Reads, fire one such flush, and 0 observations are saved, the reads-file is
+ * gone, and the NEXT (edit-bearing, significant) observation carries `files_read=[]`.
+ *
+ * PAST TENSE SINCE v3.83.0: D#178 is FIXED. `flushEpisodeWithDb` now decides significance
+ * before it touches the file, and an insignificant flush leaves it in place for the next
+ * saving one (`CLAUDE_MEM_READS_CARRY=0` restores the old order). Two numbers in the
+ * paragraph above were also wrong and are corrected here rather than left to be re-quoted:
+ * the significant share is ~59%, not "~4-8%" — the `episode_significance` meter reads 40.7%
+ * INsignificant over n=938 across three active days — and the 92-96% figure D#178 was filed
+ * on came from the same slip. What the loss actually was, replayed over 1122 real
+ * transcripts through this file's own batcher (`benchmark/episode-flush-replay.mjs`):
+ * 42.2% of the Read paths a flush consumed destroyed, 72.7% of significant flushes
+ * carrying none. Same measurement pass as CHANGELOG v3.83.0, CLAUDE.md and README — quoting
+ * a second pass here would be the stitched-across-runs error one file at a time.
+ *
+ * The D#171 conclusion below is UNAFFECTED and that is worth stating explicitly, because
+ * the fix moves the quantity its arithmetic used. Post-fix the carried distinct set runs
+ * median 1, p95 6, max 21 per delivering flush — still nowhere near rule 4's threshold of
+ * 8 on a per-EPISODE basis, and rule 4 does not read this field anyway.
+ *
+ * Note the first version of that probe used `echo hello` as its "insignificant" entry.
+ * detectBashSignificance drops it, so the episode had zero entries, flushEpisode
+ * early-returned at `entries.length === 0`, the reads were never touched — and the probe
+ * confidently reported the opposite conclusion. An insignificant entry must be asserted into
+ * the buffer before it proves anything.
  *
  * D#171 closed as won't-fix-as-specified: the repair it named does not work at the current
  * cadence, and re-pointing the rule would move the dormancy to a field nobody suspects.
- * Reopening means finding what changed in 2026-05 — a far larger change than the rule, with
- * no evidence its output was worth it (111 lifetime observations, dormant 133 days, nobody
- * noticed). The May break is tracked separately so it is not lost with the closure.
+ * That closure stands, and D#174 no longer offers a reason to reopen it — the rule's own
+ * input (`readCount`, which counts Read/Grep ENTRIES, and Read never reaches Node) is a
+ * different quantity from `filesRead` and is untouched by any of the above.
+ *
+ * EXACTLY ONE claim above is pinned by a test, and deliberately so (D#175). Every number
+ * here is a corpus measured at a timestamp — a test over those would be a snapshot that
+ * rots and gets edited into greenness. The per-FLUSH claim is different in kind: it is a
+ * property of code (the reads-file is renamed aside, then the copy is unlinked), and if
+ * someone later makes reads accumulate across flushes, every "out of reach at ~1 Read per
+ * episode" sentence above silently becomes false. That is the one this closure rests on,
+ * so `tests/feature-sweep-hooks.test.mjs` → "the reads-file is consumed, not accumulated
+ * (D#175)" drives two real flushes through the subprocess and asserts the second one starts
+ * empty. Rename-becomes-copy and the dropped unlink are separate mutations caught by
+ * separate assertions there — one does not cover the other.
+ *
+ * THAT ALARM DID NOT FIRE FOR D#178, and the reason is worth keeping. Both of its flushes
+ * are SIGNIFICANT (each buffers a `.sql` Write), so both take the collect branch under the
+ * new order too — the v3.83.0 change walked straight underneath a guard installed one
+ * commit earlier to catch exactly "reads accumulate across flushes". Its sibling cases in
+ * the same file now cover the insignificant arm, in both flag positions and in the
+ * multi-session shape; a per-flush guard whose fixture only ever exercises one arm of the
+ * branch it guards is covering the arm nobody was going to change.
  *
  * @param {object} episode
  * @returns {{significant: boolean, rule: 1|2|3|4|null, readCount: number,

package/hook.mjs

@@ -216,27 +216,124 @@ function flushEpisode(episode, hookEventName = 'PostToolUse') {
   }
 }
 
-function flushEpisodeWithDb(db, episode, hookEventName) {
-  // Collect Read file paths tracked by post-tool-use.sh
-  // Use rename to atomically collect — prevents losing concurrent appends
-  const readsFile = join(RUNTIME_DIR, `reads-${episode.project || inferProject()}.txt`);
-  const readsCollect = readsFile + `.collect-${Date.now()}`;
+// D#178 safety valve. With CLAUDE_MEM_READS_CARRY on, an insignificant flush leaves
+// `reads-<project>.txt` in place, so a long insignificant streak keeps appending to it.
+//
+// THE CAP COUNTS LINES, NOT DISTINCT PATHS, and that is the whole point. The writer
+// (`scripts/post-tool-use.sh`) appends one line per Read with no dedup, so the file grows
+// by REPEATED lines — a session re-reading the same five files forever. The first draft
+// compared the DISTINCT set against the cap, which is the quantity that stays tiny
+// (measured on the live corpus: median 1, p95 6, max 21 carried paths), so the valve could
+// not fire on the growth mode it exists to bound. That is this repo's recurring
+// "predicate that cannot return true reports the defect as absent" shape, and the pre-tag
+// review caught it here.
+//
+// Still a backstop and not a relevance bound — the same distinction
+// IMPERATIVE_POOL_BACKSTOP documents for its pool.
+const READS_CARRY_MAX_LINES = 20000;
+
+/**
+ * Bound the reads file when an insignificant flush leaves it in place. Rewrites it only
+ * when it is over READS_CARRY_MAX_LINES raw lines, keeping the newest distinct paths.
+ *
+ * @param {string} readsFile
+ * @returns {number} distinct paths now held; 0 when there is no reads file (the COMMON
+ *   case — no Read since the last collect); -1 only when the file exists but could not be
+ *   read or the trim threw. The three-way split is the point: `episode_reads` is the ruler
+ *   for this flag, and folding "nothing to hold" together with "could not look" would put
+ *   the normal case and the broken case on the same value. A first draft returned -1 for
+ *   both, which made -1 the overwhelmingly common reading and hid the failure inside it.
+ */
+function trimReadsFile(readsFile) {
+  let raw;
+  try {
+    raw = readFileSync(readsFile, 'utf8');
+  } catch (e) {
+    return e?.code === 'ENOENT' ? 0 : -1;
+  }
   try {
-    renameSync(readsFile, readsCollect);
-    const raw = readFileSync(readsCollect, 'utf8');
-    const paths = [...new Set(raw.split('\n').filter(Boolean))];
-    episode.filesRead = paths;
-    try { unlinkSync(readsCollect); } catch {}
+    const lines = raw.split('\n').filter(Boolean);
+    const paths = [...new Set(lines)];
+    if (lines.length <= READS_CARRY_MAX_LINES) return paths.length;
+    const keep = paths.slice(-READS_CARRY_MAX_LINES);
+    const tmp = readsFile + `.trim-${process.pid}`;
+    writeFileSync(tmp, keep.join('\n') + '\n', { mode: 0o600 });
+    renameSync(tmp, readsFile);
+    return keep.length;
   } catch {
-    episode.filesRead = episode.filesRead || [];
+    return -1;
   }
+}
 
+function flushEpisodeWithDb(db, episode, hookEventName) {
   // Split by CC session so concurrent same-project sessions flush as separate
   // observations. planEpisodeFlush returns [episode] BY REFERENCE for the common
   // single-session (or all-legacy) case → flushEpisodeGroup(episode) is identical
   // to pre-grouping. Two+ interleaved sessions each get their own sub-episode.
   const subs = planEpisodeFlush(episode);
+
+  // D#178. The reads file used to be consumed right here, unconditionally, BEFORE
+  // anything knew whether this flush would persist an observation — and an
+  // insignificant flush then dropped every path it had just swept up, leaving the
+  // next observation that DID save with files_read = []. Measured over 1122 real
+  // transcripts (benchmark/episode-flush-replay.mjs): 42.2% of the reads a flush
+  // consumed died that way, and 72.7% of significant flushes carried none at all.
+  //
+  // The fix is an ORDERING, not a buffer: explainSignificance reads only `entries`
+  // and `files`, never `filesRead`, so the verdict is available before the file is
+  // touched. An insignificant flush now leaves the file alone and the next
+  // significant one collects the union. Ages measured on the same corpus: the reads
+  // that survive attach a median 1.7 minutes and p90 10.1 minutes later than they do
+  // today, which is the whole cost — a read carried across two insignificant flushes
+  // lands on the edit it preceded rather than on nothing.
+  //
+  // ON by default since v3.83.0. `CLAUDE_MEM_READS_CARRY=0` restores the pre-D#178
+  // behavior byte for byte — kept as an off switch because this changes what a released
+  // artifact stores, and a defect here is invisible from the outside (the symptom is an
+  // absent field, which reads exactly like "there was nothing to record").
+  const carryReads = !['0', 'off', 'false', 'no'].includes(
+    String(process.env.CLAUDE_MEM_READS_CARRY ?? '').toLowerCase());
+  const willPersist = !carryReads || subs.some((s) => episodeHasSignificantContent(s));
+
+  // Collect Read file paths tracked by post-tool-use.sh
+  // Use rename to atomically collect — prevents losing concurrent appends
+  const readsFile = join(RUNTIME_DIR, `reads-${episode.project || inferProject()}.txt`);
+  const readsCollect = readsFile + `.collect-${Date.now()}`;
+  let readsHeld = 0;
+  if (willPersist) {
+    try {
+      renameSync(readsFile, readsCollect);
+      const raw = readFileSync(readsCollect, 'utf8');
+      const paths = [...new Set(raw.split('\n').filter(Boolean))];
+      episode.filesRead = paths;
+      try { unlinkSync(readsCollect); } catch {}
+    } catch {
+      episode.filesRead = episode.filesRead || [];
+    }
+  } else {
+    episode.filesRead = [];
+    // Not collecting means the file keeps growing across an insignificant streak, and a
+    // project that never flushes significantly would grow it without bound. Trim it.
+    //
+    // The trim's race window is WIDER than the collect path's, and saying otherwise (the
+    // first draft did) is the kind of comfortable claim that stops anyone checking: the
+    // collect path is a single atomic `renameSync`, while this is read → dedup → write tmp
+    // → rename, and a `>>` append from the bash prefilter landing inside that span is lost
+    // to the final rename. Accepted rather than fixed: the trim only runs above
+    // READS_CARRY_MAX_LINES, which no observed session approaches, so the exposure is a
+    // path or two in a session that has already read 20000 times.
+    readsHeld = trimReadsFile(readsFile);
+  }
+  // planEpisodeFlush now runs BEFORE the collection, so the multi-session branch — the
+  // one that builds fresh objects rather than returning [episode] by reference — copied
+  // whatever filesRead the buffer happened to carry, not what was just collected. The
+  // single-group path is identity and unaffected; this line is what keeps the two paths
+  // saying the same thing, and without it concurrent same-project sessions would lose
+  // their reads while a solo session kept them.
+  for (const sub of subs) if (sub !== episode) sub.filesRead = episode.filesRead;
+
   let anySignificant = false;
+  let writefail = false;
   for (const sub of subs) {
     const r = flushEpisodeGroup(sub, db);
     if (r === 'writefail') {
@@ -245,12 +342,39 @@ function flushEpisodeWithDb(db, episode, hookEventName) {
       // keep the rest. The asymmetry is safe: each group's immediate obs is persisted
       // BEFORE its flush-file write, so re-flushing the whole buffer would re-emit
       // already-saved groups as duplicate observations.
-      if (subs.length === 1) return;
+      if (subs.length === 1) { writefail = true; break; }
       continue;
     }
     if (r === 'significant') anySignificant = true;
   }
 
+  // D#178 instrument, and the ruler for the flag above. With CLAUDE_MEM_READS_CARRY
+  // off, a row with `significant: false` and `readsConsumed > 0` is that many Read
+  // paths collected and dropped on the floor. With it on, those rows become
+  // `readsConsumed: 0, readsHeld: N` — the same event, now recording a deferral
+  // instead of a loss, so one query over this sink covers both arms.
+  // Emitted HERE and not in flushEpisodeGroup on purpose: planEpisodeFlush copies
+  // the SAME filesRead array into every sub, so a per-group counter double-counts
+  // the multi-session case, and the destroyed/kept decision is `anySignificant`,
+  // which only exists at this level. `writefail` is its own arm because on the SIGNIFICANT
+  // path it keeps the episode buffer for a retry the reads file can no longer serve — it
+  // was already unlinked, so the retry re-collects nothing. A writefail flush is NOT
+  // necessarily one whose significance said collect: `flushEpisodeGroup` writes its flush
+  // file outside the significance branch, so an insignificant flush can fail there too —
+  // and with the flag on that case is strictly better than before, because the reads file
+  // was never touched and the retry still finds it.
+  // Off unless CLAUDE_MEM_METRICS=1, like every other row in this sink.
+  recordMetric(join(RUNTIME_DIR, '..'), {
+    event: 'episode_reads',
+    readsConsumed: (episode.filesRead || []).length,
+    readsHeld,
+    carry: carryReads,
+    significant: anySignificant,
+    subs: subs.length,
+    writefail,
+  });
+  if (writefail) return;
+
   // Aggregate receipt over the whole episode, gated exactly as before
   // (isSignificant → anySignificant). v2.33.4: Stop rejects hookSpecificOutput.
   if (anySignificant && RECEIPT_EVENTS.has(hookEventName)) {
@@ -807,6 +931,19 @@ async function handleStop() {
       // applyCitationDecay checks separately.
       try {
         if (transcriptPath && !process.env.CLAUDE_MEM_NO_CITATION_TRACK) {
+          // D#152/D#177: the `subagent` face, collected ONCE, up front, and used twice —
+          // by the decay block below (only under CLAUDE_MEM_SUBAGENT_DECAY) and by its own
+          // metering call at the tail. It used to be collected at the tail only, with a
+          // comment saying the position was load-bearing because lib/transcript-scan.mjs
+          // memoizes ONE file and reading the sidechains evicts the parent. That constraint
+          // is real but it is not "last" — it is "not BETWEEN two parent scans". Running it
+          // FIRST parses the sidechains before anything has memoized the parent, so the
+          // parent is then parsed once and stays memoized for every scanner after it:
+          // still one parent parse per Stop, the property the tail comment was protecting.
+          let sub = { injected: new Set(), cited: new Set(), files: 0 };
+          try { sub = collectSubagentSurface(transcriptPath); }
+          catch (e) { debugCatch(e, 'handleStop-subagent-collect'); }
+
           const ids = extractCitationsFromTranscript(transcriptPath);
           if (ids.size > 0) {
             const n = bumpCitationAccess(db, ids, project);
@@ -854,7 +991,15 @@ async function handleStop() {
             const keyCtxIds = extractInjectedFromKeyContext({
               runtimeDir: RUNTIME_DIR, project, sessionId: ccSessionId,
             });
-            if (injected.size > 0 || keyCtxIds.size > 0) {
+            // D#177: `sub.injected` counts toward the entry gate when the face is admitted.
+            // Without this a session whose ONLY injection was a dispatched agent's prompt
+            // would return here with injected.size === 0 and the face would be "in the
+            // denominator" in name only — the failure mode where a face is wired at one
+            // level and gated out at another, which is how UPS went unmetered for a whole
+            // minor version.
+            const subDecayOn = !['0', 'off', 'false', 'no'].includes(
+              String(process.env.CLAUDE_MEM_SUBAGENT_DECAY ?? '').toLowerCase());
+            if (injected.size > 0 || keyCtxIds.size > 0 || (subDecayOn && sub.injected.size > 0)) {
               // Text-floor gate: skip decay on tool-only Stops. Without this,
               // a turn that ends on tool_use locks every injected obs as
               // uncited (last_decided_session_id set), so a later turn that
@@ -867,17 +1012,71 @@ async function handleStop() {
               } else {
                 const citedMain = extractCitationsFromTranscript(transcriptPath, { mainOnly: true });
                 for (const id of citeBackIds) citedMain.add(id);
+                // D#177: admit the `subagent` face to the decay loop. It cannot ride the
+                // normal path because its injection lands in a dispatched agent's PROMPT
+                // and its citation lands in that agent's OWN transcript — so its ids enter
+                // the denominator AND its receiver-attributed cites enter the numerator,
+                // asymmetrically, together. Feeding only the first half would mark every
+                // subagent-only injection uncited by construction (that is why the face was
+                // metered-but-excluded since v3.77); feeding only the second half would
+                // credit the main-thread faces for citations the main thread never made.
+                //
+                // `sub.cited` is already the per-FILE intersection with `sub.injected`
+                // (collectSubagentSurface), so this cannot credit an id the subagent surface
+                // did not itself inject. Measured on the live corpus (1122 transcripts, 34
+                // subagent-bearing sessions): 33 marginal (session,id) pairs enter the
+                // denominator, 21.2% of them cited; 21 distinct observations behind the
+                // uncited ones, FIVE at uncited_streak = 2. Four are 3->2 down-ranks (#8597,
+                // #8847 with cited_count 56, #8948, #10246). At 2026-08-25 18:00Z #10716 was
+                // at importance 2 — one miss from a 2->1 eviction out of
+                // rankImperativeCandidates' own `importance >= 2` pool, the case
+                // IMPERATIVE_POOL_BACKSTOP does not cover, and the reason "down-ranks, not
+                // evictions" is wrong as a blanket claim. That row has since been promoted by
+                // the very session that documented it (D#179: this loop cannot tell writing
+                // `#NN` from applying it), so re-check the CLASS, not the row.
+                // Cross-crediting is 3 pairs of 1181 DISTINCT (session,id) across the five
+                // decay faces inside subagent-bearing sessions (0.25%), or 3 of 2738 the same
+                // way corpus-wide (0.11%) — ids the main thread never cited but a subagent did.
+                //
+                // ON by default since v3.83.0; `CLAUDE_MEM_SUBAGENT_DECAY=0` restores the
+                // metered-but-never-decaying state the face sat in from v3.77 to v3.82.
+                //
+                // The denominator is a COPY, not a mutation of `injected`: the edge
+                // attribution below takes `mainInjectedIds: injected` to keep sidechain-only
+                // injections from accruing file-edge misses (review D#78), and folding the
+                // subagent ids into that set would undo exactly that guard.
                 // The promotion-only half: a Key Context row the agent actually
                 // cited joins the decay set (and takes the promote branch); one
                 // it ignored is never entered, so it cannot streak or demote.
                 for (const id of keyCtxIds) if (citedMain.has(id)) injected.add(id);
+                // BOTH halves of the merge are COPIES, built AFTER the keyctx promotion above
+                // so they carry it too. When the flag is off each IS the original object, so
+                // every consumer below is byte identical to the pre-D#177 path.
+                //
+                // The copies are the whole safety property. `injected` and `citedMain` have
+                // four consumers between them and only `applyCitationDecay` should see the
+                // subagent ids; the first draft of this change mutated `citedMain` in place
+                // and the pre-tag review measured both leaks it caused:
+                //   • recordCitationSurfaces (below) scored a `pretool` row the main thread
+                //     never cited as a pretool HIT — `pretool.cited_n` 0 -> 1 on a
+                //     two-observation probe. That is the caliber CLAUDE.md publishes for the
+                //     funnel ("cited as #NN in the session's own MAIN-THREAD text"), so it
+                //     would have made citation_surface_log and citation-live-replay.mjs
+                //     permanently different rulers — the v3.81.0 cross-agent defect, mirrored.
+                //   • resolveEdgeAttribution gates sidechain edges on
+                //     `!mainInjected.has(id) && !cited.has(id)`, so a file edge flipped MISS
+                //     -> HIT (`miss_streak` 1 -> 0). The comment there defends the DENOMINATOR
+                //     half of that gate and says nothing about the numerator, which is exactly
+                //     how the leak got past a reading of it.
+                const decayInjected = subDecayOn ? new Set([...injected, ...sub.injected]) : injected;
+                const decayCited = subDecayOn ? new Set([...citedMain, ...sub.cited]) : citedMain;
                 // D#60: the idempotency key must be the CC session UUID, NOT the
                 // project-scoped memory sessionId — concurrent same-project CC
                 // sessions share the latter, so the second session's decay pass
                 // read "already decided" and silently undercounted decay_seen /
                 // streaks / adoption denominators. Fallback keeps legacy
                 // stdin-less invocations on the old key.
-                const r = applyCitationDecay(db, project, injected, citedMain, ccSessionId || sessionId);
+                const r = applyCitationDecay(db, project, decayInjected, decayCited, ccSessionId || sessionId);
                 debugLog('DEBUG', 'handleStop', `citation-decay: touched=${r.touched} promoted=${r.promoted} demoted=${r.demoted}`);
                 // R1: persist this session's invocation→cite funnel row. touched =
                 // obs resolved this run (denominator), promoted = obs cited this run
@@ -968,11 +1167,19 @@ async function handleStop() {
           // construction; folding its cites INTO citedMain would credit the
           // main-thread faces for citations the main thread never made. The
           // upsert key is (project, session, surface), so two calls with
-          // disjoint face sets do not collide. Metering only — `subagent` is in
-          // NON_ATTACHMENT_SURFACES and never reaches applyCitationDecay.
+          // disjoint face sets do not collide.
+          //
+          // SINCE v3.83.0 (D#177) this is no longer metering-only: the face DOES reach
+          // applyCitationDecay, through the `decayInjected` / `decayCited` copies above.
+          // The sentence above about folding cites into `citedMain` still holds and is the
+          // reason those are copies — this call, `resolveEdgeAttribution` and the keyctx
+          // promotion all keep the un-widened set. `CLAUDE_MEM_SUBAGENT_DECAY=0` returns
+          // the face to metering-only.
           //
-          // Placed LAST on purpose: lib/transcript-scan.mjs memoizes ONE file,
-          // so reading the sidechain files evicts the parent transcript. Run
+          // The "placed LAST" note below is now historical: `collectSubagentSurface` runs
+          // at the HEAD of this block (the decay loop needs its result), and `sub` here is
+          // that same object rather than a second call. The parse-count property the note
+          // defends is unchanged — see the comment at the collection site.
           // earlier, this block costs ONE extra parse of the parent — the memo
           // re-caches on the first re-read, so it is one, not one per later
           // scanner — and breaks the "one parse per Stop" property the block
@@ -985,7 +1192,9 @@ async function handleStop() {
           // must not enter the funnel's session denominator either.
           try {
             if (hasMainThreadAssistantText(transcriptPath)) {
-              const sub = collectSubagentSurface(transcriptPath);
+              // `sub` is the one collected at the top of this block — a second
+              // collectSubagentSurface call here would re-parse every sidechain file and,
+              // worse, could disagree with the set the decay loop above just scored.
               if (sub.injected.size > 0) {
                 recordCitationSurfaces(db, project, ccSessionId || sessionId,
                   { subagent: sub.injected }, sub.cited);

package/lib/citation-tracker.mjs

@@ -634,6 +634,10 @@ export const DECAY_DENOMINATOR_SURFACES = ATTACHMENT_SURFACES.filter((f) => !DEC
  *   commensurable with `citedMain` — scoring it there would mark every
  *   subagent-only injection uncited by construction. Metered first (this is the
  *   whole point of D#152: the face's cite-rate is unknown), decided second.
+ *   DECIDED 2026-08-25 (D#177, below): it IS in the decay loop now. It stays listed
+ *   here because this constant answers "which faces leave no attachment", a fact
+ *   about the transport — and that is exactly why its admission had to be wired at
+ *   the call site instead of riding the DECAY_DENOMINATOR_SURFACES derivation.
  *
  *   D#164 read it (2026-08-25, 30 live sessions): 25.0% (12/48) on the house
  *   id-level caliber — above fyi (10.9%) and error_recall (6.2%), both of which
@@ -659,6 +663,46 @@ export const DECAY_DENOMINATOR_SURFACES = ATTACHMENT_SURFACES.filter((f) => !DEC
  *   one release separate them also means the eviction loop they share is observed
  *   on one face before it acts on two. Tracked in D#172.
  *
+ *   D#177 — ADMITTED (2026-08-25, v3.83.0). The asymmetric merge lives in hook.mjs
+ *   handleStop, on by default with `CLAUDE_MEM_SUBAGENT_DECAY=0` as the off switch:
+ *   `sub.injected` widens the denominator and `sub.cited` — already the per-file
+ *   intersection with what the subagent surface itself injected — widens the numerator,
+ *   in the same breath. This constant stays as it is either way: it describes which
+ *   faces leave no ATTACHMENT, which is a fact about the transport, not about the
+ *   denominator. Admission happens at the call site precisely because it cannot ride
+ *   the `DECAY_DENOMINATOR_SURFACES` derivation without the cites travelling with it.
+ *
+ *   Re-measured on the 1122-transcript corpus (benchmark/citation-live-replay.mjs):
+ *   the face reads 25.5% (14/55). Cost of the merge, same walk: 33 marginal (session,id)
+ *   pairs join the denominator at 21.2% cited; behind the uncited ones sit 21 distinct
+ *   observations, FIVE at uncited_streak = 2, each one demotion away from moving.
+ *
+ *   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
+ *   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.
+ *
+ *   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
+ *   faces inside subagent-bearing sessions (1181); 0.11% is that same caliber corpus-wide
+ *   (2738). The per-face sums for the same populations are 1241 and 2878 — say which one
+ *   you mean, because quoting one ratio against the other denominator is the exact error
+ *   this sentence exists to prevent.
+ *
  * A member here that the Stop path stops feeding becomes an all-zero face, not
  * a silently-demoting one — which is the failure mode worth keeping.
  * @type {ReadonlyArray<string>}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.82.0",
+  "version": "3.83.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.82.0",
+      "version": "3.83.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.82.0",
+  "version": "3.83.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/scripts/pre-tool-recall.js

@@ -105,6 +105,45 @@ const EDGE_DECAY_K = Math.max(1, Number.isNaN(EDGE_DECAY_K_RAW) ? 3 : EDGE_DECAY
 // environment-scoped observations (tooling/CI/network gotchas that apply in
 // ANY project) stop firing on FILE-triggered recall; they stay reachable via
 // search / UPS / error-recall. NULL scope (legacy / manual rows) always passes.
+//
+// DO NOT TURN THIS ON, AND DO NOT REBUILD IT AS A DOWN-WEIGHT (D#153, closed
+// 2026-08-25). Its premise is that environment-scoped rows are the low-relevance
+// class on THIS face. Measured on the live corpus with the shipped extractors —
+// `node benchmark/citation-live-replay.mjs --by-scope`, 1122 transcripts — the
+// `pretool` face (this one) cites:
+//   environment 47.5% (67/141)  CI [39.5, 55.7]
+//   project     44.3% (293/661) CI [40.6, 48.1]
+//   file        40.0% (2/5)  ·  (gone) 37.1% (185/498)  ·  module 36.5% (31/85)
+//   (null)      34.9% (45/129)          ·  face overall 41.0% (623/1519)
+// environment is the best-citing scope bucket on the face the filter gates. The
+// CIs for environment and project OVERLAP, so "environment leads" is NOT
+// established; what is refuted is "environment is the class to suppress".
+// Its interval sits above module and null, which is the comparison that matters
+// for a lever whose whole premise is that this bucket is the weak one.
+//
+// The earlier redesign sketch (multiplicative demotion at the TYPE_QUALITY layer
+// instead of a WHERE-clause exclusion) fixes the failure mode that was measured
+// in 2026-08 — 173 recall groups going empty — but it would still down-rank this
+// bucket, so it was NOT built. Kept as an off switch rather than deleted: the
+// column and the label are used elsewhere, and a flag nobody flips costs nothing
+// as long as the reason not to flip it is written down, which is this paragraph.
+//
+// NOT corroborated by #10720, though an earlier draft of this note said so. That
+// observation is a scope LABEL distribution (364 labelled DB rows: project 184 /
+// environment 114 / module 50 / file 16), which establishes the filter's blast
+// radius — environment is 31.3% of labels, not the near-no-op it looked like at 8
+// rows — and says nothing about relevance. The refutation rests on the by-scope
+// replay alone.
+//
+// Caliber caveat, so the numbers are re-derivable rather than quotable: the six
+// buckets sum to exactly 1519, the face's own pair count, because 498 ids whose
+// observation has since left the table are reported as `(gone)` rather than
+// dropped. Those are an OLD cohort (max id 8880 against a corpus reaching 10850)
+// from id bands where the surviving population is ~81% `(null)` and ~2.5%
+// environment, so the missing bucket cannot plausibly be environment-heavy;
+// environment and project pairs sit in the same bands, so the head-to-head is not
+// era-confounded. The `(null)` bucket and the face-overall figure ARE, being
+// dominated by legacy rows.
 const SCOPE_FILTER_ON = ['1', 'on', 'true', 'yes'].includes(
   String(process.env.CLAUDE_MEM_SCOPE_FILTER || '').toLowerCase());
 const FILE_INTEL_MIN_TOKENS = Math.max(1,