claude-mem-lite 3.92.0 → 3.93.1

package/lib/hook-stdin.mjs

@@ -0,0 +1,140 @@
+// lib/hook-stdin.mjs — one bounded stdin reader for every hook entry point.
+//
+// Audit 2026-09-02 P1-9. Six hook processes read the host's JSON payload off stdin and they
+// did it six ways, in two groups:
+//
+//   BOUNDED, three different calibers: hook.mjs (3 s / 256 KB / `{text, truncated}`),
+//   scripts/user-prompt-search.js (2 s / 64 KB / bare string), scripts/pre-agent-inject.js
+//   (1.5 s / 262144 / never rejects).
+//
+//   UNBOUNDED, three copies of `for await (const chunk of process.stdin) input += chunk`:
+//   pre-tool-recall.js, pre-skill-bridge.js, post-tool-recall.js. No cap and no timeout.
+//   That matters most on `PreToolUse:Write`, whose `tool_input.content` is the ENTIRE file
+//   being written: writing a multi-megabyte file made pre-tool-recall buffer all of it and
+//   `JSON.parse` all of it, to read `file_path`. The only bound was the host's own 3 s
+//   fail-open — i.e. the hook silently did nothing, which is indistinguishable from the
+//   hook having nothing to say.
+//
+// ZERO DEPENDENCIES, deliberately: the importers are latency-sensitive hook processes whose
+// whole cost is module loading, and one of them (`pre-agent-inject.js`) exists to be the
+// cheap default-off path. Nothing here imports from the repo.
+//
+// The calibers are NOT unified. Each caller passes its own, because those numbers are
+// decisions about different payloads — a user prompt is not a tool response — and quietly
+// giving one caller another's limits is a behaviour change wearing a refactor's clothes.
+// What is shared is the mechanism: cap, timer, teardown, and the guarantee that the promise
+// settles exactly once.
+
+/** Default cap: matches the host's own full-payload tier. */
+export const DEFAULT_STDIN_MAX_BYTES = 256 * 1024;
+/**
+ * Cap for a payload that carries a WHOLE FILE: `PreToolUse`/`PostToolUse` on `Write` puts the
+ * entire file being written in `tool_input.content`. Exported and named rather than typed at
+ * each call site because two entry points see that same payload class, and two hand-written
+ * numbers for one class is the drift shape this module exists to remove — this is NOT the
+ * calibers being unified, which the note above rules out: a caller with a different payload
+ * class still passes its own.
+ *
+ * Sized as a MEMORY backstop, not a functional gate. The v3.93.0 pre-tag review measured the
+ * 256 KB default silently dropping `pretool` recall for any Write over that size, on the
+ * reasoning that a truncated payload matched what the host's 3 s fail-open already did —
+ * `JSON.parse` is 2.99 ms at 5 MB and 10.8 ms at 10 MB, so it did not.
+ */
+export const TOOL_INPUT_FILE_MAX_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Recover the scalar fields a hook needs from a TRUNCATED JSON payload prefix.
+ *
+ * Mirrors `hook.mjs handlePostToolUse`'s salvage of `tool_name`. Returns null when the
+ * prefix does not carry a `file_path` — the caller then behaves exactly as it did before
+ * salvage existed, so this can only add recalls, never remove one.
+ *
+ * Lives here rather than in the one script that calls it because it is about a payload this
+ * module bounded: the cap and the recovery from the cap are one decision, and a helper that
+ * only the truncating module's caller can reach is a helper nothing can unit-test.
+ *
+ * Deliberately regex over the prefix rather than a streaming parser: the fields are flat
+ * string scalars, and a partial-JSON parser is a dependency and a failure mode for a path
+ * whose entire budget is the host's fail-open window.
+ *
+ * @param {string} prefix Truncated payload text.
+ * @returns {{filePath: string, sessionId: string|null, toolName: string|null} | null}
+ */
+export function salvageTruncatedHookEvent(prefix) {
+  // Bounded capture. Unbounded, an 8 MB prefix whose `file_path` string is never closed
+  // makes V8 exceed its regexp backtrack limit and THROW RangeError — measured at the cap by
+  // the v3.93.0 post-release review. The throw escapes the caller's catch into its top-level
+  // one, which still exits 0 but writes a `pre-recall:top` telemetry row: the same
+  // hook-error noise the caller split `pre-recall:json` away from. 4096 is far above any
+  // real path (PATH_MAX is 4096 on Linux, 1024 on macOS), so no reachable payload is lost.
+  const fp = prefix.match(/"file_path"\s*:\s*"((?:[^"\\]|\\.){0,4096})"/);
+  if (!fp) return null;
+  let filePath;
+  // The captured group is still JSON-escaped (Windows paths arrive as `C:\\x`).
+  try { filePath = JSON.parse(`"${fp[1]}"`); } catch { return null; }
+  if (!filePath) return null;
+  const sid = prefix.match(/"session_id"\s*:\s*"([^"\\]*)"/);
+  const tn = prefix.match(/"tool_name"\s*:\s*"([^"\\]*)"/);
+  return { filePath, sessionId: sid ? sid[1] : null, toolName: tn ? tn[1] : null };
+}
+
+
+/** Default timeout: under the host's ~3 s fail-open, so we decide rather than get killed. */
+export const DEFAULT_STDIN_TIMEOUT_MS = 3000;
+
+/**
+ * Read the hook payload from a stream, bounded in both bytes and time.
+ *
+ * @param {object}  [opts]
+ * @param {number}  [opts.timeoutMs]  Give up after this long.
+ * @param {number}  [opts.maxBytes]   Stop reading past this many characters.
+ * @param {boolean} [opts.rejectOnTimeout=false]  `true` reproduces hook.mjs's contract, where
+ *   a timeout drops the event rather than acting on a partial payload. `false` resolves with
+ *   whatever arrived and `timedOut: true` — the right call for a path that is advisory and
+ *   must never throw into a host hook.
+ * @param {NodeJS.ReadableStream} [opts.stream=process.stdin]  Injectable for tests; nothing
+ *   else about this module is observable without it.
+ * @returns {Promise<{text: string, truncated: boolean, timedOut: boolean}>}
+ */
+export function readHookStdin({
+  timeoutMs = DEFAULT_STDIN_TIMEOUT_MS,
+  maxBytes = DEFAULT_STDIN_MAX_BYTES,
+  rejectOnTimeout = false,
+  stream = process.stdin,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    // Every path below routes through settle(), and settle() is a no-op after the first
+    // call. The hand-written copies each had to get this right on four separate paths
+    // (cap hit, end, error, timer) and the `.destroy()` in the cap branch can itself emit
+    // 'error' — so "resolve twice" and "resolve then reject" were both reachable shapes.
+    let done = false;
+    const settle = (fn, arg) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try { stream.destroy(); } catch { /* already gone */ }
+      fn(arg);
+    };
+
+    const timer = setTimeout(() => {
+      if (rejectOnTimeout) settle(reject, new Error('timeout'));
+      else settle(resolve, { text: data, truncated: false, timedOut: true });
+    }, timeoutMs);
+
+    try {
+      stream.setEncoding('utf8');
+      stream.on('data', (chunk) => {
+        data += chunk;
+        if (data.length > maxBytes) {
+          settle(resolve, { text: data.slice(0, maxBytes), truncated: true, timedOut: false });
+        }
+      });
+      stream.on('end', () => settle(resolve, { text: data, truncated: false, timedOut: false }));
+      stream.on('error', (err) => settle(reject, err));
+      stream.resume();
+    } catch (err) {
+      settle(reject, err);
+    }
+  });
+}

package/lib/plugin-key.mjs

@@ -0,0 +1,44 @@
+// lib/plugin-key.mjs — the plugin's identity in Claude Code's settings, and the one
+// predicate that reads it.
+//
+// Audit 2026-09-02 P2-7. `PLUGIN_KEY` and `isPluginExplicitlyDisabled` shipped twice in JS —
+// `hook.mjs` (which exits 0 on every event when the plugin is off) and `install.mjs` (which
+// reports it in `doctor`/`status` and branches on it during cleanup) — plus a third,
+// deliberate copy in `scripts/post-tool-use.sh`.
+//
+// What makes the duplication load-bearing rather than untidy: `install.mjs` writes hooks
+// DIRECTLY into `~/.claude/settings.json`, so turning the plugin off in the Claude UI does
+// not remove them. They keep firing, and this predicate is the only thing that makes
+// "disabled" mean disabled. A key that drifts on one side leaves the user with a plugin they
+// switched off and a hook set that never noticed.
+//
+// ZERO DEPENDENCIES: `hook.mjs` imports this at module scope on the hottest path in the
+// system, and the check runs before anything else can.
+//
+// The shell copy in `scripts/post-tool-use.sh` STAYS a copy and is not a defect. That path
+// is the ~5 ms bash pre-filter whose entire purpose is never reaching `node`, so it cannot
+// import anything; its own header documents the parity requirement and
+// `tests/post-tool-use-disabled.test.mjs` pins it. Two homes with a tested bridge is a
+// different thing from two homes and a comment.
+
+/** Marketplace this plugin is published under. */
+export const MARKETPLACE_KEY = 'sdsrss';
+
+/** The key Claude Code writes under `enabledPlugins` in `~/.claude/settings.json`. */
+export const PLUGIN_KEY = `claude-mem-lite@${MARKETPLACE_KEY}`;
+
+/**
+ * Whether the user has EXPLICITLY switched the plugin off.
+ *
+ * Strict `=== false`, not falsiness: an absent key means "never installed via the
+ * marketplace" (an npm-only install, which must keep working) and `true` means enabled.
+ * Only an explicit `false` is a decision to honour — treating absent as disabled would
+ * silently kill every direct-install user.
+ *
+ * @param {object|null|undefined} settings  Parsed ~/.claude/settings.json, or nullish when
+ *   it is missing or unreadable — which reads as NOT disabled, so an unparseable settings
+ *   file fails open rather than disabling the plugin the user is trying to use.
+ */
+export function isPluginExplicitlyDisabled(settings) {
+  return settings?.enabledPlugins?.[PLUGIN_KEY] === false;
+}

package/lib/registry-core.mjs

@@ -208,3 +208,51 @@ export async function enrichNamedResource(db, name, { confineTo, enrichResource,
   const { status, error } = await enrichResourceRow(db, row, { confineTo, enrichResource, env });
   return { status, name: row.name, error };
 }
+
+/**
+ * How a registry search hit should be invoked, and the path worth showing for it.
+ *
+ * Audit 2026-09-02 P2-6: this ran to ~15 lines in `mem-cli.mjs cmdRegistry` and again in
+ * `server.mjs mem_registry`, and the copies had already diverged on `portablePath`:
+ *
+ *   MCP   `isManaged ? toPortable(local_path) : ''`
+ *   CLI   `isManaged && local_path.startsWith(home) ? '~'+… : (local_path || '')`
+ *
+ * For a NON-managed resource the CLI therefore printed `Path: /home/<user>/…` — an absolute
+ * path, un-tilde'd, for a row whose `Use:` line is `Skill("x")` or `mem_use(name=…)` and
+ * never mentions the path at all. MCP printed nothing. The MCP behaviour is the one kept:
+ * the line carried no action for the reader and spelled out a home directory to do it.
+ *
+ * Returns DATA, not a rendered line. The two faces genuinely differ in dialect — the CLI
+ * indents four spaces and prints through `out()`, MCP indents two and emits Markdown bold —
+ * and collapsing that would replace a real duplicate with a formatting flag.
+ *
+ * @param {{name:string,type:string,local_path?:string,invocation_name?:string}} r
+ * @param {{home:string, managedPrefix:string}} ctx  `managedPrefix` is `<dataDir>/managed/`,
+ *   already including the trailing separator, so the caller owns CLAUDE_MEM_DIR resolution.
+ * @returns {{isManaged:boolean, portablePath:string, howToUse:string}}
+ */
+export function resourceUseHint(r, { home, managedPrefix }) {
+  const isManaged = Boolean(r.local_path && r.local_path.includes(managedPrefix));
+  const portablePath = isManaged
+    ? (r.local_path.startsWith(home) ? '~' + r.local_path.slice(home.length) : r.local_path)
+    : '';
+  const agentArg = r.type === 'agent' ? ', type="agent"' : '';
+
+  let howToUse;
+  if (isManaged) {
+    // Managed: Read(path) or mem_use — Skill() does not resolve managed resources.
+    // Agents always carry a complete .md path; only skills can be a directory, which
+    // resolves to its SKILL.md.
+    const resolvedPath = portablePath.endsWith('.md') ? portablePath : `${portablePath}/SKILL.md`;
+    howToUse = `Read("${resolvedPath}") or mem_use(name="${r.name}"${agentArg})`;
+  } else if (r.invocation_name) {
+    // Native plugin/user resource: invoke by its full invocation name.
+    howToUse = r.type === 'skill'
+      ? `Skill("${r.invocation_name}")`
+      : `Agent(subagent_type="${r.invocation_name}")`;
+  } else {
+    howToUse = `mem_use(name="${r.name}"${agentArg})`;
+  }
+  return { isManaged, portablePath, howToUse };
+}

package/lib/resolve-data-dir.mjs

@@ -82,3 +82,71 @@ export function resolveDataDir(raw) {
   }
   return containInTests(raw);
 }
+
+/**
+ * The runtime directory: episode buffers, per-session markers, cooldowns, hook telemetry.
+ *
+ * Audit 2026-09-02 P1-14. `CLAUDE_MEM_RUNTIME_DIR` was honoured by exactly the five
+ * standalone hook scripts and `scripts/hook-launcher.mjs`, and IGNORED by `hook-shared.mjs`
+ * (which `hook.mjs`, `server.mjs`, `hook-context.mjs` and `hook-episode.mjs` all take it
+ * from) and by `hook-optimize.mjs`. So setting it did not relocate the runtime dir — it
+ * SPLIT it: the `fyi` and `pretool` faces wrote markers to the override while `ups` and
+ * `keyctx` read them from the real one. A harness pointing the system at an isolated
+ * runtime got a half-isolated one, silently, with no error and no empty directory to
+ * notice.
+ *
+ * The audit's own suggestion was to delete the variable from the five scripts. Measured
+ * before copying it: it is load-bearing in ten test files, in `hook-launcher.mjs`, and in
+ * `experiment/lib/arms.mjs`, which uses it to keep an experiment arm off the real state.
+ * Removing it would have cost all of that to fix a split that one shared resolver fixes.
+ * The defect was never that the knob exists — it is that the rule for reading it had eight
+ * hand-written homes and two modules that had never heard of it.
+ *
+ * WHAT BELONGS BEHIND THIS RESOLVER, AND WHAT DELIBERATELY DOES NOT. The v3.93.0 pre-tag
+ * review found the first cut of P1-14 half-applied — `scripts/user-prompt-search.js`
+ * resolved its RUNTIME_DIR here and then built its cross-hook marker from
+ * `join(DB_DIR, 'runtime')` anyway, so under the override the `fyi` face wrote the SHARED
+ * marker to one directory while `pretool` wrote it to another. Four subsystems were split
+ * that way (marker + skill cooldown, hook-error telemetry, the metrics sink and its GC, and
+ * the native-binding breakage marker, which is the self-heal trigger). The rule that
+ * resolved them, stated so the next sweep does not overshoot:
+ *
+ *   MOVES with the override — state a HOOK writes INTO THE RUNTIME DIR and another
+ *   component reads back: cross-hook injected-ids markers, skill/pre-recall cooldowns,
+ *   hook-error telemetry, the launcher's breakage/heal markers, the native-binding
+ *   breakage marker, `ep-flush-*` / `pending-*` buffers, the shadow-recommendation log.
+ *
+ *   STAYS under the data dir, for two DIFFERENT reasons — do not collapse them:
+ *     (a) state about the ONE REAL INSTALLATION — `install.lock`, `update-state.json`,
+ *         `swap-in-progress`, the `.update-staging-*` / `.update-backup-*` residue scan.
+ *         These must not follow a per-harness override: the lock exists to serialise
+ *         concurrent installers, and two installers pointed at different override
+ *         directories would each take their own lock and both proceed.
+ *     (b) state that was never under `runtime/` at all — `metrics/` is a SIBLING of it
+ *         (`lib/metrics.mjs` is `join(dbDir, 'metrics')`) and every caller passes the data
+ *         dir. A v3.93.0 draft of this list put it in the MOVES column, which is the one
+ *         error a reader following this docblock would act on: a sweep obeying it would
+ *         convert `recordMetric(DB_DIR, …)` to a runtime-relative path and re-open exactly
+ *         what that release closed. What was fixed there was `join(RUNTIME_DIR, '..')` —
+ *         an inverse derivation of the data dir that stopped equalling `DB_DIR` the moment
+ *         the override was honoured. Deriving one dir from the other is the defect; the
+ *         sink itself never moved.
+ *
+ * `tests/runtime-dir-single-home.test.mjs` sweeps for the defect FORM (a shipped module
+ * building `join(…, 'runtime')` itself) with the stays-put sites as a named allowlist, so
+ * moving one out of that list is a deliberate edit rather than an omission.
+ *
+ * @param {string} dataDir  An already-resolved data dir (from resolveDataDir).
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string} An absolute runtime directory.
+ */
+export function resolveRuntimeDir(dataDir, env = process.env) {
+  const raw = env.CLAUDE_MEM_RUNTIME_DIR;
+  // Same "falsy means default" rule as above. A relative override is NOT rejected the way
+  // CLAUDE_MEM_DIR is: this variable is set by test harnesses that predate that check, and
+  // turning a previously-working relative path into a throw would break isolation setups
+  // in order to enforce tidiness. It is resolved against cwd instead, so the value is at
+  // least absolute by the time anything writes to it.
+  if (raw === undefined || raw === null || raw === '') return join(dataDir, 'runtime'); // runtime-dir:stays-put — this IS the default branch of the rule
+  return isAbsolute(raw) ? raw : resolve(raw);
+}

package/mem-cli.mjs

@@ -4,6 +4,7 @@
 
 import { homedir } from 'os';
 import { ensureDbWithWalRecovery, DB_PATH, DB_DIR, REGISTRY_DB_PATH } from './schema.mjs';
+import { resolveRuntimeDir } from './lib/resolve-data-dir.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
@@ -17,11 +18,11 @@ 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';
-import { fetchObsDetail, fetchPromptDetail, fetchEventDetail, OBS_FIELDS, SESSION_DETAIL_FIELDS, PROMPT_DETAIL_FIELDS, EVENT_DETAIL_FIELDS, supersededNotice } from './lib/get-core.mjs';
+import { fetchObsDetail, fetchPromptDetail, fetchEventDetail, fetchSessionDetail, OBS_FIELDS, SESSION_DETAIL_FIELDS, PROMPT_DETAIL_FIELDS, EVENT_DETAIL_FIELDS, supersededNotice } from './lib/get-core.mjs';
 import { collectBrowseTiers, getActiveMemorySessionId, BROWSE_TIERS, BROWSE_TIER_LABELS } from './lib/browse-core.mjs';
 import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady } from './deep-search.mjs';
 import { ensureRegistryDb, collectRegistryStats, listResourcesRanked, formatRegistryListLine } from './registry.mjs';
-import { IMPORT_STRING_FIELDS, importResource, removeResource, reindexResources, enrichResourceRow, enrichImportedResources, enrichNamedResource, REGISTRY_CONFINE_ENV } from './lib/registry-core.mjs';
+import { IMPORT_STRING_FIELDS, importResource, removeResource, reindexResources, enrichResourceRow, enrichImportedResources, enrichNamedResource, REGISTRY_CONFINE_ENV, resourceUseHint } from './lib/registry-core.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { computeFunnel, formatFunnel, computeSweep, formatSweep, DEFAULT_SWEEP_FLOORS, DEFAULT_SWEEP_MARGINS } from './registry-recommend.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
@@ -56,7 +57,7 @@ import { CLI_PATH, CLI_INVOKE } from './cli-path.mjs';
 import { parseArgs, out, outVerbatim, fail, relativeTime, fmtDateShort, parseIdToken, formatProbeHints, rejectBareStringFlags, resolvePositionalAlias, suggestUnknownFlags, OBS_TIME_FIELDS, formatObsFieldValue, obsFieldLabel, formatPendingPurgeLine } from './cli/common.mjs';
 import { saveObservation, saveWithClosures, formatSupersedeSkipped, formatSupersededNote } from './lib/save-observation.mjs';
 import { normalizeScope, insertObservationVector, applyObsUpdate } from './lib/observation-write.mjs';
-import { EXPORT_COLUMNS_SQL } from './lib/export-columns.mjs';
+import { EXPORT_COLUMNS_SQL, buildExportWhere } from './lib/export-columns.mjs';
 import { recallByFile } from './lib/recall-core.mjs';
 import { fetchRecent, RECENT_MAX } from './lib/recent-core.mjs';
 import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentTimeline, fetchTimelineWindow } from './lib/timeline-core.mjs';
@@ -561,8 +562,7 @@ function renderObsRows(db, ids, requestedFields) {
 }
 
 function renderSessionRows(db, ids) {
-  const placeholders = ids.map(() => '?').join(',');
-  const rows = db.prepare(`SELECT * FROM session_summaries WHERE id IN (${placeholders}) ORDER BY created_at_epoch ASC`).all(...ids);
+  const rows = fetchSessionDetail(db, ids);
   if (rows.length === 0) return null;
   const parts = [];
   for (const r of rows) {
@@ -1248,7 +1248,7 @@ async function cmdStats(db, args) {
   // recorded in the last 24h. Surfaces silent breakage (DB corruption,
   // CC upstream field rename) that would otherwise stay invisible — the
   // failure mode that left code-graph's matcher bug undetected for 10 sessions.
-  const hookErrors24h = countRecentHookErrors(join(DB_DIR, 'runtime'), now - DAY_MS);
+  const hookErrors24h = countRecentHookErrors(resolveRuntimeDir(DB_DIR), now - DAY_MS);
 
   // M-9 (audit 2026-08-14): disk footprint — a "lite" store had accumulated 360MB of
   // pre-maintain snapshots against a 59MB DB with nothing reporting it. Cheap probes
@@ -1326,7 +1326,7 @@ async function cmdStats(db, args) {
   out(`  Low-value (imp≤1, never used, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`);
   out(`  Low-signal titles (Modified/Error/Worked on…): ${lowSignalTitle.c} (${(lowSignalRatio * 100).toFixed(1)}%)`);
   out(`  Compressed: ${compressedCount.c}`);
-  out(`  Hook errors (last 24h): ${hookErrors24h}${hookErrors24h > 0 ? `  ← tail ${join(DB_DIR, 'runtime/hook-errors')}` : ''}`);
+  out(`  Hook errors (last 24h): ${hookErrors24h}${hookErrors24h > 0 ? `  ← tail ${join(resolveRuntimeDir(DB_DIR), 'hook-errors')}` : ''}`);
   // Hint threshold = the REAL eviction budget (pre-release review 2026-08-16: a
   // hardcoded 3×-DB heuristic promised an eviction that fires only past the budget).
   out(`  Disk: DB ${mb(dbBytes)}MB | ${snaps.length} backup snapshot(s) ${mb(backupBytes)}MB${backupBytes > backupBudgetBytes() ? `  ← over the ${mb(backupBudgetBytes())}MB backup budget; next maintain/save snapshot evicts oldest (>7d old)` : ''}`);
@@ -1654,42 +1654,37 @@ function cmdExport(db, args) {
   // script (`export --to "$END" > backup.json`) with an unset `$END` would silently
   // write an empty backup and report success. Reject like cmdSearch does.
   if (rejectBareStringFlags(flags, ['project', 'type', 'from', 'to'])) return;
-  const wheres = [];
-  const params = [];
-  // --include-compressed: include compressed observations (aligned with MCP mem_export).
-  // Superseded rows are excluded either way; the flag only toggles the compressed half
-  // of the live-row pair (backup/export of tombstones is opt-in, retractions are not).
-  if (flags['include-compressed'] === true || flags['include-compressed'] === 'true') {
-    wheres.push('superseded_at IS NULL');
-  } else {
-    wheres.push(liveObsFilterSql(''));
-  }
-
+  // PARSE + VALIDATE here; the SQL predicate itself comes from buildExportWhere (P2-5),
+  // shared with server.mjs runExport. The split is deliberate: the CLI `fail()`s with a
+  // usage message where the MCP tool throws, and only this face has a stderr channel for
+  // the inverted-range note below.
   const project = flags.project ? resolveProject(db, flags.project) : null;
-  if (project) { wheres.push('project = ?'); params.push(project); }
   if (flags.type) {
     // Reject unknown types — silently returning [] for `--type bogus` looked like a
     // legitimate empty filter result, hiding the typo. Mirrors cmdSearch / cmdSave / cmdUpdate.
-    const validObsTypes = OBS_TYPE_SET;
-    if (!validObsTypes.has(flags.type)) {
-      fail(`[mem] Invalid --type "${flags.type}". Valid: ${[...validObsTypes].join(', ')}`);
+    if (!OBS_TYPE_SET.has(flags.type)) {
+      fail(`[mem] Invalid --type "${flags.type}". Valid: ${[...OBS_TYPE_SET].join(', ')}`);
       return;
     }
-    wheres.push('type = ?'); params.push(flags.type);
   }
   let exportFromEpoch = null;
   let exportToEpoch = null;
   if (flags.from) {
     exportFromEpoch = new Date(flags.from).getTime();
     if (isNaN(exportFromEpoch)) { fail(`[mem] Invalid --from date: "${flags.from}". Use YYYY-MM-DD or ISO 8601.`); return; }
-    wheres.push('created_at_epoch >= ?'); params.push(exportFromEpoch);
   }
   if (flags.to) {
     exportToEpoch = new Date(flags.to).getTime();
     if (isNaN(exportToEpoch)) { fail(`[mem] Invalid --to date: "${flags.to}". Use YYYY-MM-DD or ISO 8601.`); return; }
     if (/^\d{4}-\d{2}-\d{2}$/.test(flags.to)) exportToEpoch += DAY_MS - 1;
-    wheres.push('created_at_epoch <= ?'); params.push(exportToEpoch);
   }
+  // --include-compressed: include compressed observations (aligned with MCP mem_export).
+  // Superseded rows are excluded either way; the flag only toggles the compressed half
+  // of the live-row pair (backup/export of tombstones is opt-in, retractions are not).
+  const { wheres, params } = buildExportWhere({
+    includeCompressed: flags['include-compressed'] === true || flags['include-compressed'] === 'true',
+    project, type: flags.type || null, fromEpoch: exportFromEpoch, toEpoch: exportToEpoch,
+  });
   if (exportFromEpoch !== null && exportToEpoch !== null && exportFromEpoch > exportToEpoch) {
     process.stderr.write(`[mem] Note: --from "${flags.from}" is after --to "${flags.to}"; this range is empty\n`);
   }
@@ -2211,19 +2206,8 @@ function cmdRegistry(_memDb, args) {
       for (const r of results) {
         const badge = r.quality_tier === 'installed' ? '[✓]' : r.quality_tier === 'verified' ? '[★]' : '[○]';
         const categoryLabel = r.category ? ` [${r.category}]` : '';
-        const isManaged = r.local_path && r.local_path.includes(join(DB_DIR, 'managed') + sep);
-        const portablePath = isManaged && r.local_path.startsWith(home) ? '~' + r.local_path.slice(home.length) : (r.local_path || '');
-        let howToUse;
-        if (isManaged) {
-          const resolvedPath = portablePath.endsWith('.md') ? portablePath : `${portablePath}/SKILL.md`;
-          howToUse = `Read("${resolvedPath}") or mem_use(name="${r.name}"${r.type === 'agent' ? ', type="agent"' : ''})`;
-        } else if (r.invocation_name) {
-          howToUse = r.type === 'skill'
-            ? `Skill("${r.invocation_name}")`
-            : `Agent(subagent_type="${r.invocation_name}")`;
-        } else {
-          howToUse = `mem_use(name="${r.name}"${r.type === 'agent' ? ', type="agent"' : ''})`;
-        }
+        // P2-6: the invocation rule is shared; only the four-space indent is this face's.
+        const { portablePath, howToUse } = resourceUseHint(r, { home, managedPrefix: join(DB_DIR, 'managed') + sep });
         const pathLine = portablePath ? `\n    Path: ${portablePath}` : '';
         out(`  ${badge} ${r.type === 'skill' ? 'S' : 'A'} ${r.name}${categoryLabel} — ${truncate(r.capability_summary || '', 80)}${pathLine}\n    Use: ${howToUse}`);
       }

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.92.0",
+  "version": "3.93.1",
   "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",
@@ -87,6 +87,8 @@
     "lib/lesson-bridge.mjs",
     "lib/binding-probe.mjs",
     "lib/install-shape.mjs",
+    "lib/hook-stdin.mjs",
+    "lib/plugin-key.mjs",
     "lib/hook-stdout.mjs",
     "lib/proc-lock.mjs",
     "lib/atomic-write.mjs",

package/registry-recommend.mjs

@@ -7,7 +7,7 @@
 // `off` skips all work.
 import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync, appendFileSync, readdirSync, unlinkSync } from 'fs';
 import { join } from 'path';
-import { resolveDataDir } from './lib/resolve-data-dir.mjs';
+import { resolveDataDir, resolveRuntimeDir } from './lib/resolve-data-dir.mjs';
 import { searchResources, cjkIntentTokens } from './registry-retriever.mjs';
 
 import { DAY_MS } from './lib/time-constants.mjs';
@@ -57,7 +57,7 @@ const RECO_COOLDOWN_MS = 300_000;        // 5 min, mirrors T4 SKILL_COOLDOWN_MS
 // DB_DIR formula) so tests sandbox via env without ESM-cache gymnastics, and prod reads
 // the same dir as the rest of the app.
 function recoRuntimeDir() {
-  return join(resolveDataDir(process.env.CLAUDE_MEM_DIR), 'runtime');
+  return resolveRuntimeDir(resolveDataDir(process.env.CLAUDE_MEM_DIR));
 }
 
 const TOKEN_SPLIT = /[^a-z0-9一-鿿]+/;

package/schema.mjs

@@ -152,7 +152,12 @@ export const CODE_DIR = join(homedir(), '.claude-mem-lite');
 // (citation_surface_log.surface) in LATEST_MIGRATION_COLUMNS: a table that only
 // the forced pass can create is unreachable forever once the version row says
 // "done", which is not a hypothetical — see the note there.
-export const CURRENT_SCHEMA_VERSION = 46;
+// v47: two additive indexes (P2-11 + ALGO-7). The bump is LOAD-BEARING, not bookkeeping:
+// `initSchema`'s fast path returns before the `CREATE INDEX IF NOT EXISTS` block, so on
+// every existing install at v46 a new index there would simply never be created. Same trap
+// the FTS5 migration hit — a DDL change that is not reachable from the version the DB
+// already reports is a no-op with a convincing diff.
+export const CURRENT_SCHEMA_VERSION = 47;
 
 // Sentinel columns for the LATEST migration set(s). The fast-path uses these
 // to self-heal half-migrated DBs — schema_version bumped but column ALTERs
@@ -551,6 +556,18 @@ export function initSchema(db) {
   db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_project ON sdk_sessions(project)`);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_obs_not_compressed ON observations(created_at_epoch DESC) WHERE COALESCE(compressed_into, 0) = 0`);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_handoffs_project_time ON session_handoffs(project, type, created_at_epoch DESC)`);
+  // v47 (audit 2026-09-02 P2-11 + the previous round's ALGO-7), one additive migration for
+  // both. Additive only: new indexes on existing columns, no table rewrite, no data move.
+  //
+  // The first was the ONLY genuine full table scan in the 30 statements the audit ran
+  // through EXPLAIN QUERY PLAN. Stop and SessionStart both probe "does a summary exist for
+  // this memory session?", `session_summaries` is 10,160 rows here, and the cost grows
+  // linearly with the table for a question asked on every hook event.
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_sess_sum_memory_session ON session_summaries(memory_session_id)`);
+  // The second narrows the live-row scan the injection faces run per project. Partial on the
+  // same predicate `liveObsFilterSql` uses, so the index covers exactly the rows those
+  // queries can return.
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_obs_project_live ON observations(project, created_at_epoch DESC) WHERE superseded_at IS NULL AND COALESCE(compressed_into, 0) = 0`);
 
   // FTS5 migration: recreate observations_fts when columns are missing (one-time)
   // Detect old FTS5 table missing lesson_learned or search_aliases and recreate with full column set

package/scripts/binding-probe-cli.mjs

@@ -102,7 +102,7 @@ if (first.ok) process.exit(0);
 // .node mid-compile.
 let lockPath;
 try {
-  lockPath = join(helpers.resolveDataDir(process.env.CLAUDE_MEM_DIR), 'runtime', 'install.lock');
+  lockPath = join(helpers.resolveDataDir(process.env.CLAUDE_MEM_DIR), 'runtime', 'install.lock'); // runtime-dir:stays-put — install lock serialises real installers
 } catch (e) {
   // resolveDataDir THROWS on a non-absolute CLAUDE_MEM_DIR. Unhandled, that
   // prints an 8-line rejection stack onto SessionStart stderr; one line is enough.

package/scripts/hook-launcher.mjs

@@ -39,13 +39,36 @@ const INSTALL_DIR = join(__dirname, '..');
 // non-absolute → default. Data-writing paths import that module and throw instead.
 const MEM_DIR = process.env.CLAUDE_MEM_DIR;
 const DATA_DIR = MEM_DIR && isAbsolute(MEM_DIR) ? MEM_DIR : join(homedir(), '.claude-mem-lite');
-const RUNTIME_DIR = join(DATA_DIR, 'runtime');
-const HEAL_MARKER = join(RUNTIME_DIR, 'hook-launcher-lastheal');
+// TWO runtime dirs, because this file writes BOTH classes of state and v3.93.0 shipped a
+// split by moving only doctor's READ side. `RUNTIME_DIR` is data-dir-relative and serves
+// `swap-in-progress`, which is installation identity and must NOT follow a per-harness
+// override (two installers pointed at different override dirs would each see no swap in
+// progress). `HOOK_RUNTIME_DIR` is override-aware and serves every marker another component
+// reads back — the launcher's own breakage/heal markers, which `install.mjs doctor` reads,
+// and the native-binding pair below. That second constant already existed here as
+// `NB_RUNTIME_DIR` and was applied to only half this file's markers.
+//
+// Inline `||`, not `lib/resolve-data-dir.mjs::resolveRuntimeDir`, and this is the single
+// declared exception in the tree: the launcher runs BEFORE the native binding is known to
+// work, so it imports only `node:` builtins on purpose — even a leaf lib module is a
+// resolution it declines to make on the path whose job is surviving a broken install. The
+// standalone hook scripts it mirrors (pre-tool-recall / pre-skill-bridge) honour the same
+// variable and write 78 of every 79 of these markers, so reading a different dir would mean
+// never healing. `resolveRuntimeDir` is the canonical rule (audit 2026-09-02 P1-14) and this
+// is NOT identical to it: the resolver additionally makes a RELATIVE override absolute
+// (`isAbsolute(raw) ? raw : resolve(raw)`), while this hands the relative value straight to
+// `fs`, which resolves it against cwd at call time rather than at module load. They agree on
+// unset, empty and absolute — the three cases that reach a real install. Keep the DEFAULTING
+// behaviour in step; do not read "identical" into the difference.
+// `tests/runtime-dir-single-home.test.mjs` asserts this file still carries the rule.
+const RUNTIME_DIR = join(DATA_DIR, 'runtime'); // runtime-dir:stays-put — serves swap-in-progress only; HOOK_RUNTIME_DIR carries the hook markers
+const HOOK_RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || RUNTIME_DIR;
+const HEAL_MARKER = join(HOOK_RUNTIME_DIR, 'hook-launcher-lastheal');
 const HEAL_COOLDOWN_MS = 6 * 60 * 60 * 1000;
 // Observable breakage state: written when the launcher degrades a broken install
 // to exit 0, cleared once the install is confirmed healthy. `doctor` reads it so
 // the intentional silence (no stack trace per fire) stays detectable. (#4/#8)
-const BROKEN_MARKER = join(RUNTIME_DIR, 'hook-launcher-broken');
+const BROKEN_MARKER = join(HOOK_RUNTIME_DIR, 'hook-launcher-broken');
 
 // ── Native-binding (ABI) self-heal ──────────────────────────────────────────
 // A stale better_sqlite3.node after a Node upgrade does NOT throw at import time
@@ -63,12 +86,9 @@ const BROKEN_MARKER = join(RUNTIME_DIR, 'hook-launcher-broken');
 // lib/hook-telemetry.mjs and lib/native-binding-hint.mjs); this heals from it at
 // SESSION-START only — never on the per-tool hot path, where an npm run would
 // stall the user's edit.
-// Marker dir mirrors the standalone hook scripts (pre-tool-recall /
-// pre-skill-bridge), which honor CLAUDE_MEM_RUNTIME_DIR — they write 78 of every
-// 79 of these markers, so reading a different dir would mean never healing.
-const NB_RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || RUNTIME_DIR;
-const NB_BROKEN_MARKER = join(NB_RUNTIME_DIR, 'native-binding-broken');
-const NB_HEAL_MARKER = join(NB_RUNTIME_DIR, 'native-binding-lastheal');
+// Marker dir: HOOK_RUNTIME_DIR (see its definition above for why it is override-aware).
+const NB_BROKEN_MARKER = join(HOOK_RUNTIME_DIR, 'native-binding-broken');
+const NB_HEAL_MARKER = join(HOOK_RUNTIME_DIR, 'native-binding-lastheal');
 // Literal, not imported: the pure-`node:` charter above forbids importing lib/
 // here (this file must survive a broken install). Kept in sync with
 // lib/binding-probe.mjs::NATIVE_BINDING_REBUILD_CMD, which is the single home
@@ -215,7 +235,7 @@ function recentHealAttempt() {
 
 function recordHealAttempt() {
   try {
-    mkdirSync(RUNTIME_DIR, { recursive: true });
+    mkdirSync(HOOK_RUNTIME_DIR, { recursive: true });
     writeFileSync(HEAL_MARKER, String(Date.now()));
   } catch { /* best-effort */ }
 }
@@ -229,7 +249,7 @@ function clearHealMarker() {
 
 function recordBreakage(reason) {
   try {
-    mkdirSync(RUNTIME_DIR, { recursive: true });
+    mkdirSync(HOOK_RUNTIME_DIR, { recursive: true });
     writeFileSync(BROKEN_MARKER, JSON.stringify({ reason, ts: Date.now() }));
   } catch { /* best-effort */ }
 }
@@ -306,7 +326,7 @@ function healNativeBindingIfBroken() {
       if (Date.now() - statSync(NB_HEAL_MARKER).mtimeMs < HEAL_COOLDOWN_MS) return;
     } catch { /* no marker → not on cooldown */ }
     try {
-      mkdirSync(NB_RUNTIME_DIR, { recursive: true });
+      mkdirSync(HOOK_RUNTIME_DIR, { recursive: true });
       writeFileSync(NB_HEAL_MARKER, String(Date.now()));
     } catch { /* best-effort */ }
 

package/scripts/launch.mjs

@@ -76,7 +76,7 @@ try {
   // proceeds; a broken one defers to the peer instead of racing it).
   const { acquireLock } = await import('../lib/proc-lock.mjs');
   const { resolveDataDir } = await import('../lib/resolve-data-dir.mjs');
-  const lockPath = join(resolveDataDir(process.env.CLAUDE_MEM_DIR), 'runtime', 'install.lock');
+  const lockPath = join(resolveDataDir(process.env.CLAUDE_MEM_DIR), 'runtime', 'install.lock'); // runtime-dir:stays-put — install lock serialises real installers
   let release = null;
   for (let i = 0; i < 20 && !(release = acquireLock(lockPath)); i++) {
     await new Promise((r) => setTimeout(r, 500));