claude-mem-lite 3.22.0 → 3.24.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.22.0",
+      "version": "3.24.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.22.0",
+  "version": "3.24.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/bash-utils.mjs

@@ -13,6 +13,16 @@ const CMD_WRAPPERS = new Set(['sudo', 'doas', 'env', 'time', 'command', 'nice',
 // git read subcommands whose output contains commit/log/match text, not failures.
 const GIT_READ_SUBCMDS = new Set(['grep', 'log', 'show', 'diff', 'blame', 'ls-files', 'cat-file', 'whatchanged', 'shortlog', 'reflog', 'status']);
 
+// Hard failure fingerprints — a real crash / thrown exception / non-zero-exit marker,
+// as opposed to output that merely CONTAINS the word "error" (search results, log
+// scans, prose). Deliberately strong/narrow: a JS stack frame (`\n   at fn (…)`),
+// panic/traceback/segfault, ENOENT/command-not-found, AssertionError, or a *named*
+// error class (TypeError:/ReferenceError:/…). Generic `Error:`/`exception` are
+// intentionally excluded — they appear too often in benign search/log output. Gates
+// the bugfix-shape save-nudge (lib/cite-back-hint.mjs) so `node cli.mjs search "error"`
+// + an edit in the same episode no longer looks like an unsaved fix.
+const HARD_ERROR_RE = /\bERR!|\bpanic\b|traceback|segfault|core dumped|\benoent\b|command not found|assertion\s?error|\n\s+at\s+\S|(?:type|reference|range|syntax|eval|uri)error:/i;
+
 // True when the command's PRIMARY operation (left of the first pipe, past any
 // env-assignments / wrapper like `sudo`/`env`/`time`) is a read/search — including
 // `git grep`/`git log`. Anchoring on the primary command (not "search verb appears
@@ -69,6 +79,10 @@ export function detectBashSignificance(input, response) {
   const hasHardErrorSignal = hasGreenTestSummary
     && /\bERR!|panic|traceback|enoent|command not found|exception|AssertionError|TypeError:|SyntaxError:/i.test(response);
   const isError = looksLikeError && !(hasGreenTestSummary && !hasHardErrorSignal);
+  // Strict subset of isError: a genuine failure fingerprint, not just the word "error"
+  // in benign output. Consumers that must avoid false positives (the bugfix-shape
+  // save-nudge) gate on this instead of isError.
+  const isHardError = isError && HARD_ERROR_RE.test(response);
   // Match actual test runner invocations, not commands that merely reference "test" as a keyword
   const isTest = /\b(npm\s+test|npm\s+run\s+test|yarn\s+test|pnpm\s+test|pnpm\s+run\s+test|bun\s+test|go\s+test|cargo\s+test)\b/i.test(cmd)
     || /\b(jest|pytest|vitest|mocha|cypress|playwright)\b/i.test(cmd);
@@ -85,7 +99,7 @@ export function detectBashSignificance(input, response) {
     || /\bgh\s+release\s+(?:create|edit|upload|delete)\b/i.test(cmd)
     || /\btwine\s+upload\b/i.test(cmd);
   return {
-    isError, isTest, isBuild, isGit, isDeploy,
+    isError, isHardError, isTest, isBuild, isGit, isDeploy,
     isSignificant: isError || isTest || isBuild || isGit || isDeploy,
   };
 }

package/hook-llm.mjs

@@ -803,9 +803,16 @@ ${actionList}`;
         // retry's entire purpose (a recovered bugfix lesson would silently drop
         // out of --importance 2 searches and the working tier). Gate the cap on
         // the *effective* low-signal state, not the pre-retry flag.
+        // v3.23: cap the FILE-PATH heuristic's contribution at 2. computeRuleImportance
+        // returns 3 for any entry touching schema./migration/prisma/.env/.key paths; via the
+        // Math.max below that force-promoted ordinary has-lesson episodes to "critical" imp=3
+        // even when Haiku judged them 1-2 (audit: auto imp=3 = 34.8%, e.g. a thin-lesson edit
+        // to schema.mjs). Haiku's OWN importance can still reach 3 (genuine judgment); only the
+        // path heuristic is capped. The isLessonLowSignal branch still floors no-lesson
+        // non-decision autos at ≤1; manual mem_save uses a different path and is unaffected.
         importance: isLessonLowSignal && !retryRecovered && parsed.type !== 'decision'
           ? Math.min(ruleImportance, 1)
-          : Math.max(ruleImportance, clampImportance(parsed.importance)),
+          : Math.max(Math.min(ruleImportance, 2), clampImportance(parsed.importance)),
         lessonLearned,
         searchAliases,
       };

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

@@ -47,7 +47,7 @@ import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObse
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { formatHookError } from './lib/native-binding-hint.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
-import { cleanupBroken, decayAndMarkIdle, boostAccessed, selectFuzzyDedupeIds, hardDeleteCandidateCount, purgeStale } from './lib/maintain-core.mjs';
+import { cleanupBroken, decayAndMarkIdle, boostAccessed, selectFuzzyDedupeIds, hardDeleteCandidateCount, purgeStale, recoverOrphanedChildren } from './lib/maintain-core.mjs';
 import { snapshotDb } from './lib/db-backup.mjs';
 import {
   extractCitationsFromTranscript,
@@ -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';
@@ -286,6 +287,9 @@ async function handlePostToolUse() {
     files,
     ts: Date.now(),
     isError: bashSig?.isError || false,
+    // isHardError gates the bugfix-shape save-nudge (lib/cite-back-hint.mjs): a real
+    // failure fingerprint, not just "error" appearing in search/log output.
+    isHardError: bashSig?.isHardError || false,
     isSignificant: EDIT_TOOLS.has(tool_name) ||
                    bashSig?.isSignificant || false,
     bashSig: bashSig || null,
@@ -711,6 +715,12 @@ function runSessionStartDbMutations(db, { sessionId, project, prevSessionId, now
       WHERE COALESCE(compressed_into, 0) = 0
         AND COALESCE(importance, 1) <= 1
         AND COALESCE(injection_count, 0) = 0
+        -- v3.23: never auto-hide a row that carries a real lesson. compression folds
+        -- sources into a title-only summary (lesson lost), and COMPRESSED_AUTO hides the
+        -- row from search entirely. A low-importance obs whose lesson_learned is the
+        -- distilled value must stay findable (audit: 62 lessons buried this way). The 7d
+        -- noise block below already excludes lessons; this 30d block had drifted.
+        AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
         AND created_at_epoch < ?
         AND project = ?
     `).run(autoCompressAge, project);
@@ -779,6 +789,12 @@ function runSessionStartAutoMaintain(db) {
       const cleaned = cleanupBroken(db, mctx);
       if (cleaned > 0) debugLog('DEBUG', 'auto-maintain', `cleaned ${cleaned} broken observations`);
 
+      // Self-heal legacy orphans: children whose compression keeper was hard-deleted
+      // before recoverChildrenOf existed are hidden + queue-less (unreachable). Resurface
+      // them so normal decay/GC handles them on merit. Non-destructive (un-hide only).
+      const orphansRecovered = recoverOrphanedChildren(db, mctx);
+      if (orphansRecovered > 0) debugLog('DEBUG', 'auto-maintain', `recovered ${orphansRecovered} orphaned compression children`);
+
       const { decayed, idleMarked } = decayAndMarkIdle(db, mctx);
       if (decayed > 0) debugLog('DEBUG', 'auto-maintain', `decayed ${decayed} stale observations`);
       if (idleMarked > 0) debugLog('DEBUG', 'auto-maintain', `marked ${idleMarked} idle as pending-purge`);
@@ -1371,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 {
@@ -1379,17 +1396,36 @@ 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) {
+        process.stdout.write(formatTaskImperative(imperativePick.lesson_learned, imperativePick.id) + '\n');
+      }
     } catch (e) { debugCatch(e, 'handleUserPrompt-memory'); }
   } finally {
     db.close();

package/lib/cite-back-hint.mjs

@@ -68,11 +68,17 @@ export function buildCiteBackHint(episode, cooldown) {
 // the lib so all save-prompt hints share one home + the same wording rules.
 //
 // Detection (mirrors pre-v2.83 hook.mjs:194 heuristic):
-//   • has at least one entry with isError=true
+//   • has at least one entry with a HARD failure fingerprint (isHardError) — NOT just
+//     isError. `node cli.mjs search "error"`, `npx vitest` green output, or any command
+//     whose output merely MENTIONS "error"/"failed" sets isError=true but is not a fix;
+//     gating on isError nagged on non-fixes (audit: fired on a read-only session + a
+//     scratch write). isHardError requires a real crash/exception/stack (bash-utils.mjs).
 //   • has at least one entry using an edit tool
 //   • entries.length >= 3 (rules out single-typo fixes that don't need a lesson)
 // Returns null when any condition fails or when no edited files are recoverable
 // from the entry list (defensive — episodes flushed mid-tool can have empties).
+// Legacy fallback: entries written before isHardError existed lack the field, so fall
+// back to isError for them rather than silently regress the nudge to never-fire.
 const MIN_BUGFIX_ENTRIES = 3;
 const MAX_DISPLAY_FILES = 3;
 
@@ -86,7 +92,7 @@ export function buildUnsavedBugfixHint(episode) {
   const editedFiles = new Set();
   for (const e of entries) {
     if (!e) continue;
-    if (e.isError) hasError = true;
+    if (e.isHardError !== undefined ? e.isHardError : e.isError) hasError = true;
     if (EDIT_TOOLS.has(e.tool)) {
       hasEdit = true;
       for (const f of e.files || []) editedFiles.add(f);

package/lib/compress-core.mjs

@@ -40,6 +40,10 @@ export function selectCompressionCandidates(db, { cutoff, project = null, includ
     FROM observations
     WHERE COALESCE(importance, 1) <= 1
       AND COALESCE(access_count, 0) = 0
+      -- v3.23: exclude rows carrying a real lesson — folding them into a title-only
+      -- weekly summary discards the lesson (the distilled value of a lessons store).
+      -- Mirrors the hook auto-compress lesson guard so neither path buries a lesson.
+      AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
       AND created_at_epoch < ?
       ${compressedFilter}
       ${projectFilter}

package/lib/maintain-core.mjs

@@ -98,6 +98,25 @@ export function recoverChildrenOf(db, ids) {
   ).run(...ids, ...ids).changes;
 }
 
+// Resurface children orphaned by a keeper hard-deleted BEFORE recoverChildrenOf existed
+// (legacy data). recoverChildrenOf only fires at delete time for the keepers being deleted
+// in that call; rows whose keeper vanished in a past release are missed forever. A child
+// with compressed_into = <positive keeperId> whose keeper row no longer exists is hidden
+// from every COALESCE(compressed_into,0)=0 view AND sits in no maintenance queue (not
+// COMPRESSED_AUTO, not COMPRESSED_PENDING_PURGE), so nothing ever resurfaces or GCs it —
+// it leaks its full narrative out of reach. Setting compressed_into = NULL makes it live
+// again; normal decay/GC then handles it on merit. `compressed_into > 0` excludes the
+// negative sentinels (intentional states, not orphans). NON-DESTRUCTIVE: only un-hides
+// rows, never deletes — safe to run unconditionally, no snapshot needed.
+export function recoverOrphanedChildren(db, { projectFilter = '', baseParams = [] } = {}) {
+  return db.prepare(`
+    UPDATE observations SET compressed_into = NULL
+    WHERE compressed_into > 0
+      AND NOT EXISTS (SELECT 1 FROM observations k WHERE k.id = observations.compressed_into)
+      ${projectFilter}
+  `).run(...baseParams).changes;
+}
+
 export function cleanupBroken(db, { projectFilter, baseParams, opCap = OP_CAP }) {
   const doomed = db.prepare(`
     SELECT id FROM observations
@@ -133,6 +152,11 @@ export function decayAndMarkIdle(db, { projectFilter, baseParams, staleAge, opCa
         AND COALESCE(importance, 1) = 1
         AND COALESCE(access_count, 0) = 0
         AND COALESCE(injection_count, 0) = 0
+        -- v3.23: never mark a lesson-bearing row idle→pending-purge. A lesson is the
+        -- distilled value of a lessons store; auto-GC must not silently purge it (parity
+        -- with the compress lesson guards in hook.mjs + compress-core.mjs). Truly stale
+        -- lessons are removed by explicit delete, not background decay.
+        AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
         AND created_at_epoch < ?
         ${projectFilter} LIMIT ${opCap}
     )

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

@@ -18,6 +18,7 @@ import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from '
 import { buildNotLowSignalSql } from './lib/low-signal-patterns.mjs';
 import {
   cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
+  recoverOrphanedChildren,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
   recoverChildrenOf, hardDeleteCandidateCount,
   OP_CAP, STALE_AGE_MS, PINNED_INJ_THRESHOLD,
@@ -1096,9 +1097,17 @@ async function cmdStats(db, args) {
     `SELECT AVG(COALESCE(importance,1)) as v FROM observations WHERE 1=1 ${projectFilter}`
   ).get(...baseParams);
   const thirtyDaysAgo = now - 30 * 86400000;
+  // v3.23 noise-gauge de-blinding: the prior `importance = 1` predicate was
+  // structurally blind to imp=0 — decay's floor + the LLM low-signal filter push
+  // dormant rows to 0, which on a real store is ~half the live corpus. The gauge
+  // therefore reported "0.0% noise" while the store was dormant-heavy. `<= 1` makes
+  // imp=0 visible; injection_count=0 mirrors decay's NEVER-INJECTED guard so an
+  // injected-but-decayed row (pinned noise, tracked separately) is not miscounted
+  // as "never used".
   const lowVal = db.prepare(`
     SELECT COUNT(*) as c FROM observations
-    WHERE COALESCE(importance,1) = 1 AND COALESCE(access_count,0) = 0
+    WHERE COALESCE(importance,1) <= 1 AND COALESCE(access_count,0) = 0
+      AND COALESCE(injection_count,0) = 0
       AND COALESCE(compressed_into, 0) = 0
       AND created_at_epoch < ? ${projectFilter}
   `).get(thirtyDaysAgo, ...baseParams);
@@ -1197,7 +1206,7 @@ async function cmdStats(db, args) {
   out('Data Health:');
   out(`  Est. tokens: ${tokenEst.t ?? 0}`);
   out(`  Avg importance: ${(avgImp.v ?? 1).toFixed(2)}`);
-  out(`  Low-value (imp=1, never accessed, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`);
+  out(`  Low-value (imp≤1, never used, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`);
   out(`  Low-signal titles (Modified/Error/Worked on…): ${lowSignalTitle.c} (${(lowSignalRatio * 100).toFixed(1)}%)`);
   out(`  Compressed: ${compressedCount.c}`);
   out(`  Hook errors (last 24h): ${hookErrors24h}${hookErrors24h > 0 ? `  ← tail ${join(DB_DIR, 'runtime/hook-errors')}` : ''}`);
@@ -1752,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`
@@ -1944,6 +1960,10 @@ function cmdMaintain(db, args) {
     if (ops.includes('cleanup')) {
       const deleted = cleanupBroken(db, mctx);
       results.push(`Cleaned up ${deleted} broken observations${capHint(deleted)}`);
+      // Self-heal legacy orphans (keeper hard-deleted pre-recoverChildrenOf): resurface
+      // unreachable children. Non-destructive — un-hide only, no delete.
+      const orphans = recoverOrphanedChildren(db, mctx);
+      if (orphans > 0) results.push(`Recovered ${orphans} orphaned compression children`);
     }
 
     if (ops.includes('decay')) {
@@ -2844,6 +2864,13 @@ 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.
+  if (args.includes('--execute') && !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.22.0",
+  "version": "3.24.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) || 'unknown';
 }
 
 function readCooldown(cooldownPath) {

package/scripts/user-prompt-search.js

@@ -197,6 +197,49 @@ export function hasExplicitSignal(text, { errSig, files, intent } = {}) {
   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()))];
+}
+
+// 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 +600,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 +634,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 +665,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,18 @@ 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. The production search pipeline supplies
+    // created_at_epoch (numeric) + created_at (ISO) — NOT `date`; the prior
+    // `b.date` sort silently no-op'd there (every key undefined → localeCompare 0),
+    // so "newest" degraded to relevance order and a current top-importance obs got
+    // a false [SUPERSEDED] tag (#8821). Prefer numeric epoch, fall back to the ISO
+    // string (lexically chronological), then legacy `date` for older callers/tests.
+    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/server.mjs

@@ -17,6 +17,7 @@ import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentT
 import { buildSearchFtsQuery, parseDateBounds, coreRunSearchPipeline } from './lib/search-core.mjs';
 import {
   cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
+  recoverOrphanedChildren,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
   recoverChildrenOf, hardDeleteCandidateCount,
   OP_CAP, STALE_AGE_MS,
@@ -863,9 +864,14 @@ server.registerTool(
     `).get(...baseParams);
 
     const thirtyDaysAgo = Date.now() - 30 * 86400000;
+    // v3.23 noise-gauge de-blinding (mirrors mem-cli cmdStats): `<= 1` makes the
+    // imp=0 dormant population visible (decay floor + LLM low-signal filter push
+    // ~half the live corpus to 0); injection_count=0 mirrors decay's NEVER-INJECTED
+    // guard so injected-but-decayed pinned noise isn't miscounted as "never used".
     const lowVal = db.prepare(`
       SELECT COUNT(*) as c FROM observations
-      WHERE COALESCE(importance,1) = 1 AND COALESCE(access_count,0) = 0
+      WHERE COALESCE(importance,1) <= 1 AND COALESCE(access_count,0) = 0
+        AND COALESCE(injection_count,0) = 0
         AND COALESCE(compressed_into, 0) = 0
         AND created_at_epoch < ? ${projectFilter}
     `).get(thirtyDaysAgo, ...baseParams);
@@ -915,7 +921,7 @@ server.registerTool(
       'Data Health:',
       `  Est. tokens: ${tokenEst.t ?? 0}`,
       `  Avg importance: ${(avgImp.v ?? 1).toFixed(2)}`,
-      `  Low-value (imp=1, never accessed, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`,
+      `  Low-value (imp≤1, never used, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`,
       `  Low-signal titles (Modified/Error/Worked on…): ${lowSignalTitle.c} (${(lowSignalRatio * 100).toFixed(1)}%)`,
       `  Compressed: ${compressedCount.c}`,
       ...((noiseRatio > 0.6 || lowSignalRatio > 0.3) ? ['  ⚠️ High noise ratio — consider running mem_compress / maintain'] : []),
@@ -1109,6 +1115,10 @@ server.registerTool(
         if (ops.includes('cleanup')) {
           const deleted = cleanupBroken(db, mctx);
           results.push(`Cleaned up ${deleted} broken observations` + (deleted >= OP_CAP ? ' (cap reached, re-run for more)' : ''));
+          // Self-heal legacy orphans (keeper hard-deleted pre-recoverChildrenOf):
+          // resurface unreachable children. Non-destructive — un-hide only, no delete.
+          const orphans = recoverOrphanedChildren(db, mctx);
+          if (orphans > 0) results.push(`Recovered ${orphans} orphaned compression children`);
         }
 
         if (ops.includes('decay')) {

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