claude-mem-lite 3.34.0 → 3.35.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.34.0",
+      "version": "3.35.1",
       "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.34.0",
+  "version": "3.35.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).",
   "author": {
     "name": "sdsrss"

package/cli.mjs

@@ -33,8 +33,10 @@ if (cmd === '--version' || cmd === '-v') {
   const { existsSync } = await import('fs');
   const { join } = await import('path');
   // D#29: honor CLAUDE_MEM_DIR so the install-vs-CLI help routing is correct on
-  // relocated installs (matches schema.mjs DB_DIR; HOME fallback when env unset).
-  const dataDir = process.env.CLAUDE_MEM_DIR || join(process.env.HOME || '', '.claude-mem-lite');
+  // relocated installs (matches schema.mjs DB_DIR via the shared resolver, which
+  // also fixes the HOME-unset relative-path fallback this branch used to have).
+  const { resolveDataDir } = await import('./lib/resolve-data-dir.mjs');
+  const dataDir = resolveDataDir(process.env.CLAUDE_MEM_DIR);
   const dbPath = join(dataDir, 'claude-mem-lite.db');
   if (existsSync(dbPath)) {
     const { run } = await import('./mem-cli.mjs');

package/format-utils.mjs

@@ -37,12 +37,16 @@ export function truncate(str, max = 80) {
 //      block would smuggle a privileged-channel instruction / fake tool-call narrative
 //      into the model's context. It can't escape its wrapper (class 1 closers are
 //      defanged), but a nested forged authority/tool tag is still an indirect-prompt-
-//      injection vector; strip the brackets so it reads as inert text. Other tags
-//      (<other-tag>) \u2014 and the attribute-bearing <invoke \u2026>/<parameter \u2026> forms \u2014 are
-//      deliberately left intact.
+//      injection vector; strip the brackets so it reads as inert text. Tool-call tags
+//      (<invoke \u2026>/<parameter \u2026>, bare + antml:-namespaced) are included: a prior turn's
+//      malformed tool-XML replayed through a handoff corrupted the continuation surface
+//      (mid-token truncation + model confusion), so replayed tool-XML must defang too.
+//      These carry attributes, so the match allows an optional attribute tail before the
+//      closing `>` \u2014 which also catches an attribute-bearing forgery of an authority tag
+//      (<system-reminder foo="\u2026">). Unrelated tags (<other-tag>) are left intact.
 // Reachable by editing files that contain these tokens \u2014 e.g. developing claude-mem-lite
 // itself, where source/observations carry the delimiter names.
-const CONTEXT_DELIMITER_RE = /<\/?(?:claude-mem-context|memory-context|session-handoff|system-reminder|task-notification|(?:antml:)?function_calls|(?:antml:)?function_results)>/gi;
+const CONTEXT_DELIMITER_RE = /<\/?(?:claude-mem-context|memory-context|session-handoff|system-reminder|task-notification|(?:antml:)?function_calls|(?:antml:)?function_results|(?:antml:)?invoke|(?:antml:)?parameter)(?:\s[^>]*)?>/gi;
 
 /**
  * Defang the literal context-block delimiter tags in user-derived text. Strips just the

package/hook-handoff.mjs

@@ -478,9 +478,12 @@ function renderHandoffFromRow(handoff, db, project) {
     if (summary && (summary.completed || summary.next_steps || summary.remaining_items)) {
       lines.push('');
       lines.push('<session-summary source="haiku">');
-      if (summary.completed) lines.push(summary.completed);
-      if (summary.remaining_items) lines.push(`Remaining: ${summary.remaining_items}`);
-      if (summary.next_steps) lines.push(`Next steps: ${summary.next_steps}`);
+      // Defang: these come from session_summaries, populated by Haiku OR by
+      // extractStructuredSummary over the assistant transcript tail — replayed text that can
+      // carry tool-XML / forged authority tags, same class as working_on above (audit MED-4).
+      if (summary.completed) lines.push(neutralizeContextDelimiters(summary.completed));
+      if (summary.remaining_items) lines.push(`Remaining: ${neutralizeContextDelimiters(summary.remaining_items)}`);
+      if (summary.next_steps) lines.push(`Next steps: ${neutralizeContextDelimiters(summary.next_steps)}`);
       lines.push('</session-summary>');
     }
   } catch {}

package/hook-llm.mjs

@@ -146,6 +146,22 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
       return null;
     }
 
+    // Paired-gate DROP at the auto-capture choke-point (v3.35). isLowYieldChangeObs
+    // (type=change + imp<2 + no real lesson — the substantive-title band isNoiseObservation
+    // misses) previously ran ONLY on the LLM-success path (handleLLMEpisode). The pre-save
+    // write here and the LLM-failure fallback (which keeps the pre-saved row) both bypassed
+    // it, so template change-rows survived on LLM failure. Gate covers all three write paths.
+    // Runs BEFORE capNoiseImportance: the pre-assigned importance IS the rule signal for a
+    // provisional pre-save — an imp>=2 rule-triggered episode (config/error change) must land
+    // so it stays visible immediately, survives a total LLM failure (the keep-pre-saved
+    // branch), and keeps its original created_at for the later in-place upgrade. (A dropped
+    // pre-save is not lost on LLM success — that path clean-inserts a fresh row — but it loses
+    // those three.) capNoiseImportance then caps any title-noise survivor to imp=1 as before.
+    if (isLowYieldChangeObs(obs)) {
+      debugLog('saveObservation', `dropped low-yield change: ${truncate(obs.title || '', 60)}`);
+      return null;
+    }
+
     // v2.47 P0-3: importance cap for LOW_SIGNAL titles that kept the drop gate
     // open via importance>=2 but carry no lesson/facts signal. 341 rows in live
     // DB had imp=3 under these conditions (99.4% noise). Cap to 1 so they

package/hook.mjs

@@ -47,7 +47,7 @@ import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObse
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { formatHookError } from './lib/native-binding-hint.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
-import { cleanupBroken, decayAndMarkIdle, boostAccessed, selectFuzzyDedupeIds, hardDeleteCandidateCount, purgeStale, recoverOrphanedChildren } from './lib/maintain-core.mjs';
+import { cleanupBroken, decayAndMarkIdle, boostAccessed, selectFuzzyDedupeIds, hardDeleteCandidateCount, purgeStale, recoverOrphanedChildren, recoverBuriedLessons } from './lib/maintain-core.mjs';
 import { snapshotDb } from './lib/db-backup.mjs';
 import {
   extractCitationsFromTranscript,
@@ -62,6 +62,7 @@ import { extractTailAssistantText, extractStructuredSummary } from './lib/summar
 import { searchRelevantMemories, formatMemoryLine, selectImperativeLesson } from './hook-memory.mjs';
 import { formatTaskImperative } from './lib/task-imperative.mjs';
 import { recordSkillAdoption, gcOldShadowShards } from './registry-recommend.mjs';
+import { gcOldMetricShards } from './lib/metrics.mjs';
 import { detectMemOverride } from './lib/mem-override.mjs';
 import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection, pickHandoffToInject, extractUnfinishedSummary } from './hook-handoff.mjs';
 import { checkForUpdate, getCachedUpdateBanner, isUpdateCheckDue } from './hook-update.mjs';
@@ -795,6 +796,11 @@ function runSessionStartAutoMaintain(db) {
       const orphansRecovered = recoverOrphanedChildren(db, mctx);
       if (orphansRecovered > 0) debugLog('DEBUG', 'auto-maintain', `recovered ${orphansRecovered} orphaned compression children`);
 
+      // Heal lesson rows citation-decay buried at importance 0 under the old floor=0.
+      // Non-destructive (0→1 on lesson-bearing rows only); idempotent no-op once none remain.
+      const lessonsHealed = recoverBuriedLessons(db, mctx);
+      if (lessonsHealed > 0) debugLog('DEBUG', 'auto-maintain', `healed ${lessonsHealed} lesson rows buried at importance 0`);
+
       const { decayed, idleMarked } = decayAndMarkIdle(db, mctx);
       if (decayed > 0) debugLog('DEBUG', 'auto-maintain', `decayed ${decayed} stale observations`);
       if (idleMarked > 0) debugLog('DEBUG', 'auto-maintain', `marked ${idleMarked} idle as pending-purge`);
@@ -1098,6 +1104,9 @@ async function handleSessionStart() {
   gcStalePreRecallCooldowns();
   // Bound the shadow-recommendation log (daily JSONL shards, no GC at write time).
   try { gcOldShadowShards(); } catch { /* best-effort, never blocks SessionStart */ }
+  // Same for the opt-in metrics sink (RUNTIME_DIR's parent is DB_DIR). Runs even when
+  // metrics are disabled, so shards left by a since-toggled-off run still get pruned.
+  try { gcOldMetricShards(join(RUNTIME_DIR, '..')); } catch { /* best-effort */ }
 
   // Plugin cache self-heal: Claude Code auto-updates the marketplace plugin can
   // re-populate cache/<ver>/hooks/hooks.json, reintroducing duplicate hook

package/install.mjs

@@ -7,6 +7,7 @@ import { join, resolve, dirname, isAbsolute } from 'path';
 import { homedir, tmpdir } from 'os';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { createRequire } from 'node:module';
+import { resolveDataDir } from './lib/resolve-data-dir.mjs';
 
 const PROJECT_DIR = resolve(import.meta.dirname ?? dirname(fileURLToPath(import.meta.url)));
 const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
@@ -20,7 +21,7 @@ const DATA_DIR = join(homedir(), '.claude-mem-lite');
 // the runtime/data layer READS it (pre-fix: installer wrote homedir, runtime read
 // the relocated dir → preinstalled skills silently vanished, doctor read the wrong
 // DB). Equals DATA_DIR when CLAUDE_MEM_DIR is unset (the common case).
-const MEM_DATA_DIR = process.env.CLAUDE_MEM_DIR || DATA_DIR;
+const MEM_DATA_DIR = resolveDataDir(process.env.CLAUDE_MEM_DIR);
 const DB_PATH = join(MEM_DATA_DIR, 'claude-mem-lite.db');
 const OLD_DATA_DIR = join(homedir(), '.claude-mem');
 

package/lib/citation-tracker.mjs

@@ -472,7 +472,16 @@ export function hasMainThreadAssistantText(transcriptPath) {
 }
 
 const IMPORTANCE_CAP = 3;
-const IMPORTANCE_FLOOR = 0;
+// Demote floor = 1, NOT 0. Both passive injection surfaces exclude importance 0
+// (pre-tool-recall.js requires >=2, user-prompt-search.js requires >=1), so a row
+// demoted to 0 can never be re-injected → never re-cited → never recovers: a one-way
+// burial that silently hides lesson-bearing rows the "lessons never auto-GC" guards
+// (maintain decayAndMarkIdle + compress-core) protect on every other path. Floor 1
+// keeps a decayed row on the >=1 surface with a citation-recovery path. Genuine noise
+// still sinks via maintain's PENDING_PURGE pipeline, which keys on compressed_into
+// (not importance) over injection_count=0 rows — a disjoint population from these
+// injected-but-uncited rows — so noise GC is unaffected.
+const IMPORTANCE_FLOOR = 1;
 const UNCITED_STREAK_THRESHOLD = 3;
 
 // Adoption-rate gate (P5 ②). A project's cite-rate is SUM(cited_count) /

package/lib/maintain-core.mjs

@@ -117,6 +117,29 @@ export function recoverOrphanedChildren(db, { projectFilter = '', baseParams = [
   `).run(...baseParams).changes;
 }
 
+// Heal lesson-bearing rows that citation-decay buried at importance 0 under the old
+// IMPORTANCE_FLOOR=0 (fixed in citation-tracker.mjs → floor 1). All passive injection
+// surfaces exclude importance 0 (pre-tool-recall >=2, user-prompt-search >=1, memory-context
+// >=1), so a lesson demoted there is invisible AND — being injection_count>0 by construction
+// — sits in no GC queue either (decayAndMarkIdle only marks injection_count=0 rows): stranded
+// out of reach with its distilled lesson. Lifting to 1 restores >=1-surface visibility + a
+// citation-recovery path. NON-DESTRUCTIVE (only 0→1 on lesson-bearing rows, never
+// deletes/hides), idempotent (a no-op once no imp-0 lesson rows remain), so safe to run
+// unconditionally alongside recoverOrphanedChildren. `superseded_at IS NULL` mirrors the
+// injection surfaces' own filter (pre-tool-recall:368, memory-context:217) — a de-dup loser
+// (auto-dedup sets superseded_at but leaves compressed_into=0) must NOT be lifted back into
+// injectability. Non-lesson imp-0 rows are left buried (low-value, not worth resurfacing).
+export function recoverBuriedLessons(db, { projectFilter = '', baseParams = [] } = {}) {
+  return db.prepare(`
+    UPDATE observations SET importance = 1
+    WHERE COALESCE(compressed_into, 0) = 0
+      AND COALESCE(importance, 1) = 0
+      AND superseded_at IS NULL
+      AND lesson_learned IS NOT NULL AND lesson_learned <> '' AND lower(lesson_learned) <> 'none'
+      ${projectFilter}
+  `).run(...baseParams).changes;
+}
+
 export function cleanupBroken(db, { projectFilter, baseParams, opCap = OP_CAP }) {
   const doomed = db.prepare(`
     SELECT id FROM observations

package/lib/metrics.mjs

@@ -16,7 +16,7 @@
 // skip malformed lines silently. The module imports nothing heavy so hook
 // cold-start pays near-zero when metrics are disabled.
 
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'fs';
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync } from 'fs';
 import { join } from 'path';
 
 const DAY_MS = 86400000;
@@ -68,6 +68,33 @@ export function timed(dbDir, event, fn, extra = {}) {
   }
 }
 
+/**
+ * Prune metric daily shards older than `retainDays`. recordMetric writes one
+ * YYYY-MM-DD.jsonl per day with no GC, so a long-lived CLAUDE_MEM_METRICS=1 install
+ * grows the dir unbounded. 90d keeps a full quarter for aggregate windows while
+ * bounding the dir. Runs regardless of the enable flag so a user who toggles metrics
+ * OFF still gets old shards cleaned. Shard date read from the filename (ISO dates sort
+ * lexicographically = chronologically). Best-effort, never throws — called from the
+ * SessionStart GC sweep (mirrors registry-recommend.gcOldShadowShards).
+ * @returns {number} shards removed
+ */
+export function gcOldMetricShards(dbDir, retainDays = 90) {
+  try {
+    if (!dbDir) return 0;
+    const dir = join(dbDir, 'metrics');
+    if (!existsSync(dir)) return 0;
+    const cutoff = new Date(Date.now() - retainDays * DAY_MS).toISOString().slice(0, 10);
+    let removed = 0;
+    for (const name of readdirSync(dir)) {
+      const m = /^(\d{4}-\d{2}-\d{2})\.jsonl$/.exec(name);
+      if (m && m[1] < cutoff) {
+        try { unlinkSync(join(dir, name)); removed++; } catch { /* per-entry, silent */ }
+      }
+    }
+    return removed;
+  } catch { return 0; }
+}
+
 /** Count of days to aggregate by default in readMetrics / aggregate. */
 export const DEFAULT_WINDOW_DAYS = 7;
 

package/lib/resolve-data-dir.mjs

@@ -0,0 +1,35 @@
+// Single source of truth for resolving the CLAUDE_MEM_DIR data directory.
+// Zero runtime deps (node:path + node:os only) so hot-path hook scripts can
+// import it without pulling in better-sqlite3.
+//
+// The env var is a RELOCATION knob: unset → ~/.claude-mem-lite (the common,
+// non-relocated case); set → an absolute path on a larger/faster volume.
+// Anything else is a mistake we must reject LOUDLY rather than turn into a
+// stray directory:
+//   - The literal strings "undefined"/"null" arise when a caller interpolates
+//     a JS nullish value into a shell env string (e.g. `CLAUDE_MEM_DIR='${x}'`
+//     with x === undefined). They are truthy, so `env || default` accepts them
+//     and better-sqlite3 then creates a relative `undefined/` dir at cwd.
+//   - A relative path silently resolves against each process's cwd, scattering
+//     state across directories.
+// Falsy (unset/empty) is the only non-absolute value we treat as "use default".
+import { homedir } from 'node:os';
+import { join, isAbsolute } from 'node:path';
+
+/**
+ * @param {string|undefined|null} raw  Typically process.env.CLAUDE_MEM_DIR.
+ * @returns {string} An absolute data directory.
+ * @throws if `raw` is a non-empty, non-absolute value (incl. "undefined"/"null").
+ */
+export function resolveDataDir(raw) {
+  if (raw === undefined || raw === null || raw === '') {
+    return join(homedir(), '.claude-mem-lite');
+  }
+  if (typeof raw !== 'string' || raw === 'undefined' || raw === 'null' || !isAbsolute(raw)) {
+    throw new Error(
+      `CLAUDE_MEM_DIR must be an absolute path; got ${JSON.stringify(raw)}. ` +
+      `Leave it unset to use ~/.claude-mem-lite.`
+    );
+  }
+  return raw;
+}

package/lib/startup-dashboard.mjs

@@ -8,7 +8,7 @@
 import { readGitState } from './git-state.mjs';
 import { readProjectTasks } from './task-reader.mjs';
 import { recentPlans } from './plan-reader.mjs';
-import { isAdoptedHere } from '../hook-shared.mjs';
+import { isAdoptedHere, HANDOFF_EXPIRY_EXIT } from '../hook-shared.mjs';
 
 function ageStr(ms) {
   const diff = Date.now() - ms;
@@ -22,11 +22,16 @@ function ageStr(ms) {
 
 function readRecentHandoff(db, project) {
   try {
+    // Only surface a handoff the UserPromptSubmit injection could actually deliver: apply
+    // the SAME expiry the injection's pickHandoffToInject enforces (HANDOFF_EXPIRY_EXIT).
+    // Without this the dashboard promised "context injects on your next message" for an
+    // exit handoff >7d old that pickHandoffToInject filters as expired → the promise could
+    // never be kept (batch2-reviewer Finding 1).
     return db.prepare(`
       SELECT created_at_epoch, working_on FROM session_handoffs
-      WHERE project = ? AND type = 'exit'
+      WHERE project = ? AND type = 'exit' AND created_at_epoch > ?
       ORDER BY created_at_epoch DESC LIMIT 1
-    `).get(project);
+    `).get(project, Date.now() - HANDOFF_EXPIRY_EXIT);
   } catch { return null; }
 }
 
@@ -82,10 +87,16 @@ export function buildDashboard({ db, project, projectPath = process.cwd(), stubs
   }
 
   if (handoff) {
-    parts.push(`🔄 Continuation (/exit ${ageStr(handoff.created_at_epoch)}):`);
-    if (handoff.working_on) {
-      parts.push(`  - Working on: ${handoff.working_on.slice(0, 160)}`);
-    }
+    // Continuation POINTER only. The working_on CONTENT is delivered once — by the
+    // UserPromptSubmit <session-handoff> block on a continuation-intent prompt
+    // (renderHandoffInjection). Emitting the teaser here too double-injected working_on
+    // into the model's context on every resume (post-defang: redundant, not unsafe).
+    // Wording is CONDITIONAL ("resume it to restore"), not a promise of automatic
+    // injection: the injection is gated on continuation-intent, so on a genuinely new
+    // first task the gate stays silent (stale working_on correctly not injected) and the
+    // pointer must not claim otherwise. readRecentHandoff already drops handoffs older than
+    // the injection's own expiry, so a shown pointer is always deliverable on resume.
+    parts.push(`🔄 Continuation available (/exit ${ageStr(handoff.created_at_epoch)}) — resume it to restore the full context.`);
   }
 
   if (eventCount > 0) {

package/mem-cli.mjs

@@ -18,7 +18,7 @@ import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from '
 import { buildNotLowSignalSql } from './lib/low-signal-patterns.mjs';
 import {
   cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
-  recoverOrphanedChildren,
+  recoverOrphanedChildren, recoverBuriedLessons,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
   recoverChildrenOf, hardDeleteCandidateCount,
   OP_CAP, STALE_AGE_MS, PINNED_INJ_THRESHOLD,
@@ -1972,6 +1972,10 @@ function cmdMaintain(db, args) {
       // unreachable children. Non-destructive — un-hide only, no delete.
       const orphans = recoverOrphanedChildren(db, mctx);
       if (orphans > 0) results.push(`Recovered ${orphans} orphaned compression children`);
+      // Heal lesson rows citation-decay buried at importance 0 (pre floor=1). 0→1 on
+      // lesson-bearing rows only; idempotent no-op once none remain.
+      const lessonsHealed = recoverBuriedLessons(db, mctx);
+      if (lessonsHealed > 0) results.push(`Healed ${lessonsHealed} lesson rows buried at importance 0`);
     }
 
     if (ops.includes('decay')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.34.0",
+  "version": "3.35.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",
@@ -67,6 +67,7 @@
     "lib/id-routing.mjs",
     "lib/err-sampler.mjs",
     "lib/hook-telemetry.mjs",
+    "lib/resolve-data-dir.mjs",
     "lib/file-intel.mjs",
     "lib/reread-guard.mjs",
     "lib/metrics.mjs",

package/registry-recommend.mjs

@@ -5,7 +5,7 @@
 // invocations/recommend_count. Live injection is Phase 2. `off` skips all work.
 import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync, appendFileSync, readdirSync, unlinkSync } from 'fs';
 import { join } from 'path';
-import { homedir } from 'os';
+import { resolveDataDir } from './lib/resolve-data-dir.mjs';
 import { searchResources, cjkIntentTokens } from './registry-retriever.mjs';
 
 const VALID_MODES = new Set(['shadow', 'live', 'off']);
@@ -26,7 +26,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(process.env.CLAUDE_MEM_DIR || join(homedir(), '.claude-mem-lite'), 'runtime');
+  return join(resolveDataDir(process.env.CLAUDE_MEM_DIR), 'runtime');
 }
 
 const TOKEN_SPLIT = /[^a-z0-9一-鿿]+/;

package/schema.mjs

@@ -7,10 +7,11 @@ import { homedir } from 'os';
 import { join } from 'path';
 import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, chmodSync } from 'fs';
 import { OBS_FTS_COLUMNS, debugCatch } from './utils.mjs';
+import { resolveDataDir } from './lib/resolve-data-dir.mjs';
 
 // DATA location — DB, managed resources, registry DB, runtime/. Honors
 // CLAUDE_MEM_DIR so users can relocate state to a larger/faster volume.
-export const DB_DIR = process.env.CLAUDE_MEM_DIR || join(homedir(), '.claude-mem-lite');
+export const DB_DIR = resolveDataDir(process.env.CLAUDE_MEM_DIR);
 export const DB_PATH = join(DB_DIR, 'claude-mem-lite.db');
 export const REGISTRY_DB_PATH = join(DB_DIR, 'resource-registry.db');
 // CODE / install location — server.mjs, hook.mjs, cli.mjs, package.json live

package/scripts/hook-launcher.mjs

@@ -26,15 +26,20 @@
 
 import { existsSync, mkdirSync, writeFileSync, statSync, unlinkSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { dirname, join } from 'node:path';
+import { dirname, join, isAbsolute } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { homedir } from 'node:os';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const INSTALL_DIR = join(__dirname, '..');
-const RUNTIME_DIR = process.env.CLAUDE_MEM_DIR
-  ? join(process.env.CLAUDE_MEM_DIR, 'runtime')
-  : join(homedir(), '.claude-mem-lite', 'runtime');
+// A bogus CLAUDE_MEM_DIR ("undefined"/"null"/relative from a mis-quoted env
+// interpolation) must degrade to the default here, not become a stray dir. The
+// launcher's pure-node charter (above) forbids importing lib/resolve-data-dir.mjs,
+// and its fail-open duty forbids throwing, so mirror that guard inline + lenient:
+// 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');
 const HEAL_COOLDOWN_MS = 6 * 60 * 60 * 1000;
 // Observable breakage state: written when the launcher degrades a broken install

package/scripts/post-tool-recall.js

@@ -15,11 +15,11 @@
 
 import { existsSync, readFileSync } from 'fs';
 import { basename, join } from 'path';
-import { homedir } from 'os';
+import { resolveDataDir } from '../lib/resolve-data-dir.mjs';
 
 const SALIENCE_BIND = process.env.CLAUDE_MEM_SALIENCE === 'bind';
 
-const DATA_DIR = process.env.CLAUDE_MEM_DIR || join(homedir(), '.claude-mem-lite');
+const DATA_DIR = resolveDataDir(process.env.CLAUDE_MEM_DIR);
 const RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || join(DATA_DIR, 'runtime');
 const LEGACY_COOLDOWN_PATH = join(RUNTIME_DIR, 'pre-recall-cooldown.json');
 
@@ -68,4 +68,13 @@ async function main() {
   }));
 }
 
-main().catch(() => {}).finally(() => process.exit(0));
+// No forced process.exit(0): main() consumes stdin to EOF (or early-returns without
+// touching it) and holds no open handles (no DB, no timers), so the event loop drains
+// and the process exits 0 on its own — which FLUSHES the stdout nudge above. A forced
+// exit could drop that pending async write on a piped stdout (the v3.33.1 gotcha the
+// payload-bearing sibling hooks avoid). catch() keeps the exit code 0.
+// Swallow EPIPE: if Claude Code closes the read end before the async write drains, the
+// stream emits 'error' — without the (now-removed) forced exit, an unhandled one would
+// surface as a non-zero exit + stack. A hook must never fail loud on a dropped pipe.
+process.stdout.on('error', () => {});
+main().catch(() => {});

package/scripts/pre-skill-bridge.js

@@ -7,9 +7,10 @@ import { existsSync, readFileSync } from 'fs';
 import { join, resolve, sep } from 'path';
 import { homedir } from 'os';
 import { recordHookError } from '../lib/hook-telemetry.mjs';
+import { resolveDataDir } from '../lib/resolve-data-dir.mjs';
 
 // CLAUDE_MEM_DIR mirrors pre-tool-recall.js — one env var sandboxes everything.
-const DATA_DIR = process.env.CLAUDE_MEM_DIR || join(homedir(), '.claude-mem-lite');
+const DATA_DIR = resolveDataDir(process.env.CLAUDE_MEM_DIR);
 const RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || join(DATA_DIR, 'runtime');
 // D#29: all data artifacts follow DATA_DIR (CLAUDE_MEM_DIR-aware), not a hardcoded
 // homedir — previously REGISTRY_DB_PATH/MANAGED_BASE/MARKER pinned homedir while line 12

package/scripts/pre-tool-recall.js

@@ -6,7 +6,7 @@
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { basename, join } from 'path';
-import { homedir } from 'os';
+import { resolveDataDir } from '../lib/resolve-data-dir.mjs';
 import { buildNotLowSignalSql } from '../lib/low-signal-patterns.mjs';
 import { recordHookError } from '../lib/hook-telemetry.mjs';
 import { citeFactorClause } from '../scoring-sql.mjs';
@@ -18,7 +18,7 @@ import { presentIdents } from '../lib/lesson-idents.mjs';
 // CLAUDE_MEM_DIR matches schema.mjs / main CLI — one env var sandboxes the
 // whole system. CLAUDE_MEM_DB_PATH / CLAUDE_MEM_RUNTIME_DIR remain as
 // per-component overrides for tests that mix isolated + real paths.
-const DATA_DIR = process.env.CLAUDE_MEM_DIR || join(homedir(), '.claude-mem-lite');
+const DATA_DIR = resolveDataDir(process.env.CLAUDE_MEM_DIR);
 const DB_PATH = process.env.CLAUDE_MEM_DB_PATH || join(DATA_DIR, 'claude-mem-lite.db');
 const RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || join(DATA_DIR, 'runtime');
 // A3 (v2.83): cross-hook dedup window — must mirror DEDUP_STALE_MS in

package/scripts/user-prompt-search.js

@@ -4,7 +4,7 @@
 // Lightweight: only imports schema.mjs and utils.mjs, no MCP SDK
 
 import { ensureDb, DB_DIR, REGISTRY_DB_PATH } from '../schema.mjs';
-import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, OBS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, notLowSignalTitleClause, noisePenaltyClause, stripPrivate } from '../utils.mjs';
+import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, OBS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, notLowSignalTitleClause, noisePenaltyClause, stripPrivate, neutralizeContextDelimiters } from '../utils.mjs';
 import { citeFactorClause } from '../scoring-sql.mjs';
 import { cjkPrecisionOk } from '../nlp.mjs';
 import { writeFileSync, readFileSync, existsSync, renameSync } from 'fs';
@@ -265,7 +265,7 @@ export function rowMatchesIdentifier(row, idsLower) {
 // Each row includes `bm25_raw` (pre-multiplier bm25 magnitude) alongside the
 // composite `relevance`, so callers can distinguish raw-match strength from
 // importance/type/decay inflation.
-function searchByFts(db, queryText, project, limit, typeFilter) {
+export function searchByFts(db, queryText, project, limit, typeFilter) {
   const ftsQuery = sanitizeFtsQuery(queryText);
   if (!ftsQuery) return { rows: [], mode: null };
 
@@ -299,6 +299,7 @@ function searchByFts(db, queryText, project, limit, typeFilter) {
       AND o.importance >= 1
       AND o.created_at_epoch > ?
       AND COALESCE(o.compressed_into, 0) = 0
+      AND o.superseded_at IS NULL
       AND ${notLowSignalTitleClause('o')}
       ${typeClause}
     ORDER BY relevance
@@ -345,6 +346,7 @@ function searchByFile(db, files, project, limit) {
       WHERE o.project = ?
         AND o.importance >= 1
         AND COALESCE(o.compressed_into, 0) = 0
+        AND o.superseded_at IS NULL
         AND o.created_at_epoch > ?
         AND (of2.filename = ? OR of2.filename LIKE ? ESCAPE '\\')
         AND ${notLowSignalTitleClause('o')}
@@ -420,6 +422,7 @@ function searchRecent(db, project, limit) {
     WHERE project = ?
       AND importance >= 1
       AND COALESCE(compressed_into, 0) = 0
+      AND superseded_at IS NULL
       AND created_at_epoch > ?
       AND ${notLowSignalTitleClause('')}
     ORDER BY created_at_epoch DESC
@@ -464,8 +467,10 @@ function formatResults(rows) {
   const lines = ['[mem] FYI — Related memories (continue your task):'];
   for (const r of rows) {
     const icon = typeIcon(r.type);
-    const title = truncate(r.title || '', 70);
-    const lesson = !QUIET_HOOKS && r.lesson_learned ? ` — ${truncate(r.lesson_learned, 50)}` : '';
+    // Defang replayed obs text before truncation: a poisoned title/lesson carrying tool-XML
+    // or a forged authority tag must not render as a live delimiter in this injected block.
+    const title = truncate(neutralizeContextDelimiters(r.title || ''), 70);
+    const lesson = !QUIET_HOOKS && r.lesson_learned ? ` — ${truncate(neutralizeContextDelimiters(r.lesson_learned), 50)}` : '';
     lines.push(`#${r.id} ${icon} ${title}${lesson}`);
   }
   return lines.join('\n');
@@ -479,7 +484,10 @@ function formatPromptResults(rows) {
   if (!rows || rows.length === 0) return null;
   const lines = ['[mem] FYI — Past similar questions (continue your task):'];
   for (const r of rows) {
-    const text = truncate((r.prompt_text || '').replace(/\s+/g, ' '), 80);
+    // prompt_text is a raw prior USER prompt — the highest-risk replayed class (this is
+    // exactly the column that carried malformed tool-XML into the handoff bug). Defang the
+    // delimiters, then collapse whitespace + truncate.
+    const text = truncate(neutralizeContextDelimiters(r.prompt_text || '').replace(/\s+/g, ' '), 80);
     lines.push(`P#${r.id} 💬 ${text}`);
   }
   return lines.join('\n');

package/server.mjs

@@ -17,7 +17,7 @@ import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentT
 import { buildSearchFtsQuery, parseDateBounds, parseDuration, coreRunSearchPipeline } from './lib/search-core.mjs';
 import {
   cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
-  recoverOrphanedChildren,
+  recoverOrphanedChildren, recoverBuriedLessons,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
   recoverChildrenOf, hardDeleteCandidateCount,
   OP_CAP, STALE_AGE_MS,
@@ -1139,6 +1139,10 @@ server.registerTool(
           // resurface unreachable children. Non-destructive — un-hide only, no delete.
           const orphans = recoverOrphanedChildren(db, mctx);
           if (orphans > 0) results.push(`Recovered ${orphans} orphaned compression children`);
+          // Heal lesson rows citation-decay buried at importance 0 (pre floor=1). 0→1 on
+          // lesson-bearing rows only; idempotent no-op once none remain.
+          const lessonsHealed = recoverBuriedLessons(db, mctx);
+          if (lessonsHealed > 0) results.push(`Healed ${lessonsHealed} lesson rows buried at importance 0`);
         }
 
         if (ops.includes('decay')) {

package/source-files.mjs

@@ -29,6 +29,12 @@ export const SOURCE_FILES = [
   'tier.mjs', 'tfidf.mjs',
   'nlp.mjs', 'synonyms.mjs', 'scoring-sql.mjs', 'stop-words.mjs', 'project-utils.mjs',
   'secret-scrub.mjs', 'format-utils.mjs', 'hash-utils.mjs', 'bash-utils.mjs',
+  // Single source of truth for the CLAUDE_MEM_DIR → data-dir resolver (rejects a
+  // stringified "undefined"/"null"/relative env instead of creating a stray dir).
+  // Statically imported by schema.mjs / cli.mjs / install.mjs / registry-recommend.mjs
+  // AND hook scripts (pre-tool-recall / post-tool-recall / pre-skill-bridge) — ship it
+  // or auto-update leaves schema + every hook with ERR_MODULE_NOT_FOUND on each fire.
+  'lib/resolve-data-dir.mjs',
   // lib/ — statically imported by hook-llm.mjs (activity) + hook-handoff.mjs (git-state, task-reader);
   // dynamically imported by hook.mjs (startup-dashboard) + mem-cli.mjs (doctor-benchmark, plan-reader).
   'lib/activity.mjs',