claude-mem-lite 3.5.0 → 3.6.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.5.0",
+      "version": "3.6.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.5.0",
+  "version": "3.6.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.mjs

@@ -54,6 +54,7 @@ import {
   bumpCitationAccess,
   computeCiteRecall,
   applyCitationDecay,
+  recordCitationFunnel,
   hasMainThreadAssistantText,
 } from './lib/citation-tracker.mjs';
 import { extractTailAssistantText, extractStructuredSummary } from './lib/summary-extractor.mjs';
@@ -572,6 +573,10 @@ async function handleStop() {
                 for (const id of citeBackIds) citedMain.add(id);
                 const r = applyCitationDecay(db, project, injected, citedMain, sessionId);
                 debugLog('DEBUG', 'handleStop', `citation-decay: touched=${r.touched} promoted=${r.promoted} demoted=${r.demoted}`);
+                // R1: persist this session's invocation→cite funnel row. touched =
+                // obs resolved this run (denominator), promoted = obs cited this run
+                // (numerator). Idempotent (touched is 0 on re-fire) + best-effort.
+                recordCitationFunnel(db, project, sessionId, r.touched, r.promoted);
               }
             }
           } catch (e) { debugCatch(e, 'handleStop-citation-decay'); }

package/lib/citation-tracker.mjs

@@ -544,3 +544,96 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
   try { txn(); } catch (e) { debugCatch(e, 'applyCitationDecay-txn'); return empty; }
   return { promoted, demoted, touched };
 }
+
+/**
+ * R1 — persist one accumulating per-session row of the invocation→cite funnel.
+ * Fed by applyCitationDecay's return: `injectedDelta` = obs RESOLVED this Stop
+ * (touched), `citedDelta` = obs CITED this Stop (promoted). Idempotent against
+ * Stop multi-fire by construction — a re-fired Stop re-resolves nothing (touched
+ * is 0 for already-decided obs), so the no-op gate below skips it. A later turn
+ * that resolves NEW injections accumulates onto the same (project, session) row.
+ *
+ * Unlike the per-obs cited_count/decay_seen_count counters (lifetime-cumulative,
+ * session breakdown lost), this preserves the per-session series that
+ * computeCitationFunnelTrend reads back as a trend. Telemetry only — every write
+ * is wrapped so a citation_log failure can never break the Stop handler.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} project
+ * @param {string} sessionId — memory_session_id of the resolved session
+ * @param {number} injectedDelta — obs resolved this run (applyCitationDecay.touched)
+ * @param {number} citedDelta — obs cited this run (applyCitationDecay.promoted)
+ */
+export function recordCitationFunnel(db, project, sessionId, injectedDelta, citedDelta) {
+  if (!db || !project || !sessionId) return;
+  const inj = Number(injectedDelta) || 0;
+  if (inj <= 0) return; // nothing resolved this run → no row noise
+  const cited = Math.max(0, Number(citedDelta) || 0);
+  try {
+    db.prepare(`
+      INSERT INTO citation_log (project, memory_session_id, resolved_at, injected_n, cited_n)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(project, memory_session_id) DO UPDATE SET
+        injected_n = injected_n + excluded.injected_n,
+        cited_n = cited_n + excluded.cited_n,
+        resolved_at = excluded.resolved_at
+    `).run(project, sessionId, Date.now(), inj, cited);
+  } catch (e) { debugCatch(e, 'recordCitationFunnel'); }
+}
+
+/**
+ * R1 — read the per-session invocation→cite funnel as a windowed trend.
+ * `window` aggregates [now-days, now]; `prior` aggregates [now-2*days, now-days)
+ * so `delta_pt` shows whether invocation effectiveness is rising or falling.
+ * `sessions` is the most-recent `limit` rows (per-session rate for the table view).
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {{days?: number, limit?: number, project?: string|null}} [opts]
+ * @returns {{window_days: number, sessions: Array, window: {injected:number,cited:number,rate:number}, prior: {injected:number,cited:number,rate:number}, delta_pt: number|null}}
+ */
+export function computeCitationFunnelTrend(db, { days = 7, limit = 10, project = null } = {}) {
+  const rate = (cited, inj) => (inj > 0 ? cited / inj : 0);
+  const empty = {
+    window_days: days,
+    sessions: [],
+    window: { injected: 0, cited: 0, rate: 0 },
+    prior: { injected: 0, cited: 0, rate: 0 },
+    delta_pt: null,
+  };
+  if (!db) return empty;
+  try {
+    const now = Date.now();
+    const windowStart = now - days * 86400000;
+    const priorStart = now - 2 * days * 86400000;
+    const projClause = project ? 'AND project = ?' : '';
+
+    const sessions = db.prepare(`
+      SELECT project, memory_session_id, resolved_at, injected_n, cited_n
+        FROM citation_log
+       WHERE 1=1 ${projClause}
+    ORDER BY resolved_at DESC
+       LIMIT ?
+    `).all(...(project ? [project, limit] : [limit]))
+      .map(r => ({ ...r, rate: rate(r.cited_n, r.injected_n) }));
+
+    const agg = (fromTs, toTs) => {
+      const params = toTs === null ? [fromTs] : [fromTs, toTs];
+      if (project) params.push(project);
+      const upper = toTs === null ? '' : 'AND resolved_at < ?';
+      const row = db.prepare(`
+        SELECT COALESCE(SUM(injected_n), 0) AS injected, COALESCE(SUM(cited_n), 0) AS cited
+          FROM citation_log
+         WHERE resolved_at >= ? ${upper} ${projClause}
+      `).get(...params);
+      return { injected: row.injected, cited: row.cited, rate: rate(row.cited, row.injected) };
+    };
+
+    const windowAgg = agg(windowStart, null);
+    const priorAgg = agg(priorStart, windowStart);
+    const delta_pt = priorAgg.injected > 0
+      ? Number(((windowAgg.rate - priorAgg.rate) * 100).toFixed(1))
+      : null;
+
+    return { window_days: days, sessions, window: windowAgg, prior: priorAgg, delta_pt };
+  } catch (e) { debugCatch(e, 'computeCitationFunnelTrend'); return empty; }
+}

package/mem-cli.mjs

@@ -40,6 +40,7 @@ import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentT
 import { buildSearchFtsQuery, parseDateBounds, computePerSourceWindow, effectiveObsFtsQuery, searchSessionsFts, searchPromptsFts, normalizeCrossSourceScores, applyUserSort, applyTierFilter } from './lib/search-core.mjs';
 import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { countRecentHookErrors } from './lib/hook-telemetry.mjs';
+import { computeCitationFunnelTrend } from './lib/citation-tracker.mjs';
 import { aggregateMetrics } from './lib/metrics.mjs';
 import {
   insertDeferred, listOpenWithOrdinal, dropDeferred,
@@ -2313,8 +2314,12 @@ function cmdCitationStats(db, args) {
     ? `${pollutedRows.n} obs have cited_count > decay_seen_count (pre-v34 backfill — invariant holds for new data).`
     : null;
 
+  // R1: per-session invocation→cite funnel trend (citation_log). Same `days` window
+  // as the per-project cite rate above; funnel.prior/delta_pt show the direction.
+  const funnel = computeCitationFunnelTrend(db, { days });
+
   if (json) {
-    out(JSON.stringify({ window_days: days, per_project: perProject, decay_queue: decayQueue, promoted, demoted, data_pollution_note: dataPollutionNote }, null, 2));
+    out(JSON.stringify({ window_days: days, per_project: perProject, decay_queue: decayQueue, promoted, demoted, data_pollution_note: dataPollutionNote, funnel }, null, 2));
     return;
   }
 
@@ -2325,6 +2330,28 @@ function cmdCitationStats(db, args) {
     out(`  ${r.project.padEnd(34)} ${String(rate).padStart(6)}   cited:${r.cited}/${r.resolved}   at_risk:${r.at_risk}`);
   }
   out('');
+
+  // R1: invocation→cite funnel — per-session trend + window-vs-prior direction.
+  out(`Invocation→cite funnel (recent sessions, injected→cited; rate window ${days}d):`);
+  if (funnel.sessions.length === 0) {
+    out('  (no resolved sessions in window)');
+  } else {
+    for (const s of funnel.sessions) {
+      const day = s.resolved_at ? new Date(s.resolved_at).toISOString().slice(0, 10) : '—'.repeat(10);
+      const pct = (s.rate * 100).toFixed(1) + '%';
+      out(`  ${day}  ${(s.project || '').padEnd(28)} inj ${String(s.injected_n).padStart(3)}  cited ${String(s.cited_n).padStart(3)}  ${pct.padStart(6)}`);
+    }
+  }
+  let trendLine = `window rate ${(funnel.window.rate * 100).toFixed(1)}%  cited ${funnel.window.cited}/${funnel.window.injected}`;
+  if (funnel.delta_pt === null) {
+    trendLine += '  (no prior-window data)';
+  } else {
+    const arrow = funnel.delta_pt > 0 ? '↑' : funnel.delta_pt < 0 ? '↓' : '→';
+    const sign = funnel.delta_pt > 0 ? '+' : '';
+    trendLine += `  (prior ${days}d ${(funnel.prior.rate * 100).toFixed(1)}%)  ${arrow} ${sign}${funnel.delta_pt}pt`;
+  }
+  out(trendLine);
+  out('');
   out('Active decay queue (uncited_streak >= 2, next miss → demote):');
   if (decayQueue.length === 0) out('  (none)');
   for (const r of decayQueue) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.5.0",
+  "version": "3.6.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/schema.mjs

@@ -71,7 +71,15 @@ export const CODE_DIR = join(homedir(), '.claude-mem-lite');
 // legacy trigger on existing DBs. LATEST_MIGRATION_COLUMN unchanged (no new column).
 // v37 (D#26): adds user_prompts.cc_session_id (additive, nullable). LATEST_MIGRATION_COLUMN
 // MOVES to it so the half-migrated-DB self-heal fast-path covers the new column.
-export const CURRENT_SCHEMA_VERSION = 37;
+// v38 (R1): citation_log table — per-session invocation→cite funnel telemetry. One
+// accumulating row per resolved session (injected_n / cited_n), written by
+// recordCitationFunnel from applyCitationDecay's touched/promoted at Stop. Turns the
+// per-obs cite counters (lifetime-cumulative) into a trendable per-session series so
+// `citation-stats` can answer "is memory invocation effectiveness rising or falling".
+// New TABLE (not a column) reached via CORE_SCHEMA's CREATE TABLE IF NOT EXISTS on the
+// forced migration pass; LATEST_MIGRATION_COLUMN unchanged (no new column) — same
+// pattern as v35/v36.
+export const CURRENT_SCHEMA_VERSION = 38;
 
 // Sentinel column for the LATEST migration set. The fast-path uses this to
 // self-heal half-migrated DBs — schema_version bumped but column ALTERs rolled
@@ -168,6 +176,15 @@ const CORE_SCHEMA = `
     created_at_epoch INTEGER,
     PRIMARY KEY (project, type, session_id)
   );
+
+  CREATE TABLE IF NOT EXISTS citation_log (
+    project TEXT NOT NULL,
+    memory_session_id TEXT NOT NULL,
+    resolved_at INTEGER,
+    injected_n INTEGER NOT NULL DEFAULT 0,
+    cited_n INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (project, memory_session_id)
+  );
 `;
 
 // Column migrations (idempotent — only swallow "duplicate column" errors)