claude-mem-lite 3.38.3 → 3.39.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.38.3",
+      "version": "3.39.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.38.3",
+  "version": "3.39.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/README.md

@@ -126,7 +126,7 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 - **Cross-session handoff** -- Captures session state (request, completed work, next steps, key files) on `/clear` or `/exit`, then injects context when the next session detects continuation intent via explicit keywords or FTS5 term overlap
 - **Git-SHA continuation anchor** (v2.31.0) -- Handoff rows include `git_sha_at_handoff`; any handoff matching the current `HEAD` counts as continuation regardless of TTL. Code state is a stronger continuation signal than wall-clock time
 - **Startup dashboard** (v2.31.0) -- SessionStart hook aggregates `git status` + `~/.claude/tasks/*.json` + `~/.claude/plans/*.md` + most-recent exit handoff + recent event count into a single structured block injected via `hookSpecificOutput.additionalContext`
-- **Activity namespace** (v2.31.0) -- Dedicated `events` table + FTS5 for non-memdir types (`bugfix`, `lesson`, `bug`, `discovery`, `refactor`, `feature`, `observation`, `decision`) that don't compete with `WHAT_NOT_TO_SAVE` semantics on the observations table. CLI: `claude-mem-lite activity save|search|recent|show`. Slash commands: `/lesson`, `/bug`. `hook-llm` routes non-memdir summary types through `persistHaikuSummary` so upgrades from observations→events are atomic
+- **Activity namespace** (v2.31.0) -- Dedicated `events` table + FTS5 for non-memdir types (`bugfix`, `lesson`, `bug`, `discovery`, `refactor`, `feature`, `observation`, `decision`) that don't compete with `WHAT_NOT_TO_SAVE` semantics on the observations table. CLI: `claude-mem-lite activity save|search|recent|show`. `hook-llm` routes non-memdir summary types through `persistHaikuSummary` so upgrades from observations→events are atomic. (v3.39: the `/lesson` and `/bug` slash commands were redirected from this events table to searchable **observations** — `mem_search` never read the events table, so explicit saves were unfindable; the events table remains the auto-capture activity log.)
 - **In-place observation updates** -- `mem_update` tool modifies existing observations atomically (field update + FTS text rebuild + vector re-computation in one transaction), preserving original IDs and references
 - **Bulk export** -- `mem_export` tool exports observations as JSON or JSONL, with project/type/date filtering and 1000-row pagination cap with batch guidance
 - **FTS integrity management** -- `mem_fts_check` tool verifies FTS5 index health or rebuilds indexes on demand, useful after database recovery or when search results seem wrong

package/README.zh-CN.md

@@ -99,7 +99,7 @@
 - **插件缓存 hook 自愈** -- Claude Code runtime 从 `~/.claude/plugins/cache/<mp>/<plugin>/<ver>/hooks/hooks.json` 读取插件 hook，而非 marketplace 源。当 `install.mjs` 写入 `settings.json` 的 hooks 与残留 cache `hooks.json` 同时存在（例如曾装过 marketplace 版本，或插件被 Claude Code 自动升级重建 cache），runtime 会注册两套 hook → 每次 SessionStart / UserPromptSubmit 都触发两份。`install.mjs` 和 `hook-update.mjs` 现在会清理每个 cache 版本目录下的 `hooks.json`；`hook.mjs session-start` 每次启动自愈（通过 `hasInstallManagedHooks` 门控，不影响纯插件模式用户）；`install.mjs status` 会报告 cache 污染状况（自 v2.31.1 / v2.31.2 起）。
 - **Git-SHA 延续锚点**（v2.31.0）-- handoff 记录包含 `git_sha_at_handoff` 字段，任何匹配当前 `HEAD` 的 handoff 都视为延续会话，不受 TTL 限制。代码状态比时钟时间更能反映上下文延续。
 - **启动面板**（v2.31.0）-- SessionStart hook 将 `git status` + `~/.claude/tasks/*.json` + `~/.claude/plans/*.md` + 最近 /exit 交接 + 最近事件数聚合为一个结构化块，通过 `hookSpecificOutput.additionalContext` 注入。
-- **活动命名空间**（v2.31.0）-- 为非 memdir 类型（`bugfix` / `lesson` / `bug` / `discovery` / `refactor` / `feature` / `observation` / `decision`）启用独立的 `events` 表 + FTS5，与 observations 表的 `WHAT_NOT_TO_SAVE` 语义解耦。CLI：`claude-mem-lite activity save|search|recent|show`；斜杠命令：`/lesson`、`/bug`。`hook-llm` 通过 `persistHaikuSummary` 路由非 memdir 摘要，observations → events 升级路径是事务原子的。
+- **活动命名空间**（v2.31.0）-- 为非 memdir 类型（`bugfix` / `lesson` / `bug` / `discovery` / `refactor` / `feature` / `observation` / `decision`）启用独立的 `events` 表 + FTS5，与 observations 表的 `WHAT_NOT_TO_SAVE` 语义解耦。CLI：`claude-mem-lite activity save|search|recent|show`。`hook-llm` 通过 `persistHaikuSummary` 路由非 memdir 摘要，observations → events 升级路径是事务原子的。（v3.39：`/lesson`、`/bug` 斜杠命令已从此 events 表重定向到可搜索的 **observations**——`mem_search` 从不读 events 表，显式保存因此搜不到；events 表仍作自动捕获活动日志。）
 
 ## 平台支持
 

package/adopt-content.mjs

@@ -4,10 +4,13 @@
 // claudemd.mjs primitives so the strings are testable without side effects.
 //
 // CURRENT_SENTINEL_VERSION tags the managed block as `<!-- claude-mem-lite:begin
-// vN -->`. needsRefresh() only checks for *inequality* against the installed tag,
-// so any change triggers an in-place refresh (version change = intended content
-// change, overwritten rather than treated as a user edit) — the value need not be
-// monotonic. We deliberately use `v1` (not `v2`) so the version digit differs from
+// vN -->`. needsRefresh() (claudemd.mjs) compares the version tag AND the block
+// body AND the detail-doc content — ANY of the three differing triggers an
+// in-place refresh (drift = intended content change, overwritten rather than
+// treated as a user edit). So a template edit propagates on the next SessionStart
+// even WITHOUT a version bump; the tag need not be monotonic and, in practice,
+// need not change at all — we keep `v1` across content edits (see mem #8846).
+// We deliberately use `v1` (not `v2`) so the version digit differs from
 // the sibling code-graph-mcp plugin's `<!-- code-graph-mcp:begin v2 -->` block in
 // the same CLAUDE.md; the slug already scopes the two independently (claudemd.mjs),
 // so this is a cosmetic distinguisher, not a functional one. The pre-v3.13 legacy

package/cli/activity.mjs

@@ -21,12 +21,12 @@ function formatActivityResults(rows) {
 export async function cmdActivity(db, args) {
   const sub = args[0];
   if (!sub) {
-    fail('[mem] Usage: claude-mem-lite activity <save|search|recent|show|delete> ...');
+    fail('[mem] Usage: claude-mem-lite activity <save|search|recent|show|delete|promote> ...');
     return;
   }
 
   const { positional, flags } = parseArgs(args.slice(1));
-  const { saveEvent, searchEvents, recentEvents, getEvent, EVENT_TYPES } = await import('../lib/activity.mjs');
+  const { saveEvent, searchEvents, recentEvents, getEvent, EVENT_TYPES, promoteInsightEvents } = await import('../lib/activity.mjs');
   const VALID_EVENT_TYPES = new Set(EVENT_TYPES);
   const project = flags.project ? resolveProject(db, flags.project) : inferProject();
 
@@ -172,5 +172,26 @@ export async function cmdActivity(db, args) {
     return;
   }
 
+  if (sub === 'promote') {
+    // P2(b): promote insight-bearing events (body present, importance>=N) into
+    // searchable observations. Preview by default; --execute applies. One-time
+    // backfill — the source events are marked promoted (idempotent re-runs).
+    const minImp = flags['min-importance'] !== undefined ? parseInt(flags['min-importance'], 10) : 2;
+    if (isNaN(minImp) || minImp < 1 || minImp > 3) {
+      fail('[mem] activity promote: --min-importance must be 1, 2, or 3.');
+      return;
+    }
+    const projectFilter = flags.project ? project : null;
+    const execute = flags.execute === true || flags.execute === 'true';
+    const r = promoteInsightEvents(db, { project: projectFilter, minImportance: minImp, execute });
+    if (!execute) {
+      out(`[mem] Preview: ${r.eligible} insight-bearing event(s) (body + importance>=${minImp})${projectFilter ? ` in ${projectFilter}` : ' across all projects'} would be promoted to searchable observations.`);
+      out('[mem] Run with --execute to apply. Source events are kept (marked promoted).');
+      return;
+    }
+    out(`[mem] Promoted ${r.promoted} event(s) to observations${r.deduped ? ` (${r.deduped} already had an equivalent observation)` : ''}.`);
+    return;
+  }
+
   fail(`[mem] Unknown activity subcommand: ${sub}`);
 }

package/commands/bug.md

@@ -1,14 +1,17 @@
 ---
 name: bug
-description: "Use when: logging a known bug + repro steps you can't fix right now. Writes to the mem events table (NOT memdir). Skip for bugs you're actively fixing in the current turn — just fix them."
+description: "Use when: logging a known bug + repro steps you can't fix right now. Writes a searchable observation (findable via mem_search + surfaced by recall hooks; still NOT memdir). Skip for bugs you're actively fixing in the current turn — just fix them."
 ---
 
 # /bug
 
-Record a known bug + reproduction steps. Writes to the mem `events` table
-with `event_type='bug'`. Does NOT touch memdir. Useful for bugs you can't
-fix immediately but want future sessions (or yourself after `/clear`) to
-know about and avoid re-investigating.
+Record a known bug + reproduction steps. Writes a searchable **observation**
+(`type=bugfix`, description in `lesson_learned`) so future sessions can find it
+via `mem_search` and the PreToolUse recall hooks warn when the affected files
+are edited. Does NOT touch memdir. Useful for bugs you can't fix immediately
+but want future sessions (or yourself after `/clear`) to know about and avoid
+re-investigating. (Redirected v3.39: was the `events` table, which `mem_search`
+never read.)
 
 ## When to use
 
@@ -40,16 +43,17 @@ Map severity to importance:
 Build the body as `<description>\n\nRepro:\n<repro-steps>` (or just
 `<description>` if `--repro` is absent).
 
-Run via Bash:
+Run via Bash — the body is the positional content; the description goes in
+`--lesson` so it lands in the high-weight `lesson_learned` field:
 
-    node ${CLAUDE_PLUGIN_ROOT}/cli.mjs activity save \
-      --type bug \
+    node ${CLAUDE_PLUGIN_ROOT}/cli.mjs save "<body>" \
+      --type bugfix \
       --title "<first 60 chars of description>" \
-      --body "<body>" \
-      [--file <path> | --files f1,f2,...] \
+      --lesson "<description>" \
+      [--files f1,f2,...] \
       --importance <1|2|3>
 
-Confirm to user with: `Bug logged: activity #<id>`.
+Confirm to user with: `Bug logged: #<id>`.
 
 ## Examples
 

package/commands/lesson.md

@@ -1,14 +1,17 @@
 ---
 name: lesson
-description: "Use when: capturing a non-obvious lesson/gotcha/workaround after a tricky fix or surprising behavior. Writes to the mem events table (NOT memdir). Skip for typos, renames, or user-preference rules."
+description: "Use when: capturing a non-obvious lesson/gotcha/workaround after a tricky fix or surprising behavior. Writes a searchable observation (findable via mem_search + surfaced by recall hooks; still NOT memdir/L1 prompt). Skip for typos, renames, or user-preference rules."
 ---
 
 # /lesson
 
-Record a lesson / gotcha / workaround. Writes to the mem `events` table
-with `event_type='lesson'`. Does NOT touch memdir — so lessons never end up
-in the L1 system-prompt memory section and do not conflict with the
-`WHAT_NOT_TO_SAVE` semantics sdscc enforces.
+Record a lesson / gotcha / workaround. Writes a searchable **observation**
+(`type=discovery` with the text as `lesson_learned`) so future sessions can
+find it via `mem_search` and the PreToolUse recall hooks surface it on the
+relevant files. Does NOT touch memdir — so lessons never end up in the L1
+system-prompt memory section and do not conflict with the `WHAT_NOT_TO_SAVE`
+semantics sdscc enforces. (Redirected v3.39: was the `events` table, which
+`mem_search` never read.)
 
 ## When to use
 
@@ -33,18 +36,17 @@ Don't use for trivial fixes (typos, renames), for rules that belong in memdir
 
 ## Execution
 
-Run via Bash — the CLI takes the lesson text as positional args and stores
-the full text as the title (the `activity save` command uses title-as-body
-when `--body` is absent):
+Run via Bash — pass the lesson text as the positional content and repeat it in
+`--lesson` so it lands in the high-weight `lesson_learned` field:
 
-    node ${CLAUDE_PLUGIN_ROOT}/cli.mjs activity save \
-      --type lesson \
+    node ${CLAUDE_PLUGIN_ROOT}/cli.mjs save "<full text>" \
+      --type discovery \
       --title "<first 60 chars of text>" \
-      --body "<full text>" \
-      [--file <path> | --files f1,f2,...] \
+      --lesson "<full text>" \
+      [--files f1,f2,...] \
       --importance <1|2|3>
 
-Confirm to user with: `Lesson saved: activity #<id>`.
+Confirm to user with: `Lesson saved: #<id>`.
 
 ## Examples
 

package/hook-llm.mjs

@@ -119,6 +119,17 @@ function buildFtsTextField(obs) {
   return { conceptsText, factsText, textField: [conceptsText, factsText, aliasesText, bigramText, fallbackText].filter(Boolean).join(' ') };
 }
 
+// TF-IDF vector text. Must mirror the FTS-searchable content so the vector arm and
+// the BM25 arm rank on the same signal — including lesson_learned (highest FTS
+// weight) and search_aliases (finding #8: previously omitted, so even with vectors
+// enabled the paraphrase-bridge alias terms were invisible to cosine similarity).
+export function buildVecText(obs) {
+  const conceptsText = Array.isArray(obs.concepts) ? obs.concepts.join(' ') : (obs.concepts || '');
+  const aliasesText = obs.searchAliases || '';
+  return [obs.title || '', obs.narrative || '', conceptsText, obs.lessonLearned || '', aliasesText]
+    .filter(Boolean).join(' ');
+}
+
 /**
  * Save an observation to the database with three-tier dedup.
  * @returns {number|null} The saved observation ID, or null if deduped.
@@ -256,8 +267,7 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
       });
 
       insertObservationFiles(db, id, obs.files);
-      const vecText = [obs.title || '', obs.narrative || '', (Array.isArray(obs.concepts) ? obs.concepts.join(' ') : '')].filter(Boolean).join(' ');
-      insertObservationVector(db, id, vecText);
+      insertObservationVector(db, id, buildVecText(obs));
 
       return id;
     })();

package/hook-optimize.mjs

@@ -79,6 +79,27 @@ export function rebuildVector(db, obsId, textParts) {
  */
 export function findReenrichCandidates(db, limit = 10, { scope = 'narrow', project } = {}) {
   const projectClause = project ? 'AND project = ?' : '';
+  if (scope === 'aliases') {
+    // P1 alias backfill: substantive rows missing search_aliases, REGARDLESS of
+    // lesson. Targets lesson-bearing manual saves (mem_save writes no aliases →
+    // paraphrase-unfindable) that narrow (needs lesson NULL) and wide (needs
+    // lesson NULL) both skip. Idempotent via search_aliases becoming non-null —
+    // deliberately NOT gated on optimized_at, so a lesson-less row can still be
+    // picked up by wide scope for lesson enrichment afterward.
+    const stmt = db.prepare(`
+      SELECT id, title, narrative, type, subtitle, concepts, facts, text, search_aliases, project
+      FROM observations
+      WHERE COALESCE(compressed_into, 0) = 0
+        AND superseded_at IS NULL
+        AND (search_aliases IS NULL OR search_aliases = '')
+        AND LENGTH(COALESCE(narrative, '')) > 100
+        AND ${notLowSignalTitleClause('')}
+        ${projectClause}
+      ORDER BY created_at_epoch DESC
+      LIMIT ?
+    `);
+    return project ? stmt.all(project, limit) : stmt.all(limit);
+  }
   if (scope === 'wide') {
     const stmt = db.prepare(`
       SELECT id, title, narrative, type, subtitle, concepts, facts, search_aliases, project
@@ -126,6 +147,33 @@ export async function executeReenrich(db, limit = 10, { scope = 'narrow', projec
     if (!gotSlot) { skipped++; continue; }
 
     try {
+      if (scope === 'aliases') {
+        // Alias-only backfill: generate search_aliases and APPEND them (plus any
+        // CJK bigrams) to the EXISTING FTS text. Never rebuild text from
+        // concepts/facts (empty on manual saves → would drop the original
+        // narrative terms and regress recall) and never touch the user's curated
+        // title / narrative / lesson / type / importance.
+        const aliasPrompt = `Generate alternative search terms so this memory is findable by paraphrase, synonym, or cross-language queries. Return ONLY valid JSON, no markdown fences.
+
+Title: ${truncate(cand.title || '(untitled)', 200)}
+Narrative: ${truncate(cand.narrative || '(no narrative)', 500)}
+
+JSON: {"search_aliases":["alt phrasing","synonym","spelled-out jargon","CJK term if the domain word has one"]}
+Give 3-6 aliases: words a user might search for the SAME concept but that are NOT already in the title (synonyms, the spelled-out form of an acronym, the jargon term for a described symptom, a CJK translation of a key domain term).`;
+        const parsed = await callModelJSON(aliasPrompt, 'haiku', { timeout: 15000, maxTokens: 300 });
+        const aliasArr = parsed && Array.isArray(parsed.search_aliases)
+          ? parsed.search_aliases.filter((a) => typeof a === 'string' && a.trim().length > 0)
+          : [];
+        if (!aliasArr.length) { skipped++; continue; }
+        const searchAliases = aliasArr.slice(0, 6).join(' ');
+        const aliasBigrams = cjkBigrams(searchAliases);
+        const appendedText = [cand.text || '', searchAliases, aliasBigrams].filter(Boolean).join(' ');
+        const safe = scrubRecord('observations', { text: appendedText, search_aliases: searchAliases });
+        db.prepare(`UPDATE observations SET search_aliases = ?, text = ? WHERE id = ?`)
+          .run(safe.search_aliases, safe.text, cand.id);
+        processed++;
+        continue;
+      }
       const prompt = `Re-enrich this observation with structured metadata. Return ONLY valid JSON, no markdown fences.
 
 Title: ${truncate(cand.title || '(untitled)', 200)}
@@ -780,6 +828,9 @@ export function optimizePreview(db, { project, detail = false } = {}) {
   // R-7: also report the widened-scope candidate count so users can see how many
   // bugfix/refactor/feature/decision observations are eligible for lesson backfill.
   const reenrichWide = findReenrichCandidates(db, 5000, { scope: 'wide', project }).length;
+  // P1: alias-backfill eligibility — substantive rows missing search_aliases
+  // (incl. lesson-bearing manual saves) that narrow+wide both skip.
+  const reenrichAliases = findReenrichCandidates(db, 5000, { scope: 'aliases', project }).length;
 
   const concepts = extractUniqueConcepts(db, 500, { project });
   const normalizeReady = shouldRunNormalize() && concepts.length >= 5;
@@ -794,6 +845,7 @@ export function optimizePreview(db, { project, detail = false } = {}) {
   const result = {
     reenrich,
     reenrichWide,
+    reenrichAliases,
     normalize: normalizeReady ? concepts.length : 0,
     normalizeGateOpen: shouldRunNormalize(),
     clusterMerge,
@@ -822,8 +874,10 @@ export function optimizePreview(db, { project, detail = false } = {}) {
  *   would silently waste 60% of the requested budget.
  * @param {number} [opts.maxItems=15] Total item budget across all selected tasks.
  * @param {boolean} [opts.force=false] Bypass time-based gates (e.g. normalize interval).
- * @param {'narrow'|'wide'} [opts.reenrichScope='narrow'] Scope for the re-enrich task.
+ * @param {'narrow'|'wide'|'aliases'} [opts.reenrichScope='narrow'] Scope for the re-enrich task.
  *   'wide' targets bugfix/refactor/feature/decision with narrative but no lesson (R-7).
+ *   'aliases' (P1) backfills search_aliases on substantive alias-less rows regardless
+ *   of lesson (lesson-bearing manual saves) — adds ONLY aliases, never rewrites content.
  * @param {string} [opts.project] Filter all tasks to a single project. Opt-in;
  *   absence preserves the prior all-projects default.
  */

package/lib/activity.mjs

@@ -6,6 +6,12 @@
 
 import { sanitizeFtsQuery } from '../utils.mjs';
 import { scrubRecord } from './scrub-record.mjs';
+import { saveObservation } from './save-observation.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 EVENT_TO_OBS_TYPE = { bug: 'bugfix', lesson: 'discovery', observation: 'discovery' };
 
 /**
  * Canonical event_type enum — mirrors the events.event_type CHECK constraint.
@@ -118,3 +124,51 @@ export function recentEvents(db, { project, type = null, limit = 20 } = {}) {
   const params = type ? [project, type, limit] : [project, limit];
   return db.prepare(sql).all(...params);
 }
+
+/**
+ * P2(b) one-time backfill: promote insight-bearing events (body present,
+ * importance>=minImportance) into searchable observations. mem_search / passive
+ * injection never read the events table, so explicit /bug /lesson history and
+ * high-value auto-captured events were unfindable. Each promoted event is marked
+ * (superseded_at_epoch + superseded_by_id → the new obs id) so re-runs are
+ * idempotent. The source event row is kept (activity log intact), just retired.
+ *
+ * @returns {{eligible:number, promoted:number, deduped:number}}
+ */
+export function promoteInsightEvents(db, { project = null, minImportance = 2, execute = false, limit = 5000 } = {}) {
+  const projClause = project ? 'AND project = ?' : '';
+  const sql = `
+    SELECT id, project, event_type, title, body, file_paths, importance, created_at_epoch
+    FROM events
+    WHERE body IS NOT NULL AND TRIM(body) != '' AND importance >= ?
+      AND superseded_at_epoch IS NULL ${projClause}
+    ORDER BY created_at_epoch DESC LIMIT ?
+  `;
+  const rows = project ? db.prepare(sql).all(minImportance, project, limit) : db.prepare(sql).all(minImportance, limit);
+  if (!execute) return { eligible: rows.length, promoted: 0, deduped: 0 };
+
+  const mark = db.prepare('UPDATE events SET superseded_at_epoch = ?, superseded_by_id = ? WHERE id = ?');
+  let promoted = 0;
+  let deduped = 0;
+  for (const ev of rows) {
+    const type = OBS_TYPES.has(ev.event_type) ? ev.event_type : (EVENT_TO_OBS_TYPE[ev.event_type] || 'discovery');
+    let files = [];
+    try { const p = JSON.parse(ev.file_paths || '[]'); if (Array.isArray(p)) files = p; } catch { /* keep [] */ }
+    const r = saveObservation(db, {
+      content: ev.body,
+      title: ev.title || undefined,
+      type,
+      importance: ev.importance,
+      project: ev.project,
+      files,
+      // The event body IS the insight → also seed lesson_learned (capped like the
+      // manual-save contract) so it lands in the high-weight FTS field.
+      lesson_learned: ev.body.slice(0, 500),
+      now: new Date(ev.created_at_epoch),
+    });
+    const linkId = r.kind === 'saved' ? r.id : r.existingId;
+    mark.run(Date.now(), linkId, ev.id);
+    if (r.kind === 'saved') promoted++; else deduped++;
+  }
+  return { eligible: rows.length, promoted, deduped };
+}

package/lib/cite-back-hint.mjs

@@ -125,6 +125,11 @@ function cooldownPathFor(sessionId, runtimeDir) {
 // turning per-episode hints into cross-session pressure.
 const UNSAVED_BUGFIX_LITERAL = 'Unsaved bugfix-shape';
 const ACTIVITY_SAVE_LESSON_RE = /activity\s+save\s+--type\s+(lesson|bugfix)\b/;
+// P2(a): /bug and /lesson were redirected from `activity save` (events) to
+// `cli.mjs save … --lesson` (searchable observations). Recognize that shape too,
+// or the unsaved-bugfix nudge over-fires after an explicit save. Anchored on the
+// mem CLI + the --lesson flag both skills always pass.
+const OBS_INSIGHT_SAVE_RE = /(?:cli\.mjs|claude-mem-lite)['"]?\s+save\b[^\n]*--lesson(?:-learned)?\b/;
 const MEM_SAVE_TOOL_NAMES = new Set([
   'mem_save',
   'mcp__claude_mem_lite__mem_save',
@@ -165,7 +170,7 @@ export function countUnsavedBugfixShape(transcriptPath) {
         }
         if (block.name === 'Bash') {
           const cmd = block.input?.command || '';
-          if (ACTIVITY_SAVE_LESSON_RE.test(cmd)) saved++;
+          if (ACTIVITY_SAVE_LESSON_RE.test(cmd) || OBS_INSIGHT_SAVE_RE.test(cmd)) saved++;
         }
       }
     }

package/lib/save-observation.mjs

@@ -119,6 +119,31 @@ export function saveObservation(db, params) {
   });
   const savedId = saveTx();
 
+  // P4 explicit supersession: tombstone + link prior observations this save
+  // overturns. Only same-project, currently-live rows are eligible — never
+  // tombstone another project's memory or re-stamp an already-superseded row —
+  // and never supersede the row we just wrote. superseded_at drops the row out of
+  // live search (all queries filter superseded_at IS NULL); superseded_by records
+  // WHICH observation replaced it (the missing link in finding #4). The column
+  // already exists (schema.mjs), so no migration is required.
+  let supersededIds = [];
+  const requested = Array.isArray(params.supersedes) ? params.supersedes : [];
+  const ids = [...new Set(
+    requested.map(Number).filter((n) => Number.isInteger(n) && n > 0 && n !== savedId)
+  )];
+  if (ids.length > 0) {
+    const ph = ids.map(() => '?').join(',');
+    const eligible = db.prepare(
+      `SELECT id FROM observations WHERE id IN (${ph}) AND project = ? AND superseded_at IS NULL`
+    ).all(...ids, project).map((r) => r.id);
+    if (eligible.length > 0) {
+      const ph2 = eligible.map(() => '?').join(',');
+      db.prepare(`UPDATE observations SET superseded_at = ?, superseded_by = ? WHERE id IN (${ph2})`)
+        .run(now.getTime(), savedId, ...eligible);
+      supersededIds = eligible;
+    }
+  }
+
   return {
     kind: 'saved',
     id: savedId,
@@ -126,5 +151,6 @@ export function saveObservation(db, params) {
     project,
     title: safeTitle,
     lessonCaptured: Boolean(safeLesson),
+    supersededIds,
   };
 }

package/mem-cli.mjs

@@ -747,7 +747,7 @@ function cmdSave(db, args) {
   const { positional, flags } = parseArgs(args);
   const text = positional.join(' ');
   if (!text.trim()) {
-    fail('[mem] Usage: claude-mem-lite save "<text>" [--type T] [--title T] [--importance N] [--project P] [--files f1,f2] [--lesson T] [--closes-deferred 1,D#42]');
+    fail('[mem] Usage: claude-mem-lite save "<text>" [--type T] [--title T] [--importance N] [--project P] [--files f1,f2] [--lesson T] [--closes-deferred 1,D#42] [--supersedes 8754,8771]');
     return;
   }
 
@@ -804,6 +804,20 @@ function cmdSave(db, args) {
     }
   }
 
+  // --supersedes: comma-separated observation ids this save overturns. On save they
+  // are tombstoned (drop out of live search) + linked (superseded_by = the new id).
+  // Only same-project live rows are affected (enforced in saveObservation).
+  let supersedesIds = null;
+  if (flags.supersedes !== undefined && flags.supersedes !== false) {
+    const raw = String(flags.supersedes);
+    supersedesIds = raw.split(',').map(t => t.trim()).filter(Boolean)
+      .map(t => parseInt(t, 10)).filter(n => Number.isInteger(n) && n > 0);
+    if (supersedesIds.length === 0) {
+      fail('[mem] --supersedes requires at least one positive observation id (e.g. --supersedes 8754,8771)');
+      return;
+    }
+  }
+
   let result;
   let closesIds = null;
   try {
@@ -816,6 +830,7 @@ function cmdSave(db, args) {
         project,
         files: saveFiles,
         lesson_learned: rawLesson,
+        supersedes: supersedesIds || undefined,
       });
       // Skip closure on dedup short-circuit — the obs row already exists, so
       // the deferred item should NOT be re-closed by a duplicate save call.
@@ -847,7 +862,10 @@ function cmdSave(db, args) {
   const closedNote = closesIds && closesIds.length > 0
     ? ` Closed: ${closesIds.map(i => `D#${i}`).join(', ')}.`
     : '';
-  out(`[mem] Saved #${result.id} [${result.type}] "${truncate(result.title, 80)}" (project: ${result.project})${lessonNote}${closedNote}`);
+  const supersededNote = result.supersededIds && result.supersededIds.length > 0
+    ? ` Superseded: ${result.supersededIds.map(i => `#${i}`).join(', ')}.`
+    : '';
+  out(`[mem] Saved #${result.id} [${result.type}] "${truncate(result.title, 80)}" (project: ${result.project})${lessonNote}${closedNote}${supersededNote}`);
 }
 
 // ─── cmdDefer (sub-dispatch: add | list | drop) ──────────────────────────────
@@ -2634,7 +2652,10 @@ Commands:
     --run-all           Execute bypassing gates
     --task T            Comma-separated: re-enrich,normalize,cluster-merge,smart-compress
     --max N             Max items per task (1-100, default 15)
-    --scope S           re-enrich scope: narrow (default) or wide
+    --scope S           re-enrich scope: narrow (default) | wide | aliases
+                        (aliases: backfill search_aliases on substantive rows that
+                         lack them — incl. lesson-bearing manual saves — adds ONLY
+                         aliases, never rewrites title/narrative/lesson)
     --project P         Limit to a single project (.|current = inferProject())
     --verbose / -v      Preview also dumps cluster contents + re-enrich samples
 
@@ -2965,8 +2986,8 @@ async function cmdOptimize(db, args) {
   let reenrichScope = 'narrow';
   if (scopeIdx >= 0 && args[scopeIdx + 1] !== undefined) {
     const raw = args[scopeIdx + 1];
-    if (raw !== 'narrow' && raw !== 'wide') {
-      fail(`[mem] Invalid --scope "${raw}". Use: narrow, wide`);
+    if (raw !== 'narrow' && raw !== 'wide' && raw !== 'aliases') {
+      fail(`[mem] Invalid --scope "${raw}". Use: narrow, wide, aliases`);
       return;
     }
     reenrichScope = raw;
@@ -2985,7 +3006,7 @@ async function cmdOptimize(db, args) {
     const preview = optimizePreview(db, { project, detail: verbose });
     out('[mem] 🔍 LLM Optimization Preview:');
     if (project) out(`  Project filter: ${project}`);
-    out(`  Re-enrich candidates: ${preview.reenrich}${preview.reenrichWide !== undefined && preview.reenrichWide !== null ? `  (wide scope: ${preview.reenrichWide})` : ''}`);
+    out(`  Re-enrich candidates: ${preview.reenrich}${preview.reenrichWide !== undefined && preview.reenrichWide !== null ? `  (wide scope: ${preview.reenrichWide})` : ''}${preview.reenrichAliases ? `  (aliases scope: ${preview.reenrichAliases})` : ''}`);
     out(`  Normalize: ${preview.normalizeGateOpen ? `${preview.normalize} unique concepts` : 'gate closed (7-day interval)'}`);
     out(`  Cluster-merge: ${preview.clusterMerge} clusters`);
     out(`  Smart-compress: ${preview.smartCompress} clusters`);
@@ -3019,7 +3040,7 @@ async function cmdOptimize(db, args) {
     return;
   }
 
-  out(`[mem] Running LLM optimization${reenrichScope === 'wide' ? ' (scope: wide)' : ''}${project ? ` (project: ${project})` : ''}...`);
+  out(`[mem] Running LLM optimization${reenrichScope !== 'narrow' ? ` (scope: ${reenrichScope})` : ''}${project ? ` (project: ${project})` : ''}...`);
   const results = await optimizeRun(db, { tasks, maxItems, force: runAll, reenrichScope, project });
 
   if (results.reenrich) out(`  Re-enrich: ${results.reenrich.processed || 0} processed, ${results.reenrich.skipped || 0} skipped`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.38.3",
+  "version": "3.39.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/search-scoring.mjs

@@ -32,7 +32,7 @@ const INSTRUCTIONS_BASE = [
   `  ${CLI_INVOKE} get 42,43  — full details by ID`,
   `  ${CLI_INVOKE} timeline --anchor 42  — chronological context`,
   '',
-  'MCP tools: mem_search, mem_recent, mem_save, mem_get, mem_recall, mem_timeline. If already loaded, call directly (warm server, fastest path). In tool-heavy sessions these are deferred behind ToolSearch — if using one would cost a ToolSearch load first, run the Bash CLI above instead: one call, not two. Neither needs a PATH/CLI install.',
+  'MCP tools: mem_search, mem_recent, mem_save, mem_get, mem_recall, mem_timeline (plus mem_defer/mem_defer_list/mem_defer_drop for cross-session TODOs). If already loaded, call directly (warm server, fastest path). In tool-heavy sessions these are deferred behind ToolSearch — if using one would cost a ToolSearch load first, run the Bash CLI above instead: one call, not two. Neither needs a PATH/CLI install.',
   'mem_save: Save non-obvious insights (bugfix lessons, architecture decisions).',
   'Search tips: short keywords (2-3 words), filter with obs_type when relevant.',
 ];
@@ -46,6 +46,7 @@ const INSTRUCTIONS_VERBOSE = [
   '  • Starting new feature → mem_search(query="feature area") for prior art & patterns',
   '  • After fixing a tricky bug → mem_save(type="bugfix", lesson_learned="root cause & fix")',
   '  • After architecture decision → mem_save(type="decision", lesson_learned="rationale")',
+  '  • Deferring work to a future session → mem_defer(title, priority, detail); when fixed, mem_save(..., closes_deferred=[N])',
   '  • Hook-injected context mentions #ID → mem_get(ids=[ID]) for full details',
   '',
   'Decision rules (use INSTEAD OF multi-step search):',

package/server.mjs

@@ -710,6 +710,7 @@ server.registerTool(
           project,
           files: args.files || [],
           lesson_learned: args.lesson_learned,
+          supersedes: args.supersedes,
         });
         if (r.kind === 'duplicate') return r; // dedup short-circuits BEFORE resolver — replay is idempotent
         // Resolve INSIDE tx + after dedup check so duplicate replays don't throw on
@@ -738,7 +739,10 @@ server.registerTool(
     const closedNote = closesIds && closesIds.length > 0
       ? ` Closed deferred: ${closesIds.map(i => `D#${i}`).join(', ')}.`
       : '';
-    return { content: [{ type: 'text', text: `Saved as observation #${result.id} [${result.type}] in project "${project}".${lessonNote}${closedNote}` }] };
+    const supersededNote = result.supersededIds && result.supersededIds.length > 0
+      ? ` Superseded: ${result.supersededIds.map(i => `#${i}`).join(', ')}.`
+      : '';
+    return { content: [{ type: 'text', text: `Saved as observation #${result.id} [${result.type}] in project "${project}".${lessonNote}${closedNote}${supersededNote}` }] };
   })
 );
 

package/tool-schemas.mjs

@@ -171,6 +171,15 @@ const coerceDeferredTokens = z.preprocess(
   ])).min(1).max(20)
 );
 
+// Coerce supersedes input — array of positive observation ids (accept numeric
+// strings from MCP bridges that JSON-stringify ints). Empty/other shapes reject.
+const coerceSupersedes = z.preprocess(
+  (v) => (Array.isArray(v)
+    ? v.map(x => (typeof x === 'string' && /^\d+$/.test(x.trim()) ? parseInt(x.trim(), 10) : x))
+    : v),
+  z.array(z.number().int().positive()).min(1).max(20)
+);
+
 export const memSaveSchema = {
   content: z.string().min(1).max(50000).describe('Memory content to save'),
   title: z.string().optional().describe('Short title'),
@@ -180,6 +189,7 @@ export const memSaveSchema = {
   files: coerceStringArray.optional().describe('File paths associated with this observation'),
   lesson_learned: z.string().max(500).optional().describe('Key lesson or takeaway (for bugfix: root cause & fix; for decision: rationale)'),
   closes_deferred: coerceDeferredTokens.optional().describe('Close one or more deferred_work items in the same project. Mixed array: bare integer = ordinal-within-project, "D#<n>" string = raw id. Transactional with the obs insert — a single invalid id rolls back the whole save.'),
+  supersedes: coerceSupersedes.optional().describe('Observation ids (same project) that this save overturns. They are marked superseded — dropped from live search — and linked to the new row (superseded_by). Use ONLY when this genuinely replaces a prior conclusion; do NOT use for merely-related or updated-but-still-valid memories.'),
 };
 
 export const memStatsSchema = {

package/utils.mjs

@@ -122,8 +122,13 @@ export function computeRuleImportance(episode) {
     lastWasError = entry.isError || sig?.isError;
 
     if (sig?.isError && (sig?.isTest || sig?.isBuild)) { importance = 3; break; }
-    if (files.some(f => /\.(env|pem|key)$|\/auth\.|\/credential|\/password/i.test(f))) { importance = 3; break; }
-    if (files.some(f => /migration|schema\.|prisma|alembic/i.test(f))) { importance = 3; break; }
+    // Sensitive-file → critical only when the file was EDITED, not merely read or
+    // referenced in a bash command (finding #7): reading auth.js / .env / schema.mjs
+    // incidentally during an unrelated task must not promote the whole memory to
+    // imp=3 and outrank genuine memories in top-K injection.
+    const isEdit = EDIT_TOOLS.has(entry.tool);
+    if (isEdit && files.some(f => /\.(env|pem|key)$|\/auth\.|\/credential|\/password/i.test(f))) { importance = 3; break; }
+    if (isEdit && files.some(f => /migration|schema\.|prisma|alembic/i.test(f))) { importance = 3; break; }
     if (sig?.isError && importance < 2) importance = 2;
     if (sig?.isGit && importance < 2) importance = 2;
     if (sig?.isDeploy && importance < 2) importance = 2;