claude-mem-lite 3.76.1 → 3.76.2

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.76.1",
+      "version": "3.76.2",
       "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.76.2",
   "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,18 @@ 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 `matchFileEdges` (tests/test-helpers.mjs), which
+// calls the shipped predicate. Do not reintroduce an in-process twin here.
 
 /**
  * Phase-2 task-imperative ranking (spec 2026-06-29 §4.1): score every candidate lesson

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

@@ -2154,7 +2154,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)}`);
     }
@@ -2796,7 +2797,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.76.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.76.1",
+      "version": "3.76.2",
       "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.76.2",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/scripts/pre-tool-recall.js

@@ -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 ─────────────────────────────────────────────────────