claude-mem-lite 3.80.0 → 3.81.0

package/.claude-plugin/marketplace.json

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

@@ -547,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));
@@ -578,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>}
@@ -684,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();
@@ -705,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/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.80.0",
+  "version": "3.81.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.80.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.80.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",