claude-mem-lite 2.80.1 → 2.82.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.80.1",
+      "version": "2.82.1",
       "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.80.1",
+  "version": "2.82.1",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/adopt-cli.mjs

@@ -9,7 +9,7 @@
 // --dry-run = print intent without writing
 // --status = list all adopted projects + versions
 
-import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync } from 'fs';
+import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import {
@@ -49,6 +49,24 @@ function listAllMemdirs() {
 
 function hasFlag(args, flag) { return Array.isArray(args) && args.includes(flag); }
 
+// ─── Per-project auto-adopt opt-out sentinel ─────────────────────────────────
+// `<memdir>/.mem-no-auto-adopt` is the durable, project-scoped escape hatch.
+// Survives marker deletion, sentinel removal, and plugin reinstalls — that's
+// the point: "user said no for this project" should not be reversible by
+// `rm ~/.claude-mem-lite/runtime/.auto-adopt-*`. Managed via
+// `claude-mem-lite adopt --disable` / `--enable`. silentAutoAdopt checks it
+// at entry and skips WITHOUT writing the runtime marker, so toggling
+// `--enable` re-arms auto-adopt on the next SessionStart.
+const DISABLE_SENTINEL_BASENAME = '.mem-no-auto-adopt';
+
+export function disableSentinelPath(memdir) {
+  return join(memdir, DISABLE_SENTINEL_BASENAME);
+}
+
+export function isAutoAdoptDisabled(memdir) {
+  return existsSync(disableSentinelPath(memdir));
+}
+
 /**
  * cmdAdopt — write sentinel section + plugin doc to memdir.
  * Exit code 1 on any hard failure; skipped (--all + UserEditedError) doesn't
@@ -56,6 +74,8 @@ function hasFlag(args, flag) { return Array.isArray(args) && args.includes(flag)
  */
 export function cmdAdopt(args = []) {
   if (hasFlag(args, '--status')) return statusAll();
+  if (hasFlag(args, '--disable')) return cmdDisable(args);
+  if (hasFlag(args, '--enable')) return cmdEnable(args);
 
   const all = hasFlag(args, '--all');
   const force = hasFlag(args, '--force');
@@ -122,14 +142,18 @@ function adoptOne(memdir, { force, dryRun, all }) {
 }
 
 /**
- * silentAutoAdopt — plugin-mode first-run auto-adopt helper (v2.33.0).
+ * silentAutoAdopt — plugin-mode first-run auto-adopt helper (v2.33.0+).
  *
  * Preconditions (caller must gate): CLAUDE_PLUGIN_ROOT set, MEM_NO_AUTO_ADOPT!=1,
- * MEM_QUIET_HOOKS!=1, first-attempt marker absent. This helper does NOT re-check
- * those — it only does the write + marker persistence.
+ * first-attempt marker absent. This helper does NOT re-check those — it only
+ * does the write + marker persistence. (v2.82.0: dropped MEM_QUIET_HOOKS gate;
+ * quiet is a stdout control, not a side-effect control.)
  *
  * Behavior:
- *   - Writes plugin sentinel + detail doc to the memdir for `cwd`.
+ *   - If `<memdir>/.mem-no-auto-adopt` exists: skip silently, do NOT write the
+ *     runtime marker. This keeps `--enable` re-armable: deleting the disable
+ *     sentinel lets the next SessionStart try again.
+ *   - Else: writes plugin sentinel + detail doc to the memdir for `cwd`.
  *   - Writes a per-project first-attempt marker under `markerDir` so a later
  *     `/unadopt` is respected (no re-adopt loop).
  *   - Silent: never logs, never throws. Returns structured result.
@@ -139,6 +163,9 @@ function adoptOne(memdir, { force, dryRun, all }) {
 export function silentAutoAdopt({ cwd, markerDir, markerKey }) {
   const memdir = memdirPath(cwd);
   try {
+    if (isAutoAdoptDisabled(memdir)) {
+      return { ok: true, action: 'disabled', reason: 'disabled-by-sentinel' };
+    }
     if (isAdopted(memdir, PLUGIN_SLUG)) {
       writeMarker(markerDir, markerKey);
       return { ok: true, action: 'already-adopted' };
@@ -173,20 +200,110 @@ export function hasAutoAdoptMarker(markerDir, markerKey) {
   return existsSync(join(markerDir, `.auto-adopt-${markerKey}`));
 }
 
+/**
+ * cmdDisable — `claude-mem-lite adopt --disable [--all]`.
+ *
+ * Writes `<memdir>/.mem-no-auto-adopt` so SessionStart auto-adopt skips this
+ * project permanently. Idempotent: re-running on an already-disabled memdir is
+ * a no-op. Does NOT remove an existing sentinel — pair with `unadopt` if you
+ * want both. The two operations are deliberately separate:
+ *   - `unadopt`      = "remove the contract now"
+ *   - `adopt --disable` = "and don't auto-write it back"
+ */
+function cmdDisable(args) {
+  const all = hasFlag(args, '--all');
+  const targets = all
+    ? listAllMemdirs().map((m) => m.memdir)
+    : [memdirPath(detectCwd())];
+
+  if (targets.length === 0) {
+    log('[adopt --disable] no memdirs found');
+    return;
+  }
+
+  let disabled = 0, already = 0;
+  for (const memdir of targets) {
+    if (!existsSync(memdir)) mkdirSync(memdir, { recursive: true });
+    const path = disableSentinelPath(memdir);
+    if (existsSync(path)) {
+      log(`[adopt --disable] ${memdir} → already-disabled`);
+      already++;
+      continue;
+    }
+    writeFileSync(path, JSON.stringify({ disabledAt: new Date().toISOString() }) + '\n');
+    log(`[adopt --disable] ${memdir} → disabled`);
+    disabled++;
+  }
+
+  log('');
+  log(`[adopt --disable] ${targets.length} target(s): ${disabled} newly disabled, ${already} already disabled`);
+}
+
+/**
+ * cmdEnable — `claude-mem-lite adopt --enable [--all]`.
+ *
+ * Removes the `<memdir>/.mem-no-auto-adopt` sentinel so the next SessionStart
+ * can auto-adopt again. Idempotent. Does NOT trigger an immediate adoption —
+ * run plain `claude-mem-lite adopt` if you want that now.
+ */
+function cmdEnable(args) {
+  const all = hasFlag(args, '--all');
+  const targets = all
+    ? listAllMemdirs().map((m) => m.memdir)
+    : [memdirPath(detectCwd())];
+
+  if (targets.length === 0) {
+    log('[adopt --enable] no memdirs found');
+    return;
+  }
+
+  let enabled = 0, absent = 0;
+  for (const memdir of targets) {
+    const path = disableSentinelPath(memdir);
+    if (!existsSync(path)) {
+      log(`[adopt --enable] ${memdir} → absent`);
+      absent++;
+      continue;
+    }
+    try { unlinkSync(path); } catch { /* best-effort */ }
+    log(`[adopt --enable] ${memdir} → enabled`);
+    enabled++;
+  }
+
+  log('');
+  log(`[adopt --enable] ${targets.length} target(s): ${enabled} re-enabled, ${absent} not-disabled`);
+}
+
 function statusAll() {
   const dirs = listAllMemdirs();
   log('[adopt --status] scanning ~/.claude/projects/*/memory/');
   if (dirs.length === 0) { log('  (no memdirs found)'); return; }
-  let adopted = 0;
+  let adopted = 0, disabled = 0;
   for (const { projectSlug, memdir } of dirs) {
-    if (isAdopted(memdir, PLUGIN_SLUG)) {
+    const isAdoptedHere = isAdopted(memdir, PLUGIN_SLUG);
+    const isDisabledHere = isAutoAdoptDisabled(memdir);
+    if (isAdoptedHere) {
       const idx = readMemoryIndex(memdir, PLUGIN_SLUG);
-      log(`  ✓ ${projectSlug} (${idx.version})`);
+      const suffix = isDisabledHere ? ' [auto-adopt disabled]' : '';
+      log(`  ✓ ${projectSlug} (${idx.version})${suffix}`);
       adopted++;
+      if (isDisabledHere) disabled++;
+    } else if (isDisabledHere) {
+      log(`  ✗ ${projectSlug} (auto-adopt disabled, no sentinel)`);
+      disabled++;
     }
   }
   log('');
-  log(`[adopt --status] ${adopted}/${dirs.length} adopted`);
+  log(`[adopt --status] ${adopted}/${dirs.length} adopted${disabled > 0 ? `, ${disabled} disabled` : ''}`);
+
+  // Gating snapshot — helps debug "why didn't auto-adopt fire?"
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ? 'set' : 'unset';
+  const noAutoAdopt = process.env.MEM_NO_AUTO_ADOPT === '1' ? '1 (opt-out)' : 'unset';
+  log('');
+  log('Auto-adopt gates (next SessionStart will fire only if both pass):');
+  log(`  CLAUDE_PLUGIN_ROOT  = ${pluginRoot}  (plugin-mode install required; npx stays opt-in)`);
+  log(`  MEM_NO_AUTO_ADOPT   = ${noAutoAdopt}  (global escape hatch)`);
+  log('Per-project opt-out: `claude-mem-lite adopt --disable` (run --enable to re-arm).');
 }
 
 /**

package/hook.mjs

@@ -61,6 +61,7 @@ import { checkForUpdate } from './hook-update.mjs';
 import { handleLLMOptimize } from './hook-optimize.mjs';
 import { silentAutoAdopt, hasAutoAdoptMarker } from './adopt-cli.mjs';
 import { emitV270UpgradeBanner } from './lib/upgrade-banner.mjs';
+import { loadCiteBackForEpisode } from './lib/cite-back-hint.mjs';
 // plugin-cache-guard.mjs loaded dynamically — pre-2.31.2 installs that auto-upgraded
 // from an older hook-update.mjs SOURCE_FILES (which did not list this module) would
 // crash on static import. Degrade gracefully to no-op when the module is absent.
@@ -196,6 +197,12 @@ function flushEpisode(episode, hookEventName = 'PostToolUse') {
           const filesHint = uniqueFiles.length > 0 ? ` (${uniqueFiles.join(', ')})` : '';
           lines.push(`[mem] 💡 error→fix pattern${filesHint} — consider: mem_save(type="bugfix", lesson_learned="<root cause + fix>")`);
         }
+        // v2.81: cite-back hint — fires when this episode edits a file that
+        // PreToolUse:Read/Edit nudged earlier in the same session. Precision
+        // signal (we know the file was warned about); orthogonal to the
+        // error→fix pattern above and may co-fire.
+        const citeBack = loadCiteBackForEpisode(episode, RUNTIME_DIR);
+        if (citeBack) lines.push(citeBack);
         process.stdout.write(JSON.stringify({
           suppressOutput: true,
           hookSpecificOutput: {
@@ -645,22 +652,27 @@ async function handleSessionStart() {
     }
   } catch (e) { debugCatch(e, 'session-start-cache-heal'); }
 
-  // v2.33.0: plugin-mode first-run auto-adopt. /plugin install IS consent to
-  // integration — writing the MEMORY.md sentinel once per project on first
-  // SessionStart avoids the opt-in friction. Scope is narrow:
-  //   - gated by CLAUDE_PLUGIN_ROOT (npm/npx installs stay opt-in)
-  //   - gated by !MEM_NO_AUTO_ADOPT (explicit escape hatch)
-  //   - gated by !MEM_QUIET_HOOKS (quiet = no side-effects semantics)
+  // First-run auto-adopt (v2.33.0 plugin-mode → v2.82.1 install-mode-agnostic).
+  // ANY install path — `/plugin install`, `npm install -g`, `npx`, manual — is
+  // consent to integration. Writing the MEMORY.md sentinel once per project on
+  // first SessionStart avoids the opt-in friction that left ~zero users on
+  // auto-adopt (runtime-marker directory was empty machine-wide despite v2.33
+  // shipping ~5 weeks earlier — `install.mjs`-written hooks don't propagate
+  // ${CLAUDE_PLUGIN_ROOT}, so the v2.33.0 gate was a no-op for npm/manual
+  // installs, which is most of them). Scope is now:
+  //   - gated by !MEM_NO_AUTO_ADOPT (explicit global escape hatch)
+  //   - per-project opt-out via `<memdir>/.mem-no-auto-adopt` sentinel
+  //     (managed by `claude-mem-lite adopt --disable / --enable`); checked
+  //     inside silentAutoAdopt so the helper is safe to call directly too.
   //   - first-attempt marker persists in RUNTIME_DIR so a subsequent /unadopt
   //     is respected (no re-adopt loop).
+  // Note v2.82.0: removed MEM_QUIET_HOOKS gate. That env var suppresses stdout
+  // noise; it must NOT also disable side-effect work (PostToolUse writes the
+  // DB unconditionally — auto-adopt should follow the same rule).
   // Failures (user-edited sentinel, budget exceeded, FS errors) are swallowed;
   // the marker is still written so we don't retry on every SessionStart.
   try {
-    if (
-      process.env.CLAUDE_PLUGIN_ROOT
-      && process.env.MEM_NO_AUTO_ADOPT !== '1'
-      && process.env.MEM_QUIET_HOOKS !== '1'
-    ) {
+    if (process.env.MEM_NO_AUTO_ADOPT !== '1') {
       const project = inferProject();
       if (!hasAutoAdoptMarker(RUNTIME_DIR, project)) {
         const cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();

package/lib/cite-back-hint.mjs

@@ -0,0 +1,70 @@
+// claude-mem-lite: PostToolUse cite-back hint builder.
+//
+// Fires when a flushed episode edits a file that PreToolUse:Read/Edit had
+// nudged earlier in the same session — the canonical "you fixed something we
+// warned about, save the lesson?" moment.
+//
+// Pure function: takes an episode + the session-scoped pre-recall cooldown
+// object and returns a hint string (or null). Cooldown I/O lives elsewhere so
+// this stays unit-testable without disk fixtures.
+//
+// Cooldown schema (post-v2.81): { "<path>": { ts: <number>, lessonIds: [#NN, ...] } }
+// Legacy schema   (pre-v2.81):  { "<path>": <number> } — tolerated, never emits.
+
+import { basename, join } from 'path';
+import { readFileSync } from 'fs';
+import { EDIT_TOOLS } from '../utils.mjs';
+
+const MAX_FILES = 2;
+
+export function buildCiteBackHint(episode, cooldown) {
+  if (!episode || !cooldown) return null;
+  const entries = episode.entries;
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+
+  const seen = new Set();
+  const matches = [];
+  for (const e of entries) {
+    if (!EDIT_TOOLS.has(e.tool)) continue;
+    for (const file of e.files || []) {
+      if (seen.has(file)) continue;
+      const entry = cooldown[file];
+      if (!entry || typeof entry !== 'object') continue;
+      const ids = Array.isArray(entry.lessonIds) ? entry.lessonIds : null;
+      if (!ids || ids.length === 0) continue;
+      seen.add(file);
+      matches.push({ file, ids });
+      if (matches.length >= MAX_FILES) break;
+    }
+    if (matches.length >= MAX_FILES) break;
+  }
+
+  if (matches.length === 0) return null;
+
+  const lines = ['[mem] 💡 Cite-back: you edited file(s) that received PreToolUse lessons this session.'];
+  for (const m of matches) {
+    const fname = basename(m.file);
+    const idList = m.ids.map(id => `#${id}`).join(', ');
+    lines.push(`  • ${fname} ← ${idList} — if you fixed it: /lesson --file ${fname} "<root cause + fix>"`);
+  }
+  return lines.join('\n');
+}
+
+// Path scheme MUST mirror scripts/pre-tool-recall.js cooldownPathFor() — drift
+// silently zeros cite-back across the release. Pinned by tests/cite-back-hint.test.mjs
+// 'sanitizes the sessionId the same way pre-tool-recall.js does'.
+function cooldownPathFor(sessionId, runtimeDir) {
+  const safe = String(sessionId).replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 64);
+  return join(runtimeDir, `pre-recall-cooldown-${safe}.json`);
+}
+
+export function loadCiteBackForEpisode(episode, runtimeDir) {
+  if (!episode || !episode.sessionId || !runtimeDir) return null;
+  let cooldown;
+  try {
+    cooldown = JSON.parse(readFileSync(cooldownPathFor(episode.sessionId, runtimeDir), 'utf8'));
+  } catch {
+    return null;
+  }
+  return buildCiteBackHint(episode, cooldown);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.80.1",
+  "version": "2.82.1",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -57,6 +57,7 @@
     "lib/low-signal-patterns.mjs",
     "lib/private-strip.mjs",
     "lib/citation-tracker.mjs",
+    "lib/cite-back-hint.mjs",
     "lib/summary-extractor.mjs",
     "lib/id-routing.mjs",
     "lib/err-sampler.mjs",

package/scripts/pre-tool-recall.js

@@ -49,6 +49,15 @@ function readCooldown(cooldownPath) {
   try { return JSON.parse(readFileSync(cooldownPath, 'utf8')); } catch { return {}; }
 }
 
+// v2.81: cooldown entries are {ts, lessonIds} objects so the PostToolUse
+// cite-back hint can name the lessons that were nudged. Legacy entries
+// (pre-v2.81) are bare numbers — entryTimestamp() reads both shapes.
+function entryTimestamp(v) {
+  if (typeof v === 'number') return v;
+  if (v && typeof v === 'object' && typeof v.ts === 'number') return v.ts;
+  return 0;
+}
+
 function writeCooldown(cooldownPath, data, isSessionScoped) {
   try {
     mkdirSync(RUNTIME_DIR, { recursive: true });
@@ -59,7 +68,8 @@ function writeCooldown(cooldownPath, data, isSessionScoped) {
     const cleaned = isSessionScoped ? data : {};
     if (!isSessionScoped) {
       for (const [k, v] of Object.entries(data)) {
-        if (now - v < STALE_MS) cleaned[k] = v;
+        const ts = entryTimestamp(v);
+        if (ts && now - ts < STALE_MS) cleaned[k] = v;
       }
     }
     writeFileSync(cooldownPath, JSON.stringify(cleaned));
@@ -124,7 +134,8 @@ try {
   if (isSessionScoped) {
     if (cooldown[filePath]) process.exit(0); // already recalled this file in-session
   } else {
-    if (cooldown[filePath] && (now - cooldown[filePath]) < COOLDOWN_MS) process.exit(0);
+    const ts = entryTimestamp(cooldown[filePath]);
+    if (ts && (now - ts) < COOLDOWN_MS) process.exit(0);
   }
 
   // Open DB readonly
@@ -275,7 +286,10 @@ try {
     // Cooldown applies on ALL branches (including silent-Read) so subsequent
     // calls on the same file in the same session don't re-query — preserving
     // the per-filePath invariant that underpins Read→Edit dedup.
-    cooldown[filePath] = now;
+    // v2.81: record the emitted lesson IDs so flushEpisode (hook.mjs) can
+    // build the PostToolUse cite-back hint when the user actually edits the
+    // file. Empty array on no-lesson branches keeps the schema uniform.
+    cooldown[filePath] = { ts: now, lessonIds: allRows.map(r => r.id) };
     writeCooldown(cooldownPath, cooldown, isSessionScoped);
   } catch (e) {
     // Silent failure — never block editing, but record for self-observation.

package/source-files.mjs

@@ -40,6 +40,7 @@ export const SOURCE_FILES = [
   'lib/low-signal-patterns.mjs',
   'lib/private-strip.mjs',
   'lib/citation-tracker.mjs',
+  'lib/cite-back-hint.mjs',
   'lib/summary-extractor.mjs',
   'lib/id-routing.mjs',
   'lib/err-sampler.mjs',