claude-mem-lite 3.79.0 → 3.81.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.79.0",
+      "version": "3.81.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.79.0",
+  "version": "3.81.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/hook-episode.mjs

@@ -260,6 +260,72 @@ const RESEARCH_ENTRY_THRESHOLD = 8;
  * short — an edit-driven episode that happens to contain Greps is not evidence that
  * Grep carries research episodes.
  *
+ * READ THE DENOMINATOR BEFORE READING `grepDecisive: 0`. It is a vacuous zero whenever
+ * no episode contains a Grep at all, and that is the state measured on 2026-08-25:
+ * across 555 instrumented episodes, `sum(readCount) = sum(grepCount) = 0`, and the `Grep`
+ * tool was invoked **0 times in the entire 1111-transcript history on this machine**.
+ * So "grepDecisive is 0, therefore Grep is safe to skip" is not an inference this counter
+ * supports here — it never had the chance to fire. (The decision it was built for is
+ * separately moot on that corpus: skipping a tool nobody calls saves 0ms.) Same shape as
+ * the FTS5 `rowid = ? AND fts MATCH ?` trap this repo already paid for — a predicate that
+ * cannot return true reports the defect as absent.
+ *
+ * The same measurement shows rules 4 and `buildImmediateObservation`'s `isReviewPattern`
+ * are BOTH dormant, for a reason that has nothing to do with Grep: `readCount` counts
+ * `Read || Grep`, and `Read` is filtered out at both layers (scripts/post-tool-use.sh
+ * records it to `reads-<project>.txt` and exits; SKIP_TOOLS returns early in Node), so the
+ * rule's only remaining input is a tool that is never called. Last observation the review
+ * branch produced: 133 days ago, 111 lifetime.
+ *
+ * D#171 proposed the obvious repair — re-point rule 4 at `episode.filesRead`, populated at
+ * hook.mjs:228 before this function runs, the same way rule 3 already reads
+ * `episode.files`. MEASURED 2026-08-25: IT DOES NOT WORK TODAY, and the reason is dated,
+ * not structural. Both halves matter, and the pre-tag review corrected the first draft of
+ * each.
+ *
+ * Unlike the Grep case the denominator is real: `Read` fires 1861 times across the
+ * 1114-transcript history (9.1% of all tool calls; the transcripts hold records spanning
+ * 2026-08-13..08-25, so that is a live rate, not a lifetime counter). But `filesRead` is a
+ * per-FLUSH slice, not a per-episode total — flushEpisodeWithDb renames and consumes
+ * `reads-<project>.txt` on every flush. COMPARE THE TWO RATES ON THE SAME WINDOW: the
+ * `episode_significance` metric rows cover three ACTIVE days (08-22 / 08-24 / 08-25; 08-23
+ * has no file), 607 flushes; the transcripts touched in that window carry 596 Reads. That
+ * is 0.98 Reads per episode. The first draft said 0.8 by dividing a 12-day Read rate by a
+ * 3-day flush rate — two windows, one ratio, which is the same shape of error v3.80.0
+ * recorded as "reading a lifetime counter as an active rate".
+ *
+ * At ~1 Read per episode a threshold of 8 is out of reach, and the 90-day sample agrees:
+ * `files_read` is non-empty on 34 of 1872 rows (1.8%), p50 1 / p95 5 / max 8, exactly ONE
+ * row reaching 8 — and that column is a SUPERSET of `episode.filesRead` (hook-llm.mjs
+ * merges searched files in), so the true field is smaller. Two caveats on that sample, both
+ * from the review: it only covers SIGNIFICANT episodes (saveEpisodeImmediate is gated on
+ * `isSignificant`), which is ~8% of flushes and structurally excludes the population rule 4
+ * would change; and 90 days starts AFTER the break below.
+ *
+ * THE RULE WAS NOT ALWAYS UNREACHABLE — do not write "structurally". Non-empty `files_read`
+ * by month, with the count reaching the threshold of 8:
+ *
+ *     2026-02    35/  78  44.9%   >=8:  3   max 11
+ *     2026-03   603/1004  60.1%   >=8: 49   max 53
+ *     2026-04   314/ 621  50.6%   >=8: 28   max 33
+ *     2026-05     8/ 129   6.2%   >=8:  0
+ *     2026-06     5/ 754   0.7%   >=8:  0
+ *     2026-07     8/ 919   0.9%   >=8:  1
+ *     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.
+ *
+ * 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.
+ *
  * @param {object} episode
  * @returns {{significant: boolean, rule: 1|2|3|4|null, readCount: number,
  *   grepCount: number, grepDecisive: boolean}}

package/lib/citation-tracker.mjs

@@ -20,9 +20,65 @@ import { readTranscriptEntries } from './transcript-scan.mjs';
 import { TASK_IMPERATIVE_PREFIX } from './task-imperative.mjs';
 
 import { DAY_MS } from './time-constants.mjs';
+/**
+ * The ONE caliber for an observation id appearing in text. Bounded to 1-7 digits to
+ * skip URL fragments, markdown anchors, etc.
+ *
+ * Exported because the offline benchmarks re-derive production's numbers from the same
+ * transcripts, and each had hand-copied its own: `benchmark/cite-recall.mjs` scanned
+ * citations with `{2,6}` while its OWN injected denominator used `{1,7}`, and
+ * `efficacy-observational.mjs` / `adoption-replay.mjs` had a third and fourth caliber
+ * (`{2,6}` / `{2,7}`). A denominator wider than its numerator counts an id as
+ * injected-never-cited that the numerator structurally cannot see, which biases the
+ * measured cite-rate DOWN — and nothing errors when it happens.
+ *
+ * Measured live impact at the time this was unified (2026-08-24, 3692 rows, ids 1..10834):
+ * exactly ZERO. The only ids outside `{2,6}` are four 1-digit rows, and all four have
+ * injection_count = 0, so they never entered a denominator; there are no 7-digit ids.
+ * This is a latent-class fix, not a correction to any published number — do not
+ * re-attribute past readings to it.
+ */
+export const OBS_ID_DIGITS = '\\d{1,7}';
+
+/**
+ * A fresh global matcher for a bare `#NN` citation.
+ *
+ * Returned fresh per call rather than shared: a `/g` regex carries `lastIndex`, so one
+ * exported instance reused by two scanners silently starts mid-string in whichever one
+ * runs second.
+ */
+export function citationIdRe() {
+  return new RegExp(`#(${OBS_ID_DIGITS})\\b`, 'g');
+}
+
+/**
+ * Caliber for an id scraped from UNANCHORED text that is then treated as an INJECTED
+ * (denominator) set.
+ *
+ * `citationIdRe()` above is a NUMERATOR caliber. On the numerator side a spurious `#1`
+ * costs nothing, because a cited id only counts once it intersects an injected set that
+ * WAS anchored — every injected-side extractor in this module matches a row shape
+ * (`INJECTED_ROW_RE`, `FYI_LINE_ID_RE`, `UPS_ID_RE`, `SUBAGENT_INJECT_ID_RE`). On the
+ * denominator side nothing anchors it, so a prose `#1` is a false positive by
+ * construction — it inflates "injected, never cited" and biases the measured rate DOWN.
+ *
+ * The v3.80.0 pre-tag review caught this concretely: pointing
+ * `benchmark/adoption-replay.mjs` at `citationIdRe()` pulled `#1` and `#2` out of a
+ * subagent prompt discussing fixture rows ("with `#1` superseded by `#2` …") straight into
+ * `injectedIds`, on a real transcript. Excluding 1-digit ids costs nothing measurable —
+ * the four 1-digit rows in the live corpus have `injection_count = 0` — and removes the
+ * commonest prose collision.
+ *
+ * This is a stopgap for a caliber symptom, NOT a fix for the cause. The cause is that
+ * adoption-replay scrapes a whole prompt where it should match injected ROWS, the way
+ * production does. Do not reach for this anywhere else; anchor instead.
+ */
+export function unanchoredInjectedIdRe() {
+  return new RegExp('#(\\d{2,7})\\b', 'g');
+}
+
 // `#123` / `#45678` at a word boundary — matches the CLAUDE.md cite pattern.
-// Bounded to 1-7 digits to skip URL fragments, markdown anchors, etc.
-const CITATION_RE = /#(\d{1,7})\b/g;
+const CITATION_RE = citationIdRe();
 
 /**
  * Parse a Claude Code transcript .jsonl and extract unique observation IDs
@@ -147,7 +203,7 @@ export function bumpCitationAccess(db, ids, project) {
 // Matches a pre-tool-recall / error-recall lesson line: `  #NN [type] body...`.
 // Bounded type list mirrors observations.type CHECK + the events table's allowed
 // event_type values these surfaces can emit.
-const INJECTED_RE = /#(\d{1,7})\s+\[(bugfix|decision|change|discovery|feature|refactor|lesson)\]/g;
+const INJECTED_RE = new RegExp(`#(${OBS_ID_DIGITS})\\s+\\[(bugfix|decision|change|discovery|feature|refactor|lesson)\\]`, 'g');
 // Line-anchored variant: a genuine injected ROW begins (after its short indent) with
 // `#NN [type]`. pre-tool-recall AND error-recall inline a lesson_learned body into the
 // row; a body that quotes another obs ("same as #1234 [decision]") must NOT count as
@@ -217,7 +273,7 @@ function eachHookAttachment(transcriptPath, fn, opts = {}) {
 // like "see (#999)" doesn't pollute the injected set (would streak-uncite an
 // obs we never actually displayed as a top-level entry).
 const UPS_LINE_PREFIX = '- [';
-const UPS_ID_RE = /\(#(\d{1,7})\)/g;
+const UPS_ID_RE = new RegExp(`\\(#(${OBS_ID_DIGITS})\\)`, 'g');
 // Quote-normalized (see normalizeHookCommand): real recorded command is
 // `node "/abs/hook.mjs" user-prompt` → normalized to `node /abs/hook.mjs user-prompt`.
 const UPS_COMMAND_SUFFIX = 'hook.mjs user-prompt';
@@ -230,7 +286,7 @@ const UPS_COMMAND_SUFFIX = 'hook.mjs user-prompt';
 const FYI_HEADER = '[mem] FYI — Related memories';
 // Anchored at line start so `P#NN` past-question rows (user_prompts, different id
 // space) and any `#NN` inside lesson text are NOT matched.
-const FYI_LINE_ID_RE = /^#(\d{1,7})\s/;
+const FYI_LINE_ID_RE = new RegExp(`^#(${OBS_ID_DIGITS})\\s`);
 
 /**
  * The injection FACES memory can reach the model through, as stored in
@@ -491,15 +547,60 @@ export function extractAllInjected(transcriptPath, opts = {}) {
  * requires each face to be either in the union or listed here — so a face added later
  * cannot slip out of the denominator by being forgotten, only by being argued for.
  *
- * - `task_imperative` (v3.76): metering it is the point of adding it — D#137/D#150/D#151
- *   are all blocked on not knowing this face's cite-rate. Widening the denominator at the
- *   same moment would change what gets demoted in every live install on upgrade, and it
- *   would do so on the face whose framing is itself the open question: if the imperative
- *   framing under-performs, the penalty lands on the LESSONS it carried (imperativePick
- *   selects high-value ones) rather than on the framing. Read the rate first, then decide.
- *   Removing an entry from this set is the one-line change that widens the denominator.
+ * EMPTY since 2026-08-25, by decision rather than by default. `task_imperative` was its
+ * only member; the history is kept because the exit criterion is the reusable part.
+ *
+ * - `task_imperative` (v3.76 -> admitted 2026-08-25): it was excluded on a stated
+ *   condition — "if the imperative framing under-performs, the penalty lands on the
+ *   LESSONS it carried (imperativePick selects high-value ones) rather than on the
+ *   framing" — with the instruction to read the rate first. THE RATE WAS READ AND THE
+ *   CONDITION IS NOT MET. Over the live 1113-transcript corpus: 44.1% (15/34), against
+ *   pretool 38.3% (521/1362), fyi 10.9%, ups 8.4%, error_recall 6.2%.
+ *
+ *   citation_surface_log alone would NOT have supported this — it held n=8 over 2.1 days,
+ *   because the FLAG had been parked for weeks while the METER had only run since v3.76.
+ *   Re-deriving the rate by walking live transcripts with the shipped extractors turned
+ *   n=8 into n=34. Worth keeping as a habit: when a face's row count looks too small to
+ *   decide on, check whether the meter is younger than the behaviour before concluding
+ *   there is no data.
+ *
+ *   Two caveats travel with the number. n=34, so its CI overlaps pretool's: "does not
+ *   under-perform" is established, "leads" is not. And imperativePick returns a single
+ *   top-ranked lesson, so this is a top-1 pick measured against faces that inject bulk
+ *   lists — a confound in this face's favour that no amount of n removes.
+ *
+ *   Measured blast radius, same-corpus one-pass A/B (4-face union vs 5-face union in the
+ *   SAME walk — never by subtracting two counts taken at different times): 22 new
+ *   (session,id) rows = +0.90% of the denominator across 17 sessions, 9 of the 22 cited
+ *   (40.9%).
+ *
+ *   COUNT THE STREAK ON THE RIGHT UNIT. The first version of this note said "zero of them
+ *   uncited across the >=3 sessions UNCITED_STREAK_THRESHOLD requires, so no demotions" —
+ *   measured on marginal sessions only, which is NOT the unit applyCitationDecay uses.
+ *   `uncited_streak` is per-OBSERVATION and is driven by every face at once, so the real
+ *   question is whether a marginal uncited resolution lands on a row the other four faces
+ *   have already walked to 2. It does: 13 of the 22 marginal pairs are uncited, and of the
+ *   16 distinct observations behind them FIVE sit at uncited_streak = 2 today — four of
+ *   those (#8847, #8948, #10251, #10527) are ids this flip newly resolves as uncited, i.e.
+ *   one imperative-only silent session from demotion. #8847 is imp=3 with cited_count=56.
+ *   The product's own CLI calls that state "Active decay queue (uncited_streak >= 2, next
+ *   miss -> demote)"; a release note claiming three sessions of margin contradicted it.
+ *
+ *   THE RESIDUAL RISK, unresolved and deliberately shipped: all 22 marginal rows are
+ *   importance=3, because rankImperativeCandidates orders by importance DESC and takes 50,
+ *   and in the five largest projects here the imp=3 population alone exceeds that limit
+ *   (projects--mem 326, code-graph-mcp 121). So a demotion 3->2 EVICTS a lesson from this
+ *   face's candidate pool rather than merely down-ranking it — a feedback loop the four
+ *   original denominator faces do not have, because they select on FTS relevance. It is
+ *   NOT permanent: 3->2 still clears the pool's `>= 2` gate (it only loses the LIMIT 50
+ *   race), and updatePromote restores importance on the next citation from ANY face, so a
+ *   row returns the moment something else surfaces and cites it. If lessons start
+ *   disappearing from imperative picks, this is the first place to look, and the cap
+ *   belongs in rankImperativeCandidates (raise LIMIT above the imp=3 population, or exempt
+ *   this face's picks from demotion) rather than back here. Tracked with `subagent` in
+ *   D#172.
  */
-const DECAY_EXCLUDED_SURFACES = new Set(['task_imperative']);
+const DECAY_EXCLUDED_SURFACES = new Set();
 
 /** @type {ReadonlyArray<string>} faces that DO feed the decay denominator. */
 export const DECAY_DENOMINATOR_SURFACES = ATTACHMENT_SURFACES.filter((f) => !DECAY_EXCLUDED_SURFACES.has(f));
@@ -522,6 +623,28 @@ export const DECAY_DENOMINATOR_SURFACES = ATTACHMENT_SURFACES.filter((f) => !DEC
  *   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.
  *
+ *   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
+ *   ARE in the denominator, so "it performs badly" is not available as a reason
+ *   to keep it out. The two costs that ARE measured: (1) admitting it means
+ *   feeding its receiver-attributed cites alongside `citedMain`, which would flip
+ *   3 main-face (session,id) pairs from demote to promote on a cite the main thread
+ *   never made — 3 of the 1064 such pairs inside the 30 subagent-bearing sessions
+ *   sampled (0.28%), or 3 of 1935 (0.16%) if you widen to every subagent-bearing
+ *   session in the corpus; state which denominator you mean, the phrase "main-face
+ *   ids" alone does not pin it; (2) the 33 rows it would newly add cite at 15.2% and are
+ *   94% importance=3 — same LIMIT-50 eviction loop described under
+ *   `task_imperative` above, since both faces share selectImperativeLesson. Three
+ *   of those 33 would actually demote over that corpus.
+ *
+ *   Its sibling was admitted on 2026-08-25; this one deliberately was NOT, and the
+ *   difference is not the rate. task_imperative needed one line and no change to
+ *   `citedMain`; this face needs the receiver-attributed cites merged in
+ *   asymmetrically, and its numerator only became trustworthy on 2026-08-25 (see
+ *   collectSubagentSurface — it credited cross-agent citations until then). Letting
+ *   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.
+ *
  * 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>}
@@ -569,7 +692,7 @@ export function unionSurfaces(bySurface) {
 const SUBAGENT_INJECT_MARKER = /surfaced by your operator's claude-mem-lite/;
 // Row-anchored to the `#NN — ` tag so a #NN quoted inside the lesson body does NOT enter
 // the injected set — same discipline as INJECTED_ROW_RE for the attachment surfaces.
-const SUBAGENT_INJECT_ID_RE = /^\s{0,4}#(\d{1,7})\s+—/;
+const SUBAGENT_INJECT_ID_RE = new RegExp(`^\\s{0,4}#(${OBS_ID_DIGITS})\\s+—`);
 
 /**
  * Extract observation ids injected into a subagent's PROMPT by pre-agent-inject.js
@@ -628,20 +751,32 @@ export function findSubagentTranscripts(transcriptPath) {
  * also why the Stop path records this face in its own recordCitationSurfaces
  * call: one call carries one `cited` set for every face in it.
  *
- * UNIT — read this before reading the rate it produces. Both sets are unioned
- * across ALL of the session's sidechain files, so the resulting rate is
- * "fraction of injected ids that appear anywhere in any sidechain of this
- * session", NOT per-dispatch adoption. An id handed to agent A and cited by
- * agent B counts as a hit, and an id handed to three agents and cited by one
- * counts as one full hit rather than a third. Observed in real data (review of
- * v3.77.0): 1 of this project's 7 historical hits is exactly that shape. The
- * number is therefore biased HIGH against per-dispatch adoption — which matters
- * because D#152's instruction is to read this rate and then decide whether the
- * face enters the decay denominator (D#164). Per-dispatch attribution would
- * need per-file accounting, deliberately not built yet.
+ * UNIT — read this before reading the rate it produces (D#164 settled the first
+ * half of it; the second half is still a live caveat).
+ *
+ * `injected` is unioned by id across the session's sidechain files, which is the
+ * house caliber: every other face also counts an obs once per session no matter
+ * how many times it was injected. `cited` is NOT unioned — an id is credited only
+ * when the agent that RECEIVED it is the agent that cited it. This face is the
+ * only one where injection and citation can land in different contexts, so the
+ * union form silently counted "agent A was handed it, agent B mentioned it" as
+ * adoption. Measured over 30 live sessions before the attribution was added:
+ * 13/48 unioned vs 12/48 receiver-attributed.
+ *
+ * What is still biased HIGH: an id handed to three agents and cited by one counts
+ * as one full hit rather than a third, because the id-level denominator collapses
+ * the three dispatches into one. On the same corpus that is 48 ids over 82
+ * (dispatch, id) PAIRS — not 82 files: the sessions hold ~268 sidechain transcripts and
+ * most carry no injection — i.e. 25.0% id-level against 14.6% per-dispatch. Opportunity-level
+ * accounting would need a denominator shape citation_surface_log does not have
+ * (its key is (project, session, surface)), and changing that would put this face
+ * on a different ruler from the other six — so the id-level number is the one
+ * that is comparable to pretool/ups/fyi, and the per-dispatch number is the one
+ * to quote when asking "does a dispatched agent use what it was handed".
  *
  * @param {string|null|undefined} transcriptPath main-thread transcript (.jsonl)
  * @returns {{injected: Set<number>, cited: Set<number>, files: number}}
+ *   `cited` is always a subset of `injected`.
  */
 export function collectSubagentSurface(transcriptPath) {
   const injected = new Set();
@@ -649,8 +784,13 @@ export function collectSubagentSurface(transcriptPath) {
   let files = 0;
   for (const p of findSubagentTranscripts(transcriptPath)) {
     files++;
-    for (const id of extractInjectedFromSubagentPrompt(p)) injected.add(id);
-    for (const id of extractCitationsFromTranscript(p)) cited.add(id);
+    // Per-file intersection, not two unions: the pairing is the whole point.
+    const seen = extractInjectedFromSubagentPrompt(p);
+    const said = extractCitationsFromTranscript(p);
+    for (const id of seen) {
+      injected.add(id);
+      if (said.has(id)) cited.add(id);
+    }
   }
   return { injected, cited, files };
 }

package/lib/cite-back-hint.mjs

@@ -15,6 +15,9 @@ import { basename, join } from 'path';
 import { readFileSync } from 'fs';
 import { readTranscriptEntries } from './transcript-scan.mjs';
 import { EDIT_TOOLS } from '../utils.mjs';
+// One caliber for `#NN`. citation-tracker.mjs does NOT import this module, so the edge
+// is acyclic.
+import { citationIdRe } from './citation-tracker.mjs';
 
 const MAX_FILES = 2;
 
@@ -269,7 +272,9 @@ export function loadCiteBackForEpisode(episode, runtimeDir) {
 // #NN. The Stop handler unions these into the cited set passed to
 // applyCitationDecay (lib/citation-tracker.mjs), so acting on a lesson promotes
 // it and lifts the project's adoption rate. Returns an empty set on missing path.
-const CITE_BACK_ID_RE = /#(\d{1,7})\b/g;
+// The ids collected here are unioned into the SAME cited set applyCitationDecay reads,
+// so this caliber must be the extractor's own — imported, not a sixth hand-copy.
+const CITE_BACK_ID_RE = citationIdRe();
 
 export function extractCiteBackSignals(transcriptPath) {
   const ids = new Set();

package/lib/hook-stdout.mjs

@@ -27,6 +27,40 @@
 let parts = [];
 let queuedEvent = null;
 let systemParts = [];
+let queuedInput = null;
+
+/** Emit the noisy drop notice. stderr is safe: the host never parses it as the envelope. */
+function warnDrop(deps, msg) {
+  const warn = deps.warn || ((m) => { try { process.stderr.write(m); } catch { /* never block on a warning */ } });
+  warn(msg);
+}
+
+/**
+ * Claim this process's single hookEventName, or refuse the contribution.
+ *
+ * Mixed event names cannot be merged — Claude Code throws when
+ * hookSpecificOutput.hookEventName does not match the event it dispatched.
+ * In practice one process serves one event; keep the first and drop the
+ * stragglers rather than emit an envelope the host rejects outright.
+ *
+ * The drop is NOISY on purpose. It is unreachable today (all call sites are
+ * event-consistent), but flushEpisode's hookEventName DEFAULTS to 'PostToolUse',
+ * so a future caller that omits the argument would both mis-tag its receipt and
+ * have it swallowed without a trace. Silently vanishing work is this repo's
+ * most-repeated defect class.
+ *
+ * @returns {boolean} true when the caller may proceed.
+ */
+function claimEvent(hookEventName, what, deps) {
+  if (queuedEvent && queuedEvent !== hookEventName) {
+    warnDrop(deps, `[claude-mem-lite] hook-stdout: dropped a ${hookEventName} ${what} — this process `
+      + `already queued ${queuedEvent}, and one envelope carries exactly one hookEventName. `
+      + 'This is a wiring bug: the contribution is lost.\n');
+    return false;
+  }
+  queuedEvent = hookEventName;
+  return true;
+}
 
 /**
  * Queue a contribution to this process's single stdout envelope.
@@ -40,26 +74,40 @@ export function queueHookContext(hookEventName, text, deps = {}) {
   if (!hookEventName) return;
   const body = String(text ?? '').trim();
   if (!body) return;
-  // Mixed event names cannot be merged — Claude Code throws when
-  // hookSpecificOutput.hookEventName does not match the event it dispatched.
-  // In practice one process serves one event; keep the first and drop the
-  // stragglers rather than emit an envelope the host rejects outright.
-  //
-  // The drop is NOISY on purpose. It is unreachable today (all call sites are
-  // event-consistent), but flushEpisode's hookEventName DEFAULTS to 'PostToolUse',
-  // so a future caller that omits the argument would both mis-tag its receipt and
-  // have it swallowed without a trace. Silently vanishing work is this repo's
-  // most-repeated defect class; stderr is safe here because the host never parses it
-  // as the envelope.
-  if (queuedEvent && queuedEvent !== hookEventName) {
-    const warn = deps.warn || ((m) => { try { process.stderr.write(m); } catch { /* never block on a warning */ } });
-    warn(`[claude-mem-lite] hook-stdout: dropped a ${hookEventName} contribution — this process `
-      + `already queued ${queuedEvent}, and one envelope carries exactly one hookEventName. `
-      + 'This is a wiring bug: the contribution is lost.\n');
+  if (!claimEvent(hookEventName, 'contribution', deps)) return;
+  parts.push(body);
+}
+
+/**
+ * Queue a `hookSpecificOutput.updatedInput` — a REPLACEMENT of the tool's input,
+ * not a contribution to it. PreToolUse is the only event whose schema carries one
+ * (2.1.241 bundle: `{hookEventName: "PreToolUse", permissionDecision?,
+ * permissionDecisionReason?, updatedInput?, additionalContext?}`), and that same
+ * schema is why this belongs here rather than in its own writer: a mutation and a
+ * context line may ride ONE envelope, so a hook that grew both would otherwise
+ * emit two documents and lose both (the v3.70.0 degradation this module exists for).
+ *
+ * FIRST writer wins, and a second is dropped noisily. Unlike additionalContext
+ * there is no merge: two callers each hand over a whole tool_input, so last-wins
+ * would silently discard the earlier mutation — the same vanishing-work shape
+ * claimEvent guards against.
+ *
+ * @param {string} hookEventName Event name for hookSpecificOutput.
+ * @param {object} input Replacement tool_input; non-objects and null are ignored.
+ * @param {{warn?: (msg: string) => void}} [deps]
+ * @returns {void}
+ */
+export function queueHookUpdatedInput(hookEventName, input, deps = {}) {
+  if (!hookEventName) return;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return;
+  if (!claimEvent(hookEventName, 'updatedInput', deps)) return;
+  if (queuedInput) {
+    warnDrop(deps, '[claude-mem-lite] hook-stdout: dropped a second updatedInput — one envelope '
+      + 'replaces the tool input exactly once, and merging two whole inputs is not defined. '
+      + 'This is a wiring bug: the second mutation is lost.\n');
     return;
   }
-  queuedEvent = hookEventName;
-  parts.push(body);
+  queuedInput = input;
 }
 
 /**
@@ -93,24 +141,25 @@ export function queueHookSystemMessage(text) {
  * @returns {boolean} true when an envelope was written.
  */
 export function flushHookStdout(deps = {}) {
-  const hasContext = queuedEvent && parts.length > 0;
+  const hasContext = Boolean(queuedEvent) && parts.length > 0;
+  const hasInput = Boolean(queuedEvent) && queuedInput !== null;
   const hasSystem = systemParts.length > 0;
-  if (!hasContext && !hasSystem) return false;
+  if (!hasContext && !hasInput && !hasSystem) return false;
   const write = deps.write || ((s) => process.stdout.write(s));
   const envelope = { suppressOutput: true };
   if (hasSystem) envelope.systemMessage = systemParts.join('\n');
-  // Omitted entirely when there is no model-facing context: Stop's schema REJECTS a
-  // hookSpecificOutput block, and an envelope carrying only a user notice must not
-  // invent an event name to hang one on.
-  if (hasContext) {
-    envelope.hookSpecificOutput = {
-      hookEventName: queuedEvent,
-      additionalContext: parts.join('\n\n'),
-    };
+  // Omitted entirely when there is nothing addressed to the host's per-event block:
+  // Stop's schema REJECTS a hookSpecificOutput block, and an envelope carrying only a
+  // user notice must not invent an event name to hang one on.
+  if (hasContext || hasInput) {
+    envelope.hookSpecificOutput = { hookEventName: queuedEvent };
+    if (hasInput) envelope.hookSpecificOutput.updatedInput = queuedInput;
+    if (hasContext) envelope.hookSpecificOutput.additionalContext = parts.join('\n\n');
   }
   parts = [];
   queuedEvent = null;
   systemParts = [];
+  queuedInput = null;
   write(JSON.stringify(envelope) + '\n');
   return true;
 }
@@ -120,9 +169,15 @@ export function resetHookStdout() {
   parts = [];
   queuedEvent = null;
   systemParts = [];
+  queuedInput = null;
 }
 
 /** Test seam: what is queued right now. */
 export function peekHookStdout() {
-  return { hookEventName: queuedEvent, parts: [...parts], systemParts: [...systemParts] };
+  return {
+    hookEventName: queuedEvent,
+    parts: [...parts],
+    systemParts: [...systemParts],
+    updatedInput: queuedInput,
+  };
 }

package/mem-cli.mjs

@@ -2651,9 +2651,11 @@ function cmdCitationStats(db, args) {
     for (const s of surfaceFunnel.surfaces) {
       const pct = (s.rate * 100).toFixed(1) + '%';
       // Which faces actually move importance is NOT readable from the rates —
-      // and an annotated keyctx beside a bare task_imperative reads as "that
-      // one does feed decay", which is false. Derived from the exported sets so
-      // the note cannot drift from the behaviour it describes.
+      // and an annotated keyctx beside a bare `subagent` reads as "that one
+      // does feed decay", which is false. Derived from the exported sets so
+      // the note cannot drift from the behaviour it describes. (The example
+      // used to name task_imperative; it joined the denominator on 2026-08-25
+      // once its rate was read, leaving `subagent` as the bare non-decay face.)
       const note = s.surface === 'keyctx'
         ? '  (promotion-only: never demotes)'
         : (DECAY_DENOMINATOR_SURFACES.includes(s.surface)

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.79.0",
+  "version": "3.81.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.79.0",
+      "version": "3.81.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.79.0",
+  "version": "3.81.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/post-tool-recall.js

@@ -17,6 +17,11 @@ import { existsSync, readFileSync } from 'fs';
 import { basename, join } from 'path';
 import { resolveDataDir } from '../lib/resolve-data-dir.mjs';
 import { recordHookError } from '../lib/hook-telemetry.mjs';
+// D#154: every envelope on this stdout goes through the one writer. This script has a
+// single emit today, so the change buys nothing on its own — it buys that a SECOND
+// emit added later merges instead of producing two JSON documents, which the host
+// parses as neither (lib/hook-stdout.mjs). Import-free module over no runtime deps.
+import { queueHookContext, flushHookStdout } from '../lib/hook-stdout.mjs';
 
 const SALIENCE_BIND = process.env.CLAUDE_MEM_SALIENCE === 'bind';
 
@@ -69,10 +74,8 @@ async function main() {
   for (const d of dropped.slice(0, 3)) {
     lines.push(`[mem] ⚠ your edit to ${basename(filePath)} dropped \`${d.token}\` flagged by #${d.obsId} — if intentional say so, else re-check before moving on.`);
   }
-  process.stdout.write(JSON.stringify({
-    suppressOutput: true,
-    hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: lines.join('\n') },
-  }));
+  queueHookContext('PostToolUse', lines.join('\n'));
+  flushHookStdout();
 }
 
 // No forced process.exit(0): main() consumes stdin to EOF (or early-returns without

package/scripts/pre-agent-inject.js

@@ -66,15 +66,28 @@ async function main() {
   const { ensureDb } = await import('../schema.mjs');
   const { inferProject } = await import('../utils.mjs');
   const { buildSubagentInjection } = await import('../hook-memory.mjs');
+  // D#154: single envelope writer. Deferred to this line, not hoisted to a static
+  // import, because the file's stated contract is that the default-off path costs one
+  // env check and nothing else — the deferral filed this as "shared module vs
+  // import-free fast path, pick one", but the script already resolves that conflict
+  // three lines up: dynamic import on the enabled path only. The fast path above is
+  // untouched.
+  const { queueHookUpdatedInput, flushHookStdout } = await import('../lib/hook-stdout.mjs');
 
   let db;
   try { db = ensureDb(); } catch (e) { await recordFailure('agent-inject:db-open', e); return; }
   try {
     const updatedInput = buildSubagentInjection(db, hook.tool_input, inferProject());
     if (updatedInput) {
-      process.stdout.write(JSON.stringify({
-        hookSpecificOutput: { hookEventName: 'PreToolUse', updatedInput },
-      }));
+      // Behaviour delta vs the hand-written envelope this replaced: it now carries
+      // top-level `suppressOutput: true`. Verified display-only in the 2.1.241 bundle —
+      // the field is documented "Hide stdout from transcript (default: false)" and is
+      // read at exactly one place, the transcript-render branch
+      // (`if (a6(he) && !he.suppressOutput && …)`); the updatedInput mutation is taken
+      // from the parsed hookSpecificOutput regardless. Hiding it is also the right
+      // audience call: this payload is the whole prompt echoed back, not a message.
+      queueHookUpdatedInput('PreToolUse', updatedInput);
+      flushHookStdout();
     }
   } catch (e) { await recordFailure('agent-inject:query', e); /* never break a dispatch */ } finally {
     try { db.close(); } catch { /* */ }

package/scripts/pre-skill-bridge.js

@@ -11,6 +11,9 @@ import { resolveDataDir } from '../lib/resolve-data-dir.mjs';
 // format-utils.mjs is import-free — pulling three defang helpers keeps this script
 // inside its "lightweight standalone" budget (no heavy transitive deps).
 import { neutralizeContextDelimiters, neutralizeSkillDelimiters, neutralizeSkillBridgeDelimiters } from '../format-utils.mjs';
+// D#154: single envelope writer. Also import-free (no runtime deps), so it stays
+// inside this script's "lightweight standalone" budget.
+import { queueHookContext, flushHookStdout } from '../lib/hook-stdout.mjs';
 
 // CLAUDE_MEM_DIR mirrors pre-tool-recall.js — one env var sandboxes everything.
 const DATA_DIR = resolveDataDir(process.env.CLAUDE_MEM_DIR);
@@ -110,13 +113,8 @@ try {
     } else {
       additionalContext = `<skill-bridge name="${safeName}" source="managed">\n${defang(content)}\n</skill-bridge>\n\nThis skill was loaded from the managed registry. Follow the instructions above.`;
     }
-    process.stdout.write(JSON.stringify({
-      suppressOutput: true,
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        additionalContext,
-      },
-    }));
+    queueHookContext('PreToolUse', additionalContext);
+    flushHookStdout();
   } catch (e) {
     // Silent failure — never block Skill tool, but record for self-observation.
     recordHookError('skill-bridge:query', e, RUNTIME_DIR, { skillName });

package/scripts/pre-tool-recall.js

@@ -19,6 +19,25 @@ import { shouldWarnReread, buildRereadWarning, readFileMeta } from '../lib/rerea
 import { recordMetric } from '../lib/metrics.mjs';
 import { presentIdents } from '../lib/lesson-idents.mjs';
 import { neutralizeContextDelimiters } from '../format-utils.mjs';
+// D#154: the one stdout writer. This script has THREE emit sites (Read→Edit ack,
+// repeated-read guard, lesson block) and they stay one document because each branch
+// process.exit()s before reaching the next.
+//
+// Be precise about what routing them through the queue does and does not buy, because an
+// earlier version of this comment claimed "a second write is now impossible by
+// construction" and that is FALSE (pre-tag review, v3.80.0): each site flushes
+// IMMEDIATELY after queueing, and the flush resets the queue — so queue→flush→queue→flush
+// emits two documents exactly like two raw writes would. Merging is a property of
+// DEFERRING the flush (what hook.mjs does with a single flush at the end of its dispatch),
+// not of using the queue.
+//
+// What it does buy: one construction site instead of three, so the "only the writer
+// assembles an envelope" invariant is checkable (tests/hook-script-stdout-contract.test.mjs),
+// and the merge is AVAILABLE to anyone who later defers the flush. The mutual exclusion
+// itself is still control flow — the process.exit(0) below.
+//
+// Import-free module, no runtime deps — nothing added to this script's load cost.
+import { queueHookContext, flushHookStdout } from '../lib/hook-stdout.mjs';
 // Recall queries the SAVE-path project, so this MUST produce the same string as the
 // save path. It used to be a hand-kept copy of the same 6 lines; that copy had already
 // drifted once (missing the process.env.PWD fallback, so a symlinked project dir
@@ -305,16 +324,11 @@ try {
       const wasReadMode = typeof entry === 'object' && entry.mode === 'read';
       if (!isRead && wasReadMode && seenIds.length > 0 && !SALIENCE_LEGACY) {
         const idList = seenIds.map(id => `#${id}`).join(', ');
-        process.stdout.write(JSON.stringify({
-          suppressOutput: true,
-          hookSpecificOutput: {
-            hookEventName: 'PreToolUse',
-            additionalContext: [
-              '[mem] PreToolUse recall — system-injected context, continue your planned action:',
-              `[mem] ⚠ Lessons ${idList} were shown when you Read ${basename(filePath)} — ${ACTIVE_DIRECTIVE}`,
-            ].join('\n'),
-          },
-        }));
+        queueHookContext('PreToolUse', [
+          '[mem] PreToolUse recall — system-injected context, continue your planned action:',
+          `[mem] ⚠ Lessons ${idList} were shown when you Read ${basename(filePath)} — ${ACTIVE_DIRECTIVE}`,
+        ].join('\n'));
+        flushHookStdout();
         cooldown[filePath] = { ...entry, mode: 'edit' };
         writeCooldown(cooldownPath, cooldown, isSessionScoped);
       } else if (isRead && !REREAD_GUARD_OFF && typeof entry === 'object' && entry.reread) {
@@ -322,16 +336,11 @@ try {
         // nudge to reuse what's already in context. Read-only; never throws.
         const meta = readFileMeta(filePath);
         if (shouldWarnReread(entry.reread, meta ? meta.mtimeMs : null, isFullRead, REREAD_MIN_TOKENS)) {
-          process.stdout.write(JSON.stringify({
-            suppressOutput: true,
-            hookSpecificOutput: {
-              hookEventName: 'PreToolUse',
-              additionalContext: [
-                '[mem] PreToolUse recall — system-injected context, continue your planned action:',
-                buildRereadWarning(basename(filePath), entry.reread.tokens),
-              ].join('\n'),
-            },
-          }));
+          queueHookContext('PreToolUse', [
+            '[mem] PreToolUse recall — system-injected context, continue your planned action:',
+            buildRereadWarning(basename(filePath), entry.reread.tokens),
+          ].join('\n'));
+          flushHookStdout();
           recordMetric(DATA_DIR, { event: 'reread_warn' }); // tier-1 firing counter (②)
         }
       }
@@ -605,13 +614,8 @@ try {
     }
 
     if (lines.length > 0) {
-      process.stdout.write(JSON.stringify({
-        suppressOutput: true,
-        hookSpecificOutput: {
-          hookEventName: 'PreToolUse',
-          additionalContext: lines.join('\n'),
-        },
-      }));
+      queueHookContext('PreToolUse', lines.join('\n'));
+      flushHookStdout();
     }
     // Cooldown applies on ALL branches (including silent-Read) so subsequent
     // calls on the same file in the same session don't re-query — preserving