claude-mem-lite 2.59.0 → 2.60.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.59.0",
+      "version": "2.60.0",
       "source": "./",
       "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.59.0",
+  "version": "2.60.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'delete', 'update', 'export', 'compress', 'maintain', 'optimize', 'fts-check', 'registry', 'import', 'enrich', 'activity', 'adopt', 'unadopt', 'help']);
+const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'delete', 'update', 'export', 'compress', 'maintain', 'optimize', 'fts-check', 'registry', 'import', 'enrich', 'activity', 'adopt', 'unadopt', 'memdir-audit', 'help']);
 const INSTALL_COMMANDS = new Set(['install', 'uninstall', 'status', 'doctor', 'cleanup', 'cleanup-hooks', 'self-update', 'release']);
 
 const cmd = process.argv[2];

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 { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords } from './utils.mjs';
+import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, truncate, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords } from './utils.mjs';
 import { recordMetric } from './lib/metrics.mjs';
 import { DB_DIR } from './schema.mjs';
 
@@ -78,6 +78,44 @@ function candidateCoverage(row, queryTerms) {
 const FILE_RECALL_LOOKBACK_MS = 60 * 86400000; // 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
+// referenced code before applying the lesson — code may have moved or been
+// renamed since capture. Pure-decision/architecture obs (no file_paths)
+// don't get the hint: their drift is text-only and Claude already verifies
+// at consumption time per the project mem-usage contract.
+const STALE_OBS_THRESHOLD_MS = 30 * 86400000;
+
+/**
+ * Format a single line for the <memory-context> block emitted by
+ * handleUserPrompt. Pure function — exported for unit testing.
+ *
+ * @param {object} obs Row with {id, type, title, lesson_learned,
+ *   created_at_epoch, files_modified}. files_modified is a JSON-encoded
+ *   string array (column shape) or null.
+ * @returns {string} `- [type] title[ | Lesson: X] (#id)[ [verify-before-use]]`
+ */
+export function formatMemoryLine(obs) {
+  const lessonTag = obs.lesson_learned ? ` | Lesson: ${obs.lesson_learned}` : '';
+  let staleHint = '';
+  if (typeof obs.created_at_epoch === 'number'
+    && Date.now() - obs.created_at_epoch > STALE_OBS_THRESHOLD_MS
+    && hasFilePaths(obs.files_modified)) {
+    staleHint = ' [verify-before-use]';
+  }
+  return `- [${obs.type}] ${truncate(obs.title, 80)}${lessonTag} (#${obs.id})${staleHint}`;
+}
+
+function hasFilePaths(filesModified) {
+  if (!filesModified || typeof filesModified !== 'string') return false;
+  try {
+    const arr = JSON.parse(filesModified);
+    return Array.isArray(arr) && arr.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Search for relevant past observations to inject as memory context.
  * Quality gates: importance>=1 (with 0.6x penalty), type-boosted, lesson-boosted, BM25-thresholded (adaptive: 0 for <5 obs, 1.5 otherwise).
@@ -124,6 +162,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     // penalty factor (for the final JS score).
     const selectStmt = db.prepare(`
       SELECT o.id, o.type, o.title, o.subtitle, o.narrative, o.importance, o.lesson_learned, o.project,
+             o.created_at_epoch, o.files_modified,
              ${OBS_BM25} as relevance,
              ${noisePenaltyClause('o')} as noise_penalty
       FROM observations_fts

package/hook.mjs

@@ -45,7 +45,8 @@ import {
 import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObservation } from './hook-llm.mjs';
 import { extractCitationsFromTranscript, bumpCitationAccess } from './lib/citation-tracker.mjs';
 import { extractTailAssistantText, extractStructuredSummary } from './lib/summary-extractor.mjs';
-import { searchRelevantMemories } from './hook-memory.mjs';
+import { searchRelevantMemories, formatMemoryLine } from './hook-memory.mjs';
+import { detectMemOverride } from './lib/mem-override.mjs';
 import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection, pickHandoffToInject, extractUnfinishedSummary } from './hook-handoff.mjs';
 import { checkForUpdate } from './hook-update.mjs';
 import { handleLLMOptimize } from './hook-optimize.mjs';
@@ -1111,8 +1112,11 @@ async function handleUserPrompt() {
       } catch (e) { debugCatch(e, 'handleUserPrompt-handoff'); }
     }
 
-    // Semantic memory injection: search past observations for the user's prompt
-    try {
+    // Semantic memory injection: search past observations for the user's prompt.
+    // P0 short-circuit on user-explicit "ignore memory" / "不要用记忆" override
+    // (mirrors CC built-in memoryTypes.ts:215). Skip both Key Context lookup
+    // and the <memory-context> emission for this turn.
+    if (!detectMemOverride(promptText)) try {
       const keyObs = db.prepare(`
         SELECT id FROM observations
         WHERE project = ? AND COALESCE(compressed_into, 0) = 0
@@ -1135,10 +1139,7 @@ async function handleUserPrompt() {
       const memories = searchRelevantMemories(db, promptText, project, keyContextIds);
       if (memories.length > 0) {
         const lines = ['<memory-context relevance="high">'];
-        for (const m of memories) {
-          const lessonTag = m.lesson_learned ? ` | Lesson: ${m.lesson_learned}` : '';
-          lines.push(`- [${m.type}] ${truncate(m.title, 80)}${lessonTag} (#${m.id})`);
-        }
+        for (const m of memories) lines.push(formatMemoryLine(m));
         lines.push('</memory-context>');
         process.stdout.write(lines.join('\n') + '\n');
       }

package/lib/mem-override.mjs

@@ -0,0 +1,31 @@
+// User-explicit "ignore memory" override detector. Mirrors CC built-in
+// memoryTypes.ts:215 ("If the user says to *ignore* or *not use* memory:
+// Do not apply remembered facts"). Tight regexes — must require both an
+// "ignore-class" verb AND the memory token, so phrases like "memory leak",
+// "记忆中的事件", "MEM-1234" pass through unaffected.
+//
+// Two parallel patterns:
+//   EN — ignore|skip|forget|disable|drop|reject + (optional qualifier)
+//        + memor(y|ies) | memory-context | past context | recall;
+//        plus the negated form: do not / don't + use|read|inject|apply.
+//   CN — 1) ignore-class verbs (无视|忽略|忽视|跳过|拒绝|不再[用|看|读|参考])
+//           + (optional qualifier) + 记忆
+//        2) 不要|别|不需|不必 + use-class verb (用|看|读|参考|...) + 记忆.
+//
+// Lives under lib/ (not scripts/) because hook.mjs imports it directly
+// for the handleUserPrompt short-circuit. install.mjs/hook-update.mjs
+// rename scripts/ as a directory; an individual `scripts/<file>.mjs`
+// entry in SOURCE_FILES would collide with that rename.
+
+const MEM_OVERRIDE_EN = /\b(?:ignore|skip|forget|disable|drop|reject)\s+(?:(?:any|all|the|past|prior|previous|recalled?|injected|stored)\s+){0,3}(?:memor(?:y|ies)|memory-?context|mem[\s-]context|past\s+context|recall)\b|\b(?:do\s+not|don['’`]?t)\s+(?:use|read|inject|apply)\s+(?:(?:any|all|the|past|prior|previous|recalled?|injected|stored)\s+){0,3}(?:memor(?:y|ies)|memory-?context|mem[\s-]context|past\s+context|recall)\b/i;
+
+const MEM_OVERRIDE_CN = /(?:无视|忽略|忽视|跳过|拒绝|不再用|不再看|不再读|不再参考)\s*(?:任何|所有|过去|先前|之前|历史|相关|这次|本次|过往|注入|的){0,3}\s*记忆|(?:不要|别|不需|不必)\s*(?:再)?\s*(?:用|看|读|查|参考|使用|启用|采用|采纳|读取|加载|应用|注入|带上)\s*(?:任何|所有|过去|先前|之前|历史|相关|这次|本次|过往|注入|的){0,3}\s*记忆/;
+
+/**
+ * Returns true if the prompt explicitly tells Claude to ignore memory.
+ * UPS hook + handleUserPrompt memory injection MUST short-circuit on true.
+ */
+export function detectMemOverride(text) {
+  if (!text || typeof text !== 'string') return false;
+  return MEM_OVERRIDE_EN.test(text) || MEM_OVERRIDE_CN.test(text);
+}

package/mem-cli.mjs

@@ -17,9 +17,10 @@ import { searchResources } from './registry-retriever.mjs';
 import { optimizePreview, optimizeRun } from './hook-optimize.mjs';
 import { buildSessionContextLines } from './hook-context.mjs';
 import { cmdAdopt, cmdUnadopt } from './adopt-cli.mjs';
+import { auditMemdir, memdirPath } from './memdir.mjs';
 import { probeOtherSources as probeIdSources, bucketIdTokens } from './lib/id-routing.mjs';
-import { basename } from 'path';
-import { readFileSync } from 'fs';
+import { basename, join } from 'path';
+import { readFileSync, existsSync, readdirSync } from 'fs';
 
 // v2.41: shared CLI helpers extracted to cli/common.mjs. Keep this file as the
 // router + remaining-command bodies during the incremental split. Future work:
@@ -1905,6 +1906,65 @@ function cmdRegistry(_memDb, args) {
   }
 }
 
+// ─── memdir-audit ────────────────────────────────────────────────────────────
+// Body-structure audit for ~/.claude/projects/<encoded>/memory/feedback_*.md
+// and project_*.md. CLI-only by design — running this every session would be
+// noise; it's a one-shot governance pass. Exit code 0 = 100% compliant,
+// 1 = at least one file is non-compliant (so it can gate CI if a project
+// wants to enforce structure).
+
+function _formatAuditResult(memdir, result) {
+  const lines = [`[mem] memdir audit: ${memdir}`];
+  const fmt = (label, list) =>
+    list.length ? `${label} (${list.length}):\n  - ${list.join('\n  - ')}` : `${label} (0)`;
+  lines.push(fmt('Compliant', result.compliant));
+  lines.push(fmt('Missing **Why:**', result.missingWhy));
+  lines.push(fmt('Missing **How to apply:**', result.missingHowToApply));
+  lines.push(fmt('Missing both', result.missingBoth));
+  lines.push(`Total: ${result.total} file(s) (${result.compliant.length} compliant)`);
+  return lines.join('\n');
+}
+
+function _resolveMemdirsForAudit(flags) {
+  if (typeof flags.memdir === 'string' && flags.memdir.length > 0) {
+    return [flags.memdir];
+  }
+  if (flags.all === true || flags.all === 'true') {
+    const projectsRoot = join(homedir(), '.claude', 'projects');
+    if (!existsSync(projectsRoot)) return [];
+    let entries;
+    try { entries = readdirSync(projectsRoot); } catch { return []; }
+    return entries
+      .map(name => join(projectsRoot, name, 'memory'))
+      .filter(p => existsSync(p))
+      .sort();
+  }
+  return [memdirPath(process.cwd())];
+}
+
+function cmdMemdirAudit(args) {
+  const { flags } = parseArgs(args);
+  const memdirs = _resolveMemdirsForAudit(flags);
+  if (memdirs.length === 0) {
+    out('[mem] No memdirs to audit (use --memdir <path> or run inside a Claude Code project).');
+    return;
+  }
+  let nonCompliant = 0;
+  let totalScanned = 0;
+  for (const md of memdirs) {
+    const result = auditMemdir(md);
+    out(_formatAuditResult(md, result));
+    totalScanned += result.total;
+    nonCompliant +=
+      result.missingWhy.length + result.missingHowToApply.length + result.missingBoth.length;
+    if (memdirs.length > 1) out('');
+  }
+  if (memdirs.length > 1) {
+    out(`[mem] Scanned ${memdirs.length} memdir(s), ${totalScanned} memory file(s), ${nonCompliant} non-compliant.`);
+  }
+  if (nonCompliant > 0) process.exitCode = 1;
+}
+
 // ─── Help ────────────────────────────────────────────────────────────────────
 
 function cmdHelp() {
@@ -2046,6 +2106,12 @@ Commands:
   unadopt               Precise removal of the sentinel block + plugin_claude_mem_lite.md.
     --all               Unadopt every project
 
+  memdir-audit          Audit memdir feedback_*.md / project_*.md for the
+                        body-structure contract (**Why:** + **How to apply:**).
+                        Exit 0 if every file is compliant, 1 otherwise.
+    --memdir <path>     Audit an explicit memdir path (escape hatch)
+    --all               Audit every project under ~/.claude/projects/*/memory/
+
 DB: ${DB_PATH}`);
 }
 
@@ -2240,6 +2306,7 @@ export async function run(argv) {
   // no DB needed. Route them before ensureDb() so an unbootable DB doesn't block.
   if (cmd === 'adopt') { cmdAdopt(cmdArgs); return; }
   if (cmd === 'unadopt') { cmdUnadopt(cmdArgs); return; }
+  if (cmd === 'memdir-audit') { cmdMemdirAudit(cmdArgs); return; }
 
   let db;
   try {

package/memdir.mjs

@@ -9,7 +9,7 @@
 //
 // See docs/plans/2026-04-16-invited-memory-pattern.md for rationale.
 
-import { readFileSync, writeFileSync, existsSync, renameSync, unlinkSync, mkdirSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, renameSync, unlinkSync, mkdirSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { createHash } from 'crypto';
@@ -268,3 +268,67 @@ export function removePluginDoc(memdir, slug) {
   if (!existsSync(path)) return;
   try { unlinkSync(path); } catch { /* best-effort */ }
 }
+
+// ─── P2: body-structure audit ────────────────────────────────────────────────
+// CC's CLAUDE.md memory contract requires feedback_*.md and project_*.md to
+// carry **Why:** + **How to apply:** lines. user_*.md and reference_*.md
+// have no body-structure requirement (per memoryTypes.ts <body_structure>
+// blocks). MEMORY.md (the index) is excluded too — it lists pointers, not
+// memory content. This is intentionally a CLI-only tool (not a hook): it
+// is a one-shot governance pass, running it on every session would just be
+// noise.
+
+const AUDIT_FILE_RE = /^(feedback|project)_[A-Za-z0-9_-]+\.md$/;
+const WHY_RE = /^\s*\*\*Why:\*\*/m;
+const HOW_RE = /^\s*\*\*How to apply:\*\*/m;
+
+/**
+ * Strip the leading YAML frontmatter block (between `---` fences) so audit
+ * checks run only against body content. Returns input unchanged if no
+ * frontmatter is present.
+ */
+function stripFrontmatter(content) {
+  if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) return content;
+  const m = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
+  return m ? content.slice(m[0].length) : content;
+}
+
+/**
+ * Scan a memdir for feedback_* and project_* files and bucket them by
+ * body-structure compliance. Pure function — IO is read-only and bounded
+ * to the directory listing + per-file Reads.
+ *
+ * @param {string} memdir Absolute path to memdir
+ * @returns {{
+ *   compliant: string[],
+ *   missingWhy: string[],
+ *   missingHowToApply: string[],
+ *   missingBoth: string[],
+ *   total: number,
+ * }}
+ */
+export function auditMemdir(memdir) {
+  const result = { compliant: [], missingWhy: [], missingHowToApply: [], missingBoth: [], total: 0 };
+  if (!memdir || !existsSync(memdir)) return result;
+
+  let entries;
+  try { entries = readdirSync(memdir); } catch { return result; }
+
+  const targets = entries.filter(n => AUDIT_FILE_RE.test(n)).sort();
+  for (const name of targets) {
+    let body = '';
+    try {
+      const raw = readFileSync(join(memdir, name), 'utf8');
+      body = stripFrontmatter(raw);
+    } catch { /* unreadable — count as missingBoth */ }
+
+    const hasWhy = WHY_RE.test(body);
+    const hasHow = HOW_RE.test(body);
+    if (hasWhy && hasHow) result.compliant.push(name);
+    else if (!hasWhy && !hasHow) result.missingBoth.push(name);
+    else if (!hasWhy) result.missingWhy.push(name);
+    else result.missingHowToApply.push(name);
+  }
+  result.total = targets.length;
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.59.0",
+  "version": "2.60.0",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {
@@ -58,6 +58,7 @@
     "lib/id-routing.mjs",
     "lib/err-sampler.mjs",
     "lib/metrics.mjs",
+    "lib/mem-override.mjs",
     "cli/common.mjs",
     "cli/fts-check.mjs",
     "cli/doctor.mjs",

package/scripts/prompt-search-utils.mjs

@@ -101,6 +101,12 @@ export function detectIntent(text) {
   return first;
 }
 
+// detectMemOverride lives in lib/mem-override.mjs (importable from hook.mjs
+// without dragging the scripts/ tree into SOURCE_FILES). Re-exported here so
+// scripts/user-prompt-search.js and existing tests can keep importing it
+// from the same module as the rest of the prompt-side helpers.
+export { detectMemOverride } from '../lib/mem-override.mjs';
+
 // ─── Error Signature Extraction ─────────────────────────────────────────────
 
 /**

package/scripts/user-prompt-search.js

@@ -9,7 +9,7 @@ import { cjkPrecisionOk } from '../nlp.mjs';
 import { writeFileSync, readFileSync, existsSync, renameSync } from 'fs';
 import { join } from 'path';
 import Database from 'better-sqlite3';
-import { shouldSkip, computeEffectiveLen, detectIntent, shouldSkipByDedup, extractFiles, extractErrorSignature, DEDUP_STALE_MS, matchRegistrySkillName } from './prompt-search-utils.mjs';
+import { shouldSkip, computeEffectiveLen, detectIntent, shouldSkipByDedup, extractFiles, extractErrorSignature, DEDUP_STALE_MS, matchRegistrySkillName, detectMemOverride } from './prompt-search-utils.mjs';
 
 // ─── Constants ──────────────────────────────────────────────────────────────
 
@@ -491,6 +491,12 @@ async function main() {
   // Skip short/confirmation/slash-command/simple-op prompts
   if (shouldSkip(promptText)) return;
 
+  // P0: User-explicit "ignore memory" override (mirrors CC built-in
+  // memoryTypes.ts:215). When the prompt directly tells Claude to skip
+  // memory recall, we short-circuit before FTS — no FTS budget burn,
+  // no .claude-mem-injected-* state churn, no surface emission.
+  if (detectMemOverride(promptText)) return;
+
   // T3 (v2.31): additional raw-length gate on top of shouldSkip's CJK-weighted
   // effective-length check. Suppresses medium-short Latin prompts ("run tests",
   // "fix bug now") that carry too few content tokens for a meaningful FTS lookup.

package/source-files.mjs

@@ -53,6 +53,11 @@ export const SOURCE_FILES = [
   'memdir.mjs',
   'adopt-content.mjs',
   'adopt-cli.mjs',
+  // P0 (v2.59.x): user-explicit "ignore memory" override detector. Lives
+  // under lib/ (not scripts/) so hook.mjs can statically import it without
+  // colliding with the scripts/ directory rename in installExtractedRelease
+  // — see the SWITCHABLE_PATHS loop in hook-update.mjs.
+  'lib/mem-override.mjs',
 ];
 
 /**