claude-mem-lite 3.23.0 → 3.25.0

package/.claude-plugin/marketplace.json

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

@@ -5,6 +5,7 @@ import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, truncate, OBS_BM25, no
 import { citeFactorJs } from './scoring-sql.mjs';
 import { recordMetric } from './lib/metrics.mjs';
 import { DB_DIR } from './schema.mjs';
+import { extractIdents } from './lib/lesson-idents.mjs';
 
 const MAX_MEMORY_INJECTIONS = 3;
 const MEMORY_LOOKBACK_MS = 60 * 86400000; // 60 days
@@ -399,3 +400,42 @@ export function recallForFile(db, filePath, project) {
     return [];
   }
 }
+
+/**
+ * Phase-2 task-imperative selection (spec 2026-06-29 §4.1): the single highest-value
+ * lesson relevant to THIS prompt, for delivery at the task-prompt position under the
+ * imperative template. Own gate (importance>=2 + non-empty lesson + identifier overlap
+ * with the prompt, top-1) — deliberately independent of searchRelevantMemories' coverage/
+ * BM25 filters so a high-value lesson is not dropped by the context-list scoring.
+ * @returns {{id:number, lesson_learned:string}|null}
+ */
+export function selectImperativeLesson(db, userPrompt, project, excludeIds = []) {
+  if (!db || !userPrompt) return null;
+  const promptIdents = new Set(extractIdents(userPrompt));
+  if (promptIdents.size === 0) return null; // no symbol anchor → no imperative (precision-first)
+  const exclude = new Set(excludeIds);
+  let rows;
+  try {
+    rows = db.prepare(`
+      SELECT id, title, lesson_learned, importance
+      FROM observations
+      WHERE project = ?
+        AND COALESCE(compressed_into, 0) = 0
+        AND COALESCE(importance, 1) >= 2
+        AND lesson_learned IS NOT NULL
+        AND TRIM(lesson_learned) != ''
+        AND LOWER(TRIM(lesson_learned)) != 'none'
+      ORDER BY importance DESC, created_at_epoch DESC
+      LIMIT 50
+    `).all(project);
+  } catch { return null; }
+  let best = null, bestScore = 0;
+  for (const r of rows) {
+    if (exclude.has(r.id)) continue;
+    const overlap = extractIdents(`${r.lesson_learned} ${r.title || ''}`).filter((id) => promptIdents.has(id)).length;
+    if (overlap === 0) continue;
+    const score = (r.importance || 2) * overlap;
+    if (score > bestScore) { bestScore = score; best = r; }
+  }
+  return best ? { id: best.id, lesson_learned: best.lesson_learned } : null;
+}

package/hook.mjs

@@ -59,7 +59,8 @@ import {
   hasMainThreadAssistantText,
 } from './lib/citation-tracker.mjs';
 import { extractTailAssistantText, extractStructuredSummary } from './lib/summary-extractor.mjs';
-import { searchRelevantMemories, formatMemoryLine } from './hook-memory.mjs';
+import { searchRelevantMemories, formatMemoryLine, selectImperativeLesson } from './hook-memory.mjs';
+import { formatTaskImperative } from './lib/task-imperative.mjs';
 import { recordSkillAdoption, gcOldShadowShards } from './registry-recommend.mjs';
 import { detectMemOverride } from './lib/mem-override.mjs';
 import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection, pickHandoffToInject, extractUnfinishedSummary } from './hook-handoff.mjs';
@@ -1386,6 +1387,7 @@ async function handleUserPrompt() {
         ORDER BY created_at_epoch DESC LIMIT 5
       `).all(project);
       const keyContextIds = keyObs.map(o => o.id);
+      const pathAInjectedIds = [];
 
       // Read IDs already injected by user-prompt-search.js to avoid duplicate injection
       try {
@@ -1394,17 +1396,39 @@ async function handleUserPrompt() {
         const { ids, ts } = JSON.parse(raw);
         // Only use if written within last 10 seconds (same prompt cycle)
         if (ts && Date.now() - ts < 10000 && Array.isArray(ids)) {
-          for (const id of ids) keyContextIds.push(id);
+          for (const id of ids) { keyContextIds.push(id); pathAInjectedIds.push(id); }
         }
       } catch { /* file may not exist — that's fine */ }
 
-      const memories = searchRelevantMemories(db, promptText, project, keyContextIds);
+      // Phase-2 task-imperative (default OFF — CLAUDE_MEM_TASK_IMPERATIVE): the single
+      // highest-value lesson relevant to THIS prompt, delivered at the prompt position under
+      // an imperative template. Excluded from the <memory-context> list so it is never
+      // injected twice. Channel-isolation measure (efficacy arm U, 2026-06-29): task-prompt
+      // 6-8/8 vs PreToolUse hook 0/8. Flipping the default ON is a separate L3 decision
+      // gated on the live cite-recall canary.
+      const taskImperativeOn = process.env.CLAUDE_MEM_TASK_IMPERATIVE === 'on'
+        || process.env.CLAUDE_MEM_TASK_IMPERATIVE === '1';
+      // Exclude only ids path-A (user-prompt-search.js) already injected — NOT the
+      // key-context top-5, which overlaps the high-value lesson pool and would suppress
+      // the pick. The chosen id is excluded from the <memory-context> block below instead.
+      const imperativePick = taskImperativeOn
+        ? selectImperativeLesson(db, promptText, project, pathAInjectedIds)
+        : null;
+      const contextExclude = imperativePick ? [...keyContextIds, imperativePick.id] : keyContextIds;
+
+      const memories = searchRelevantMemories(db, promptText, project, contextExclude);
       if (memories.length > 0) {
         const lines = ['<memory-context relevance="high">'];
         for (const m of memories) lines.push(formatMemoryLine(m));
         lines.push('</memory-context>');
         process.stdout.write(lines.join('\n') + '\n');
       }
+      if (imperativePick) {
+        // Guard the write on a non-empty return — formatTaskImperative yields '' for a
+        // lesson that strips to empty (e.g. "."), which would otherwise emit a bare line.
+        const imperativeLine = formatTaskImperative(imperativePick.lesson_learned, imperativePick.id);
+        if (imperativeLine) process.stdout.write(imperativeLine + '\n');
+      }
     } catch (e) { debugCatch(e, 'handleUserPrompt-memory'); }
   } finally {
     db.close();

package/lib/task-imperative.mjs

@@ -0,0 +1,18 @@
+// lib/task-imperative.mjs — pure formatter for the task-imperative memory line.
+// Shared by the live UserPromptSubmit emitter (Phase 2) AND efficacy arm U (the
+// measurement that gates Phase 2): ONE tested source of truth so the measured
+// framing and the shipped framing cannot drift. Hot-path-shared → regex/string
+// only, NO heavy imports (lesson #8447), mirroring lib/lesson-idents.mjs.
+//
+// Delivers a high-value lesson at the task-prompt position as an imperative,
+// task-bound constraint: attribution kept (honest + #NN cite-traceable), the
+// path-A/B softeners ("FYI", "continue your task", "NOT a new user message")
+// dropped.
+// Spec: docs/superpowers/specs/2026-06-29-task-imperative-memory-injection-design.md
+
+export function formatTaskImperative(lesson, id) {
+  const body = String(lesson || '').trim().replace(/\.$/, '');
+  if (!body) return '';
+  const tag = (id === undefined || id === null || id === '') ? '' : ` (#${id})`;
+  return `Memory — a past lesson applies to THIS task. You must: ${body}.${tag}`;
+}

package/mem-cli.mjs

@@ -1761,6 +1761,13 @@ function cmdRestore(db, argv) {
 
 function cmdCompress(db, args) {
   const { flags } = parseArgs(args);
+  // Sibling-command flag footgun: compress executes with --execute (optimize uses
+  // --run, maintain uses positional `execute`). A bare --run previously fell through to
+  // a silent preview; fail fast pointing at the right flag. --execute still wins if both.
+  if ((flags.run === true || flags.run === 'true') && flags.execute !== true && flags.execute !== 'true') {
+    fail("[mem] compress executes with --execute, not --run (--run is optimize's flag). Re-run: claude-mem-lite compress --execute");
+    return;
+  }
   const preview = flags.execute !== true && flags.execute !== 'true';
   // Reject malformed --age-days explicitly. The prior fallback (`|| 30`) silently used
   // the default whenever the value parsed as NaN or <1, so users typing `--age-days abc`
@@ -2857,6 +2864,16 @@ async function cmdEnrich(argv) {
 async function cmdOptimize(db, args) {
   const run = args.includes('--run');
   const runAll = args.includes('--run-all');
+  // Sibling-command flag footgun: optimize executes with --run (compress uses
+  // --execute, maintain uses positional `execute`). A bare --execute previously fell
+  // through to a silent preview, so the user thought they ran a mutation but didn't.
+  // Catch both `--execute` and the `--execute=value` form (the latter slipped a bare
+  // `args.includes('--execute')` and fell through to a silent preview — review minor).
+  const hasExecuteFlag = args.some(a => a === '--execute' || a.startsWith('--execute='));
+  if (hasExecuteFlag && !run && !runAll) {
+    fail("[mem] optimize executes with --run, not --execute (--execute is compress's flag). Re-run: claude-mem-lite optimize --run");
+    return;
+  }
   const verbose = args.includes('--verbose') || args.includes('-v');
   // T2-P1-D: --task accepts a single task or a comma-separated list, parity with MCP memOptimizeSchema.tasks.
   const VALID_TASKS = ['re-enrich', 'normalize', 'cluster-merge', 'smart-compress'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.23.0",
+  "version": "3.25.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",
@@ -71,6 +71,7 @@
     "lib/reread-guard.mjs",
     "lib/metrics.mjs",
     "lib/lesson-idents.mjs",
+    "lib/task-imperative.mjs",
     "lib/lesson-bridge.mjs",
     "lib/binding-probe.mjs",
     "lib/proc-lock.mjs",

package/registry-github.mjs

@@ -14,7 +14,14 @@ export function parseGitHubUrl(url) {
   // ("main?x#y") and corrupts the GitHub API URL built from it, so the import
   // fails with a confusing 404 on a URL that opens fine in the browser.
   const clean = url.split(/[?#]/)[0];
-  const match = clean.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?(?:\/tree\/([^/]+)(\/.*)?)?$/);
+  // RFC 3986: scheme + host are case-insensitive, but the path (owner/repo/branch/dir)
+  // is NOT. Lowercase ONLY the scheme://github.com prefix — and only when github.com is
+  // the real host (followed by '/' or end, never as a substring of github.com.evil.com)
+  // — so a pasted "HTTPS://GitHub.com/…" (valid, opens in the browser) isn't rejected as
+  // "Invalid GitHub URL". The structural host check in the match below is unchanged, so
+  // github.com.evil.com / github.com@evil.com still fail.
+  const normalized = clean.replace(/^https?:\/\/github\.com(?=\/|$)/i, m => m.toLowerCase());
+  const match = normalized.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?(?:\/tree\/([^/]+)(\/.*)?)?$/);
   if (!match) return null;
   const [, owner, repo, branch, pathRaw] = match;
   return {

package/scripts/pre-tool-recall.js

@@ -104,14 +104,19 @@ async function bridgeTopLesson(rows, changeText) {
 
 // ─── Helpers ────────────────────────────────────────────────────────────────
 
+// SYNC: must produce the SAME string as utils.mjs::inferProject (the path obs are SAVED
+// under) and the bash post-tool-use.sh fast-path — recall queries the SAVE-path project.
+// This previously used process.cwd() WITHOUT the process.env.PWD fallback the other two
+// have, so under a symlinked project dir (PWD = logical/symlinked path, cwd = resolved)
+// with CLAUDE_PROJECT_DIR unset it computed a DIFFERENT project than the save path and
+// silently recalled nothing. Resolution order + sanitize + 100-char cap now match utils.
 function inferProject() {
-  const dir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const dir = process.env.CLAUDE_PROJECT_DIR || process.env.PWD || process.cwd();
   const base = basename(dir);
   const parent = basename(join(dir, '..'));
-  let project = (parent && parent !== '.' && parent !== '/')
+  const raw = (parent && parent !== '.' && parent !== '/')
     ? `${parent}--${base}` : base;
-  project = project.replace(/[^a-zA-Z0-9_.-]/g, '-') || 'unknown';
-  return project;
+  return raw.replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 100);
 }
 
 function readCooldown(cooldownPath) {

package/scripts/user-prompt-search.js

@@ -172,6 +172,20 @@ function isFollowUpSession() {
 // catches the prompt via those channels rather than the identifier itself.
 const TECH_IDENTIFIER_RE = /\b(?:[a-z][a-z0-9]*_[a-z0-9_]+|[A-Z][A-Z0-9]*_[A-Z0-9_]+|[A-Z]{2,}[0-9][A-Z0-9_]*|[a-z]{2,}[A-Z][a-zA-Z0-9]+|[a-z]+(?:-[a-z]+){2,})\b/;
 
+// Reviewer #2 (v3.25.0): the kebab (≥3-seg) and camelCase arms above structurally
+// match a handful of ordinary English phrases / product names that are NOT code
+// identifiers — `up-to-date`, `state-of-the-art`, `macOS`, etc. Left unfiltered they
+// (a) widen the default-ON hasExplicitSignal gate on prose-only prompts and (b) let
+// such a token drive the opt-in identifier bypass. Stop-list them (lowercased). Real
+// 3-segment kebab identifiers (`pre-tool-use`, `user-prompt-search`) are deliberately
+// NOT here — only attested non-identifier prose.
+const IDENTIFIER_STOPWORDS = new Set([
+  'up-to-date', 'out-of-date', 'up-to-speed', 'out-of-the-box', 'state-of-the-art',
+  'end-to-end', 'off-by-one', 'easy-to-use', 'day-to-day', 'step-by-step',
+  'face-to-face', 'one-to-one', 'one-on-one', 'back-to-back', 'side-by-side',
+  'apples-to-apples', 'macos',
+]);
+
 // CJK presence channel (Important #2): bilingual users (project memory
 // `feedback_*` calls this out explicitly) ask CJK questions that may carry
 // genuine debug intent without containing an English identifier. CJK is
@@ -192,11 +206,55 @@ export function hasExplicitSignal(text, { errSig, files, intent } = {}) {
   if (errSig === undefined && extractErrorSignature(text)) return true;
   if (files === undefined && extractFiles(text).length > 0) return true;
   if (intent === undefined && detectIntent(text)) return true;
-  if (TECH_IDENTIFIER_RE.test(text)) return true;
+  if (extractTechIdentifiers(text).length > 0) return true;
   if (CJK_CHAR_RE.test(text) && computeEffectiveLen(text) >= CJK_MIN_EFFECTIVE_LEN) return true;
   return false;
 }
 
+// ─── Identifier-exact-match precision bypass (default OFF) ───────────────────
+//
+// CLAUDE_MEM_UPS_IDENTIFIER_BYPASS=1 enables it. Rationale: the score-floors below
+// (OR_TOP_BM25_FLOOR / TOP_REL_FLOOR) drop the WHOLE FTS set when the top row's
+// magnitude is weak. But a rare code identifier (camelCase / snake_case / CONST_CASE
+// / kebab≥3) match has high *semantic* precision even at modest BM25 — a df=1 term
+// like `sanitizeFtsQuery` scores only ~23 raw yet is an unambiguous hit. So an obs
+// whose title/lesson EXACT-matches an identifier the prompt names is a precision pass
+// — the same independent-signal rationale that already exempts sigRows (error
+// signatures) and fileRows (file names) from these floors. When enabled, such rows are
+// restored after the floors run.
+//
+// Default OFF — opt-in. benchmark/ups-ab.mjs measured it TRADEOFF on the real corpus
+// (+3 recall recoveries / +4 injections over 12 positives / 8 hard-negatives); the
+// "cost" was eager surfacing of on-identifier obs on non-recall-framed prompts, not
+// off-topic noise. Kept opt-in (below the NET-POSITIVE/NEUTRAL ship bar). See #8858.
+export const IDENTIFIER_BYPASS = process.env.CLAUDE_MEM_UPS_IDENTIFIER_BYPASS === '1';
+const TECH_IDENTIFIER_RE_G = new RegExp(TECH_IDENTIFIER_RE.source, 'g');
+
+// All tech-identifier tokens in `text`, lowercased + de-duped (for case-insensitive
+// row matching). Empty array when none — callers treat that as "no bypass candidates".
+export function extractTechIdentifiers(text) {
+  return [...new Set((String(text || '').match(TECH_IDENTIFIER_RE_G) || []).map(s => s.toLowerCase()))]
+    .filter(s => !IDENTIFIER_STOPWORDS.has(s));
+}
+
+// True when the obs row's title or lesson contains any of `idsLower` as a standalone
+// token (not embedded in a longer identifier). Title/lesson only — the searchByFts
+// SELECT carries no narrative, and requiring the hit in the title/lesson is the
+// stricter, higher-precision condition (intentional).
+export function rowMatchesIdentifier(row, idsLower) {
+  if (!idsLower || idsLower.length === 0) return false;
+  const hay = `${row.title || ''} ${row.lesson_learned || ''}`.toLowerCase();
+  const isWordChar = (c) => c !== undefined && /[a-z0-9_]/.test(c);
+  return idsLower.some((id) => {
+    let from = 0, i;
+    while ((i = hay.indexOf(id, from)) >= 0) {
+      if (!isWordChar(hay[i - 1]) && !isWordChar(hay[i + id.length])) return true;
+      from = i + 1;
+    }
+    return false;
+  });
+}
+
 // ─── DB Query Functions ─────────────────────────────────────────────────────
 
 // Returns { rows, mode } where mode is 'AND' (initial pass), 'OR' (fallback
@@ -557,6 +615,9 @@ async function main() {
     const signalPresent = hasExplicitSignal(promptText, {
       errSig, files: filesForGate, intent,
     });
+    // Identifier tokens the prompt names (for the precision bypass below). Empty
+    // unless CLAUDE_MEM_UPS_IDENTIFIER_BYPASS=1, so this is a no-op when disabled.
+    const promptIdentifiers = IDENTIFIER_BYPASS ? extractTechIdentifiers(promptText) : [];
 
     if (intent?.useRecent) {
       // Recall intent: show recent observations
@@ -588,6 +649,14 @@ async function main() {
         typeof r.relevance === 'number' && Math.abs(r.relevance) >= bm25Floor
       );
 
+      // Identifier-exact-match precision bypass (default off — see IDENTIFIER_BYPASS).
+      // Capture rows that exact-match a prompt identifier BEFORE the set-floors below;
+      // they carry independent precision signal (sigRows/fileRows rationale) and are
+      // restored after the floors so a low top-score can't drop a named-identifier hit.
+      const bypassRows = (IDENTIFIER_BYPASS && promptIdentifiers.length > 0)
+        ? ftsRows.filter(r => rowMatchesIdentifier(r, promptIdentifiers))
+        : [];
+
       // v2.43.x: OR-mode raw-BM25 floor. In OR-fallback mode the composite
       // TOP_REL_FLOOR below is inflated by importance × type_quality × decay
       // multipliers — a weak single-stem hit on an importance=3 bugfix obs
@@ -611,6 +680,15 @@ async function main() {
         ftsRows = [];
       }
 
+      // Restore identifier-matched precision rows the set-floors above dropped.
+      // No-op when the bypass is off (bypassRows is []) or when the floors kept the
+      // rows anyway (dedup by id). Re-sort so the merged set stays relevance-ordered.
+      if (bypassRows.length > 0) {
+        const kept = new Set(ftsRows.map(r => r.id));
+        for (const r of bypassRows) if (!kept.has(r.id)) ftsRows.push(r);
+        ftsRows.sort((a, b) => (a.relevance ?? 0) - (b.relevance ?? 0));
+      }
+
       // Merge: FTS results first, then file results, deduplicated
       const seen = new Set(ftsRows.map(r => r.id));
       rows = [...ftsRows];

package/search-scoring.mjs

@@ -130,7 +130,8 @@ export function reRankWithContext(db, results, project) {
 /**
  * Mark older, lower-importance observations as superseded when multiple touch the same file.
  * Mutates result objects in-place by adding superseded=true flag.
- * @param {object[]} results Array of search result objects with source, files_modified, date, importance
+ * @param {object[]} results Array of search result objects with source, files_modified,
+ *   created_at_epoch (or created_at / legacy date), importance
  */
 export function markSuperseded(results) {
   if (!results || results.length === 0) return;
@@ -150,7 +151,20 @@ export function markSuperseded(results) {
   // Persistent superseding belongs in mem_maintain/mem_compress write paths.
   for (const [, obsForFile] of fileMap) {
     if (obsForFile.length < 2) continue;
-    obsForFile.sort((a, b) => (b.date || '').localeCompare(a.date || ''));
+    // Sort newest-first by recency. Every production obs row carries `date`
+    // (= created_at ISO, set by ftsRowToResult); the FTS/type paths also carry
+    // created_at_epoch, the vector/type-list paths carry date-only. So the prior
+    // `b.date` sort already ordered correctly in production — this is defensive
+    // hardening, not a prod no-op fix (a post-release review corrected the original
+    // #8821 "missing-`date`" diagnosis). Prefer the numeric epoch, fall back to the
+    // ISO created_at (lexically chronological), then legacy `date`, so the key holds
+    // for any caller regardless of which recency fields it supplies.
+    obsForFile.sort((a, b) => {
+      const ka = a.created_at_epoch ?? a.created_at ?? a.date ?? '';
+      const kb = b.created_at_epoch ?? b.created_at ?? b.date ?? '';
+      if (typeof ka === 'number' && typeof kb === 'number') return kb - ka;
+      return String(kb).localeCompare(String(ka));
+    });
     const newest = obsForFile[0];
     for (let i = 1; i < obsForFile.length; i++) {
       if ((obsForFile[i].importance ?? 1) <= (newest.importance ?? 1)) {

package/source-files.mjs

@@ -66,6 +66,10 @@ export const SOURCE_FILES = [
   // are present in the pre-edit file (component 2). Imported ONLY by
   // scripts/pre-tool-recall.js; kept here for the same reason as file-intel.mjs.
   'lib/lesson-idents.mjs',
+  // Phase-2 task-imperative framing helper (2026-06-29): formatTaskImperative, the single
+  // source of the imperative line. Statically imported by hook.mjs (live emitter, gated by
+  // CLAUDE_MEM_TASK_IMPERATIVE) — must ship even with the flag off.
+  'lib/task-imperative.mjs',
   // comprehension-bridge forcing-function (CLAUDE_MEM_SALIENCE=bridge): rewrites
   // a recalled lesson into a check bound to the change hunk. Dynamic-imported by
   // scripts/pre-tool-recall.js ONLY under the flag, but must still ship so the