claude-mem-lite 2.99.0 → 3.0.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.99.0",
+      "version": "3.0.1",
       "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": "2.99.0",
+  "version": "3.0.1",
   "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/lib/file-intel.mjs

@@ -0,0 +1,160 @@
+// lib/file-intel.mjs — pure, zero-dependency builder for the PreToolUse:Read
+// "file intelligence" injection (feature ①). Before Claude reads a file, surface
+// its approximate token size + a one-line "what's in it" so the agent can decide
+// to read fully, read a slice, or grep instead.
+//
+// Imported by the hot standalone scripts/pre-tool-recall.js, so it MUST stay
+// dependency-free and cheap: one bounded file read + regex, no heavy imports.
+// (Lesson #8447: fast-path scripts can't pull in utils.mjs, which drags in
+// child_process/nlp/scoring-sql.) estimateContentTokens is therefore a hand-
+// mirror of utils.estimateTokens; tests/file-intel.test.mjs pins the two so a
+// change to the canonical estimator surfaces as a failing mirror test.
+
+import { statSync, openSync, readSync, closeSync } from 'fs';
+import { basename as pathBasename } from 'path';
+
+const SUMMARY_MAX = 80;
+const DEFAULT_MIN_TOKENS = 800;
+const DEFAULT_MAX_READ_BYTES = 24 * 1024;
+
+// Mirror of utils.estimateTokens (ASCII ~4 chars/token, CJK ~1.5). Kept local so
+// the standalone hook stays lean — see file header + the mirror test.
+export function estimateContentTokens(text) {
+  const s = text || '';
+  if (!s) return 1;
+  let cjkCount = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if ((c >= 0x4e00 && c <= 0x9fff) || (c >= 0x3400 && c <= 0x4dbf) ||
+        (c >= 0x3000 && c <= 0x303f) || (c >= 0xff00 && c <= 0xffef) ||
+        (c >= 0xac00 && c <= 0xd7af)) {
+      cjkCount++;
+    }
+  }
+  const asciiLen = s.length - cjkCount;
+  return Math.max(1, Math.ceil(asciiLen / 4) + Math.ceil(cjkCount / 1.5));
+}
+
+// 850 → "850", 6100 → "6.1k", 12000 → "12k".
+export function humanTokens(n) {
+  if (n < 1000) return String(n);
+  if (n < 10000) return (n / 1000).toFixed(1) + 'k';
+  return Math.round(n / 1000) + 'k';
+}
+
+function cap(s) {
+  const t = s.replace(/\s+/g, ' ').trim();
+  return t.length <= SUMMARY_MAX ? t : t.slice(0, SUMMARY_MAX - 1) + '…';
+}
+
+function isGenericComment(text) {
+  if (/^[-=*_#·]{3,}$/.test(text)) return true;
+  const l = text.toLowerCase();
+  return l.startsWith('eslint') || l.startsWith('prettier') || l.startsWith('tslint') ||
+    l.startsWith('stylelint') || l.startsWith('istanbul') || l.startsWith('c8 ') ||
+    l.startsWith('copyright') || l.startsWith('license') || l.startsWith('spdx') ||
+    l.startsWith('use strict') || l.startsWith('@') || l.startsWith('global ') ||
+    l.startsWith('generated') || l.startsWith('auto-generated') || l.startsWith('nolint');
+}
+
+// First meaningful header comment in the first 15 lines, skipping blanks,
+// shebangs, and boilerplate (eslint/license/etc). Stops at the first real code
+// line so we don't scan deep into the body.
+function extractHeaderComment(content) {
+  const lines = content.split('\n');
+  const limit = Math.min(lines.length, 15);
+  for (let i = 0; i < limit; i++) {
+    const t = lines[i].trim();
+    if (!t) continue;
+    if (t.startsWith('#!')) continue; // shebang
+    const m = t.match(/^(?:\/\/\/?|#|--|\/\*\*?|\*)\s*(.+)/);
+    if (m) {
+      const text = m[1].replace(/\*\/\s*$/, '').trim();
+      if (text.length > 4 && !isGenericComment(text)) return text;
+      continue;
+    }
+    break; // real code line — no header comment
+  }
+  return '';
+}
+
+function extractExports(content) {
+  const names = [];
+  const re = /export\s+(?:default\s+)?(?:async\s+)?(?:function\*?|class|const|let|var|interface|type|enum)\s+(\w+)/g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    if (!names.includes(m[1])) names.push(m[1]);
+  }
+  if (names.length === 0) return '';
+  const shown = names.slice(0, 5).join(', ');
+  return names.length > 5 ? `Exports ${shown} + ${names.length - 5} more` : `Exports ${shown}`;
+}
+
+// Best-effort one-line "what's in it". '' when nothing useful is found.
+export function extractFileSummary(content, filename) {
+  const src = content || '';
+  if (!src.trim()) return '';
+  const name = (filename || '').toLowerCase();
+  const dot = name.lastIndexOf('.');
+  const ext = dot >= 0 ? name.slice(dot) : '';
+
+  if (ext === '.md' || ext === '.mdx') {
+    const m = src.match(/^#{1,6}\s+(.+)$/m);
+    if (m) return cap(m[1]);
+  }
+
+  if (ext === '.json') {
+    try {
+      const obj = JSON.parse(src);
+      if (obj && typeof obj.description === 'string' && obj.description.trim()) return cap(obj.description);
+      if (obj && typeof obj.name === 'string' && obj.name.trim()) return cap(obj.name);
+    } catch { /* partial / invalid JSON — no summary */ }
+    return '';
+  }
+
+  const hdr = extractHeaderComment(src);
+  if (hdr) return cap(hdr);
+
+  if (['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(ext)) {
+    const exp = extractExports(src);
+    if (exp) return cap(exp);
+  }
+
+  return '';
+}
+
+export function formatFileIntelLine({ basename, tokens, summary }) {
+  const head = `[mem] 📄 ${basename} ~${humanTokens(tokens)} tok`;
+  return summary ? `${head} · ${summary}` : head;
+}
+
+// IO wrapper: returns the formatted intel line for filePath, or null when the
+// file is unreadable or below the token threshold. Never throws — it runs inside
+// a PreToolUse hook that must always exit 0.
+export function fileIntelFor(filePath, opts = {}) {
+  const minTokens = opts.minTokens ?? DEFAULT_MIN_TOKENS;
+  const maxReadBytes = opts.maxReadBytes ?? DEFAULT_MAX_READ_BYTES;
+
+  let size;
+  try {
+    const st = statSync(filePath);
+    if (!st.isFile()) return null;
+    size = st.size;
+  } catch { return null; }
+
+  try {
+    const fd = openSync(filePath, 'r');
+    try {
+      const buf = Buffer.allocUnsafe(Math.min(size, maxReadBytes));
+      const n = buf.length > 0 ? readSync(fd, buf, 0, buf.length, 0) : 0;
+      const sample = buf.subarray(0, n).toString('utf8');
+      // Files within the read window are estimated exactly; larger files estimate
+      // from byte size (≈4 ASCII bytes/token). The '~' already signals approximation
+      // and we never slurp a multi-MB file inside a hook.
+      const tokens = size <= maxReadBytes ? estimateContentTokens(sample) : Math.ceil(size / 4);
+      if (tokens < minTokens) return null;
+      const summary = extractFileSummary(sample, filePath);
+      return formatFileIntelLine({ basename: pathBasename(filePath), tokens, summary });
+    } finally { closeSync(fd); }
+  } catch { return null; }
+}

package/lib/reread-guard.mjs

@@ -0,0 +1,55 @@
+// lib/reread-guard.mjs — pure logic + one IO helper for feature ② (repeated-read
+// guard). When the agent does a full Read of a file it already read this session
+// and the file is unchanged, nudge it to reuse what it has instead of re-slurping.
+//
+// Imported by the hot standalone scripts/pre-tool-recall.js — stays light, reuses
+// the token estimator from ./file-intel.mjs (also pure). Never throws.
+//
+// False-positive guards (the bit OpenWolf's equivalent omits — its "unless
+// modified" lives only in instructions, not the hook):
+//   - full-vs-full only: paging with offset/limit never warns
+//   - mtime check: a file changed since the prior read never warns
+//   - token floor: re-reading a tiny file is cheap, not worth a nudge
+
+import { statSync, openSync, readSync, closeSync } from 'fs';
+import { estimateContentTokens, humanTokens } from './file-intel.mjs';
+
+const DEFAULT_MIN_TOKENS = 600;
+const DEFAULT_MAX_READ_BYTES = 24 * 1024;
+
+// IO: { mtimeMs, tokens } for an on-disk file, or null. Never throws.
+export function readFileMeta(filePath, maxReadBytes = DEFAULT_MAX_READ_BYTES) {
+  let st;
+  try {
+    st = statSync(filePath);
+    if (!st.isFile()) return null;
+  } catch { return null; }
+
+  const size = st.size;
+  if (size > maxReadBytes) {
+    return { mtimeMs: st.mtimeMs, tokens: Math.ceil(size / 4) };
+  }
+  try {
+    const fd = openSync(filePath, 'r');
+    try {
+      const buf = Buffer.allocUnsafe(size);
+      const n = size > 0 ? readSync(fd, buf, 0, size, 0) : 0;
+      return { mtimeMs: st.mtimeMs, tokens: estimateContentTokens(buf.subarray(0, n).toString('utf8')) };
+    } finally { closeSync(fd); }
+  } catch { return null; }
+}
+
+// Pure: should a repeat read warn? recorded = { mtimeMs, tokens, full }.
+export function shouldWarnReread(recorded, currentMtimeMs, isFullRead, minTokens = DEFAULT_MIN_TOKENS) {
+  if (!recorded || typeof recorded !== 'object') return false;
+  if (!recorded.full || !isFullRead) return false;      // only full-vs-full re-reads
+  if (!(recorded.tokens >= minTokens)) return false;     // big enough to matter
+  if (currentMtimeMs === null || currentMtimeMs === undefined) return false;
+  return currentMtimeMs <= recorded.mtimeMs;             // unchanged since last read
+}
+
+// Pure: the warning line (no framing — the hook prepends the shared framing line).
+export function buildRereadWarning(basename, tokens) {
+  return `[mem] 🔁 You already read ${basename} this session (~${humanTokens(tokens)} tok, unchanged) `
+    + `— reuse what you have instead of re-reading; pass offset/limit if you need a specific part.`;
+}

package/mem-cli.mjs

@@ -39,6 +39,7 @@ import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentT
 import { buildSearchFtsQuery, parseDateBounds, computePerSourceWindow, effectiveObsFtsQuery, searchSessionsFts, searchPromptsFts, normalizeCrossSourceScores, applyUserSort, applyTierFilter } from './lib/search-core.mjs';
 import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { countRecentHookErrors } from './lib/hook-telemetry.mjs';
+import { aggregateMetrics } from './lib/metrics.mjs';
 import {
   insertDeferred, listOpenWithOrdinal, dropDeferred,
   resolveDeferredIds, closeDeferredItems,
@@ -1154,6 +1155,13 @@ async function cmdStats(db, args) {
   out(`  Low-value (imp=1, never accessed, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`);
   out(`  Compressed: ${compressedCount.c}`);
   out(`  Hook errors (last 24h): ${hookErrors24h}${hookErrors24h > 0 ? `  ← tail ${join(DB_DIR, 'runtime/hook-errors')}` : ''}`);
+  // Tier-1 firing counters for ① file-intel + ② reread-guard (recorded by
+  // pre-tool-recall.js via lib/metrics.mjs; CLAUDE_MEM_METRICS=1 to enable).
+  const featAgg = aggregateMetrics(DB_DIR, 7);
+  const fiN = featAgg.file_intel?.count ?? 0;
+  const rrN = featAgg.reread_warn?.count ?? 0;
+  const metricsOn = process.env.CLAUDE_MEM_METRICS === '1';
+  out(`  Feature injections (7d): 📄 file-intel ${fiN} · 🔁 reread-warn ${rrN}${(!metricsOn && fiN + rrN === 0) ? '  (set CLAUDE_MEM_METRICS=1 to record)' : ''}`);
   if (noiseRatio > 0.6) out('  ⚠️ High noise ratio — consider running mem compress');
   out('');
   // Tier counts only live (uncompressed, non-superseded) observations — surface the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.99.0",
+  "version": "3.0.1",
   "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",
@@ -63,6 +63,8 @@
     "lib/id-routing.mjs",
     "lib/err-sampler.mjs",
     "lib/hook-telemetry.mjs",
+    "lib/file-intel.mjs",
+    "lib/reread-guard.mjs",
     "lib/metrics.mjs",
     "lib/binding-probe.mjs",
     "lib/mem-override.mjs",
@@ -140,7 +142,7 @@
     "zod": "^4.3.6"
   },
   "overrides": {
-    "hono": ">=4.12.21",
+    "hono": ">=4.12.26",
     "fast-uri": ">=3.1.2",
     "ip-address": ">=10.1.1"
   },

package/scripts/pre-tool-recall.js

@@ -10,6 +10,9 @@ import { homedir } from 'os';
 import { buildNotLowSignalSql } from '../lib/low-signal-patterns.mjs';
 import { recordHookError } from '../lib/hook-telemetry.mjs';
 import { citeFactorClause } from '../scoring-sql.mjs';
+import { fileIntelFor } from '../lib/file-intel.mjs';
+import { shouldWarnReread, buildRereadWarning, readFileMeta } from '../lib/reread-guard.mjs';
+import { recordMetric } from '../lib/metrics.mjs';
 
 // CLAUDE_MEM_DIR matches schema.mjs / main CLI — one env var sandboxes the
 // whole system. CLAUDE_MEM_DB_PATH / CLAUDE_MEM_RUNTIME_DIR remain as
@@ -39,6 +42,23 @@ const SALIENCE_LEGACY = process.env.CLAUDE_MEM_SALIENCE === 'legacy'
   || process.env.CLAUDE_MEM_SALIENCE === '0';
 const ACK_DIRECTIVE = "apply each lesson to this edit or rule it out — state '#NN applied' or '#NN n/a — <reason>' in your next user-facing message.";
 const STALE_MS = 10 * 60 * 1000;   // 10 minutes cleanup threshold for legacy file
+// Feature ① (file intelligence): on the first Read of a file each session, inject
+// its approximate token size + a one-line summary so the agent can decide to read
+// fully, slice, or grep. Read-only (Edit/Write already commit to the file). Default
+// ON; CLAUDE_MEM_FILE_INTEL=0 disables. Files below the token floor stay silent so
+// small reads carry no noise. Env names mirror schema.mjs CLAUDE_MEM_* convention (#8447).
+const FILE_INTEL_OFF = ['0', 'off', 'false', 'no'].includes(
+  String(process.env.CLAUDE_MEM_FILE_INTEL || '').toLowerCase());
+const FILE_INTEL_MIN_TOKENS = Math.max(1,
+  parseInt(process.env.CLAUDE_MEM_FILE_INTEL_MIN_TOKENS, 10) || 800);
+// Feature ② (repeated-read guard): when the agent does a FULL re-read of a file
+// it already read this session and the file is unchanged (mtime), nudge it to
+// reuse context instead of re-slurping. Read-only; only fires above the floor and
+// never on offset/limit paging. Default ON; CLAUDE_MEM_REREAD_GUARD=0 disables.
+const REREAD_GUARD_OFF = ['0', 'off', 'false', 'no'].includes(
+  String(process.env.CLAUDE_MEM_REREAD_GUARD || '').toLowerCase());
+const REREAD_MIN_TOKENS = Math.max(1,
+  parseInt(process.env.CLAUDE_MEM_REREAD_MIN_TOKENS, 10) || 600);
 // Stale-cooldown GC moved to hook.mjs::handleSessionStart — running it on every
 // Edit cost 15-30 disk stats per call. SessionStart fires once at session boot,
 // which is enough to keep RUNTIME_DIR from growing unbounded.
@@ -153,11 +173,17 @@ try {
   let filePath;
   let sessionId;
   let toolName;
+  // isFullRead: a Read with no offset/limit reads the whole file. The reread
+  // guard only flags full-vs-full re-reads, so paging never trips it.
+  let isFullRead = true;
   try {
     const event = JSON.parse(input);
     filePath = event.tool_input?.file_path;
     sessionId = event.session_id || null;
     toolName = event.tool_name || null;
+    const off = event.tool_input?.offset;
+    const lim = event.tool_input?.limit;
+    isFullRead = (off === undefined || off === null) && (lim === undefined || lim === null);
   } catch (e) {
     recordHookError('pre-recall:json', e, RUNTIME_DIR, { inputLen: input.length });
     process.exit(0);
@@ -218,6 +244,23 @@ try {
         }));
         cooldown[filePath] = { ...entry, mode: 'edit' };
         writeCooldown(cooldownPath, cooldown, isSessionScoped);
+      } else if (isRead && !REREAD_GUARD_OFF && typeof entry === 'object' && entry.reread) {
+        // ② repeated-read guard: a full re-read of an unchanged, sizable file —
+        // nudge to reuse what's already in context. Read-only; never throws.
+        const meta = readFileMeta(filePath);
+        if (shouldWarnReread(entry.reread, meta ? meta.mtimeMs : null, isFullRead, REREAD_MIN_TOKENS)) {
+          process.stdout.write(JSON.stringify({
+            suppressOutput: true,
+            hookSpecificOutput: {
+              hookEventName: 'PreToolUse',
+              additionalContext: [
+                '[mem] PreToolUse recall — system-injected context, continue your planned action:',
+                buildRereadWarning(basename(filePath), entry.reread.tokens),
+              ].join('\n'),
+            },
+          }));
+          recordMetric(DATA_DIR, { event: 'reread_warn' }); // tier-1 firing counter (②)
+        }
       }
       process.exit(0); // already recalled this file in-session
     }
@@ -340,6 +383,16 @@ try {
     // v2.31 T2: emit JSON with hookSpecificOutput.additionalContext so the message
     // reliably renders across CC variants (sdscc drops plain-text stdout from PreToolUse).
     // suppressOutput:true hides it from transcript mode per CC hook docs.
+    // Feature ①: file intelligence (size + summary) for the first Read of this
+    // file this session. Read-only; opt out via CLAUDE_MEM_FILE_INTEL=0. Never
+    // throws — fileIntelFor returns null on unreadable/below-threshold files.
+    let fileIntelLine = null;
+    if (isRead && !FILE_INTEL_OFF) {
+      try { fileIntelLine = fileIntelFor(filePath, { minTokens: FILE_INTEL_MIN_TOKENS }); } catch {}
+    }
+    // Tier-1 firing counter (①). recordMetric no-ops unless CLAUDE_MEM_METRICS=1,
+    // so default users pay nothing; observers see counts in `doctor` / `stats`.
+    if (fileIntelLine) recordMetric(DATA_DIR, { event: 'file_intel' });
     const lines = [];
     // v2.34.6: Read mode uses 120-char truncation (Edit mode keeps the 240-char
     // cap from R3-UX). Rationale: Read is a one-shot nudge with 1 lesson max;
@@ -347,11 +400,20 @@ try {
     // carries the actionable "Fix:" guidance — short enough per-lesson at 240,
     // but the total payload is bounded by the 3-row limit and the cooldown.
     const LESSON_MAX = isRead ? 120 : 240;
-    if (allRows.length > 0) {
+    // Feature ① (file-intel): null on Edit/Write and on below-threshold or
+    // unreadable files. When present (first Read of a sizable file this session),
+    // it leads the injection, above any lessons.
+    const hasLessons = allRows.length > 0;
+    const showFraming = hasLessons || Boolean(fileIntelLine)
+      || (!isRead && process.env.CLAUDE_MEM_PRETOOL_NUDGE === '1');
+    if (showFraming) {
       // Framing line mirrors #7758 handoff-injection fix: without an explicit
       // "system-injected, continue" disclaimer, observed turn-end after Edit+reminder
       // when the model misreads passive lesson context as a closing note.
       lines.push(`[mem] PreToolUse recall — system-injected context, continue your planned action:`);
+    }
+    if (fileIntelLine) lines.push(fileIntelLine);
+    if (hasLessons) {
       lines.push(`[mem] Lessons for ${fname}:`);
       for (const r of allRows) {
         if (r.lesson_learned) {
@@ -386,7 +448,7 @@ try {
       //
       // Read never emitted this (passive). The cooldown write below still runs on
       // every branch, so Read→Edit dedup + cite-back lessonId tracking are intact.
-      lines.push(`[mem] PreToolUse recall — system-injected context, continue your planned action:`);
+      // (Framing line already pushed above via showFraming.)
       lines.push(`[mem] No prior lessons for ${fname} — if you solve a non-obvious bug here, run: /lesson --file ${fname} "<root cause + fix>"`);
     }
 
@@ -408,7 +470,16 @@ try {
     // v2.98: mode records WHERE the injection happened so the Read→Edit ack
     // nudge can distinguish "lessons seen passively at Read" from "already
     // surfaced at an action point".
-    cooldown[filePath] = { ts: now, lessonIds: allRows.map(r => r.id), mode: isRead ? 'read' : 'edit' };
+    // ② repeated-read guard: record file metadata on the first Read so a later
+    // full re-read of the unchanged file can be flagged. Read-only, session-scoped;
+    // one stat + bounded read, first-read only.
+    const rereadMeta = (isRead && !REREAD_GUARD_OFF && isSessionScoped) ? readFileMeta(filePath) : null;
+    cooldown[filePath] = {
+      ts: now,
+      lessonIds: allRows.map(r => r.id),
+      mode: isRead ? 'read' : 'edit',
+      ...(rereadMeta ? { reread: { mtimeMs: rereadMeta.mtimeMs, tokens: rereadMeta.tokens, full: isFullRead } } : {}),
+    };
     writeCooldown(cooldownPath, cooldown, isSessionScoped);
     // A3 (v2.83): merge our newly-emitted IDs into the cross-hook injected
     // file so the next UPS prompt skips them too. Always write, even on

package/source-files.mjs

@@ -52,6 +52,12 @@ export const SOURCE_FILES = [
   // and mem-cli.mjs (countRecentHookErrors for `stats`). Missing from
   // manifest → tarball ships hooks that ERR_MODULE_NOT_FOUND on every fire.
   'lib/hook-telemetry.mjs',
+  // v3.0: read-time file-intelligence (①) + repeated-read guard (②). Imported
+  // ONLY by scripts/pre-tool-recall.js (reread-guard also imports file-intel) —
+  // NOT reachable from the 5 ENTRY_MODULES, so the hook-script coverage test in
+  // source-files-sync.test.mjs is what keeps these from being dropped on bump.
+  'lib/file-intel.mjs',
+  'lib/reread-guard.mjs',
   'lib/metrics.mjs',
   // v2.71.x: better-sqlite3 ABI probe + auto-rebuild. Shared by install.mjs
   // (post-`npm install` verify) and scripts/launch.mjs (pre-server-launch