claude-mem-lite 2.54.0 → 2.58.2

package/hook.mjs

@@ -25,7 +25,7 @@ import { homedir } from 'os';
 import {
   truncate, inferProject, detectBashSignificance,
   extractErrorKeywords, extractFilePaths, isRelatedToEpisode,
-  makeEntryDesc, scrubSecrets, EDIT_TOOLS, debugCatch, debugLog,
+  makeEntryDesc, scrubSecrets, stripPrivate, EDIT_TOOLS, debugCatch, debugLog,
   COMPRESSED_AUTO, COMPRESSED_PENDING_PURGE, isoWeekKey, OBS_BM25,
   computeMinHash, estimateJaccardFromMinHash, jaccardSimilarity,
 } from './utils.mjs';
@@ -639,10 +639,14 @@ async function handleSessionStart() {
 
       // Auto-compress: mark old low-importance observations as compressed (30+ days, importance=1)
       // Lightweight: only marks rows, doesn't create summaries (full compression via mem_compress)
+      // v2.56.0 #4: protect injection_count > 0 obs (proven contextually relevant
+      // via hook-memory injection, even if user never explicitly fetched). Same
+      // protection applied symmetrically in auto-maintain decay/mark-idle below.
       const compressed = db.prepare(`
         UPDATE observations SET compressed_into = ${COMPRESSED_AUTO}
         WHERE COALESCE(compressed_into, 0) = 0
           AND importance = 1
+          AND COALESCE(injection_count, 0) = 0
           AND created_at_epoch < ?
           AND project = ?
       `).run(autoCompressAge, project);
@@ -708,6 +712,11 @@ async function handleSessionStart() {
         if (cleaned.changes > 0) debugLog('DEBUG', 'auto-maintain', `cleaned ${cleaned.changes} broken observations`);
 
         // Decay: reduce importance of old, never-accessed observations
+        // v2.56.0 #4: injection_count is a separate engagement signal —
+        // hook-memory.mjs bumps it when the obs is auto-injected into Claude's
+        // context. Pre-v2.56 only checked access_count, so an obs auto-injected
+        // 8x (proven contextually relevant) still got decayed/marked. Adding
+        // `injection_count = 0` treats injection as first-class engagement.
         const decayed = db.prepare(`
           UPDATE observations SET importance = MAX(1, COALESCE(importance, 1) - 1)
           WHERE id IN (
@@ -715,13 +724,15 @@ async function handleSessionStart() {
             WHERE COALESCE(compressed_into, 0) = 0
               AND COALESCE(importance, 1) > 1
               AND COALESCE(access_count, 0) = 0
+              AND COALESCE(injection_count, 0) = 0
               AND created_at_epoch < ?
             LIMIT ${OP_CAP}
           )
         `).run(STALE_AGE);
         if (decayed.changes > 0) debugLog('DEBUG', 'auto-maintain', `decayed ${decayed.changes} stale observations`);
 
-        // Mark idle: importance=1, never-accessed, old → pending-purge (will be purged next cycle)
+        // Mark idle: importance=1, never-accessed, never-injected, old → pending-purge
+        // (will be purged next cycle). v2.56.0 #4: injection_count protects.
         const idleMarked = db.prepare(`
           UPDATE observations SET compressed_into = ${COMPRESSED_PENDING_PURGE}
           WHERE id IN (
@@ -729,6 +740,7 @@ async function handleSessionStart() {
             WHERE COALESCE(compressed_into, 0) = 0
               AND COALESCE(importance, 1) = 1
               AND COALESCE(access_count, 0) = 0
+              AND COALESCE(injection_count, 0) = 0
               AND created_at_epoch < ?
             LIMIT ${OP_CAP}
           )
@@ -1020,11 +1032,21 @@ async function handleUserPrompt() {
   let hookData;
   try { hookData = JSON.parse(raw.text); } catch { return; }
 
-  const promptText = hookData.prompt || hookData.user_prompt;
-  if (!promptText || typeof promptText !== 'string') return;
-
-  // Skip internal Claude Code protocol messages — not real user input
-  if (promptText.startsWith('<task-notification>')) return;
+  const rawPrompt = hookData.prompt || hookData.user_prompt;
+  if (!rawPrompt || typeof rawPrompt !== 'string') return;
+
+  // Skip internal Claude Code protocol messages — not real user input.
+  // Check on raw text BEFORE stripPrivate (the marker is a literal sentinel,
+  // wrapping it in <private> would never make sense, but order matters: a
+  // future <task-notification> with embedded <private> blocks should still
+  // be classified as protocol first.)
+  if (rawPrompt.startsWith('<task-notification>')) return;
+
+  // Strip user-marked <private>...</private> blocks at the input boundary so
+  // every downstream consumer (user_prompts INSERT, FTS query, continuation
+  // detection, semantic-memory injection) sees the redacted text — single
+  // source of truth for the privacy primitive.
+  const promptText = stripPrivate(rawPrompt);
 
   const sessionId = getSessionId();
   const db = openDb();

package/install.mjs

@@ -29,23 +29,13 @@ import { createRequire } from 'module';
 
 import { RESOURCE_METADATA } from './install-metadata.mjs';
 import { scanPluginCacheHookPollution } from './plugin-cache-guard.mjs';
-import { SOURCE_FILES } from './source-files.mjs';
+import { SOURCE_FILES, HOOK_SCRIPT_FILES } from './source-files.mjs';
 
-/**
- * Hook scripts that non-dev install must copy into ~/.claude-mem-lite/scripts/
- * to keep settings.json hook commands resolvable. Single source of truth so
- * adding a new PreToolUse/PostToolUse hook script can't drift from the install
- * copy block (which previously hand-listed only 3 of these and silently
- * dropped pre-tool-recall.js + pre-skill-bridge.js — every fresh install left
- * settings.json pointing at non-existent files).
- */
-export const HOOK_SCRIPT_FILES = [
-  'post-tool-use.sh',
-  'user-prompt-search.js',
-  'prompt-search-utils.mjs',
-  'pre-tool-recall.js',
-  'pre-skill-bridge.js',
-];
+// Re-export for backward compatibility — tests/install-hook-scripts.test.mjs
+// and any external consumers still import HOOK_SCRIPT_FILES from install.mjs.
+// The constant itself moved to source-files.mjs in v2.55 so hook-update.mjs
+// can share it without a static cycle.
+export { HOOK_SCRIPT_FILES };
 
 export function copyHookScripts(srcDir, destDir) {
   for (const name of HOOK_SCRIPT_FILES) {
@@ -349,12 +339,10 @@ async function install() {
     if (existsSync(join(PROJECT_DIR, 'registry'))) {
       symlinkSync(join(PROJECT_DIR, 'registry'), regLink);
     }
-    // Symlink commands/ directory
-    const cmdLink = join(DATA_DIR, 'commands');
-    if (existsSync(cmdLink)) try { rmSync(cmdLink, { recursive: true, force: true }); } catch {}
-    if (existsSync(join(PROJECT_DIR, 'commands'))) {
-      symlinkSync(join(PROJECT_DIR, 'commands'), cmdLink);
-    }
+    // commands/ is intentionally NOT linked: Claude Code reads slash commands
+    // from the plugin cache (~/.claude/plugins/cache/<mp>/<plugin>/<ver>/commands/)
+    // or user-level ~/.claude/commands/, never from ~/.claude-mem-lite/commands/.
+    // Pre-v2.55 maintained a symlink/copy here that had no consumers.
     ok('Symlinks created in ~/.claude-mem-lite/ → dev dir');
   } else {
     log('Installing to ~/.claude-mem-lite/...');
@@ -375,15 +363,7 @@ async function install() {
     copyHookScripts(join(PROJECT_DIR, 'scripts'), scriptsDir);
     // Ensure bash script is executable
     try { execFileSync('chmod', ['+x', join(scriptsDir, 'post-tool-use.sh')], { stdio: 'pipe' }); } catch {}
-    // Copy commands directory
-    const commandsDir = join(DATA_DIR, 'commands');
-    if (!existsSync(commandsDir)) mkdirSync(commandsDir, { recursive: true });
-    const commandsSrc = join(PROJECT_DIR, 'commands');
-    if (existsSync(commandsSrc)) {
-      for (const f of readdirSync(commandsSrc).filter(f => f.endsWith('.md'))) {
-        copyFileSync(join(commandsSrc, f), join(commandsDir, f));
-      }
-    }
+    // commands/ is intentionally NOT copied — see dev-mode branch above.
     // Copy registry manifest
     const registryDir = join(DATA_DIR, 'registry');
     if (!existsSync(registryDir)) mkdirSync(registryDir, { recursive: true });
@@ -1614,9 +1594,10 @@ function syncVersions() {
     const marketJson = JSON.parse(readFileSync(marketJsonPath, 'utf8'));
     const plugin = marketJson.plugins?.[0];
     if (plugin && plugin.version !== version) {
+      const prev = plugin.version;
       plugin.version = version;
       writeFileSync(marketJsonPath, JSON.stringify(marketJson, null, 2) + '\n');
-      ok(`marketplace.json: ${plugin.version} → ${version}`);
+      ok(`marketplace.json: ${prev} → ${version}`);
     } else if (plugin) {
       ok(`marketplace.json: already ${version}`);
     }
@@ -1624,6 +1605,27 @@ function syncVersions() {
     warn('marketplace.json not found');
   }
 
+  // Sync CLAUDE.md `**Version**: x.y.z` line — install-e2e asserts this
+  // matches package.json so omitting it here would break CI on every release.
+  const claudeMdPath = join(PROJECT_DIR, 'CLAUDE.md');
+  if (existsSync(claudeMdPath)) {
+    const orig = readFileSync(claudeMdPath, 'utf8');
+    const versionLine = /^- \*\*Version\*\*: .+$/m;
+    if (versionLine.test(orig)) {
+      const patched = orig.replace(versionLine, `- **Version**: ${version}`);
+      if (patched !== orig) {
+        writeFileSync(claudeMdPath, patched);
+        ok(`CLAUDE.md: → ${version}`);
+      } else {
+        ok(`CLAUDE.md: already ${version}`);
+      }
+    } else {
+      warn('CLAUDE.md: `**Version**:` line not found — skipped');
+    }
+  } else {
+    warn('CLAUDE.md not found');
+  }
+
   console.log('');
 }
 

package/lib/low-signal-patterns.mjs

@@ -147,6 +147,44 @@ export function capNoiseImportance(obs) {
   return original > 1 ? 1 : original;
 }
 
+/**
+ * v2.56.0 #1: paired-gate DROP for type=change + null/short lesson + low importance.
+ *
+ * Pairs with capNoiseImportance (DEMOTE) per #8152's paired-gate model. The
+ * existing isNoiseObservation gate is title-pattern keyed (LOW_SIGNAL regex);
+ * Haiku-titled `change` obs with substantive-looking titles but no extractable
+ * lesson slip through it. This gate is type+lesson keyed and catches them.
+ *
+ * Empirical baseline (CLAUDE.md, projects--mem): type=change has 16.5% hit-rate
+ * vs decision 72.7%. type=change is 67% of recent 30d obs, and Haiku writes
+ * lesson_learned=null/'none' for ~70% of curated observations (per
+ * hook-llm.mjs:639 lowSignalLesson set). When *all three* hold — change type +
+ * no lesson + Haiku didn't flag importance>=2 — the obs is by definition
+ * low-yield and adds noise to the corpus.
+ *
+ * Scope: ONLY type='change'. bugfix/decision get a lesson-retry pass already
+ * (hook-llm.mjs:648); feature/refactor/discovery aren't dominated by null
+ * lessons in the same way.
+ *
+ * Opt-out: env `CLAUDE_MEM_KEEP_LOW_SIGNAL=1` disables (parity with
+ * isNoiseObservation).
+ *
+ * @param {object} obs { type, lessonLearned|lesson_learned, importance }
+ * @param {object} [env=process.env] Environment (injected for testability)
+ * @returns {boolean} true = drop, caller should skip insert
+ */
+export function isLowYieldChangeObs(obs, env = process.env) {
+  if (env && env.CLAUDE_MEM_KEEP_LOW_SIGNAL === '1') return false;
+  if (!obs || obs.type !== 'change') return false;
+  if ((obs.importance ?? 1) >= 2) return false;
+  const lesson = obs.lessonLearned ?? obs.lesson_learned;
+  const trimmed = (typeof lesson === 'string') ? lesson.trim() : '';
+  if (!trimmed) return true;                              // null / undefined / whitespace
+  if (trimmed.toLowerCase() === 'none') return true;      // Haiku default
+  if (trimmed.length < 12) return true;                   // "ok" / "fixed it" / "works"
+  return false;
+}
+
 export function isNoiseObservation(obs, env = process.env) {
   if (env && env.CLAUDE_MEM_KEEP_LOW_SIGNAL === '1') return false;
   const title = (obs && obs.title) || '';

package/lib/private-strip.mjs

@@ -0,0 +1,36 @@
+// claude-mem-lite: Strip <private>...</private> blocks from user-supplied text
+// before any persistence or downstream processing.
+//
+// Use case: user wraps sensitive content (test fixtures, internal IDs, draft
+// secrets that scrubSecrets misses) in <private>X</private> to opt out of
+// memory capture. Replaces each well-formed pair with [redacted] to preserve
+// surrounding grammar and FTS bigram boundaries.
+//
+// Mirrors thedotmack/claude-mem v13's <private> primitive (referenced in
+// observation #8252 follow-up scope) — same syntax for cross-tool familiarity.
+//
+// Intentionally does NOT strip:
+//   - Open-without-close (`<private>...` with no `</private>`): user may still
+//     be typing; aggressive strip-to-EOL would surprise. Caller can chain a
+//     length cap (`promptText.slice(0, 10000)`) after this for safety.
+//   - Stray `</private>` with no opener: same reasoning, leave intact.
+// Both gaps are documented for callers to layer additional guards if needed.
+//
+// Case-insensitive on the tag (`<PRIVATE>`, `<Private>` all work) since users
+// type by hand. Non-greedy match handles multiple blocks correctly.
+
+const PRIVATE_BLOCK_RE = /<private>([\s\S]*?)<\/private>/gi;
+const REDACTION_MARKER = '[redacted]';
+
+/**
+ * Replace each well-formed <private>...</private> block with [redacted].
+ * Returns input unchanged if no closed block is present.
+ *
+ * @param {unknown} text Input string (non-string passes through)
+ * @returns {string|unknown} Stripped text, or input unchanged if not a string
+ */
+export function stripPrivate(text) {
+  if (typeof text !== 'string') return text;
+  if (!text.includes('<')) return text; // fast path — most prompts have no tags
+  return text.replace(PRIVATE_BLOCK_RE, REDACTION_MARKER);
+}

package/mem-cli.mjs

@@ -905,6 +905,43 @@ async function cmdStats(db, args) {
     await renderQualityReport(db, { project, days });
     return;
   }
+  // v2.57.x B2: --retry shows the lesson_retry_stats aggregate. Answers
+  // "is the bugfix/decision retry path (1 extra Haiku call per attempt)
+  // paying off?". If recovered/attempts < 0.10 over a long window, the
+  // path is dead weight and should be deleted.
+  const retry = flags.retry === true || flags.retry === 'true';
+  if (retry) {
+    const { readRetryStats } = await import('./hook-llm.mjs');
+    const rows = readRetryStats(db, days);
+    const totalAttempts = rows.reduce((a, r) => a + r.attempts, 0);
+    const totalRecovered = rows.reduce((a, r) => a + r.recovered, 0);
+    const recoveryRate = totalAttempts > 0 ? totalRecovered / totalAttempts : 0;
+    if (flags.json === true || flags.json === 'true') {
+      out(JSON.stringify({
+        days, total_attempts: totalAttempts, total_recovered: totalRecovered,
+        recovery_rate: Number(recoveryRate.toFixed(4)),
+        per_day: rows,
+      }, null, 2));
+      return;
+    }
+    out(`[mem] lesson-retry stats — last ${days}d (UTC date buckets)`);
+    out(`  attempts:  ${totalAttempts}`);
+    out(`  recovered: ${totalRecovered}`);
+    out(`  rate:      ${(recoveryRate * 100).toFixed(1)}% ${totalAttempts === 0 ? '(no data — retry path may be unused this window)' : ''}`);
+    if (totalAttempts >= 50 && recoveryRate < 0.10) {
+      out('  ⚠ recovery rate <10% over ≥50 attempts — retry path likely dead weight, consider deleting');
+    } else if (totalAttempts >= 50 && recoveryRate >= 0.30) {
+      out('  ✓ recovery rate ≥30% — retry path actively saving lessons');
+    }
+    if (rows.length > 0) {
+      out('\n  date         attempts  recovered  rate');
+      for (const r of rows.slice(0, 14)) {
+        const rate = r.attempts > 0 ? (r.recovered / r.attempts * 100).toFixed(1) + '%' : '—';
+        out(`  ${r.date_bucket}  ${String(r.attempts).padStart(8)}  ${String(r.recovered).padStart(9)}  ${rate.padStart(5)}`);
+      }
+    }
+    return;
+  }
 
   const projectFilter = project ? 'AND project = ?' : '';
   const baseParams = project ? [project] : [];
@@ -1566,6 +1603,9 @@ function cmdMaintain(db, args) {
     }
 
     if (ops.includes('decay')) {
+      // v2.56.0 #4: parity with hook.mjs auto-maintain — injection_count > 0
+      // protects from decay/mark-idle, treating hook injection as first-class
+      // engagement alongside access_count.
       const decayed = db.prepare(`
         UPDATE observations SET importance = MAX(1, COALESCE(importance, 1) - 1)
         WHERE id IN (
@@ -1573,12 +1613,13 @@ function cmdMaintain(db, args) {
           WHERE COALESCE(compressed_into, 0) = 0
             AND COALESCE(importance, 1) > 1
             AND COALESCE(access_count, 0) = 0
+            AND COALESCE(injection_count, 0) = 0
             AND created_at_epoch < ?
             ${projectFilter} LIMIT ${OP_CAP}
         )
       `).run(staleAge, ...baseParams);
 
-      // Mark importance=1, never-accessed, old observations as pending-purge (aligned with MCP)
+      // Mark importance=1, never-accessed, never-injected, old → pending-purge.
       const idleMarked = db.prepare(`
         UPDATE observations SET compressed_into = ${COMPRESSED_PENDING_PURGE}
         WHERE id IN (
@@ -1586,6 +1627,7 @@ function cmdMaintain(db, args) {
           WHERE COALESCE(compressed_into, 0) = 0
             AND COALESCE(importance, 1) = 1
             AND COALESCE(access_count, 0) = 0
+            AND COALESCE(injection_count, 0) = 0
             AND created_at_epoch < ?
             ${projectFilter} LIMIT ${OP_CAP}
         )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.54.0",
+  "version": "2.58.2",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {
@@ -15,6 +15,7 @@
   },
   "scripts": {
     "lint": "eslint .",
+    "dead-code": "knip",
     "test": "vitest run",
     "test:smoke": "vitest run tests/smoke.test.mjs",
     "test:coverage": "vitest run --coverage",
@@ -51,6 +52,7 @@
     "lib/doctor-drift.mjs",
     "lib/stats-quality.mjs",
     "lib/low-signal-patterns.mjs",
+    "lib/private-strip.mjs",
     "lib/citation-tracker.mjs",
     "lib/summary-extractor.mjs",
     "lib/id-routing.mjs",
@@ -117,13 +119,16 @@
     "zod": "^4.3.6"
   },
   "overrides": {
-    "hono": ">=4.12.14"
+    "hono": ">=4.12.16",
+    "fast-uri": ">=3.1.2",
+    "ip-address": ">=10.1.1"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^10.0.0",
     "fast-check": "^4.5.3",
+    "knip": "^6.12.1",
     "vitest": "^4.0.18"
   }
 }

package/schema.mjs

@@ -26,7 +26,21 @@ export const REGISTRY_DB_PATH = join(DB_DIR, 'resource-registry.db');
 // 2839/6429 (44%) orphaned rows (historic deletes during FK-OFF migrations)
 // and 3282/6429 (51%) stale-vocab rows (rebuildVocabulary never pruned old
 // versions before v2.47). Idempotent one-shot DELETE on ensureDb.
-export const CURRENT_SCHEMA_VERSION = 28;
+//
+// v29 (v2.57.x): (1) sdk_sessions_id_invariant trigger guarding the v2.33.1
+// mix pattern (memory_session_id and content_session_id must not be the same
+// non-null value — they're different ID schemes). (2) lesson_retry_stats
+// aggregate table tracking how often hook-llm.mjs retry path actually
+// recovers a lesson (vs being a wasted Haiku call). Both purely additive.
+//
+// v30 (v2.57.x patch): trigger body fix — UUID-shape gate so test fixtures
+// using short literal IDs ('sess-1') don't trigger. Initial v29 trigger
+// fired on any equal non-null pair, breaking 60+ test scaffolds that write
+// the same literal to both columns by helper convention. v30 forces
+// DROP+CREATE so DBs that picked up the strict v29 trigger get the UUID-
+// gated body. Required because `CREATE TRIGGER IF NOT EXISTS` is a no-op
+// when the trigger already exists, even with a different body.
+export const CURRENT_SCHEMA_VERSION = 30;
 
 const CORE_SCHEMA = `
   CREATE TABLE IF NOT EXISTS sdk_sessions (
@@ -471,6 +485,62 @@ export function initSchema(db) {
     }
   } catch { /* non-critical — normalization can retry on next open */ }
 
+  // ─── v29 (v2.57.x): session-id mix invariant + lesson-retry stats ─────────
+  //
+  // (B1) sdk_sessions_id_mix_check trigger — guards the v2.33.1 bug pattern
+  // where memory_session_id and content_session_id were silently the same
+  // value because a caller passed the wrong ID type. The two columns hold
+  // *different* ID schemes (mem-internal `hook-<project>-<hash>` vs Claude
+  // Code UUID); they should never be equal non-null in production.
+  //
+  // Trigger fires only when both values look like CC UUIDs (length 36 +
+  // hyphenated 8-4-4-4-12 LIKE pattern). This is the v2.33.1 fingerprint —
+  // a CC UUID accidentally written into BOTH columns. Test fixtures use
+  // short literal strings ('sess-1') for which neither column holds a UUID,
+  // so the trigger correctly bypasses them; the audit function below reports
+  // any mix regardless for diagnostic completeness.
+  //
+  // DROP+CREATE pattern (not IF NOT EXISTS) so v29 DBs that captured the
+  // initial strict trigger body get the UUID-gated v30 body on next init.
+  // Cheap — triggers are metadata-only DDL; this runs once per schema
+  // version bump (gated by the fast-path schema_version check above).
+  db.exec(`
+    DROP TRIGGER IF EXISTS sdk_sessions_id_mix_check_ai;
+    DROP TRIGGER IF EXISTS sdk_sessions_id_mix_check_au;
+    CREATE TRIGGER sdk_sessions_id_mix_check_ai
+      BEFORE INSERT ON sdk_sessions
+      WHEN NEW.memory_session_id IS NOT NULL
+        AND NEW.memory_session_id = NEW.content_session_id
+        AND length(NEW.memory_session_id) = 36
+        AND NEW.memory_session_id LIKE '________-____-____-____-____________'
+      BEGIN
+        SELECT RAISE(ABORT, 'sdk_sessions invariant: memory_session_id and content_session_id must not hold the same UUID value (v2.33.1 mix pattern)');
+      END;
+    CREATE TRIGGER sdk_sessions_id_mix_check_au
+      BEFORE UPDATE ON sdk_sessions
+      WHEN NEW.memory_session_id IS NOT NULL
+        AND NEW.memory_session_id = NEW.content_session_id
+        AND length(NEW.memory_session_id) = 36
+        AND NEW.memory_session_id LIKE '________-____-____-____-____________'
+      BEGIN
+        SELECT RAISE(ABORT, 'sdk_sessions invariant: memory_session_id and content_session_id must not hold the same UUID value (v2.33.1 mix pattern)');
+      END;
+  `);
+
+  // (B2) lesson_retry_stats — daily aggregate of hook-llm.mjs retry path
+  // outcomes. attempts = times the bugfix/decision retry prompt was issued;
+  // recovered = times the retry actually returned a non-low-signal lesson.
+  // Used by `claude-mem-lite stats --retry` to answer "is the extra Haiku
+  // call paying off?" — if recovered/attempts < 0.1 over a long window,
+  // delete the retry path and save one LLM call per bugfix/decision.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS lesson_retry_stats (
+      date_bucket TEXT PRIMARY KEY,
+      attempts INTEGER NOT NULL DEFAULT 0,
+      recovered INTEGER NOT NULL DEFAULT 0
+    )
+  `);
+
   // Record schema version for fast-path on subsequent calls
   db.exec('CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL)');
   db.transaction(() => {
@@ -481,6 +551,67 @@ export function initSchema(db) {
   return db;
 }
 
+// ─── Session-consistency audit (B1) ─────────────────────────────────────────
+//
+// Used by `claude-mem-lite doctor --session-audit` to surface dangling state
+// that the schema invariant trigger only catches at insert/update time. The
+// trigger is a forward-protection; this function detects historical drift.
+//
+// Returns shape: {
+//   id_mix_uuid_shape:  rows where both columns hold the same UUID-shaped value
+//                       (the v2.33.1 production fingerprint — alarming),
+//   id_mix_other:       rows where both columns equal but NOT UUID-shaped
+//                       (typically test-fixture scaffold convention — informational),
+//   missing_mem_id:     sdk_sessions rows where memory_session_id IS NULL after grace,
+//   orphan_obs:         observations.memory_session_id values not in sdk_sessions,
+//   healthy:            true when id_mix_uuid_shape + missing_mem_id + orphan_obs == 0;
+//                       id_mix_other does NOT drive healthy=false, mirroring the
+//                       trigger's UUID-shape gate so doctor doesn't misfire on DBs
+//                       contaminated with test-fixture-style literal IDs.
+// }
+//
+// Post-review fix (Important #5): split id_mix to avoid false-positive doctor
+// failures on DBs that contain test fixtures or any 'sess-1'-style literal
+// equality. The trigger only fires for UUID-shaped equality (the actual bug
+// fingerprint); the audit now mirrors that policy for the exit-code-driving
+// metric while still surfacing the broader count for diagnostic transparency.
+export function auditSessionConsistency(db, { graceMinutes = 5 } = {}) {
+  const cutoff = Date.now() - graceMinutes * 60_000;
+  // UUID-shape gate mirrors the v30 trigger — same length=36 + LIKE pattern.
+  const UUID_LIKE = '________-____-____-____-____________';
+  const idMixUuidShape = db.prepare(`
+    SELECT COUNT(*) AS c FROM sdk_sessions
+    WHERE memory_session_id IS NOT NULL
+      AND memory_session_id = content_session_id
+      AND length(memory_session_id) = 36
+      AND memory_session_id LIKE ?
+  `).get(UUID_LIKE).c;
+  const idMixOther = db.prepare(`
+    SELECT COUNT(*) AS c FROM sdk_sessions
+    WHERE memory_session_id IS NOT NULL
+      AND memory_session_id = content_session_id
+      AND NOT (length(memory_session_id) = 36 AND memory_session_id LIKE ?)
+  `).get(UUID_LIKE).c;
+  const missingMemId = db.prepare(`
+    SELECT COUNT(*) AS c FROM sdk_sessions
+    WHERE memory_session_id IS NULL
+      AND started_at_epoch < ?
+  `).get(cutoff).c;
+  const orphanObs = db.prepare(`
+    SELECT COUNT(*) AS c FROM observations o
+    WHERE NOT EXISTS (
+      SELECT 1 FROM sdk_sessions s WHERE s.memory_session_id = o.memory_session_id
+    )
+  `).get().c;
+  return {
+    id_mix_uuid_shape: idMixUuidShape,
+    id_mix_other: idMixOther,
+    missing_mem_id: missingMemId,
+    orphan_obs: orphanObs,
+    healthy: idMixUuidShape === 0 && missingMemId === 0 && orphanObs === 0,
+  };
+}
+
 /**
  * Ensure DB directory, database file, and all tables exist.
  * Safe to call from any process (hook or server). Idempotent.

package/scripts/setup.sh

@@ -26,6 +26,7 @@ fi
 log_ok()   { echo -e "${GREEN}✓${NC} $*" >&2; }
 log_info() { echo -e "${BLUE}ℹ${NC} $*" >&2; }
 log_warn() { echo -e "${YELLOW}⚠${NC} $*" >&2; }
+# shellcheck disable=SC2317  # kept for API symmetry with log_ok/log_info/log_warn
 log_err()  { echo -e "${RED}✗${NC} $*" >&2; }
 
 # 1. Migrate unhidden dir (~/claude-mem-lite/ → ~/.claude-mem-lite/)
@@ -71,8 +72,9 @@ mkdir -p "$DATA_DIR/runtime"
 if [[ ! -d "$ROOT/node_modules/better-sqlite3" ]]; then
   # Fast path: symlink from data dir (instant, no network needed)
   if [[ -d "$DATA_DIR/node_modules/better-sqlite3" ]]; then
-    ln -sfn "$DATA_DIR/node_modules" "$ROOT/node_modules" 2>/dev/null && \
-      log_ok "Dependencies linked from $DATA_DIR" || true
+    if ln -sfn "$DATA_DIR/node_modules" "$ROOT/node_modules" 2>/dev/null; then
+      log_ok "Dependencies linked from $DATA_DIR"
+    fi
   fi
   # Slow path: npm install (first-time only, ~10-20s for native addon)
   if [[ ! -d "$ROOT/node_modules/better-sqlite3" ]]; then
@@ -122,11 +124,15 @@ if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
   CACHE_DIR="$HOME/.claude/plugins/cache/sdsrss/claude-mem-lite"
   if [[ -d "$CACHE_DIR" ]]; then
     # List version dirs sorted by semver descending, skip top 3
-    # Use while-read instead of mapfile for bash 3.2 (macOS) compatibility
+    # Use glob + while-read for bash 3.2 (macOS) compatibility (no mapfile, no `ls | grep`)
     OLD_VERS=()
+    shopt -s nullglob
+    _all_dirs=("$CACHE_DIR"/[0-9]*)
+    shopt -u nullglob
     while IFS= read -r ver; do
       [[ -n "$ver" ]] && OLD_VERS+=("$ver")
-    done < <(ls -1 "$CACHE_DIR" | grep -E '^[0-9]+\.' | sort -t. -k1,1nr -k2,2nr -k3,3nr | tail -n +4)
+    done < <(for _d in "${_all_dirs[@]}"; do [[ -d "$_d" ]] && echo "${_d##*/}"; done | sort -t. -k1,1nr -k2,2nr -k3,3nr | tail -n +4)
+    unset _all_dirs _d
     if [[ ${#OLD_VERS[@]} -gt 0 ]]; then
       for ver in "${OLD_VERS[@]}"; do
         rm -rf "${CACHE_DIR:?}/$ver" 2>/dev/null || true
@@ -136,5 +142,53 @@ if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
   fi
 fi
 
+# 9. Residue detection (plugin mode only): warn once if legacy direct-install
+#    hooks remain in ~/.claude/settings.json. A user who installed via global
+#    `claude-mem-lite install` and later switched to the marketplace plugin
+#    will run every hook twice (direct settings.json hooks AND plugin hooks)
+#    until they run `claude-mem-lite uninstall` to clear the settings.json
+#    entries. /plugin uninstall does not touch settings.json.
+RESIDUE_MARKER="$DATA_DIR/runtime/.residue-warned-v2.55"
+if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" && ! -f "$RESIDUE_MARKER" ]]; then
+  SETTINGS="$HOME/.claude/settings.json"
+  if [[ -f "$SETTINGS" ]]; then
+    SETTINGS_PATH="$SETTINGS" node -e '
+      const fs = require("fs");
+      try {
+        const raw = fs.readFileSync(process.env.SETTINGS_PATH, "utf8");
+        const data = JSON.parse(raw);
+        const hooks = data.hooks || {};
+        const events = Object.keys(hooks);
+        const found = [];
+        for (const ev of events) {
+          const list = Array.isArray(hooks[ev]) ? hooks[ev] : [];
+          for (const entry of list) {
+            const inner = Array.isArray(entry?.hooks) ? entry.hooks : [];
+            for (const h of inner) {
+              const cmd = String(h?.command || "");
+              if (cmd.includes(".claude-mem-lite/") || cmd.includes("claude-mem-lite/scripts") || cmd.includes("claude-mem-lite/hook.mjs")) {
+                found.push(ev);
+                break;
+              }
+            }
+          }
+        }
+        if (found.length) {
+          process.stderr.write("\n");
+          process.stderr.write("\x1b[33m⚠\x1b[0m Legacy direct-install hooks detected in " + process.env.SETTINGS_PATH + "\n");
+          process.stderr.write("  Events with stale entries: " + [...new Set(found)].join(", ") + "\n");
+          process.stderr.write("  These will fire alongside plugin hooks (each tool call runs twice).\n");
+          process.stderr.write("  Fix: run \x1b[1mclaude-mem-lite uninstall\x1b[0m to clear settings.json,\n");
+          process.stderr.write("       then keep using the plugin install. (One-time warning.)\n\n");
+          process.exit(2);
+        }
+      } catch {}
+    ' || true
+  fi
+  # Mark the warning as shown regardless of result — silence is fine if no
+  # residue, and the warning above is one-shot per data-dir.
+  touch "$RESIDUE_MARKER"
+fi
+
 log_ok "claude-mem-lite ready"
 exit 0