claude-mem-lite 3.76.1 → 3.77.0

package/.claude-plugin/marketplace.json

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

@@ -1,7 +1,7 @@
 // claude-mem-lite — Semantic Memory Injection
 // Search past observations for relevant memories to inject as context at user-prompt time.
 
-import { relaxFtsQueryToOr, debugCatch, truncate, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords, neutralizeContextDelimiters, basenameAnySep } from './utils.mjs';
+import { relaxFtsQueryToOr, debugCatch, truncate, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords, neutralizeContextDelimiters } from './utils.mjs';
 import { upsFtsQuery } from './lib/ups-query.mjs';
 import { citeFactorJs, TYPE_QUALITY, TYPE_QUALITY_DEFAULT } from './scoring-sql.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
@@ -98,8 +98,6 @@ function candidateCoverage(row, queryTerms) {
   return hits / queryTerms.length;
 }
 
-const FILE_RECALL_LOOKBACK_MS = 60 * DAY_MS; // 60 days
-const MAX_FILE_RECALL = 2;
 
 // P1: stale-obs verify-before-use threshold. An injected obs older than this
 // AND carrying file paths is flagged so Claude is reminded to grep/Read the
@@ -358,8 +356,27 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     // v26 P0: bump injection_count (NOT access_count) for injected rows.
     // Before v26 this was bumping access_count, which conflated auto-injection
     // with real cites/recalls/opens — polluting the noise-ratio signal the
-    // penalty clause now depends on. access_count is reserved for explicit
-    // access (cmdRecall/cmdGet/cmdTimeline/pre-tool-recall/citation-tracker).
+    // penalty clause now depends on.
+    //
+    // The two counters are NOT a metering pair, and reading them as one is how
+    // 2026-08-22 produced a wrong diagnosis off this very comment. Enumerated
+    // from the write sites rather than from memory:
+    //   access_count    — lib/recall-core.mjs (mem_recall / CLI recall),
+    //                     lib/get-core.mjs (mem_get), lib/timeline-core.mjs
+    //                     (timeline anchor), lib/citation-tracker.mjs (CITED
+    //                     ids only). All explicit. This comment used to list
+    //                     "pre-tool-recall" here too; scripts/pre-tool-recall.js
+    //                     bumps NOTHING, and the only code that would have was
+    //                     the unreferenced `recallForFile` twin deleted below.
+    //   injection_count — this line and scripts/user-prompt-search.js only, and
+    //                     deliberately so: scoring-sql.mjs noisePenaltyClause
+    //                     reads it as a NOISE signal (x0.5 at >=4, x0.2 at >=8),
+    //                     so it is valid only on QUERY-CONDITIONED faces. v3.66.0
+    //                     added an unconditional Key Context bump "mirroring"
+    //                     this one and v3.66.1 reverted it — an always-rendered
+    //                     face measures elapsed sessions, not noise (D#124,
+    //                     lib/keyctx-marker.mjs:53). The complete per-face
+    //                     denominator is citation_surface_log, not this column.
     // Per-row try/catch for FTS trigger safety (project_non_obvious.md).
     const result = coverageFiltered.slice(0, MAX_MEMORY_INJECTIONS);
     const now = Date.now();
@@ -380,49 +397,20 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
   }
 }
 
-/**
- * Recall observations related to a specific file being edited.
- * Useful for surfacing past bugfixes / decisions when revisiting a file.
- * @param {import('better-sqlite3').Database} db Memory database
- * @param {string} filePath File path (absolute or relative)
- * @param {string} project Current project
- * @returns {object[]} Up to MAX_FILE_RECALL observations with {id, type, title, importance, lesson_learned}
- */
-export function recallForFile(db, filePath, project) {
-  if (!db || !filePath) return [];
-  try {
-    // Both separators: filePath comes from a hook payload written by the
-    // CLIENT's OS, so a Windows path can reach a POSIX host (and vice versa).
-    const basename = basenameAnySep(filePath);
-    const cutoff = Date.now() - FILE_RECALL_LOOKBACK_MS;
-    // Escape SQL LIKE wildcards in filename to prevent injection
-    const escaped = basename.replace(/%/g, '\\%').replace(/_/g, '\\_');
-    const likePattern = `%${escaped}`;
-    const rows = db.prepare(`
-      SELECT DISTINCT o.id, o.type, o.title, o.importance, o.lesson_learned
-      FROM observations o
-      JOIN observation_files of2 ON of2.obs_id = o.id
-      WHERE o.project = ?
-        AND o.importance >= 2
-        AND ${liveObsFilterSql('o')}
-        AND o.created_at_epoch > ?
-        AND (of2.filename = ? OR of2.filename LIKE ? ESCAPE '\\')
-      ORDER BY o.created_at_epoch DESC
-      LIMIT ?
-    `).all(project, cutoff, filePath, likePattern, MAX_FILE_RECALL);
-    const now = Date.now();
-    const updateStmt = db.prepare('UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id = ?');
-    // Per-row try/catch for FTS trigger safety — mirror the injection-bump loop
-    // (searchRelevantMemories) and project_non_obvious.md. Without it, one
-    // SQLITE_CORRUPT_VTAB on the access_count UPDATE trigger throws to the outer
-    // catch and discards the ENTIRE file-recall result set.
-    for (const r of rows) { try { updateStmt.run(now, r.id); } catch {} }
-    return rows;
-  } catch (e) {
-    debugCatch(e, 'recallForFile');
-    return [];
-  }
-}
+// `recallForFile` lived here until 2026-08-22: an in-process file-recall
+// implementation with ZERO production callers, superseded by the standalone
+// scripts/pre-tool-recall.js hook (which owns the cooldown, scope filter,
+// edge-decay filter and event leg this function never had). Five test files
+// asserted against it, which made it look alive and cost real money twice:
+//   - its bare `%<basename>` LIKE lacked the path-boundary arms that
+//     lib/file-edge-match.mjs added for the bash-utils.mjs/utils.mjs collision;
+//   - 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 `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/lib/file-edge-match.mjs

@@ -20,9 +20,30 @@
 // LIKE wildcards in the basename are escaped (sqlite gotcha #9); LIKE itself
 // is ASCII-case-insensitive, matching arm 1/2's NOCASE.
 //
-// Dependency-free on purpose: pre-tool-recall.js is a ~30ms cold-start script.
-
-import { basename } from 'path';
+// The basename split accepts EITHER separator regardless of host OS. node:path
+// `basename` is host-native: on a POSIX host it does not treat '\' as a
+// separator, so `basename('C:\\proj\\src\\x.mjs')` returns the WHOLE path and
+// arms 2-4 degrade to garbage — a Windows-shaped payload then recalls nothing.
+// That mattered because the header above declares filename heterogeneous with
+// EITHER separator, and hook payloads carry the CLIENT machine's path shape.
+// The correct split existed only in `recallForFile` (hook-memory.mjs), a twin
+// with no production caller, and the Windows tests asserted against the twin —
+// so the shipped half carried the gap unobserved until 2026-08-22.
+//
+// Accepting both separators WIDENS matching for one exotic case, on the record as a
+// decision rather than a side effect: '\' is a legal POSIX filename character, so a
+// file literally named `b\c.mjs` now derives to `c.mjs` and can match observations
+// recorded against `c.mjs`. Arm 4 (`%\<basename>`) still catches the old spelling, so
+// a pre-tag review measured zero lost matches across 9 probes × 15 stored filename
+// shapes — the change is purely additive. Real exposure is nil: 0 of 6406
+// observation_files rows on the maintainer's DB contain a backslash. A recall system
+// over-recalling a hypothetical file is the right side to err on.
+//
+// Dependency-free on purpose: pre-tool-recall.js is a ~30ms cold-start script and
+// imports nothing from utils.mjs (which pulls in child_process and five modules),
+// so the split is inlined below rather than imported. utils.mjs used to export the
+// same two lines as `basenameAnySep`; that copy was deleted in the same round once
+// its only consumer went, so this file is now the sole home.
 
 /**
  * SQL boolean expression for the four-arm match. Placeholder order matches
@@ -34,9 +55,24 @@ export function fileMatchClause(alias = '') {
     `OR ${p}filename LIKE ? ESCAPE '\\' OR ${p}filename LIKE ? ESCAPE '\\')`;
 }
 
+/**
+ * Last path segment, splitting on '/' OR '\' whatever the host OS is.
+ * THE only copy in the repo — keep it that way, and import it rather than
+ * re-deriving. A second copy is what produced the gap this replaced: the
+ * derivation existed twice and the tests asserted the one that did not ship.
+ * Exported for the one caller that needs the key without the SQL
+ * (scripts/pre-tool-recall.js's events leg, which matches a JSON array in a
+ * TEXT column rather than the observation_files junction).
+ * Not for filesystem access — '\' is a legal POSIX filename character.
+ */
+export function basenameAnySep(p) {
+  const s = String(p ?? '').replace(/[/\\]+$/, '');
+  return s.slice(Math.max(s.lastIndexOf('/'), s.lastIndexOf('\\')) + 1);
+}
+
 /** Bind values for fileMatchClause, in placeholder order. */
 export function fileMatchParams(filePath) {
-  const fname = basename(filePath);
+  const fname = basenameAnySep(filePath);
   const escaped = fname.replace(/%/g, '\\%').replace(/_/g, '\\_');
   // `%\\` before the basename: under ESCAPE '\', a literal backslash is
   // written '\\' — so the JS string carries two backslash characters.

package/lib/recall-core.mjs

@@ -5,9 +5,9 @@
 // the maintain hand-sync drift (#8614). Renderers stay per-surface; the data
 // contract lives here.
 
-import { basename } from 'path';
 import { notLowSignalTitleClause } from '../utils.mjs';
 import { liveObsFilterSql } from './inject-search-core.mjs';
+import { fileMatchClause, fileMatchParams, basenameAnySep } from './file-edge-match.mjs';
 
 /**
  * Recall observations linked to a file (basename or full path). Returns
@@ -23,9 +23,14 @@ import { liveObsFilterSql } from './inject-search-core.mjs';
  * and must not reach this clause: nobody asks for retracted content.
  */
 export function recallByFile(db, file, { limit = 10, includeNoise = false } = {}) {
-  const filename = basename(file);
-  const escaped = filename.replace(/%/g, '\\%').replace(/_/g, '\\_');
-  const likePattern = `%${escaped}`;
+  // Shared predicate, not a hand-rolled one (pre-tag review of v3.76.2, SF-1/S3).
+  // This face carried BOTH defects v3.76.2 fixed in the injection path: node:path
+  // `basename` (so a Windows-shaped argument derived to the whole string and matched
+  // nothing) and a bare `%<basename>` suffix LIKE with no path boundary (so recalling
+  // `utils.mjs` returned `bash-utils.mjs` lessons). recallByFile is mem_recall (MCP)
+  // AND the CLI `recall` command, so both surfaces were wrong. fileMatchClause's
+  // four arms and fileMatchParams' escaping are the single home for this.
+  const filename = basenameAnySep(file);
   const noiseClause = includeNoise ? '' : `AND ${notLowSignalTitleClause('o')}`;
   const rows = db.prepare(`
     SELECT DISTINCT o.id, o.type, o.title, o.lesson_learned, o.importance,
@@ -33,11 +38,11 @@ export function recallByFile(db, file, { limit = 10, includeNoise = false } = {}
     FROM observations o
     JOIN observation_files of2 ON of2.obs_id = o.id
     WHERE ${liveObsFilterSql('o')}
-      AND (of2.filename = ? OR of2.filename LIKE ? ESCAPE '\\')
+      AND ${fileMatchClause('of2')}
       ${noiseClause}
     ORDER BY o.created_at_epoch DESC
     LIMIT ?
-  `).all(filename, likePattern, limit);
+  `).all(...fileMatchParams(file), limit);
 
   if (rows.length > 0) {
     const ph = rows.map(() => '?').join(',');

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 {
@@ -2154,7 +2155,8 @@ function cmdMaintain(db, args) {
     if (ops.includes('demote_pinned')) {
       // Repair the citation-decay blind spot: decay protects injection_count>0, so a
       // heavily-injected-but-uncited memory stays pinned at max importance forever.
-      // demotePinned (maintain-core) drops it to 1 in one pass. Floor 1, not purge.
+      // demotePinned (maintain-core) floors it in one pass: no lesson_learned -> 1,
+      // lesson-bearing -> 2 (v3.76.1 dual floor). Floor, not purge.
       const demoted = demotePinned(db, mctx);
       results.push(`Demoted ${demoted} pinned-but-uncited observations (inj>=${PINNED_INJ_THRESHOLD}, cited=0; no lesson → importance 1, lesson → 2)${capHint(demoted)}`);
     }
@@ -2648,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}`);
     }
   }
@@ -2796,7 +2806,9 @@ Commands:
     --merge-ids K:R,... For dedup: keepId:removeId pairs (e.g. 10:11,20:21:22)
     --project P         Filter by project
     --retain-days N     For purge_stale: keep last N days (default 30)
-                        demote_pinned: importance→1 for inj>=8 & cited=0 (clears pinned noise).
+                        demote_pinned: floors importance for inj>=8 & cited=0 — to 1 with no
+                        lesson_learned, to 2 with one (clears pinned noise; a lesson-bearing
+                        row keeps eligibility on every importance>=2 injection face).
                         In the default set since v3.76.0; runs AFTER boost, which would
                         otherwise hand the row straight back. Opt out of the DEFAULT with
                         CLAUDE_MEM_SKIP_DEMOTE_PINNED=1 — an explicit --ops demote_pinned

package/npm-shrinkwrap.json

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

package/scripts/pre-tool-recall.js

@@ -13,7 +13,7 @@ import { liveObsFilterSql } from '../lib/inject-search-core.mjs';
 import { buildNotLowSignalSql } from '../lib/low-signal-patterns.mjs';
 import { recordHookError } from '../lib/hook-telemetry.mjs';
 import { citeFactorClause } from '../scoring-sql.mjs';
-import { fileMatchClause, fileMatchParams } from '../lib/file-edge-match.mjs';
+import { fileMatchClause, fileMatchParams, basenameAnySep } from '../lib/file-edge-match.mjs';
 import { fileIntelFor } from '../lib/file-intel.mjs';
 import { shouldWarnReread, buildRereadWarning, readFileMeta } from '../lib/reread-guard.mjs';
 import { recordMetric } from '../lib/metrics.mjs';
@@ -355,7 +355,14 @@ try {
 
   try {
     const project = inferProject();
-    const fname = basename(filePath);
+    // Same any-separator split the observations leg gets through fileMatchParams
+    // (pre-tag review of v3.76.2, SF-1/S1). This derivation feeds the EVENTS leg
+    // ~120 lines below, which matches a JSON array inside events.file_paths rather
+    // than the observation_files junction, so it cannot use fileMatchClause — but it
+    // needs the same key, and host-native `basename` gave it the whole path for a
+    // Windows-shaped payload. Fixing the observations leg alone would have left this
+    // hook recalling lessons but no events.
+    const fname = basenameAnySep(filePath);
     // Escape LIKE wildcards (still needed below for the events file_paths arms)
     const escaped = fname.replace(/%/g, '\\%').replace(/_/g, '\\_');
     // P0 (D#78): path-boundary match — editing utils.mjs must NOT pull lessons

package/scripts/user-prompt-search.js

@@ -6,6 +6,7 @@
 import { ensureDb, DB_DIR, REGISTRY_DB_PATH } from '../schema.mjs';
 import { relaxFtsQueryToOr, truncate, typeIcon, inferProject, OBS_BM25, notLowSignalTitleClause, stripPrivate, neutralizeContextDelimiters, MAX_UPS_PROMPT_BYTES } from '../utils.mjs';
 import { liveObsFilterSql, injectionRelevanceSql } from '../lib/inject-search-core.mjs';
+import { fileMatchClause, fileMatchParams, basenameAnySep } from '../lib/file-edge-match.mjs';
 import { cjkPrecisionOk } from '../nlp.mjs';
 import { upsFtsQuery } from '../lib/ups-query.mjs';
 import { writeFileSync, readFileSync, existsSync, renameSync } from 'fs';
@@ -448,10 +449,13 @@ function searchByFile(db, files, project, limit) {
   const results = [];
 
   for (const file of files.slice(0, 3)) {
-    const basename = file.split('/').pop();
+    // Shared predicate (pre-tag review of v3.76.2, SF-1/S2). This leg used
+    // `file.split('/').pop()` — weaker than node:path `basename`, since it misses '\'
+    // even ON a Windows host — plus a bare `%<basename>` suffix LIKE with no path
+    // boundary, so a prompt mentioning `utils.mjs` recalled `bash-utils.mjs` lessons.
+    // fileMatchClause's four arms and fileMatchParams' escaping are the single home.
+    const basename = basenameAnySep(file);
     if (!basename || basename.length < 2) continue;
-    const escaped = basename.replace(/%/g, '\\%').replace(/_/g, '\\_');
-    const likePattern = `%${escaped}`;
 
     // R1: exclude LOW_SIGNAL degraded titles from file-level recall.
     const rows = db.prepare(`
@@ -462,11 +466,11 @@ function searchByFile(db, files, project, limit) {
         AND o.importance >= 1
         AND ${liveObsFilterSql('o')}
         AND o.created_at_epoch > ?
-        AND (of2.filename = ? OR of2.filename LIKE ? ESCAPE '\\')
+        AND ${fileMatchClause('of2')}
         AND ${notLowSignalTitleClause('o')}
       ORDER BY o.created_at_epoch DESC
       LIMIT ?
-    `).all(project, cutoff, file, likePattern, limit);
+    `).all(project, cutoff, ...fileMatchParams(file), limit);
 
     results.push(...rows);
   }

package/tool-schemas.mjs

@@ -247,7 +247,7 @@ export const memOptimizeSchema = {
 export const memMaintainSchema = {
   action: z.enum(['scan', 'execute']).describe('scan=analyze candidates, execute=apply changes'),
   operations: z.array(z.enum(['dedup', 'decay', 'cleanup', 'boost', 'demote_pinned', 'purge_stale', 'rebuild_vectors', 'vacuum'])).optional()
-    .describe('Operations: dedup=find/merge duplicate observations, decay=reduce importance of old low-value obs, cleanup=remove orphaned records, boost=promote frequently-accessed obs, demote_pinned=importance→1 for obs injected>=8 times but never cited (clears pinned noise the decay op cannot reach; in the default set since v3.76.0 and ordered after boost, since boost would otherwise raise the row straight back — set CLAUDE_MEM_SKIP_DEMOTE_PINNED=1 to drop it from the DEFAULT set only), purge_stale=DELETE pending-purge obs older than retain_days (requires confirm=true; first call previews), rebuild_vectors=rebuild TF-IDF vocabulary and all observation vectors, vacuum=reclaim freelist dead space (whole-DB)'),
+    .describe('Operations: dedup=find/merge duplicate observations, decay=reduce importance of old low-value obs, cleanup=remove orphaned records, boost=promote frequently-accessed obs, demote_pinned=floor importance for obs injected>=8 times but never cited — to 1 with no lesson_learned, to 2 with one (v3.76.1: a lesson-bearing row keeps eligibility on every importance>=2 injection face) (clears pinned noise the decay op cannot reach; in the default set since v3.76.0 and ordered after boost, since boost would otherwise raise the row straight back — set CLAUDE_MEM_SKIP_DEMOTE_PINNED=1 to drop it from the DEFAULT set only), purge_stale=DELETE pending-purge obs older than retain_days (requires confirm=true; first call previews), rebuild_vectors=rebuild TF-IDF vocabulary and all observation vectors, vacuum=reclaim freelist dead space (whole-DB)'),
   merge_ids: z.preprocess(
     (v) => Array.isArray(v) ? v.map(g => Array.isArray(g) ? g.map(x => typeof x === 'string' ? parseInt(x, 10) : x) : g) : v,
     z.array(z.array(z.number().int()).min(2))

package/utils.mjs

@@ -47,20 +47,15 @@ export function isPathConfined(candidate, allowedBase) {
   return resolved === base || resolved.startsWith(base + sep);
 }
 
-/**
- * Basename that treats BOTH '/' and '\' as separators on every host OS.
- * `path.basename` follows the HOST's rules, so on POSIX it returns a Windows
- * path unchanged. Hook payloads carry the CLIENT's paths and
- * observation_files.filename stores either separator (lib/file-edge-match.mjs),
- * so DB search keys derived from them must be host-independent.
- * Not for filesystem access — '\' is a legal POSIX filename character.
- * @param {string} p Path in any separator style
- * @returns {string} Last segment, trailing separators ignored; '' if none
- */
-export function basenameAnySep(p) {
-  const s = String(p ?? '').replace(/[/\\]+$/, '');
-  return s.slice(Math.max(s.lastIndexOf('/'), s.lastIndexOf('\\')) + 1);
-}
+// `basenameAnySep` lived here until 2026-08-22. Its sole production consumer was
+// `recallForFile` (hook-memory.mjs), which had no callers of its own and was
+// deleted the same round; keeping the export would have added a dead name to the
+// knip baseline. The behaviour it encoded is NOT gone — it moved into
+// lib/file-edge-match.mjs (module-private, so that ~30ms cold-start path stays
+// free of this module's child_process import), which is where the split actually
+// had to happen: `path.basename` follows the HOST's rules, so on POSIX it returns
+// a Windows path unchanged, while observation_files.filename stores either
+// separator. tests/win-path-basename.test.mjs asserts it through fileMatchParams.
 
 // ─── Token Estimation ─────────────────────────────────────────────────────