claude-mem-lite 3.47.0 → 3.49.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.47.0",
+      "version": "3.49.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.47.0",
+  "version": "3.49.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/hook-context.mjs

@@ -8,8 +8,9 @@ import {
   debugLog, debugCatch, neutralizeContextDelimiters,
   DECAY_HALF_LIFE_BY_TYPE, DEFAULT_DECAY_HALF_LIFE_MS, notLowSignalTitleClause,
 } from './utils.mjs';
-import { STALE_SESSION_MS, FALLBACK_OBS_WINDOW_MS, RUNTIME_DIR, effectiveQuiet } from './hook-shared.mjs';
+import { STALE_SESSION_MS, FALLBACK_OBS_WINDOW_MS, RUNTIME_DIR, effectiveQuiet, isQuietHooks } from './hook-shared.mjs';
 import { extractUnfinishedSummary } from './hook-handoff.mjs';
+import { recentInjectableEvents, renderInjectableEvent } from './lib/events-injection.mjs';
 
 /**
  * Infer the project directory from environment variables or cwd.
@@ -390,6 +391,24 @@ export function buildSessionContextLines(db, project, now = new Date(), currentC
     }
   }
 
+  // HIGH-1 (full audit 2026-07-16): surface recent high-importance events — the
+  // canonical store for promoted bugfix/decision/lesson memories that
+  // persistHaikuSummary upgrade-deletes out of observations. Without this section
+  // SessionStart never shows them. E# prefix keeps citation extractors (bare-`#`
+  // anchored) from reading an event id as an observation id. Gated on isQuietHooks()
+  // ONLY (explicit low-noise opt-out), NOT effectiveQuiet: unlike Key Context, events
+  // never appear in the obs-only Recent table and are absent from the MEMORY.md
+  // sentinel, so an adopted project (the default) would otherwise have zero
+  // SessionStart surface for them. Never throws (recentInjectableEvents catches).
+  if (!isQuietHooks()) {
+    const keyEvents = recentInjectableEvents(db, { project, limit: 5 });
+    if (keyEvents.length > 0) {
+      summaryLines.push('### Key Events');
+      for (const e of keyEvents) summaryLines.push(`- ${renderInjectableEvent(e)}`);
+      summaryLines.push('');
+    }
+  }
+
   // 5. Working state from latest /clear handoff.
   // Session scoping: when currentCcSessionId is provided, restrict to this session's
   // own clear handoff so parallel sessions don't see each other's Working State block.

package/hook-llm.mjs

@@ -21,6 +21,7 @@ import {
 import { EVENT_TYPES, saveEvent } from './lib/activity.mjs';
 import { isNoiseObservation, capNoiseImportance, isLowYieldChangeObs } from './lib/low-signal-patterns.mjs';
 import { episodeHasSignificantContent } from './hook-episode.mjs';
+import { OBS_TYPE_SET } from './lib/obs-types.mjs';
 
 // T9: memdir-incompatible types live in the `events` table, not `observations`.
 // Set lookup is O(1) — authoritative source is lib/activity.mjs::EVENT_TYPES.
@@ -771,7 +772,7 @@ ${actionList}`;
   const ruleImportance = computeRuleImportance(episode);
 
   let obs;
-  const validTypes = new Set(['decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change']);
+  const validTypes = OBS_TYPE_SET;
 
   const gotSlot = await acquireLLMSlot();
   if (gotSlot) {

package/hook-optimize.mjs

@@ -15,6 +15,7 @@ import { scrubRecord } from './lib/scrub-record.mjs';
 import { getVocabulary, computeVector, cosineSimilarity, vecTextForRow } from './tfidf.mjs';
 import { MERGE_JACCARD_LOW, AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { DB_DIR } from './schema.mjs';
+import { OBS_TYPE_SET } from './lib/obs-types.mjs';
 
 const RUNTIME_DIR = join(DB_DIR, 'runtime');
 
@@ -150,7 +151,7 @@ export async function executeReenrich(db, limit = 10, { scope = 'narrow', projec
   if (candidates.length === 0) return { processed: 0, skipped: 0 };
 
   let processed = 0, skipped = 0;
-  const validTypes = new Set(['decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change']);
+  const validTypes = OBS_TYPE_SET;
 
   for (const cand of candidates) {
     const gotSlot = await acquireLLMSlot();
@@ -929,19 +930,28 @@ export async function optimizeRun(db, { tasks, maxItems = 15, force = false, ree
     try {
       switch (task) {
         case 're-enrich':
-          if (reenrichScope === 'narrow') {
-            // P1-2: the default maintenance pass covers BOTH narrow (fill lesson/concepts on
-            // fully-degraded rows) AND aliases (backfill search_aliases on lesson-bearing
-            // manual saves that narrow+wide both skip — mem_save writes no aliases, so without
-            // this they stay paraphrase-unfindable). Split the budget so neither starves.
-            // An explicit --scope wide|aliases still runs exactly that one scope (below).
-            const aliasBudget = Math.max(1, Math.floor(budget.reenrich / 2));
-            const narrowRes = await executeReenrich(db, budget.reenrich - aliasBudget, { scope: 'narrow', project });
-            const aliasRes = await executeReenrich(db, aliasBudget, { scope: 'aliases', project });
+          if (reenrichScope === 'narrow' || reenrichScope === 'wide') {
+            // P1-2 (v3.43) + audit 2026-07-17 P4: the maintenance pass covers BOTH the main
+            // scope (narrow = fill lesson/concepts on fully-degraded rows; wide = lesson
+            // backfill on substantive event-typed rows) AND aliases (backfill search_aliases
+            // on lesson-bearing manual saves that narrow+wide both skip — mem_save writes no
+            // aliases, so without this they stay paraphrase-unfindable). v3.43 hung the split
+            // only on the DEFAULT 'narrow' branch, but the DAILY auto path (handleLLMOptimize
+            // via auto-maintain) passes 'wide' explicitly — so aliases never had a cadence and
+            // live coverage crawled at ~15%. The split is ADAPTIVE: aliases takes at most half
+            // the budget and only what its candidate pool actually holds, so a zero-candidate
+            // aliases pass costs nothing and the main scope keeps its full budget.
+            // An explicit --scope aliases still runs exactly that one scope (below).
+            const half = Math.max(1, Math.floor(budget.reenrich / 2));
+            const aliasBudget = Math.min(half, findReenrichCandidates(db, half, { scope: 'aliases', project }).length);
+            const mainRes = await executeReenrich(db, budget.reenrich - aliasBudget, { scope: reenrichScope, project });
+            const aliasRes = aliasBudget > 0
+              ? await executeReenrich(db, aliasBudget, { scope: 'aliases', project })
+              : { processed: 0, skipped: 0 };
             results.reenrich = {
-              processed: (narrowRes.processed || 0) + (aliasRes.processed || 0),
-              skipped: (narrowRes.skipped || 0) + (aliasRes.skipped || 0),
-              byScope: { narrow: narrowRes, aliases: aliasRes },
+              processed: (mainRes.processed || 0) + (aliasRes.processed || 0),
+              skipped: (mainRes.skipped || 0) + (aliasRes.skipped || 0),
+              byScope: { [reenrichScope]: mainRes, aliases: aliasRes },
             };
           } else {
             results.reenrich = await executeReenrich(db, budget.reenrich, { scope: reenrichScope, project });

package/hook.mjs

@@ -61,6 +61,7 @@ import {
 import { resolveEdgeAttribution, readPreRecallFileEdges } from './lib/edge-attribution.mjs';
 import { extractTailAssistantText, extractStructuredSummary } from './lib/summary-extractor.mjs';
 import { searchRelevantMemories, formatMemoryLine, selectImperativeLesson } from './hook-memory.mjs';
+import { searchInjectableEvents, renderInjectableEvent } from './lib/events-injection.mjs';
 import { formatTaskImperative } from './lib/task-imperative.mjs';
 import { recordSkillAdoption, gcOldShadowShards } from './registry-recommend.mjs';
 import { gcOldMetricShards } from './lib/metrics.mjs';
@@ -87,7 +88,7 @@ import { getVocabulary } from './tfidf.mjs';
 // Prevent recursive hooks from background claude -p calls
 // Background workers (llm-episode, llm-summary) are exempt — they're ours
 const event = process.argv[2];
-const BG_EVENTS = new Set(['llm-episode', 'llm-summary', 'auto-compress', 'llm-optimize']);
+const BG_EVENTS = new Set(['llm-episode', 'llm-summary', 'auto-compress', 'llm-optimize', 'auto-maintain']);
 
 // Respect Claude Code plugin disable state even when legacy settings.json hooks remain.
 // install.mjs writes direct hooks into ~/.claude/settings.json, so disabling the plugin
@@ -420,7 +421,18 @@ function triggerErrorRecall(db, toolInput, response) {
     `).all(ftsQuery, project, nowR);
 
     const out = formatErrorRecallHints(rows);
-    if (out) process.stdout.write(out);
+    if (out) {
+      // MED-3 (full audit 2026-07-16): emit via the JSON envelope (trailing '\n'),
+      // NOT raw stdout. A raw multi-line write corrupts a co-emitted episode-flush
+      // receipt (both write to PostToolUse stdout in the same call → `<text>{json}`)
+      // and is silently dropped on CC variants that ignore plain-text PostToolUse
+      // stdout. This is the same suppressOutput+additionalContext channel
+      // flushEpisode uses; two separate JSON lines each parse independently.
+      process.stdout.write(JSON.stringify({
+        suppressOutput: true,
+        hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: out },
+      }) + '\n');
+    }
   } catch (e) { debugCatch(e, 'triggerErrorRecall'); }
 }
 
@@ -975,6 +987,29 @@ function runSessionStartAutoMaintain(db) {
   }
 }
 
+// SessionStart boot path (MED-4): cheap 24h gate pre-check only. When maintenance is
+// due, the heavy pass (VACUUM-INTO snapshot + purge/cleanup/decay/dedup) is handed to
+// a detached `auto-maintain` worker via spawnBackground so it never blocks interactive
+// session start. The worker re-checks the same gate (idempotent) before doing the work.
+function scheduleSessionStartAutoMaintain() {
+  const maintainFile = join(RUNTIME_DIR, 'last-auto-maintain.json');
+  try {
+    const last = JSON.parse(readFileSync(maintainFile, 'utf8'));
+    if (Date.now() - last.epoch < 24 * 3600000) return; // not due — no spawn
+  } catch { /* no gate file → due */ }
+  if (!process.env.CLAUDE_MEM_SKIP_MAINTAIN) spawnBackground('auto-maintain');
+}
+
+// Detached `auto-maintain` worker entry: opens its own DB and runs the maintenance
+// pass off the interactive boot path. runSessionStartAutoMaintain still owns the 24h
+// gate + the compress/optimize spawns at its tail.
+function handleAutoMaintain() {
+  const db = openDb();
+  if (!db) return;
+  try { runSessionStartAutoMaintain(db); }
+  finally { try { db.close(); } catch { /* ignore */ } }
+}
+
 function saveHandoffAndFastSummary(db, { prevSessionId, prevProject, project, ccSessionId, episodeSnapshot, now }) {
   // Shared clear handoff reference — queried once, used by fast summary + working state
   let prevClearHandoff = null;
@@ -1285,7 +1320,7 @@ async function handleSessionStart() {
 
     runSessionStartDbMutations(db, { sessionId, project, prevSessionId, now });
 
-    runSessionStartAutoMaintain(db);
+    scheduleSessionStartAutoMaintain();
 
     // ── Non-transactional operations (side effects, background work) ──
 
@@ -1520,6 +1555,21 @@ async function handleUserPrompt() {
         lines.push('</memory-context>');
         process.stdout.write(lines.join('\n') + '\n');
       }
+      // HIGH-1 (full audit 2026-07-16): surface FTS-matched events — the canonical
+      // store for promoted bugfix/decision/lesson memories that persistHaikuSummary
+      // upgrade-deletes out of observations. Without this leg they are unreachable at
+      // prompt time. Separate E#-tagged block so it doesn't perturb observation
+      // ranking and citation extractors (bare-`#` anchored) never read an event id as
+      // an obs id. Nested try so an events failure can't suppress the imperative pick.
+      try {
+        const events = searchInjectableEvents(db, { prompt: promptText, project });
+        if (events.length > 0) {
+          const elines = ['<memory-context relevance="events">'];
+          for (const e of events) elines.push(`- ${renderInjectableEvent(e)}`);
+          elines.push('</memory-context>');
+          process.stdout.write(elines.join('\n') + '\n');
+        }
+      } catch (e) { debugCatch(e, 'handleUserPrompt-events'); }
       if (imperativePick) {
         // Guard the write on a non-empty return — formatTaskImperative yields '' for a
         // lesson that strips to empty (e.g. "."), which would otherwise emit a bare line.
@@ -1639,6 +1689,7 @@ try {
     case 'llm-episode':      await handleLLMEpisode(); break;
     case 'llm-summary':      await handleLLMSummary(); break;
     case 'auto-compress':    handleAutoCompress(); break;
+    case 'auto-maintain':    handleAutoMaintain(); break;
     case 'llm-optimize':   await handleLLMOptimize(); break;
     // Detached update refresh spawned by handleSessionStart (audit P3d) — does the
     // GitHub fetch + (non-plugin) install off the SessionStart critical path,

package/lib/activity.mjs

@@ -8,10 +8,11 @@ import { sanitizeFtsQuery } from '../utils.mjs';
 import { scrubRecord } from './scrub-record.mjs';
 import { saveObservation } from './save-observation.mjs';
 import { notLowSignalTitleClause } from '../scoring-sql.mjs';
+import { OBS_TYPE_SET } from './obs-types.mjs';
 
 // Observation types (mirrors the observations.type enum) — events carry a wider
 // set, so promotion maps the extras (lesson/bug/observation) onto valid obs types.
-const OBS_TYPES = new Set(['decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change']);
+const OBS_TYPES = OBS_TYPE_SET;
 const EVENT_TO_OBS_TYPE = { bug: 'bugfix', lesson: 'discovery', observation: 'discovery' };
 
 /**

package/lib/citation-tracker.mjs

@@ -707,7 +707,13 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
       }
     }
   });
-  try { txn(); } catch (e) { debugCatch(e, 'applyCitationDecay-txn'); return empty; }
+  // IMMEDIATE (not the default DEFERRED): this txn reads each obs then writes it.
+  // Under concurrent same-project Stop hooks a DEFERRED txn pins a read snapshot
+  // first, and the second session's write then hits SQLITE_BUSY_SNAPSHOT — a
+  // snapshot-upgrade conflict busy_timeout cannot resolve — silently dropping the
+  // whole decay pass (promotes/demotes/streak + the paired funnel deltas). Taking
+  // the write lock up front lets busy_timeout actually serialize the two sessions.
+  try { txn.immediate(); } catch (e) { debugCatch(e, 'applyCitationDecay-txn'); return empty; }
   return { promoted, demoted, touched };
 }
 

package/lib/delete-core.mjs

@@ -0,0 +1,72 @@
+// lib/delete-core.mjs — shared hard-delete orchestration for the CLI `delete`
+// command (mem-cli.mjs cmdDelete) and the MCP `mem_delete` tool (server.mjs).
+// Both surfaces previously inlined a byte-for-byte-equivalent copy of this logic,
+// kept in sync by "aligned with MCP mem_delete" / "matching the CLI delete" parity
+// comments — the project's documented #1 drift risk. Consolidated here so there is
+// one implementation: pre-delete snapshot, stale related_ids cleanup,
+// merged/compressed-child recovery, and the delete transaction.
+import { snapshotDb } from './db-backup.mjs';
+import { recoverChildrenOf } from './maintain-core.mjs';
+import { debugCatch } from '../utils.mjs';
+
+/**
+ * Hard-delete the given observation ids with full orchestration. The CALLER owns
+ * the confirm/preview gating and fetches whatever rows it needs to render (existence
+ * check, preview list, missing-id note); this performs only the irreversible mutation
+ * once the caller has decided to proceed.
+ *
+ * Order (preserved from the pre-extraction inline paths):
+ *   1. snapshotDb OUTSIDE any transaction (VACUUM INTO cannot run inside one). Best-
+ *      effort: no-op on :memory:, never throws.
+ *   2. In ONE transaction: strip the deleted ids out of other rows' related_ids
+ *      (coarse LIKE pre-filter → JSON-parse precise filter), recover children
+ *      merged/compressed INTO the doomed rows (compressed_into has no FK), then DELETE.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {number[]} ids  observation ids to delete
+ * @param {{ snapshotTag?: string }} [opts]
+ * @returns {{ deleted: number, recoveredChildren: number, snapshotPath: string|null }}
+ */
+export function deleteObservations(db, ids, { snapshotTag = 'pre-delete' } = {}) {
+  const placeholders = ids.map(() => '?').join(',');
+
+  // Snapshot before the irreversible hard-delete so a wrong-id delete has a pre-image,
+  // matching the maintain purge/cleanup hard-delete paths (audit MED-2). Best-effort
+  // (never throws, skips :memory:). Must run OUTSIDE the transaction below (VACUUM INTO).
+  const snapshotPath = snapshotDb(db, { tag: snapshotTag });
+
+  const deletedIds = new Set(ids);
+  const deleteTx = db.transaction(() => {
+    // Clean up stale references in other observations' related_ids.
+    // LIKE %id% is a coarse pre-filter (false positives: %1% matches [10], [21]) — it only
+    // narrows which rows to fetch; the JSON parse + Set.has below is the precise filter.
+    // Acceptable because observation count per user is typically <10K.
+    const likeConditions = ids.map(() => `related_ids LIKE ?`).join(' OR ');
+    const likeParams = ids.map(id => `%${id}%`);
+    const referencing = db.prepare(`
+      SELECT id, related_ids FROM observations
+      WHERE related_ids IS NOT NULL AND related_ids != '[]' AND (${likeConditions})
+    `).all(...likeParams);
+    for (const r of referencing) {
+      let refIds;
+      try { refIds = JSON.parse(r.related_ids); } catch (e) { debugCatch(e, 'deleteRelatedIds'); continue; }
+      // Only rewrite a well-formed integer array; a malformed related_ids value is left
+      // untouched rather than reshaped by the filter (the stricter of the two originals).
+      if (!Array.isArray(refIds) || !refIds.every(id => Number.isInteger(id))) continue;
+      const filtered = refIds.filter(id => !deletedIds.has(id));
+      if (filtered.length !== refIds.length) {
+        db.prepare('UPDATE observations SET related_ids = ? WHERE id = ?').run(JSON.stringify(filtered), r.id);
+      }
+    }
+    // Resurface rows merged/compressed INTO the doomed keepers before deleting, else they
+    // dangle behind a now-missing parent (compressed_into has no FK) — invisible to every
+    // COALESCE(compressed_into,0)=0 view and unrecoverable. Same guard the maintain
+    // hard-delete paths use (recoverChildrenOf).
+    const recovered = recoverChildrenOf(db, ids);
+    // Execute deletion (FTS5 cleanup handled by the observations_ad trigger).
+    const deleted = db.prepare(`DELETE FROM observations WHERE id IN (${placeholders})`).run(...ids);
+    return { changes: deleted.changes, recovered };
+  });
+  const result = deleteTx();
+  return { deleted: result.changes, recoveredChildren: result.recovered, snapshotPath };
+}

package/lib/events-injection.mjs

@@ -0,0 +1,100 @@
+// lib/events-injection.mjs — surface `events` into the passive injection surfaces.
+//
+// HIGH-1 (full audit 2026-07-16): persistHaikuSummary upgrade-deletes every
+// event-typed memory (bugfix/decision/lesson/discovery/…) out of `observations`
+// and into the `events` table, so after Haiku enrichment the high-value history
+// lives ONLY in events. v3.44 wired events into mem_search + PreToolUse recall,
+// but the passive injection surfaces still read only observations — so the promoted
+// memories were unreachable at prompt/session time.
+//
+// Wiring (v3.48.0): SessionStart context (hook-context.mjs, recency) + UserPromptSubmit
+// path B (hook.mjs memory-context, FTS). Path A (user-prompt-search.js) is INTENTIONALLY
+// not wired: both UserPromptSubmit hooks fire on every prompt and there is no cross-hook
+// events dedup, so wiring path A too would double-inject the same event. Do NOT "complete"
+// the wiring by adding events here to path A.
+//
+// id-space discipline: events share the numeric id space with observations but are a
+// separate table, so injected events are rendered with an `E#` prefix. The
+// citation-tracker injected-id extractors all anchor on a BARE `#`
+// (FYI `/^#\d/`, memory-context `/\(#\d/`, error-recall row-anchored), so an `E#`
+// row is never mis-attributed to an observation id (which would let citation decay
+// mutate an unrelated observation sharing that id). Events carry no citation columns,
+// so they inject as reference-only — reachability, not decay bookkeeping.
+
+import { searchEventsFts } from './search-core.mjs';
+import { neutralizeContextDelimiters } from '../format-utils.mjs';
+import { sanitizeFtsQuery } from '../utils.mjs';
+
+const DEFAULT_LIMIT = 3;
+const DEFAULT_MIN_IMPORTANCE = 2;
+const TITLE_MAX = 80;
+const LESSON_MAX = 160;
+
+function normalizeRow(r) {
+  return {
+    id: r.id,
+    type: r.event_type || r.type || 'event',
+    title: r.title || '',
+    lesson_learned: (r.body ?? r.lesson_learned) || null,
+    importance: r.importance,
+    created_at_epoch: r.created_at_epoch,
+  };
+}
+
+/**
+ * FTS-matched events for a prompt (UserPromptSubmit surfaces). Superseded events are
+ * excluded by searchEventsFts; importance floor drops low-value rows. Never throws.
+ * @returns {Array<{id,type,title,lesson_learned,importance,created_at_epoch}>}
+ */
+export function searchInjectableEvents(db, { prompt, ftsQuery, project, limit = DEFAULT_LIMIT, minImportance = DEFAULT_MIN_IMPORTANCE } = {}) {
+  if (!db || !project) return [];
+  const q = ftsQuery || (prompt ? sanitizeFtsQuery(prompt) : null);
+  if (!q) return [];
+  try {
+    const rows = searchEventsFts(db, {
+      ftsQuery: q, project, projectBoost: project,
+      importance: minImportance, perSourceLimit: limit,
+    });
+    return rows.map(normalizeRow);
+  } catch { return []; }
+}
+
+/**
+ * Recency + importance events (SessionStart context — no FTS query available).
+ * Excludes superseded events. Never throws.
+ * @returns {Array<{id,type,title,lesson_learned,importance,created_at_epoch}>}
+ */
+export function recentInjectableEvents(db, { project, limit = DEFAULT_LIMIT, minImportance = DEFAULT_MIN_IMPORTANCE } = {}) {
+  if (!db || !project) return [];
+  try {
+    const rows = db.prepare(`
+      SELECT id, event_type, title, body, importance, created_at_epoch
+      FROM events
+      WHERE project = ?
+        AND superseded_at_epoch IS NULL
+        AND COALESCE(importance, 1) >= ?
+      ORDER BY created_at_epoch DESC
+      LIMIT ?
+    `).all(project, minImportance, limit);
+    return rows.map(normalizeRow);
+  } catch { return []; }
+}
+
+/**
+ * Render one injectable event as a defanged `E#<id> [<type>] <title> — <lesson>` line.
+ * The E# prefix keeps citation-tracker extractors (which anchor on a bare `#`) from
+ * mis-reading the event id as an observation id.
+ */
+export function renderInjectableEvent(row) {
+  const title = neutralizeContextDelimiters((row.title || '').slice(0, TITLE_MAX));
+  // row.type is a frozen event_type enum (saveEvent is reached only via
+  // hook-llm.mjs behind `if (EVENT_TYPE_SET.has(summary.type))`), so it carries no
+  // injection markers and is intentionally NOT defanged — mirrors the un-defanged
+  // `[type]` for observations. If an unvalidated event writer is ever added, defang it.
+  const head = `E#${row.id} [${row.type}] ${title}`;
+  if (row.lesson_learned) {
+    const lesson = neutralizeContextDelimiters(row.lesson_learned.trim().slice(0, LESSON_MAX));
+    if (lesson) return `${head} — ${lesson}`;
+  }
+  return head;
+}

package/lib/export-columns.mjs

@@ -14,7 +14,10 @@
 // + branch + timing. `id` + `memory_session_id` are informational (restore remaps id and
 // buckets under a synthetic restore session). Session-idempotency keys (last_decided/
 // last_cited_session_id, demoted_at, optimized_at) are intentionally NOT exported — they are
-// meaningless after a row is re-bucketed under a restore session.
+// meaningless after a row is re-bucketed under a restore session. Also intentionally NOT
+// exported: `related_ids` (holds observation ids, stale/dangling after restore remaps ids)
+// and `discovery_tokens` (a derived retrieval metric, rebuilt by the live system; exporting
+// it would freeze a stale value into backups).
 export const EXPORT_COLUMNS = [
   'id', 'memory_session_id', 'project', 'type', 'title', 'subtitle', 'narrative', 'text',
   'concepts', 'facts', 'files_read', 'files_modified', 'lesson_learned', 'search_aliases',

package/lib/obs-types.mjs

@@ -0,0 +1,12 @@
+// Single source of truth for the observation `type` vocabulary.
+//
+// Audit 2026-07-17 MED-3: this list was hardcoded verbatim in 10 JS sites + the SQL
+// CHECK constraint (schema.mjs observations DDL) — the project's #1 bug class
+// (fix-lands-on-one-surface) sitting latent on the core type vocabulary. Every
+// validator now imports from here; the SQL CHECK stays a literal (SQLite DDL cannot
+// interpolate at migration time) and is locked to this list by
+// tests/obs-types-invariant.test.mjs, which also fails if a new hardcoded copy of
+// the list appears anywhere else in the runtime source.
+export const OBS_TYPES = Object.freeze(['decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change']);
+
+export const OBS_TYPE_SET = new Set(OBS_TYPES);

package/lib/save-nudge.mjs

@@ -0,0 +1,22 @@
+// Save-time lesson nudge (audit 2026-07-17 P4): bugfix/decision are the types whose
+// value lives in the lesson (root cause + fix / constraint + tradeoff), yet they are
+// exactly where lessonless writes concentrate (14d live data: bugfix 18.8% / decision
+// 28.7% lessonless, worsening). The nudge fires in the SAVE RESPONSE — the one moment
+// the model still has the context to write the lesson — and names the exact follow-up
+// call, so acting on it costs one tool call. Zero LLM cost; the async backfill arm
+// (optimizeRun wide/aliases re-enrich) stays the safety net for saves that ignore it.
+//
+// Shared by server.mjs (mem_save) and mem-cli.mjs (cmdSave) — one gate, two phrasings,
+// no twin drift.
+const NUDGE_TYPES = new Set(['bugfix', 'decision']);
+
+/**
+ * @param {{ type: string, id: number, lessonCaptured: boolean, surface: 'mcp'|'cli' }} p
+ * @returns {string} nudge text to append ('' when no nudge applies)
+ */
+export function buildLessonNudge({ type, id, lessonCaptured, surface }) {
+  if (lessonCaptured || !NUDGE_TYPES.has(type)) return '';
+  return surface === 'cli'
+    ? `\n[mem] ⚠ ${type} #${id} saved without a lesson — capture the root cause + fix while it's fresh: claude-mem-lite update ${id} --lesson "<root cause + fix>"`
+    : ` ⚠ Saved without lesson_learned — a ${type} is worth keeping only with its lesson. Capture it now: mem_update(id=${id}, lesson_learned="<root cause + fix>").`;
+}

package/lib/search-core.mjs

@@ -245,17 +245,59 @@ export function searchEventsFts(db, { ftsQuery, project = null, projectBoost = n
   `).all(...params);
 }
 
+// A lone match has no within-source spread to normalize against (MED-5, v3.48.0).
+// A magnitude-blind constant (-0.5) fixed the dominating direction — an incidental
+// lone hit no longer outranks a strongly-matched page — but buried the opposite,
+// equally common shape (audit 2026-07-17 MED-1): events are the CANONICAL store for
+// promoted bugfix/decision memories AND a low-cardinality source, so "the best
+// answer is one strong event" is routine, and within-source max-normalization pins
+// every multi-hit source's best to -1 regardless of absolute strength.
+//
+// Fix: band the lone hit by its raw magnitude RELATIVE to the global raw max across
+// all scored rows — the cross-source signal the per-source normalization destroys.
+// obs/event/session BM25 live on comparable scales (weighted bm25 × decay ×
+// project-boost), so the ratio is meaningful there; small-scale sources (prompts,
+// bm25 ≈ -1) can only be penalized by this comparison, never inflated — the safe
+// direction. Bands (ratio = |lone| / globalMaxAbs, first match wins):
+//   ratio ≥ 1   → -1.05  the lone hit IS the strongest raw match anywhere: rank it
+//                        strictly ahead of every normalized -1 (ties in raw
+//                        strength resolve toward the lone hit — the [-1, 0] band
+//                        convention is deliberately exceeded here)
+//   ratio ≥ 0.5 → -0.75  comparable to the best: above neutral, below the leaders
+//   ratio ≥ 0.1 → -0.5   the MED-5 neutral mid
+//   ratio < 0.1 → -0.25  grazing match: sink it
+// score === 0 rows (the prompts CJK LIKE fallback — zero confidence) are excluded
+// from normalization entirely and keep their 0, sorting last in the ascending
+// merge (audit L3: the old clamp promoted a lone 0-score row to the neutral mid).
+const SINGLE_MATCH_BANDS = [
+  [1.0, -1.05],
+  [0.5, -0.75],
+  [0.1, -0.5],
+  [0, -0.25],
+];
+
 /**
  * Normalize each source's BM25 scores to [-1, 0] before cross-source merge.
  * Prevents observations (BM25 can reach -40) from systematically outranking
- * sessions (-6) and prompts (-1) regardless of relevance. Sources with a
- * single scored row are skipped — normalizing would inflate a weak match to
- * -1.0. Mutates `results` in place; callers re-sort afterwards.
+ * sessions (-6) and prompts (-1) regardless of relevance. A source with a single
+ * scored row is banded by its magnitude relative to the global raw max (see
+ * SINGLE_MATCH_BANDS) — it has no within-source spread to normalize against.
+ * Mutates `results` in place; callers re-sort afterwards.
  */
 export function normalizeCrossSourceScores(results, sourceKey) {
+  const scored = results.filter((r) => r.score !== null && r.score !== undefined && r.score !== 0);
+  const globalMaxAbs = scored.length ? Math.max(...scored.map((r) => Math.abs(r.score))) : 0;
   for (const src of ['obs', 'session', 'prompt', 'event']) {
-    const srcResults = results.filter((r) => r[sourceKey] === src && r.score !== null && r.score !== undefined);
-    if (srcResults.length < 2) continue;
+    // score === 0 stays out: for multi-row sources 0/maxAbs would be 0 anyway, and a
+    // lone 0-score row must not be banded upward (it only occurs as the prompts LIKE
+    // fallback, which never coexists with real prompt FTS hits).
+    const srcResults = results.filter((r) => r[sourceKey] === src && r.score !== null && r.score !== undefined && r.score !== 0);
+    if (srcResults.length === 0) continue;
+    if (srcResults.length === 1) {
+      const ratio = globalMaxAbs > 0 ? Math.abs(srcResults[0].score) / globalMaxAbs : 0;
+      srcResults[0].score = SINGLE_MATCH_BANDS.find(([floor]) => ratio >= floor)[1];
+      continue;
+    }
     const maxAbs = Math.max(...srcResults.map((r) => Math.abs(r.score)));
     if (maxAbs > 0) {
       for (const r of srcResults) r.score = r.score / maxAbs;