claude-mem-lite 3.16.2 → 3.16.3

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.16.2",
+      "version": "3.16.3",
       "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.16.2",
+  "version": "3.16.3",
   "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/adopt-content.mjs

@@ -43,6 +43,8 @@ PreToolUse hooks already run \`mem_recall\` for past lessons before Read/Edit/Wr
 | Deferring to a future session | \`mem_defer({title, priority:1|2|3, detail})\`; when fixed, add \`closes_deferred=[N]\` to \`mem_save\` |
 | Looking up past work / history | \`mem_search "keywords"\` · \`mem_recent\` · \`mem_timeline\` |
 
+Path cost is round-trips, not milliseconds: the PreToolUse hook above already recalls (0 calls) — prefer it. For an explicit query, if these \`mem_*\` tools are deferred behind ToolSearch this session, the Bash CLI (exact path in the detail doc) is one call vs two (ToolSearch + call).
+
 Full tool + CLI tables, citation/decay rules, and save discipline → \`.claude/plugin_claude_mem_lite.md\``;
 }
 
@@ -77,6 +79,16 @@ PreToolUse hook 在你 Read / Edit / Write 文件前已自动 \`mem_recall\` 该
 \`mem_search\` / \`mem_recent\` / \`mem_recall\` / \`mem_get\` / \`mem_save\` / \`mem_timeline\` +
 \`mem_defer\` / \`mem_defer_list\` / \`mem_defer_drop\`。
 
+### 选 MCP 还是 CLI：按 round-trip,不是执行毫秒
+
+真正的开销是模型往返次数,不是工具执行——暖 MCP 调用 ~25ms、CLI 冷启 ~90ms,在一次推理(秒级)面前都是噪声。按往返次数选路：
+
+1. **被动 hook（0 往返）**：上面的 PreToolUse recall 已自动跑,最快,优先采纳,别重复调。
+2. **CLI via Bash（1 往返）**：工具多的会话里 \`mem_*\` 会被 defer 到 ToolSearch 后面——这时一次 MCP 调用 = ToolSearch + call = **2 往返**,而 Bash 跑一条 CLI 只 **1 往返**。派出去的子 agent 通常也拿不到 \`mem_*\` 工具,CLI 是它唯一的 1-往返路径。用下面「CLI 速查」表里的命令。
+3. **MCP 直调（已加载时 1 往返）**：\`mem_*\` 已在上下文里(未被 defer)就直接调,暖进程执行最快、省掉 ToolSearch。
+
+一句话：能让 hook 代劳就别调；要显式查,若得先 ToolSearch 才能用 \`mem_*\`,改跑 CLI。
+
 | 时机 | 工具 | 关键参数 |
 |------|------|----------|
 | Edit / Write 前 | \`mem_recall\` | \`file="<路径>"\`（hook 通常已代劳） |

package/format-utils.mjs

@@ -24,6 +24,32 @@ export function truncate(str, max = 80) {
   return str.slice(0, end) + '\u2026';
 }
 
+/**
+ * Render the PostToolUse error-recall hint block (hook.mjs::triggerErrorRecall).
+ * The single most-relevant hit (rows[0]) that carries a lesson_learned gets its
+ * lesson INLINED, so the agent can act with zero follow-up round-trips: the old
+ * "pointer + mem_get for details" form cost a deferred mem_get (2 model turns in
+ * tool-heavy sessions, where mem_* is gated behind ToolSearch) at the exact
+ * moment a fix is needed. Later rows stay as #ID pointers to keep the injected
+ * payload bounded (one body, not three). Upstream noise gating (low-signal title
+ * exclusion) is the SELECT's job (see triggerErrorRecall).
+ * @param {Array<{id:number,type:string,title:string,lesson_learned?:string}>} rows
+ * @returns {string} stdout block (trailing newline) or '' when there are no rows
+ */
+export function formatErrorRecallHints(rows) {
+  if (!rows || rows.length === 0) return '';
+  const lines = rows.map((r, i) => {
+    const head = `  #${r.id} [${r.type}] ${truncate(r.title, 60)}`;
+    // Inline the lesson body for the single most-relevant hit only (bounded payload).
+    if (i === 0 && typeof r.lesson_learned === 'string' && r.lesson_learned.trim()) {
+      return `${head} \u2014 ${truncate(r.lesson_learned.trim(), 200)}`;
+    }
+    return head;
+  });
+  const ids = rows.map(r => r.id).join(',');
+  return `[claude-mem-lite] Related memories found for this error:\n${lines.join('\n')}\n  \u2192 Use mem_get(ids=[${ids}]) for details.\n`;
+}
+
 /**
  * Map observation type to its display emoji icon.
  * @param {string} type Observation type (decision, bugfix, feature, etc.)

package/hook.mjs

@@ -26,7 +26,7 @@ import {
   truncate, inferProject, detectBashSignificance,
   extractErrorKeywords, extractFilePaths, isRelatedToEpisode,
   makeEntryDesc, scrubSecrets, stripPrivate, EDIT_TOOLS, debugCatch, debugLog,
-  COMPRESSED_AUTO, COMPRESSED_PENDING_PURGE, OBS_BM25,
+  COMPRESSED_AUTO, COMPRESSED_PENDING_PURGE, OBS_BM25, notLowSignalTitleClause, formatErrorRecallHints,
 } from './utils.mjs';
 import {
   readEpisodeRaw, episodeFile,
@@ -363,19 +363,18 @@ function triggerErrorRecall(db, toolInput, response) {
 
     const nowR = Date.now();
     const rows = db.prepare(`
-      SELECT o.id, o.type, o.title
+      SELECT o.id, o.type, o.title, o.lesson_learned
       FROM observations_fts
       JOIN observations o ON observations_fts.rowid = o.id
       WHERE observations_fts MATCH ? AND o.project = ?
+        AND ${notLowSignalTitleClause('o')}
       ORDER BY ${OBS_BM25}
         * (1.0 + EXP(-0.693 * (? - o.created_at_epoch) / 1209600000.0))
       LIMIT 3
     `).all(ftsQuery, project, nowR);
 
-    if (rows.length > 0) {
-      const hints = rows.map(r => `  #${r.id} [${r.type}] ${truncate(r.title, 60)}`).join('\n');
-      process.stdout.write(`[claude-mem-lite] Related memories found for this error:\n${hints}\n  → Use mem_get(ids=[${rows.map(r => r.id).join(',')}]) for details.\n`);
-    }
+    const out = formatErrorRecallHints(rows);
+    if (out) process.stdout.write(out);
   } catch (e) { debugCatch(e, 'triggerErrorRecall'); }
 }
 

package/lib/citation-tracker.mjs

@@ -10,7 +10,8 @@
 // column UPDATE including access_count. Per-row UPDATEs wrapped in try-catch
 // to prevent SQLITE_CORRUPT_VTAB cascades from stopping the whole scan.
 
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
 import { debugCatch } from '../utils.mjs';
 
 // `#123` / `#45678` at a word boundary — matches the CLAUDE.md cite pattern.
@@ -155,6 +156,11 @@ export function bumpCitationAccess(db, ids, project) {
 // Bounded type list mirrors observations.type CHECK + the events table's allowed
 // event_type values these surfaces can emit.
 const INJECTED_RE = /#(\d{1,7})\s+\[(bugfix|decision|change|discovery|feature|refactor|lesson)\]/g;
+// Line-anchored variant: a genuine injected ROW begins (after its short indent) with
+// `#NN [type]`. pre-tool-recall AND error-recall inline a lesson_learned body into the
+// row; a body that quotes another obs ("same as #1234 [decision]") must NOT count as
+// injected: that id would pollute the citation-decay denominator and falsely demote.
+const INJECTED_ROW_RE = new RegExp('^\\s{0,6}' + INJECTED_RE.source);
 
 // Add a numeric obs id to `set` if it parses to a sane in-range positive int.
 function addObsId(set, raw) {
@@ -229,9 +235,10 @@ export function extractInjectedFromPreToolUse(transcriptPath, opts = {}) {
   const ids = new Set();
   eachHookAttachment(transcriptPath, ({ command, text }) => {
     if (!command.includes('pre-tool-recall')) return;
-    INJECTED_RE.lastIndex = 0;
-    let m;
-    while ((m = INJECTED_RE.exec(text))) addObsId(ids, m[1]);
+    for (const line of text.split('\n')) {
+      const m = INJECTED_ROW_RE.exec(line);
+      if (m) addObsId(ids, m[1]);
+    }
   }, opts);
   return ids;
 }
@@ -293,11 +300,14 @@ export function extractInjectedFromErrorRecall(transcriptPath, opts = {}) {
   eachHookAttachment(transcriptPath, ({ command, text }) => {
     if (!command.includes('post-tool-use')) return;
     if (!text.includes('Related memories found for this error')) return;
-    // INJECTED_RE requires `#NN [type]`, so the trailing
-    // `→ Use mem_get(ids=[7933,8455])` line (bare numbers) is not matched.
-    INJECTED_RE.lastIndex = 0;
-    let m;
-    while ((m = INJECTED_RE.exec(text))) addObsId(ids, m[1]);
+    // Per-line anchored: match only a row that STARTS with `#NN [type]` (after its
+    // indent), NOT every such token in the block. The inlined lesson body (v3.16.x)
+    // can quote another obs id, which must not enter the injected set; the trailing
+    // `Use mem_get(ids=[...])` line (bare numbers) is excluded too.
+    for (const line of text.split('\n')) {
+      const m = INJECTED_ROW_RE.exec(line);
+      if (m) addObsId(ids, m[1]);
+    }
   }, opts);
   return ids;
 }
@@ -353,6 +363,72 @@ export function extractAllInjected(transcriptPath, opts = {}) {
   ]);
 }
 
+/**
+ * Cite-recall over ONE transcript file, using the SAME methodology as the
+ * citation-decay loop: injected = extractAllInjected (OUR hook injections only),
+ * cited = #NN in assistant text, ratio = |injected ∩ cited| / |injected|.
+ *
+ * Thread is keyed by FILE LOCATION, not the isSidechain field. Claude Code writes
+ * each subagent's turns to a SEPARATE file (<session>/subagents/agent-*.jsonl),
+ * NOT inline in the parent transcript (verified empirically: 0 isSidechain records
+ * across 60 parent transcripts; the subagent files carry isSidechain=true). So a
+ * whole subagent file IS the sidechain — aggregateProjectCiteRecall splits by path.
+ *
+ * @param {string} transcriptPath
+ * @returns {{injected: number, cited: number, recalled: number, ratio: number}}
+ */
+export function computeThreadCiteRecall(transcriptPath) {
+  const injected = extractAllInjected(transcriptPath);
+  const cited = extractCitationsFromTranscript(transcriptPath);
+  let recalled = 0;
+  for (const id of injected) if (cited.has(id)) recalled++;
+  return {
+    injected: injected.size,
+    cited: cited.size,
+    recalled,
+    ratio: injected.size > 0 ? recalled / injected.size : 0,
+  };
+}
+
+/**
+ * Aggregate cite-recall across a project's transcripts, split MAIN vs SIDECHAIN
+ * by file location. `txDir` = ~/.claude/projects/<encoded>/. Main = the top-level
+ * <session>.jsonl files; sidechain = every <session>/subagents/agent-*.jsonl.
+ * Descends ONE level into the literal `subagents` subdir only — no unbounded
+ * recursion. mtime-gated by `cutoff` (epoch ms; 0 = no window).
+ *
+ * @param {string} txDir
+ * @param {{cutoff?: number}} [opts]
+ * @returns {{main: {injected:number,recalled:number,files:number}, sidechain: {injected:number,recalled:number,files:number,withInjections:number}}}
+ */
+export function aggregateProjectCiteRecall(txDir, { cutoff = 0 } = {}) {
+  const main = { injected: 0, recalled: 0, files: 0 };
+  const sidechain = { injected: 0, recalled: 0, files: 0, withInjections: 0 };
+  const within = (p) => { try { return statSync(p).mtimeMs >= cutoff; } catch { return false; } };
+  let entries;
+  try { entries = readdirSync(txDir, { withFileTypes: true }); } catch { return { main, sidechain }; }
+  for (const ent of entries) {
+    const full = join(txDir, ent.name);
+    if (ent.isFile() && ent.name.endsWith('.jsonl')) {
+      if (!within(full)) continue;
+      const r = computeThreadCiteRecall(full);
+      main.injected += r.injected; main.recalled += r.recalled; main.files++;
+    } else if (ent.isDirectory()) {
+      let subFiles;
+      try { subFiles = readdirSync(join(full, 'subagents')); } catch { continue; }
+      for (const sf of subFiles) {
+        if (!sf.endsWith('.jsonl')) continue;
+        const sp = join(full, 'subagents', sf);
+        if (!within(sp)) continue;
+        const r = computeThreadCiteRecall(sp);
+        sidechain.injected += r.injected; sidechain.recalled += r.recalled; sidechain.files++;
+        if (r.injected > 0) sidechain.withInjections++;
+      }
+    }
+  }
+  return { main, sidechain };
+}
+
 /**
  * True iff the transcript contains at least one non-whitespace text block from
  * a main-thread assistant turn. Gates the citation-decay loop so a tool-only

package/mem-cli.mjs

@@ -26,8 +26,9 @@ import { buildSessionContextLines } from './hook-context.mjs';
 import { cmdAdopt, cmdUnadopt } from './adopt-cli.mjs';
 import { parseIntFlag, isNumericToken } from './lib/cli-flags.mjs';
 import { auditMemdir, memdirPath } from './memdir.mjs';
+import { aggregateProjectCiteRecall } from './lib/citation-tracker.mjs';
 import { probeOtherSources as probeIdSources, bucketIdTokens } from './lib/id-routing.mjs';
-import { join, sep } from 'path';
+import { join, sep, dirname } from 'path';
 import { readFileSync, existsSync, readdirSync } from 'fs';
 
 // v2.41: shared CLI helpers extracted to cli/common.mjs. Keep this file as the
@@ -2210,20 +2211,61 @@ function cmdMemdirAudit(args) {
   if (nonCompliant > 0) process.exitCode = 1;
 }
 
+// `citation-stats --sidechain`: subagent (sidechain) cite-recall, the blind spot the
+// main decay loop excludes (it runs mainOnly). aggregateProjectCiteRecall scans THIS
+// project's transcripts: top-level <session>.jsonl = main, and
+// <session>/subagents/agent-*.jsonl = sidechain (descends ONE level into the literal
+// subagents/ dir only, no unbounded recursion). Same methodology, so comparable.
+function _reportSidechainCiteRecall({ days, json }) {
+  const cutoff = Date.now() - days * 86400 * 1000;
+  // memdir = ~/.claude/projects/<encoded>/memory; transcripts are its siblings.
+  const txDir = dirname(memdirPath(process.cwd()));
+  const { main, sidechain } = aggregateProjectCiteRecall(txDir, { cutoff });
+  const rate = b => (b.injected > 0 ? (100 * b.recalled / b.injected) : null);
+  const sideRate = rate(sidechain), mainRate = rate(main);
+
+  if (json) {
+    out(JSON.stringify({
+      window_days: days,
+      main: { ...main, rate: mainRate },
+      sidechain: { ...sidechain, rate: sideRate },
+    }));
+    return;
+  }
+
+  const pct = r => (r === null ? '—' : `${r.toFixed(1)}%`);
+  out(`Sidechain (subagent) cite-recall — last ${days}d:`);
+  out(`  main        ${pct(mainRate).padStart(6)}   recalled ${main.recalled} / injected ${main.injected}   (${main.files} transcript(s))`);
+  out(`  sidechain   ${pct(sideRate).padStart(6)}   recalled ${sidechain.recalled} / injected ${sidechain.injected}   (${sidechain.files} subagent file(s), ${sidechain.withInjections} with injections)`);
+  if (sidechain.files > 0 && sidechain.injected === 0) {
+    out('  → subagent transcripts exist but received ZERO memory injections: claude-mem-lite');
+    out('    hooks do NOT fire inside subagents (no PreToolUse/PostToolUse recall, no');
+    out('    SessionStart block, no mem_* tools). Subagents are memory-blind — giving them');
+    out('    memory needs a NEW surface (inject at Agent/Task dispatch), not deepening.');
+  } else if (sidechain.files === 0) {
+    out('  → no subagent transcripts in window.');
+  }
+}
+
 /**
  * `citation-stats` — visualize the citation-decay feedback loop:
  * per-project cite rate + active decay queue + recently promoted.
  * Read-only over observations.
  *
  * Flags:
- *   --json      machine-readable output
- *   --days N    project cite-rate window (default 7)
+ *   --json       machine-readable output
+ *   --days N     project cite-rate window (default 7)
+ *   --sidechain  subagent (sidechain) cite-recall vs main — the decay-loop blind spot
  */
 function cmdCitationStats(db, args) {
   const { flags } = parseArgs(args);
   const json = flags.json === true || flags.json === 'true';
   const days = parseIntFlag(flags.days, { name: '--days', defaultValue: 7, max: 365 });
 
+  if (flags.sidechain === true || flags.sidechain === 'true') {
+    return _reportSidechainCiteRecall({ days, json });
+  }
+
   const cutoff = Date.now() - days * 86400 * 1000;
   const perProject = db.prepare(`
     SELECT project,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.16.2",
+  "version": "3.16.3",
   "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

@@ -15,9 +15,14 @@ import { CLI_INVOKE } from './cli-path.mjs';
 // Decision-rules sections; keeps the irreducible CLI/MCP tool list. Intended
 // for users who adopted invited-memory (MEMORY.md sentinel carries the same
 // triggers at higher authority). Default false preserves v2.31.2 behavior.
+// The CLI-vs-MCP round-trip routing rule lives in BASE (not VERBOSE) on purpose:
+// it must reach adopted (quiet) projects too, where tool-heavy sessions defer the
+// mem_* tools behind ToolSearch (CLI via Bash = 1 model round-trip; ToolSearch +
+// call = 2). Execution latency is NOT the lever — warm MCP (~25ms) actually beats
+// CLI cold-start (~90ms); both are noise against one model turn. Round-trips are.
 
 const INSTRUCTIONS_BASE = [
-  'Long-term memory across sessions. Hooks auto-inject context; CLI preferred for explicit queries.',
+  'Long-term memory across sessions. Hooks auto-inject context (0 round-trips) — prefer adopting that over any call. For an explicit query, pick the path with fewer model round-trips (CLI vs MCP below).',
   '',
   `CLI (via Bash) — invoke as \`${CLI_INVOKE} <cmd>\` (resolves on any install shape; the bare \`claude-mem-lite\` shorthand works only after an optional global \`npm i -g claude-mem-lite\`):`,
   `  ${CLI_INVOKE} search "query"  — FTS5 full-text search`,
@@ -27,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 for programmatic access (always available — no PATH/CLI install needed).',
+  '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.',
   'mem_save: Save non-obvious insights (bugfix lessons, architecture decisions).',
   'Search tips: short keywords (2-3 words), filter with obs_type when relevant.',
 ];

package/utils.mjs

@@ -14,7 +14,7 @@ export { cjkBigrams, extractCjkSynonymTokens, extractCjkKeywords, extractCjkLike
 export { resolveProject, _resetProjectCache } from './project-utils.mjs';
 export { scrubSecrets, SECRET_PATTERNS } from './secret-scrub.mjs';
 export { stripPrivate } from './lib/private-strip.mjs';
-export { truncate, typeIcon, fmtDate, fmtTime, isoWeekKey } from './format-utils.mjs';
+export { truncate, typeIcon, fmtDate, fmtTime, isoWeekKey, formatErrorRecallHints } from './format-utils.mjs';
 export { computeMinHash, estimateJaccardFromMinHash, jaccardSimilarity } from './hash-utils.mjs';
 export { detectBashSignificance, extractErrorKeywords, extractFilePaths, stripTestSuffix } from './bash-utils.mjs';