claude-mem-lite 3.70.2 → 3.72.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.70.2",
+      "version": "3.72.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.70.2",
+  "version": "3.72.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/cli/activity.mjs

@@ -10,6 +10,7 @@
 
 import { inferProject } from '../utils.mjs';
 import { resolveProject } from '../project-utils.mjs';
+import { resolveCliProject as cliProject } from '../lib/cli-project.mjs';
 import { parseArgs, out, fail, rejectBareStringFlags } from './common.mjs';
 import { parseIntFlag, isNumericToken } from '../lib/cli-flags.mjs';
 
@@ -28,7 +29,13 @@ export async function cmdActivity(db, args) {
   const { positional, flags } = parseArgs(args.slice(1));
   const { saveEvent, searchEvents, recentEvents, getEvent, EVENT_TYPES, promoteInsightEvents } = await import('../lib/activity.mjs');
   const VALID_EVENT_TYPES = new Set(EVENT_TYPES);
-  const project = flags.project ? resolveProject(db, flags.project) : inferProject();
+  // `save` CREATES a row, so it keeps plain inferProject(): the DB-aware fallback is a read
+  // affordance, and applying it to a write absorbs a not-yet-born subproject's first event
+  // into the enclosing repo (pre-tag review, reproduced). Every other subcommand reads or
+  // operates on rows that already exist, where falling back is what finds them.
+  const project = flags.project
+    ? resolveProject(db, flags.project)
+    : (sub === 'save' ? inferProject() : cliProject(db));
 
   if (sub === 'save') {
     // Reject value-less string flags before they reach saveEvent as a boolean `true`

package/cli/doctor.mjs

@@ -5,13 +5,13 @@
 // for install health checks). With --benchmark or --metrics it is routed to
 // mem-cli which delegates to this handler.
 
-import { inferProject } from '../utils.mjs';
+import { resolveCliProject as cliProject } from '../lib/cli-project.mjs';
 import { out } from './common.mjs';
 
 export async function cmdDoctor(db, args) {
   if (args.includes('--benchmark')) {
     const { runBenchmark } = await import('../lib/doctor-benchmark.mjs');
-    const project = inferProject();
+    const project = cliProject(db);
     // Sample recent user prompts so the CLI report has non-null injection_rate
     // and hook latency. Without this, runBenchmark's prompts default of [] makes
     // every metric 0/null — a dead command from the user's perspective. Tests

package/hook-precompact.mjs

@@ -21,19 +21,25 @@ import { recordKeyContextInjection } from './lib/keyctx-marker.mjs';
  * @param {string} [ctx.sessionId]
  * @returns {void}
  */
-export function handlePreCompact({ db, project, sessionId }) {
+export function handlePreCompact({ db, project, sessionId, runtimeDir = RUNTIME_DIR }) {
   try {
     const collector = {};
     const body = buildSessionContextLines(db, project, new Date(), sessionId || null, collector);
-    if (!body || String(body).trim() === '') return;
-    process.stdout.write(`<claude-mem-context>\n${body}\n</claude-mem-context>\n`);
-    // Same recorder as handleSessionStart: marker + injection_count bump (D#124).
-    // A re-render into a compacted context is a fresh injection of those rows.
+    const rendered = body && String(body).trim() !== '';
+    if (rendered) {
+      process.stdout.write(`<claude-mem-context>\n${body}\n</claude-mem-context>\n`);
+    }
+    // Recorded even when NOTHING was re-rendered, matching handleSessionStart — the two
+    // callers must describe the same set (keyctx-marker.mjs header), and the marker is an
+    // exclude-set for what is actually in context. The old empty-body early return left the
+    // PREVIOUS render's ids standing while compaction removed the block they described, so
+    // <memory-context> went on suppressing rows that were no longer shown: D#123 review C-1
+    // exactly, on the twin leg. An empty render means an empty exclude-set, not a stale one.
     recordKeyContextInjection(db, {
-      runtimeDir: RUNTIME_DIR,
+      runtimeDir,
       project,
       sessionId: sessionId || null,
-      ids: collector.keyContextIds || [],
+      ids: rendered ? (collector.keyContextIds || []) : [],
     });
   } catch (e) {
     debugCatch(e, 'handlePreCompact');

package/hook.mjs

@@ -48,7 +48,7 @@ import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObse
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { formatHookError } from './lib/native-binding-hint.mjs';
 import { recordHookError } from './lib/hook-telemetry.mjs';
-import { queueHookContext, flushHookStdout } from './lib/hook-stdout.mjs';
+import { queueHookContext, queueHookSystemMessage, flushHookStdout } from './lib/hook-stdout.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
 import { cleanupBroken, decayAndMarkIdle, boostAccessed, selectFuzzyDedupeIds, hardDeleteCandidateCount, purgeStale, recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans } from './lib/maintain-core.mjs';
 import { snapshotDb } from './lib/db-backup.mjs';
@@ -73,7 +73,7 @@ import { recordSkillAdoption, gcOldShadowShards } from './registry-recommend.mjs
 import { gcOldMetricShards, recordMetric } from './lib/metrics.mjs';
 import { detectMemOverride } from './lib/mem-override.mjs';
 import { injectedIdsFileName, keyContextIdsFileName } from './lib/injected-ids.mjs';
-import { recordKeyContextInjection } from './lib/keyctx-marker.mjs';
+import { recordKeyContextInjection, touchKeyContextMarker } from './lib/keyctx-marker.mjs';
 import { liveObsFilterSql, recencyDecaySql } from './lib/inject-search-core.mjs';
 import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection, pickHandoffToInject, extractUnfinishedSummary } from './hook-handoff.mjs';
 import { checkForUpdate, getCachedUpdateBanner, isUpdateCheckDue } from './hook-update.mjs';
@@ -1549,7 +1549,12 @@ async function handleSessionStart() {
     let updateCheckDue = false;
     try {
       const banner = getCachedUpdateBanner();
-      if (banner) stdoutParts.push(String(banner).trim());
+      // The human channel, not additionalContext: "vX available" is a notice for the
+      // USER. Folding it into additionalContext under suppressOutput:true kept its
+      // content and lost its audience. Claude Code renders a command hook's top-level
+      // systemMessage as its own hook_system_message, independent of the context
+      // block — see lib/hook-stdout.mjs for the bundle evidence.
+      if (banner) queueHookSystemMessage(String(banner));
       updateCheckDue = isUpdateCheckDue();
     } catch (e) { debugCatch(e, 'session-start-update'); }
 
@@ -1755,6 +1760,11 @@ async function handleUserPrompt() {
         if (Array.isArray(ids) && !(session && ccSessionId && session !== ccSessionId)) {
           keyContextIds.push(...ids);
         }
+        // The marker's validity is session-lifetime but gcStalePreRecallCooldowns sweeps it
+        // by AGE. Stamping it on read makes that sweep mean "24h with no prompt in this
+        // session" instead of "24h since the render" — otherwise a session running past a
+        // day loses its own exclude-set and re-injects what Key Context is still showing.
+        touchKeyContextMarker({ runtimeDir: RUNTIME_DIR, project, sessionId: ccSessionId });
       } catch { /* no marker — nothing was injected, exclude nothing */ }
       const pathAInjectedIds = [];
 

package/install.mjs

@@ -1852,6 +1852,44 @@ async function doctor() {
     dwarn('Dev drift: check failed — ' + e.message);
   }
 
+  // Hook scripts: the check above grades SOURCE_FILES, which holds zero `scripts/` entries.
+  // Hook scripts ship from the separate HOOK_SCRIPT_FILES manifest into
+  // ~/.claude-mem-lite/scripts/, and every settings.json hook command names one of those
+  // absolute paths — so "the tarball shipped without scripts/" (source-files.mjs:243) killed
+  // every hook while doctor printed an all-clear. Both classes are issues here; see
+  // checkHookScriptDrift for why the managed-files demote branch must not be copied over.
+  try {
+    // Same gate as the managed-files check: a plugin-only install never deploys into
+    // ~/.claude-mem-lite, and its hooks run from ${CLAUDE_PLUGIN_ROOT}/scripts/ instead.
+    const skipScripts = !shape.managed && !!shape.activePluginVersion;
+    const { checkHookScriptDrift, HOOK_SCRIPT_ENTRY_POINTS } = await import('./lib/doctor-drift.mjs');
+    const h = skipScripts ? null : checkHookScriptDrift(INSTALL_DIR, HOOK_SCRIPT_FILES);
+    const scriptRemedy = `claude-mem-lite self-update (or: node ${join(INSTALL_DIR, 'install.mjs')} repair)`;
+    if (skipScripts) {
+      ok('Hook scripts: n/a (plugin-only install — hooks run from the plugin cache)');
+    } else if (!h.present) {
+      warn(`Hook scripts: ${join(INSTALL_DIR, 'scripts')} `
+        + `${h.dirSymlink ? 'is a dangling symlink' : 'is absent'} — all ${HOOK_SCRIPT_ENTRY_POINTS.size} hook `
+        + `commands name absolute paths under it, so no hook can fire. Fix: ${scriptRemedy}`);
+      issues++;
+    } else if (h.missingCount > 0) {
+      const parts = [];
+      if (h.missingEntryFiles.length > 0) {
+        parts.push(`${h.missingEntryFiles.length} hook entry (${h.missingEntryFiles.join(', ')}) — the command cannot start`);
+      }
+      if (h.missingModuleFiles.length > 0) {
+        parts.push(`${h.missingModuleFiles.length} imported helper (${h.missingModuleFiles.join(', ')}) — ERR_MODULE_NOT_FOUND at hook time`);
+      }
+      warn(`Hook scripts: ${h.missingCount} missing — ${parts.join('; ')}. Fix: ${scriptRemedy}`);
+      issues++;
+    } else {
+      ok(`Hook scripts: ${HOOK_SCRIPT_FILES.length} present `
+        + `(${h.dirSymlink ? 'dev — scripts/ symlinked to the repo' : 'copy install'})`);
+    }
+  } catch (e) {
+    dwarn('Hook scripts: check failed — ' + e.message);
+  }
+
   // Stale temp files
   try {
     // hook-update + the episode workers write runtime/ + staging under DB_DIR

package/lib/cli-project.mjs

@@ -0,0 +1,125 @@
+// lib/cli-project.mjs — which project a terminal-invoked CLI command should read.
+//
+// `inferProject()` names the directory the process stands in (CLAUDE_PROJECT_DIR || PWD ||
+// cwd). Inside a hook that is always the session root, because Claude Code sets
+// CLAUDE_PROJECT_DIR. In a bare terminal it is not set, so the name follows the user:
+// `cd src/auth && claude-mem-lite recent` asks for `src--auth`, which holds nothing, while
+// the session's hooks have been writing `projects--mem`. The command answers "No recent
+// observations" about a project full of them.
+//
+// Anchoring on the git work-tree root instead was tried and reverted before shipping (see
+// project-utils.mjs): Claude Code started in `mono/packages/api` sets CLAUDE_PROJECT_DIR to
+// the PACKAGE dir, so hooks write `packages--api` while a git anchor sends the CLI to
+// `mono--monorepo` — the same split, mirrored. No purely path-derived rule separates the two
+// cases, because the difference is which name the hooks actually chose. The DB knows.
+//
+// So: compute both candidates, prefer whichever already holds rows, cwd winning ties.
+//
+// READ COMMANDS ONLY. The tie rule ("can only redirect when the cwd-derived name holds
+// NOTHING") reads like a universal safety argument, and pre-tag review reproduced why it is
+// not: for a read, "cwd holds nothing" means there is nothing to lose; for a WRITE it is the
+// normal precondition of a project about to be born. Applying the fallback to save /
+// defer add / restore / import-jsonl absorbed a fresh package dir's first rows into the
+// enclosing repo, and once the session's hooks later wrote `packages--api`, those rows were
+// unreachable from the directory they were written in. Write paths keep plain
+// inferProject(); callers in mem-cli.mjs and cli/activity.mjs mark which is which.
+//
+// Lives here, not in project-utils.mjs: that module is DB-free and on the hook hot path, and
+// hook-side resolution must stay byte-identical (hooks already have the right answer).
+
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join, resolve } from 'path';
+// inferProject through the utils.mjs barrel ON PURPOSE, not projectNameFromDir directly:
+// "what does this process call its project" must keep exactly ONE definition, so anything
+// that later changes it (a config file, a new env var) moves both faces together instead of
+// letting this module drift into a second answer. It is also the seam mem-cli's own tests
+// stub, and a resolver that bypassed it would quietly stop resolving what they exercise.
+import { inferProject } from '../utils.mjs';
+import { projectNameFromDir } from '../project-utils.mjs';
+
+// Bounded so a pathological path (symlink loop, very deep tree) cannot spin. 64 levels is
+// far past any real repo checkout; the loop also stops when dirname() reaches a fixed point.
+const MAX_WALK_DEPTH = 64;
+
+/**
+ * Nearest enclosing git work-tree root, or null.
+ *
+ * Checks for a `.git` ENTRY, not a directory: a linked worktree and a submodule both put a
+ * `.git` FILE at their root, and both are work-tree roots for this purpose.
+ *
+ * @param {string} startDir
+ * @returns {string|null}
+ */
+export function findGitRoot(startDir) {
+  let dir = resolve(startDir);
+  for (let i = 0; i < MAX_WALK_DEPTH; i++) {
+    if (existsSync(join(dir, '.git'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;   // filesystem root
+    dir = parent;
+  }
+  return null;
+}
+
+// Memoized per process: every CLI command resolves once, but a single command can ask
+// several times (search resolves for the query, the reranker and the tier window).
+let _cache = new Map();
+
+/** Reset the per-process memo (for tests). */
+export function _resetCliProjectCache() { _cache = new Map(); }
+
+// Ordered cheapest-signal-last. Each is a distinct way a directory can already BE a project:
+//   sdk_sessions   — hook.mjs inserts a row on the first SessionStart, long before any
+//                    observation exists. Without it, a package dir Claude Code had been
+//                    running in all morning still read as "holds nothing" and the fallback
+//                    fired on a directory that was already its own project (pre-tag review).
+//   deferred_work  — `defer add` in a fresh repo writes no observation either.
+//   observations   — the common case.
+const ROW_PROBES = [
+  'SELECT 1 FROM observations WHERE project = ? LIMIT 1',
+  'SELECT 1 FROM sdk_sessions WHERE project = ? LIMIT 1',
+  'SELECT 1 FROM deferred_work WHERE project = ? LIMIT 1',
+];
+
+function hasRows(db, project) {
+  for (const sql of ROW_PROBES) {
+    if (db.prepare(sql).get(project)) return true;
+  }
+  return false;
+}
+
+/**
+ * The project a CLI command should target when the user gave no --project.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {{dir?: string}} [opts] `dir` overrides the directory to resolve from (tests).
+ * @returns {string} Canonical project name
+ */
+export function resolveCliProject(db, { dir, homeDir = homedir() } = {}) {
+  const base = dir || process.env.CLAUDE_PROJECT_DIR || process.env.PWD || process.cwd();
+  // `dir` is a test seam for pointing the walk at a fixture; the real path asks inferProject.
+  const cwdName = dir ? projectNameFromDir(dir) : inferProject();
+  if (_cache.has(base)) return _cache.get(base);
+  let chosen = cwdName;
+  try {
+    const root = findGitRoot(base);
+    // A dotfiles repo at ~/.git puts EVERY directory under home in one work tree, which
+    // would make an unrelated scratch dir resolve to the home project. Home is a container,
+    // not a project — unless the user is standing in it, in which case it is the ordinary
+    // case and the candidates coincide anyway.
+    const rootName = root && !(root === resolve(homeDir) && resolve(base) !== resolve(homeDir))
+      ? projectNameFromDir(root)
+      : null;
+    // Only the case where cwd holds nothing can move the answer — see the tie rule above.
+    if (rootName && rootName !== cwdName && !hasRows(db, cwdName) && hasRows(db, rootName)) {
+      chosen = rootName;
+    }
+  } catch {
+    // Resolution runs before every command; a probe that throws (locked DB, a table an older
+    // schema lacks) must degrade to today's behaviour, never take the command down.
+    chosen = cwdName;
+  }
+  _cache.set(base, chosen);
+  return chosen;
+}

package/lib/doctor-drift.mjs

@@ -19,13 +19,12 @@ import { join } from 'path';
 // dead weight there — while an absent ENTRY POINT is fatal in every shape, because the
 // command names that path directly.
 //
-// Scope note (pre-tag review): this classifies only what the CALLER passes in, and
-// install.mjs passes SOURCE_FILES, which holds zero `scripts/` entries — hook scripts are
-// installed from the separate HOOK_SCRIPT_FILES manifest. An earlier draft mapped those
-// into this set; it could never match a single path, so it is gone rather than left as
-// inert code implying coverage it does not have. Extending doctor to check the hook-script
-// manifest is real work with its own fixture, and is tracked as deferred rather than
-// implied here.
+// Scope note: this classifies only what the CALLER passes in, and install.mjs passes
+// SOURCE_FILES, which holds zero `scripts/` entries — hook scripts are installed from the
+// separate HOOK_SCRIPT_FILES manifest. An earlier draft mapped those into this set; it
+// could never match a single path, so it was removed rather than left as inert code
+// implying coverage it did not have. The hook-script manifest now has its own check with
+// its own severity rules: `checkHookScriptDrift` below.
 const ENTRY_POINTS = new Set([
   'cli.mjs', 'mem-cli.mjs', 'server.mjs', 'hook.mjs', 'install.mjs',
 ]);
@@ -72,3 +71,64 @@ export function checkDevDrift(installDir, sourceFiles) {
     details: plainFiles.slice(0, 5),
   };
 }
+
+// Hook scripts a hook COMMAND LINE names directly — install.mjs's settings.json template
+// and hooks/hooks.json both spell these paths out. Absent ⇒ the command cannot start.
+// `prompt-search-utils.mjs` is deliberately absent from this set: nothing invokes it, it is
+// imported by user-prompt-search.js. The split drives the message, not the severity — see
+// checkHookScriptDrift.
+//
+// Exported so the set is not a second hand-maintained copy of the hook wiring that can go
+// stale in silence: tests/doctor-hook-script-manifest.test.mjs re-derives it from the
+// `command` strings in hooks/hooks.json and asserts equality, so registering a new hook
+// script without classifying it here goes red.
+export const HOOK_SCRIPT_ENTRY_POINTS = new Set([
+  'post-tool-use.sh', 'user-prompt-search.js', 'pre-tool-recall.js',
+  'post-tool-recall.js', 'pre-skill-bridge.js', 'pre-agent-inject.js',
+  'hook-launcher.mjs',
+]);
+
+/**
+ * Integrity of the HOOK_SCRIPT_FILES manifest under `<installDir>/scripts/`.
+ *
+ * Separate from checkDevDrift because the two manifests install in different SHAPES, and
+ * #10686's rule — grade by which path RESOLVES the file — lands differently for each:
+ *
+ *   • dev install: install.mjs symlinks the whole `scripts/` DIRECTORY (one link), not each
+ *     file. So per-file lstat sees plain files through the link, and "plain file among
+ *     symlinks = drift" — the signal checkDevDrift is built on — does not exist here at all.
+ *     Applying it would flag every healthy dev install with 8 phantom drifts. What a missing
+ *     file means instead: the install dir IS the repo dir, so it is missing from the repo.
+ *   • copy install: an entry script is named by a command line (dead hook if absent), and
+ *     user-prompt-search.js resolves `./prompt-search-utils.mjs` against the install dir
+ *     (ERR_MODULE_NOT_FOUND on every user prompt if absent).
+ *
+ * Both classes are therefore fatal in both shapes. The entry/module split is kept for the
+ * MESSAGE — telling the reader which consequence they have — and must NOT be re-used to
+ * demote the module class the way the managed-files check legitimately does.
+ *
+ * `present:false` covers a scripts/ dir that was never created AND a dangling symlink:
+ * existsSync follows links, and the hook commands resolve through it to the same nothing.
+ *
+ * @param {string} installDir
+ * @param {string[]} hookScriptFiles HOOK_SCRIPT_FILES manifest
+ */
+export function checkHookScriptDrift(installDir, hookScriptFiles) {
+  const scriptsDir = join(installDir, 'scripts');
+  let dirSymlink = false;
+  try { dirSymlink = lstatSync(scriptsDir).isSymbolicLink(); } catch { /* absent — handled below */ }
+  const classify = (missing) => ({
+    missingCount: missing.length,
+    missingEntryFiles: missing.filter((n) => HOOK_SCRIPT_ENTRY_POINTS.has(n)),
+    missingModuleFiles: missing.filter((n) => !HOOK_SCRIPT_ENTRY_POINTS.has(n)),
+  });
+  if (!existsSync(scriptsDir)) {
+    const all = classify([...hookScriptFiles]);
+    return { present: false, dirSymlink, ...all };
+  }
+  const missing = [];
+  for (const name of hookScriptFiles) {
+    if (!existsSync(join(scriptsDir, name))) missing.push(name);
+  }
+  return { present: true, dirSymlink, ...classify(missing) };
+}

package/lib/hook-stdout.mjs

@@ -26,15 +26,17 @@
 
 let parts = [];
 let queuedEvent = null;
+let systemParts = [];
 
 /**
  * Queue a contribution to this process's single stdout envelope.
  *
  * @param {string} hookEventName Event name for hookSpecificOutput.
  * @param {string} text additionalContext contribution; empty/blank is ignored.
+ * @param {{warn?: (msg: string) => void}} [deps]
  * @returns {void}
  */
-export function queueHookContext(hookEventName, text) {
+export function queueHookContext(hookEventName, text, deps = {}) {
   if (!hookEventName) return;
   const body = String(text ?? '').trim();
   if (!body) return;
@@ -42,11 +44,46 @@ export function queueHookContext(hookEventName, text) {
   // hookSpecificOutput.hookEventName does not match the event it dispatched.
   // In practice one process serves one event; keep the first and drop the
   // stragglers rather than emit an envelope the host rejects outright.
-  if (queuedEvent && queuedEvent !== hookEventName) return;
+  //
+  // The drop is NOISY on purpose. It is unreachable today (all call sites are
+  // event-consistent), but flushEpisode's hookEventName DEFAULTS to 'PostToolUse',
+  // so a future caller that omits the argument would both mis-tag its receipt and
+  // have it swallowed without a trace. Silently vanishing work is this repo's
+  // most-repeated defect class; stderr is safe here because the host never parses it
+  // as the envelope.
+  if (queuedEvent && queuedEvent !== hookEventName) {
+    const warn = deps.warn || ((m) => { try { process.stderr.write(m); } catch { /* never block on a warning */ } });
+    warn(`[claude-mem-lite] hook-stdout: dropped a ${hookEventName} contribution — this process `
+      + `already queued ${queuedEvent}, and one envelope carries exactly one hookEventName. `
+      + 'This is a wiring bug: the contribution is lost.\n');
+    return;
+  }
   queuedEvent = hookEventName;
   parts.push(body);
 }
 
+/**
+ * Queue a line for the HUMAN, not the model.
+ *
+ * Claude Code renders a command hook's top-level `systemMessage` as its own
+ * `hook_system_message` conversation message, independently of
+ * `hookSpecificOutput.additionalContext` — verified in the 2.1.234 bundle
+ * (`if (G.systemMessage) { … yield { message: yc({ type: "hook_system_message", … }) } }`)
+ * and documented there as "Display a message to the user (all hooks)". One envelope
+ * can therefore carry context for the model AND a notice for the user.
+ *
+ * Needed because v3.70.0's merge folded the update banner into additionalContext with
+ * `suppressOutput: true`, which kept its content and lost its audience.
+ *
+ * @param {string} text Notice for the user; empty/blank is ignored.
+ * @returns {void}
+ */
+export function queueHookSystemMessage(text) {
+  const body = String(text ?? '').trim();
+  if (!body) return;
+  systemParts.push(body);
+}
+
 /**
  * Write the queued contributions as one envelope. Idempotent: a second call
  * with nothing queued writes nothing, so calling it from both the dispatcher
@@ -56,18 +93,25 @@ export function queueHookContext(hookEventName, text) {
  * @returns {boolean} true when an envelope was written.
  */
 export function flushHookStdout(deps = {}) {
-  if (!queuedEvent || parts.length === 0) return false;
+  const hasContext = queuedEvent && parts.length > 0;
+  const hasSystem = systemParts.length > 0;
+  if (!hasContext && !hasSystem) return false;
   const write = deps.write || ((s) => process.stdout.write(s));
-  const payload = JSON.stringify({
-    suppressOutput: true,
-    hookSpecificOutput: {
+  const envelope = { suppressOutput: true };
+  if (hasSystem) envelope.systemMessage = systemParts.join('\n');
+  // Omitted entirely when there is no model-facing context: Stop's schema REJECTS a
+  // hookSpecificOutput block, and an envelope carrying only a user notice must not
+  // invent an event name to hang one on.
+  if (hasContext) {
+    envelope.hookSpecificOutput = {
       hookEventName: queuedEvent,
       additionalContext: parts.join('\n\n'),
-    },
-  }) + '\n';
+    };
+  }
   parts = [];
   queuedEvent = null;
-  write(payload);
+  systemParts = [];
+  write(JSON.stringify(envelope) + '\n');
   return true;
 }
 
@@ -75,9 +119,10 @@ export function flushHookStdout(deps = {}) {
 export function resetHookStdout() {
   parts = [];
   queuedEvent = null;
+  systemParts = [];
 }
 
 /** Test seam: what is queued right now. */
 export function peekHookStdout() {
-  return { hookEventName: queuedEvent, parts: [...parts] };
+  return { hookEventName: queuedEvent, parts: [...parts], systemParts: [...systemParts] };
 }

package/lib/keyctx-marker.mjs

@@ -18,11 +18,19 @@
 // Never throws: a marker-write failure must not break context delivery, and it
 // must not cost the metering either — the bump runs first.
 
-import { writeFileSync } from 'fs';
+import { writeFileSync, statSync, utimesSync } from 'fs';
 import { join } from 'path';
 import { debugCatch } from '../utils.mjs';
 import { keyContextIdsFileName } from './injected-ids.mjs';
 
+/**
+ * How stale the marker's stamp must be before a read refreshes it.
+ *
+ * The reader runs on every user prompt, so an unconditional touch would be one write per
+ * prompt for no gain. One hour is far below the 24h sweep and far above prompt cadence.
+ */
+export const KEYCTX_TOUCH_AFTER_MS = 60 * 60 * 1000;
+
 /**
  * Record one Key Context render: bump the rendered rows, then persist the id
  * list for the prompt-time exclude-set and the citation extractor.
@@ -72,3 +80,37 @@ export function recordKeyContextInjection(db, { runtimeDir, project, sessionId =
 
   return { bumped, written };
 }
+
+/**
+ * Refresh an existing marker's mtime so the 24h sweep in hook.mjs measures time since the
+ * session last USED it rather than time since the render.
+ *
+ * The marker's validity is session-lifetime (injected-ids.mjs), but its GC is age-based, on
+ * the policy borrowed from the cooldown / injected-ids markers — whose semantics genuinely
+ * ARE time-windowed. A session that outlives 24h therefore had its own exclude-set deleted
+ * mid-session, after which handleUserPrompt re-injects rows the Key Context block is still
+ * showing. Keying the sweep on session liveness instead does not work: hook.mjs marks any
+ * session older than STALE_SESSION_MS 'abandoned' by started_at_epoch, so the long session
+ * reads as dead there too. Still being read is the signal that separates the two.
+ *
+ * Only refreshes an EXISTING file: a missing marker means "nothing was injected, exclude
+ * nothing", and fabricating an empty one would invent an exclude-set for a session whose
+ * block may well be on screen. Never throws — it runs in the user-prompt hot path.
+ *
+ * @param {{runtimeDir: string, project: string, sessionId?: string|null}} ctx
+ * @param {number} [nowMs] injectable clock
+ * @returns {boolean} true when the stamp was moved
+ */
+export function touchKeyContextMarker({ runtimeDir, project, sessionId = null } = {}, nowMs = Date.now()) {
+  if (!runtimeDir || !project) return false;
+  try {
+    const p = join(runtimeDir, keyContextIdsFileName(project, sessionId));
+    if (nowMs - statSync(p).mtimeMs <= KEYCTX_TOUCH_AFTER_MS) return false;
+    const stamp = new Date(nowMs);
+    utimesSync(p, stamp, stamp);
+    return true;
+  } catch (e) {
+    debugCatch(e, 'keyctx-marker-touch');
+    return false;
+  }
+}

package/mem-cli.mjs

@@ -6,6 +6,14 @@ import { homedir } from 'os';
 import { ensureDbWithWalRecovery, DB_PATH, DB_DIR, REGISTRY_DB_PATH } from './schema.mjs';
 import { truncate, typeIcon, inferProject, scrubSecrets, COMPRESSED_PENDING_PURGE } from './utils.mjs';
 import { resolveProject } from './project-utils.mjs';
+// READ commands resolve the project DB-aware: a subdirectory whose own name holds no rows
+// falls back to the enclosing work-tree root, so `cd src/auth && … recent` reads what the
+// session's hooks wrote. WRITE commands (save / defer add / restore / import-jsonl) keep
+// plain inferProject() — pre-tag review reproduced the reason: for a read, "cwd holds
+// nothing" means there is nothing to lose, but for a write it is the normal precondition of
+// a project about to be born, and absorbing it into the enclosing repo strands the row once
+// the session's hooks start writing the subdirectory's own name. Hook-side is untouched.
+import { resolveCliProject as cliProject } from './lib/cli-project.mjs';
 import { _resetVocabCache, vecTextForRow, vectorsEnabled } from './tfidf.mjs';
 import { reRankWithContext } from './search-scoring.mjs';
 import { searchObservationsHybrid } from './search-engine.mjs';
@@ -174,7 +182,7 @@ async function cmdSearch(db, args, { llm } = {}) {
   const emitDeferredTrailer = () => {
     if (!wantDeferredTrailer) return;
     try {
-      const rows = searchDeferredWork(db, query, project || inferProject());
+      const rows = searchDeferredWork(db, query, project || cliProject(db));
       for (const line of formatDeferredSearchTrailer(rows, 'claude-mem-lite get D#<id>')) out(line);
     } catch { /* trailer is best-effort; never break search */ }
   };
@@ -236,7 +244,7 @@ async function cmdSearch(db, args, { llm } = {}) {
 
   const res = await coreRunSearchPipeline(
     {
-      db, currentProject: project ? null : inferProject(), env: process.env,
+      db, currentProject: project ? null : cliProject(db), env: process.env,
       searchObservationsHybrid, deepSearch, shouldEscalateToDeep, autoDeepLlmReady,
       reRankWithContext, llm,
     },
@@ -249,11 +257,11 @@ async function cmdSearch(db, args, { llm } = {}) {
       obsTypeFallback: false,            // #8217 removed list-by-type fallback from the CLI
       crossSourceEpochSortNoFts: false,  // CLI never reaches cross-source with empty ftsQuery (fails earlier)
       rerankPolicy: 'cli',               // re-rank/supersede on any obs; re-sort gated on cross-source
-      rerankProject: project || inferProject(),
+      rerankProject: project || cliProject(db),
       recentListingNoFts: false,
       tolerateMissingFts: true,          // pre-FTS legacy DBs: swallow session/prompt FTS errors
       tierPosition: 'early',             // tier filter inside the obs block (before sessions/prompts)
-      tierProject: project || inferProject(),
+      tierProject: project || cliProject(db),
     }
   );
   const isDeep = res.isDeep;
@@ -404,7 +412,7 @@ function cmdRecent(db, args) {
   const limit = isValid
     ? rawLimit
     : parseIntFlag(flags.limit, { name: '--limit', defaultValue: 10, max: RECENT_MAX });
-  const project = flags.project ? resolveProject(db, flags.project) : inferProject();
+  const project = flags.project ? resolveProject(db, flags.project) : cliProject(db);
   const jsonOutput = flags.json === true || flags.json === 'true';
 
   // `recent --type bugfix` previously parsed as a silent no-op — users naturally
@@ -1061,7 +1069,7 @@ function cmdDeferAdd(db, args) {
 
 function cmdDeferList(db, args) {
   const { flags } = parseArgs(args);
-  const project = flags.project ? resolveProject(db, flags.project) : inferProject();
+  const project = flags.project ? resolveProject(db, flags.project) : cliProject(db);
   const limit = parseIntFlag(flags.limit, { name: '--limit', defaultValue: 10, max: 100 });
   const list = listOpenWithOrdinal(db, project, limit);
   if (list.length === 0) {
@@ -1100,7 +1108,7 @@ function cmdDeferDrop(db, args) {
   // without N shell invocations.
   const rawTokens = idStr.split(',').map(s => s.trim()).filter(Boolean);
   const tokens = rawTokens.map(t => /^\d+$/.test(t) ? parseInt(t, 10) : t);
-  const project = flags.project ? resolveProject(db, flags.project) : inferProject();
+  const project = flags.project ? resolveProject(db, flags.project) : cliProject(db);
 
   let realIds;
   try {
@@ -1329,7 +1337,7 @@ function cmdContext(db, args) {
   // Generate context live from DB — same builder the SessionStart hook uses.
   // Pre-v2.30 this command parsed a snapshot out of CLAUDE.md, but the hook no
   // longer writes there; DB is now the single source of truth.
-  const project = flags.project ? resolveProject(db, flags.project) : inferProject();
+  const project = flags.project ? resolveProject(db, flags.project) : cliProject(db);
   const block = buildSessionContextLines(db, project).trim();
 
   if (!block) {
@@ -1369,7 +1377,7 @@ function cmdContext(db, args) {
 
 function cmdBrowse(db, args) {
   const { flags } = parseArgs(args);
-  const project = flags.project ? resolveProject(db, flags.project) : inferProject();
+  const project = flags.project ? resolveProject(db, flags.project) : cliProject(db);
   const tierFilter = flags.tier || null;
   if (tierFilter && !['working', 'active', 'archive'].includes(tierFilter)) {
     fail(`[mem] Invalid tier: "${tierFilter}". Use: working, active, or archive`);
@@ -2783,7 +2791,7 @@ Commands:
                         (aliases: backfill search_aliases on substantive rows that
                          lack them — incl. lesson-bearing manual saves — adds ONLY
                          aliases, never rewrites title/narrative/lesson)
-    --project P         Limit to a single project (.|current = inferProject())
+    --project P         Limit to a single project (.|current = the current project)
     --verbose / -v      Preview also dumps cluster contents + re-enrich samples
 
   doctor                Environment diagnostics and benchmarks
@@ -3130,12 +3138,12 @@ async function cmdOptimize(db, args) {
   }
   // --project <name> filters all 4 tasks to one project. Opt-in; absence
   // preserves prior cross-project default. `.` or `current` auto-resolve via
-  // inferProject() so users don't need to remember the exact name.
+  // the CLI project resolver so users don't need to remember the exact name.
   const projectIdx = args.indexOf('--project');
   let project;
   if (projectIdx >= 0 && args[projectIdx + 1]) {
     const raw = args[projectIdx + 1];
-    project = (raw === '.' || raw === 'current') ? inferProject() : raw;
+    project = (raw === '.' || raw === 'current') ? cliProject(db) : raw;
   }
 
   if (!run && !runAll) {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.70.2",
+  "version": "3.72.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.70.2",
+      "version": "3.72.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.26.0",
         "better-sqlite3": "^12.6.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.70.2",
+  "version": "3.72.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",
@@ -57,6 +57,7 @@
     "lib/startup-dashboard.mjs",
     "lib/doctor-benchmark.mjs",
     "lib/doctor-drift.mjs",
+    "lib/cli-project.mjs",
     "lib/stats-quality.mjs",
     "lib/low-signal-patterns.mjs",
     "lib/private-strip.mjs",

package/project-utils.mjs

@@ -29,7 +29,22 @@ const _cache = new Map();
  * @returns {string} Sanitized project identifier safe for use in filenames
  */
 export function inferProject() {
-  const p = process.env.CLAUDE_PROJECT_DIR || process.env.PWD || process.cwd();
+  return projectNameFromDir(process.env.CLAUDE_PROJECT_DIR || process.env.PWD || process.cwd());
+}
+
+/**
+ * The naming rule alone, applied to an arbitrary directory: "parent--basename", sanitized.
+ *
+ * Split out of inferProject() so lib/cli-project.mjs can build its second candidate (the git
+ * work-tree root) with THIS rule rather than a copy of it — two copies of the rule would let
+ * the CLI face and the hook face drift apart on the next sanitization change, which is the
+ * exact class of bug this module's candidate-selection exists to close. Still DB-free and
+ * allocation-cheap, so the hook hot path is unaffected.
+ *
+ * @param {string} p Absolute directory path
+ * @returns {string} Sanitized project identifier safe for use in filenames
+ */
+export function projectNameFromDir(p) {
   const base = basename(p);
   const parent = basename(dirname(p));
   const raw = parent && parent !== '.' && parent !== '/' ? `${parent}--${base}` : base;

package/scripts/binding-probe-cli.mjs

@@ -32,6 +32,15 @@ const ROOT = process.env.PROBE_ROOT || join(dirname(fileURLToPath(import.meta.ur
 // broken flag, and a helperless broken tree is repaired by the hook-launcher
 // path instead. Out of process like every other probe here — loading a stale
 // .node caches a dead module handle for the rest of THIS process.
+// Output-identical twin of lib/binding-probe.mjs::flattenBindingError, kept here
+// because bareProbe runs when lib/ could not be imported. Same 240 cap, same
+// ellipsis, same 'unknown' floor — asserted for parity by the tests.
+function flattenLocal(err, max = 240) {
+  const s = String(err ?? '').replace(/\s+/g, ' ').trim();
+  if (!s) return 'unknown';
+  return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+
 function bareProbe(root) {
   const script =
     'try {'
@@ -49,11 +58,23 @@ function bareProbe(root) {
   //
   // Flattening is inlined, NOT lib/binding-probe.mjs::flattenBindingError, because
   // this function is the fallback for a tree where lib/ failed to import — `helpers`
-  // is still null on every path that reaches here. Duplicated deliberately; keep the
-  // two in step.
-  const why = String(r.stdout || '').replace(/\s+/g, ' ').trim().slice(0, 240)
-    || (r.error && r.error.message)
-    || `probe exited ${r.status ?? `on signal ${r.signal}`}`;
+  // is still null on every path that reaches here.
+  //
+  // The twin must stay byte-identical in OUTPUT, and it did not: the first draft
+  // capped with a bare `.slice(0, 240)` while the shared helper appends an ellipsis,
+  // so they already disagreed at the one boundary the duplication exists to protect.
+  // A comment is not a guard, and this repo's hand-maintained twins have drifted
+  // before. tests/binding-error-diagnosis.test.mjs now drives THIS path in a
+  // lib/-less tree and asserts parity with the shared helper.
+  // Order matters: flattenLocal floors to the string 'unknown', which is truthy, so
+  // `flattenLocal(x) || fallback` would make the fallbacks unreachable and swallow a
+  // spawn error or an exit code whenever the child printed nothing. Pick the source
+  // FIRST, then flatten it.
+  const printed = String(r.stdout || '').trim();
+  const spawnErr = r.error && r.error.message;
+  const why = printed ? flattenLocal(printed)
+    : spawnErr ? flattenLocal(spawnErr)
+      : `probe exited ${r.status ?? `on signal ${r.signal}`}`;
   process.stderr.write(`[claude-mem-lite] binding probe: ${why}\n`);
   return false;
 }

package/scripts/launch.mjs

@@ -20,9 +20,32 @@ if (!existsSync(join(ROOT, 'node_modules', 'better-sqlite3'))) {
     });
     process.stderr.write('[claude-mem-lite] Dependencies installed\n');
   } catch (e) {
-    // Plugin-cache / multi-user / disk-full installs can fail here. Without this
-    // catch the user sees a Node stack trace; with it they get an actionable line.
-    const detail = e.message?.split('\n')[0] || e.code || 'unknown error';
+    // Plugin-cache / multi-user / disk-full installs can fail here, and this is not a
+    // rare path: Claude Code materializes each new plugin-cache version WITHOUT
+    // node_modules, so the guard above opens on the first MCP launch after every
+    // plugin update. Without this catch the user sees a Node stack trace.
+    //
+    // `.split('\n')[0]` is CORRECT here, unlike the four binding-error sites fixed in
+    // v3.70.2, and the difference is the `stdio` above: stderr is **inherit**, so
+    // npm's own diagnosis (`npm error code EROFS`, `path …`, `rofs EROFS: read-only
+    // file system …`) has already streamed straight to the user's terminal by the time
+    // we get here — verified by running this file against an unwritable ROOT. With
+    // stderr inherited, execSync's `e.message` holds only "Command failed: <cmd>";
+    // there is no captured diagnosis to lose. Do NOT "fix" this by piping stderr to
+    // recover it: piping is what made a compiling better-sqlite3 look hung under the
+    // 5-min bash timeout (bug audit 2026-05), which is why stderr is inherited.
+    //
+    // A pre-tag review measured `e.message` under `stdio: 'pipe'`, where stderr IS
+    // folded into the message, and concluded this line drops the diagnosis. It does
+    // not — the stdio differs. Recorded here because the same wrong conclusion is
+    // easy to reach from the code alone.
+    //
+    // `e.status` not `e.code`: execSync failures carry the exit status on `status`,
+    // so the old `|| e.code` rung was dead.
+    const detail = e?.message?.split('\n')[0]
+      || (e?.status != null ? `npm exited ${e.status}` : '')
+      || (e?.signal ? `npm killed by ${e.signal}` : '')
+      || 'unknown error';
     process.stderr.write(`[claude-mem-lite] npm install failed in ${ROOT} — ${detail}\n`);
     process.stderr.write(`[claude-mem-lite] Likely cause: read-only directory, disk full, or network blocked.\n`);
     process.stderr.write(`[claude-mem-lite] Repair: cd "${ROOT}" && npm install --omit=dev\n`);

package/source-files.mjs

@@ -45,6 +45,10 @@ export const SOURCE_FILES = [
   'lib/startup-dashboard.mjs',
   'lib/doctor-benchmark.mjs',
   'lib/doctor-drift.mjs',
+  // DB-aware project pick for terminal-invoked CLI commands. Statically imported by
+  // mem-cli.mjs, cli/activity.mjs and cli/doctor.mjs — ship it or every CLI command
+  // throws ERR_MODULE_NOT_FOUND in installed/tarball runtimes.
+  'lib/cli-project.mjs',
   'lib/stats-quality.mjs',
   'lib/low-signal-patterns.mjs',
   'lib/private-strip.mjs',