claude-mem-lite 3.76.2 → 3.77.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.76.2",
+      "version": "3.77.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.76.2",
+  "version": "3.77.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-memory.mjs

@@ -407,8 +407,10 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
 //   - it was the ONLY code splitting basenames on either separator, so the six
 //     Windows-path tests aimed at it went green while the shipped predicate
 //     carried the gap (fixed in lib/file-edge-match.mjs, same round).
-// Those suites now run through `matchFileEdges` (tests/test-helpers.mjs), which
-// calls the shipped predicate. Do not reintroduce an in-process twin here.
+// Those suites now run through `fileEdgeMatchOnly` (tests/test-helpers.mjs),
+// which calls the shipped MATCH clause — and only that clause; the rest of the
+// injection query is guarded by the subprocess cases in
+// tests/pre-tool-recall.test.mjs. Do not reintroduce an in-process twin here.
 
 /**
  * Phase-2 task-imperative ranking (spec 2026-06-29 §4.1): score every candidate lesson

package/hook.mjs

@@ -62,6 +62,7 @@ import {
   applyCitationDecay,
   recordCitationFunnel,
   recordCitationSurfaces,
+  collectSubagentSurface,
   hasMainThreadAssistantText,
 } from './lib/citation-tracker.mjs';
 import { resolveEdgeAttribution, readPreRecallFileEdges } from './lib/edge-attribution.mjs';
@@ -860,6 +861,41 @@ async function handleStop() {
             const payload = { ...stats, ...bugfixStats, lowStreak, decisionSignal, project, savedAt: Date.now() };
             writeFileSync(dest, JSON.stringify(payload), { mode: 0o600 });
           } catch (e) { debugCatch(e, 'handleStop-cite-recall-persist'); }
+
+          // D#152: the `subagent` face. Recorded in its OWN
+          // recordCitationSurfaces call because it carries a different `cited`
+          // set — a lesson handed to a dispatched subagent is cited in that
+          // subagent's own transcript. Folding it into the main call would score
+          // subagent injections against citedMain and report 0% by
+          // 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.
+          //
+          // Placed LAST on purpose: lib/transcript-scan.mjs memoizes ONE file,
+          // so reading the sidechain files evicts the parent transcript. Run
+          // 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
+          // above documents. Measured by instrumenting the parse: 1 parent parse
+          // at this position, 2 when relocated earlier. ~25ms on the largest
+          // real transcript here (5.4MB), matching lib/transcript-scan.mjs's
+          // own header figure.
+          // The text floor is re-checked rather than inherited — same reason as
+          // every other face: a tool-only Stop must not bank a verdict, and it
+          // must not enter the funnel's session denominator either.
+          try {
+            if (hasMainThreadAssistantText(transcriptPath)) {
+              const sub = collectSubagentSurface(transcriptPath);
+              if (sub.injected.size > 0) {
+                recordCitationSurfaces(db, project, ccSessionId || sessionId,
+                  { subagent: sub.injected }, sub.cited);
+                debugLog('DEBUG', 'handleStop',
+                  `subagent-face: files=${sub.files} injected=${sub.injected.size} cited=${sub.cited.size}`);
+              }
+            }
+          } catch (e) { debugCatch(e, 'handleStop-subagent-face'); }
         }
       } catch (e) { debugCatch(e, 'handleStop-citation-track'); }
     } finally {

package/lib/citation-tracker.mjs

@@ -246,9 +246,14 @@ const FYI_LINE_ID_RE = /^#(\d{1,7})\s/;
  * imperative line — which is how it stayed unmetered since v3.23 while being a live
  * injection: the `ups` matcher gates on `<memory-context` and collects only `- [` rows.
  * The two faces therefore OVERLAP on attachments but never on ids.
- * @type {ReadonlyArray<'pretool'|'ups'|'error_recall'|'fyi'|'task_imperative'|'keyctx'>}
+ * `subagent` (v3.77, D#152) is the second one: pre-agent-inject.js appends the
+ * memory block to a DISPATCHED subagent's task prompt via PreToolUse
+ * `updatedInput`, and Claude Code writes that turn to
+ * `<session>/subagents/agent-*.jsonl` — never to the parent transcript. See
+ * NON_ATTACHMENT_SURFACES.
+ * @type {ReadonlyArray<'pretool'|'ups'|'error_recall'|'fyi'|'task_imperative'|'keyctx'|'subagent'>}
  */
-export const CITATION_SURFACES = ['pretool', 'ups', 'error_recall', 'fyi', 'task_imperative', 'keyctx'];
+export const CITATION_SURFACES = ['pretool', 'ups', 'error_recall', 'fyi', 'task_imperative', 'keyctx', 'subagent'];
 
 // Single source of truth for "which attachment belongs to which face, and how
 // its ids are read off". Both the per-face extractors below AND the one-pass
@@ -499,6 +504,30 @@ const DECAY_EXCLUDED_SURFACES = new Set(['task_imperative']);
 /** @type {ReadonlyArray<string>} faces that DO feed the decay denominator. */
 export const DECAY_DENOMINATOR_SURFACES = ATTACHMENT_SURFACES.filter((f) => !DECAY_EXCLUDED_SURFACES.has(f));
 
+/**
+ * Faces that leave NO hook attachment in the parent transcript. Because
+ * DECAY_DENOMINATOR_SURFACES is derived from ATTACHMENT_SURFACES, these can
+ * never enter the decay denominator by the derivation — they enter only if a
+ * call site unions them in deliberately. That silence is the danger, so each is
+ * named here with the reason it stays out:
+ *
+ * - `keyctx` (D#124): the SessionStart Key Context block re-renders the same
+ *   fixed top-10 unconditionally, so an uncited render says nothing about
+ *   relevance. handleStop feeds its ids in PROMOTION-ONLY — cited ones join the
+ *   decay set, ignored ones never do. v3.66.0 fed them as a bare denominator
+ *   and the block ate its own contents.
+ * - `subagent` (D#152): the injection lands in a dispatched subagent's PROMPT
+ *   and its cite signal lands in that subagent's OWN transcript, so it is not
+ *   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.
+ *
+ * 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>}
+ */
+export const NON_ATTACHMENT_SURFACES = ['keyctx', 'subagent'];
+
 /**
  * Flatten a per-face breakdown into the single injected set the decay loop
  * takes. Derived — NOT a second hand-maintained face list — so adding a face to
@@ -565,6 +594,67 @@ export function extractInjectedFromSubagentPrompt(transcriptPath) {
   return ids;
 }
 
+/**
+ * Locate the sidechain (subagent) transcripts belonging to ONE session, given
+ * that session's main transcript path. Claude Code lays them out as
+ * `<dir>/<sessionId>.jsonl` + `<dir>/<sessionId>/subagents/agent-<name>-<hash>.jsonl`,
+ * so the directory is derived from the parent path — no directory scan, no
+ * dependence on the CC session id being available at the call site.
+ *
+ * Two search shapes that look right and silently return nothing (#10801, and the
+ * reason D#152 sat blocked): the files are NOT at the transcript directory's top
+ * level, and grepping the PARENT transcript for `isSidechain` finds 0 records —
+ * the flag lives inside the subagent files themselves.
+ *
+ * @param {string|null|undefined} transcriptPath main-thread transcript (.jsonl)
+ * @returns {string[]} absolute paths, empty when the session dispatched no subagents
+ */
+export function findSubagentTranscripts(transcriptPath) {
+  if (!transcriptPath || typeof transcriptPath !== 'string') return [];
+  if (!transcriptPath.endsWith('.jsonl')) return [];
+  const dir = join(transcriptPath.slice(0, -'.jsonl'.length), 'subagents');
+  let names;
+  try { names = readdirSync(dir); } catch { return []; }
+  return names.filter((n) => n.endsWith('.jsonl')).map((n) => join(dir, n)).sort();
+}
+
+/**
+ * Read the `subagent` face for ONE session: ids injected into dispatched
+ * subagents' prompts, and the ids those subagents actually cited.
+ *
+ * `cited` is read from the SUBAGENT transcripts, not the parent — a lesson
+ * handed to a subagent is cited (or not) in that subagent's own text, and
+ * scoring it against the main thread would report 0% by construction. That is
+ * 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.
+ *
+ * @param {string|null|undefined} transcriptPath main-thread transcript (.jsonl)
+ * @returns {{injected: Set<number>, cited: Set<number>, files: number}}
+ */
+export function collectSubagentSurface(transcriptPath) {
+  const injected = new Set();
+  const cited = new Set();
+  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);
+  }
+  return { injected, cited, files };
+}
+
 export function computeThreadCiteRecall(transcriptPath) {
   const injected = extractAllInjected(transcriptPath);
   // Subagent files carry NO hook-attachment injection; pre-agent-inject.js injects into

package/mem-cli.mjs

@@ -64,7 +64,7 @@ import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentT
 import { buildSearchFtsQuery, parseDateBounds, parseDuration, coreRunSearchPipeline } from './lib/search-core.mjs';
 import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { countRecentHookErrors } from './lib/hook-telemetry.mjs';
-import { computeCitationFunnelTrend, computeSurfaceFunnel } from './lib/citation-tracker.mjs';
+import { computeCitationFunnelTrend, computeSurfaceFunnel, DECAY_DENOMINATOR_SURFACES } from './lib/citation-tracker.mjs';
 
 // Human labels for citation_surface_log.surface. Padded to a common width so
 // the citation-stats face table lines up; the enum itself lives in
@@ -74,8 +74,9 @@ const SURFACE_LABELS = {
   ups:            'UserPromptSubmit   ',
   error_recall:   'error-recall       ',
   fyi:            'FYI (prompt-search)',
-  task_imperative: 'task-imperative   ',
+  task_imperative: 'task-imperative    ',
   keyctx:         'Key Context        ',
+  subagent:       'subagent (dispatch)',
 };
 import { aggregateMetrics, readMetrics } from './lib/metrics.mjs';
 import {
@@ -2649,7 +2650,15 @@ function cmdCitationStats(db, args) {
   } else {
     for (const s of surfaceFunnel.surfaces) {
       const pct = (s.rate * 100).toFixed(1) + '%';
-      const note = s.surface === 'keyctx' ? '  (promotion-only: never demotes)' : '';
+      // 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.
+      const note = s.surface === 'keyctx'
+        ? '  (promotion-only: never demotes)'
+        : (DECAY_DENOMINATOR_SURFACES.includes(s.surface)
+          ? ''
+          : '  (metered only: outside the decay denominator)');
       out(`  ${SURFACE_LABELS[s.surface] || s.surface}  inj ${String(s.injected).padStart(4)}  cited ${String(s.cited).padStart(4)}  ${pct.padStart(6)}  over ${s.sessions} session(s)${note}`);
     }
   }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.76.2",
+  "version": "3.77.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.76.2",
+      "version": "3.77.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.76.2",
+  "version": "3.77.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/schema.mjs

@@ -280,7 +280,7 @@ const CORE_SCHEMA = `
   -- v45: per-INJECTION-FACE twin of citation_log. One row per
   -- (project, session, surface); the surface column is one of the
   -- CITATION_SURFACES enum in lib/citation-tracker.mjs
-  -- (pretool | ups | error_recall | fyi | task_imperative | keyctx). The column is plain
+  -- (pretool | ups | error_recall | fyi | task_imperative | keyctx | subagent). The column is plain
   -- TEXT with no CHECK: the JS enum is the gate (recordCitationSurfaces drops unknown
   -- labels), which is why adding a face needs no migration.
   --