claude-mem-lite 2.35.0 → 2.36.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.35.0",
+      "version": "2.36.0",
       "source": "./",
       "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.35.0",
+  "version": "2.36.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/hook-llm.mjs

@@ -16,6 +16,7 @@ import {
   sessionFile, getSessionId, openDb, callLLM, sleep,
 } from './hook-shared.mjs';
 import { EVENT_TYPES, saveEvent } from './lib/activity.mjs';
+import { isNoiseObservation } from './lib/low-signal-patterns.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.
@@ -69,6 +70,14 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
       VALUES (?, ?, ?, ?, ?, 'active')
     `).run(sessionId, sessionId, project, now.toISOString(), now.getTime());
 
+    // P0: write-side noise block — LOW_SIGNAL title with no recoverable signal
+    // (no lesson, importance<2, empty facts, thin narrative) is dropped before
+    // dedup/MinHash/vector work. Opt-out: CLAUDE_MEM_KEEP_LOW_SIGNAL=1.
+    if (isNoiseObservation(obs)) {
+      debugLog('saveObservation', `dropped noise: ${truncate(obs.title || '', 60)}`);
+      return null;
+    }
+
     // Three-tier dedup — returns null (not throw) for dedup hits
     // Tier 1 (fast): 5-min Jaccard on titles
     const fiveMinAgo = now.getTime() - DEDUP_WINDOW_MS;
@@ -464,6 +473,38 @@ export function buildImmediateObservation(episode) {
   };
 }
 
+// ─── Lesson retry prompt (P3) ───────────────────────────────────────────────
+
+/**
+ * Build a lesson-focused retry prompt after Haiku's first pass for
+ * bugfix/decision returned null/empty/'none'. Narrow ask: one non-obvious
+ * insight a future session would benefit from — either root cause (bugfix)
+ * or tradeoff (decision).
+ *
+ * @param {object} episode
+ * @param {object} firstPass — parsed first-pass response (title, type, narrative)
+ * @returns {string} prompt
+ */
+export function buildLessonRetryPrompt(episode, firstPass) {
+  const actionList = episode.entries.map((e, i) =>
+    `${i + 1}. [${e.tool}] ${e.desc}${e.isError ? ' (ERROR)' : ''}`
+  ).join('\n');
+  const typeHint = firstPass.type === 'bugfix'
+    ? 'For this bugfix: what was the root cause + how to spot it next time? Example: "FTS5 trigger fires on any UPDATE — wrap access_count writes in try/catch."'
+    : 'For this decision: what tradeoff was made + why? Example: "Chose single-source module over schema column because 1 drift point, not 4."';
+  return `A ${firstPass.type} episode just completed. First-pass title: "${firstPass.title || 'untitled'}".
+
+Actions:
+${actionList}
+
+${typeHint}
+
+If the work was purely mechanical with no insight worth remembering, reply {"lesson":"none"}.
+Otherwise reply in 12-280 chars.
+
+Reply ONLY valid JSON, no markdown fences: {"lesson":"..."}`;
+}
+
 // ─── Background: LLM Episode Extraction (Tier 2 F) ──────────────────────────
 
 export async function handleLLMEpisode() {
@@ -506,6 +547,7 @@ Action: ${e.desc}
 Error: ${e.isError ? 'yes' : 'no'}
 
 JSON: {"type":"decision|bugfix|feature|refactor|discovery|change","title":"concise ≤80 char description","narrative":"what changed, why, and outcome (2-3 sentences)","concepts":["kw1","kw2"],"facts":["fact1","fact2"],"importance":1,"lesson_learned":"non-obvious insight or 'none' if routine","search_aliases":["alt query 1","alt query 2"]}
+type: pick by strongest signal. decision = explicit tradeoff / "chose X over Y because Z" / rejected an approach (e.g. "Rejected schema migration — single-source module + sync test instead"; "Heterogeneous hook events → heterogeneous context budgets"). bugfix = prior-failing path fixed with a named root cause. feature = new user-visible capability. refactor = behavior unchanged but structure improved. discovery = learned how a system works (read-heavy, no writes). change = routine edit with no new principle (default if unsure and nothing else fits).
 Facts: each MUST be (1) atomic—one claim, (2) self-contained—no pronouns, include file/function name, (3) specific—"refreshToken() in auth.ts:45 uses 1h TTL" not "handles tokens"
 importance: Be strict — default to 1. 0=pure browsing with zero learning value. 1=routine file edits, standard changes, normal workflow (MOST episodes). 2=notable ONLY if it reveals something non-obvious: error fix with discovered root cause, architectural decision with explicit tradeoff, config change with unexpected side effects. 3=critical: breaking change affecting users, security vulnerability fix, data migration. Ask yourself: "would a future session benefit from knowing this?" — if not, it's importance=1.
 lesson_learned: REQUIRED field. State what was learned that isn't obvious from reading the code. Examples: "FTS5 porter stemmer doesn't tokenize CJK — need bigram workaround", "vitest --reporter=verbose hangs on large test suites, use default reporter". If purely routine with nothing learned, write "none" (not null).
@@ -523,6 +565,7 @@ Actions (${episode.entries.length} total):
 ${actionList}
 
 JSON: {"type":"decision|bugfix|feature|refactor|discovery|change","title":"coherent ≤80 char summary","narrative":"what was done, why, and outcome (3-5 sentences)","concepts":["keyword1","keyword2"],"facts":["specific fact 1","specific fact 2"],"importance":1,"lesson_learned":"non-obvious insight or 'none' if routine","search_aliases":["alt query 1","alt query 2"]}
+type: pick by strongest signal. decision = explicit tradeoff / "chose X over Y because Z" / rejected an approach (e.g. "Rejected schema migration — single-source module + sync test instead"; "Heterogeneous hook events → heterogeneous context budgets"). bugfix = prior-failing path fixed with a named root cause. feature = new user-visible capability. refactor = behavior unchanged but structure improved. discovery = learned how a system works (read-heavy, no writes). change = routine edit with no new principle (default if unsure and nothing else fits).
 Facts: each MUST be (1) atomic—one claim, (2) self-contained—no pronouns, include file/function name, (3) specific—"refreshToken() in auth.ts:45 uses 1h TTL" not "handles tokens"
 importance: Be strict — default to 1. 0=pure browsing with zero learning value. 1=routine file edits, standard changes, normal workflow (MOST episodes). 2=notable ONLY if it reveals something non-obvious: error fix with discovered root cause, architectural decision with explicit tradeoff, config change with unexpected side effects. 3=critical: breaking change affecting users, security vulnerability fix, data migration. Ask yourself: "would a future session benefit from knowing this?" — if not, it's importance=1.
 lesson_learned: REQUIRED field. State what was learned that isn't obvious from reading the code. Examples: "FTS5 porter stemmer doesn't tokenize CJK — need bigram workaround", "vitest --reporter=verbose hangs on large test suites, use default reporter". If purely routine with nothing learned, write "none" (not null).
@@ -570,7 +613,31 @@ search_aliases: 2-6 alternative search terms someone might use to find this memo
       const rawLesson = typeof parsed.lesson_learned === 'string' ? parsed.lesson_learned.trim() : '';
       const lowSignalLesson = new Set(['none', '', 'n/a', 'null', 'todo', 'tbd', 'na', '-', 'nothing', 'nil']);
       const isLessonLowSignal = lowSignalLesson.has(rawLesson.toLowerCase()) || rawLesson.length < 12;
-      const lessonLearned = isLessonLowSignal ? null : rawLesson.slice(0, 500);
+      let lessonLearned = isLessonLowSignal ? null : rawLesson.slice(0, 500);
+
+      // P3: for bugfix/decision, retry once with a lesson-focused prompt.
+      // These types have the highest reuse value (~72.7% hit-rate vs change
+      // ~16.5%), and Haiku's first pass writes NULL ~70% of the time for
+      // curated observations. Retry budget: 1 extra callLLM per bugfix/decision
+      // episode. Opt-out: CLAUDE_MEM_NO_LESSON_RETRY=1.
+      if (isLessonLowSignal &&
+          (parsed.type === 'bugfix' || parsed.type === 'decision') &&
+          !process.env.CLAUDE_MEM_NO_LESSON_RETRY) {
+        try {
+          const retryPrompt = buildLessonRetryPrompt(episode, parsed);
+          const retryRaw = callLLM(retryPrompt, 10000);
+          if (retryRaw) {
+            const retry = parseJsonFromLLM(retryRaw);
+            const retryLesson = typeof retry?.lesson === 'string' ? retry.lesson.trim() : '';
+            const retryIsLow = lowSignalLesson.has(retryLesson.toLowerCase()) || retryLesson.length < 12;
+            if (!retryIsLow) {
+              lessonLearned = retryLesson.slice(0, 500);
+              debugLog('DEBUG', 'llm-episode', `lesson-retry: recovered ${retryLesson.length}-char lesson for ${parsed.type}`);
+            }
+          }
+        } catch (e) { debugCatch(e, 'lesson-retry'); }
+      }
+
       const searchAliases = Array.isArray(parsed.search_aliases)
         ? parsed.search_aliases.slice(0, 6).join(' ')
         : null;

package/hook.mjs

@@ -42,6 +42,7 @@ import {
   spawnBackground,
 } from './hook-shared.mjs';
 import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObservation } from './hook-llm.mjs';
+import { extractCitationsFromTranscript, bumpCitationAccess } from './lib/citation-tracker.mjs';
 import { searchRelevantMemories } from './hook-memory.mjs';
 import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection, extractUnfinishedSummary } from './hook-handoff.mjs';
 import { checkForUpdate } from './hook-update.mjs';
@@ -344,12 +345,16 @@ async function handleStop() {
   // This is the stable CC identifier — the mem plugin's file-based getSessionId()
   // collides across parallel sessions for the same project (see docs/bug.txt).
   let ccSessionId = null;
+  let transcriptPath = null;
   try {
     const raw = await readStdin();
     const hookData = JSON.parse(raw.text);
     if (typeof hookData?.session_id === 'string' && hookData.session_id.length > 0) {
       ccSessionId = hookData.session_id;
     }
+    if (typeof hookData?.transcript_path === 'string' && hookData.transcript_path.length > 0) {
+      transcriptPath = hookData.transcript_path;
+    }
   } catch { /* stdin unavailable — fall back to local session id */ }
 
   // Capture session info BEFORE cleanup. All DB lookups use the mem-internal id
@@ -448,6 +453,19 @@ async function handleStop() {
           }
         }
       } catch (e) { debugCatch(e, 'handleStop-fast-summary'); }
+
+      // P4: scan transcript for `#NN` observation citations in assistant text
+      // and bump access_count for matched rows. Closes the loop on the "cite #NN"
+      // contract — before P4 this was a one-way obligation with no feedback.
+      try {
+        if (transcriptPath && !process.env.CLAUDE_MEM_NO_CITATION_TRACK) {
+          const ids = extractCitationsFromTranscript(transcriptPath);
+          if (ids.size > 0) {
+            const n = bumpCitationAccess(db, ids, project);
+            debugLog('DEBUG', 'handleStop', `citations: ${ids.size} ids scanned, ${n} obs bumped`);
+          }
+        }
+      } catch (e) { debugCatch(e, 'handleStop-citation-track'); }
     } finally {
       db.close();
     }

package/lib/citation-tracker.mjs

@@ -0,0 +1,82 @@
+// Citation tracker (P4): scan Claude Code transcript for `#NN` observation-id
+// citations in assistant text, then bulk-increment access_count for matched rows.
+//
+// Closes the loop on the CLAUDE.md "cite #NN" contract — before P4, citations
+// were a one-way obligation with no measurable feedback. Now each honored
+// citation bumps access_count, making contract compliance observable via
+// mem_stats and preventing cited lessons from decaying into dead memory.
+//
+// FTS5 caveat (project_non_obvious.md): observations_au trigger fires on any
+// 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 { debugCatch } from '../utils.mjs';
+
+// `#123` / `#45678` at a word boundary — matches the CLAUDE.md cite pattern.
+// Bounded to 1-7 digits to skip URL fragments, markdown anchors, etc.
+const CITATION_RE = /#(\d{1,7})\b/g;
+
+/**
+ * Parse a Claude Code transcript .jsonl and extract unique observation IDs
+ * cited inside assistant text blocks.
+ *
+ * @param {string} transcriptPath Path to transcript file (.jsonl)
+ * @returns {Set<number>} unique IDs referenced as `#NN` in assistant text
+ */
+export function extractCitationsFromTranscript(transcriptPath) {
+  const ids = new Set();
+  if (!transcriptPath || !existsSync(transcriptPath)) return ids;
+  let raw;
+  try { raw = readFileSync(transcriptPath, 'utf8'); } catch { return ids; }
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    // Claude Code transcript: one JSON per line with type='assistant' | 'user' | ...
+    if (entry.type !== 'assistant' || !entry.message) continue;
+    const content = entry.message.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (block.type !== 'text' || typeof block.text !== 'string') continue;
+      CITATION_RE.lastIndex = 0;
+      let m;
+      while ((m = CITATION_RE.exec(block.text))) {
+        const id = Number(m[1]);
+        if (Number.isInteger(id) && id > 0 && id < 1e7) ids.add(id);
+      }
+    }
+  }
+  return ids;
+}
+
+/**
+ * Increment `access_count` (and `last_accessed_at`) for each cited observation
+ * that belongs to `project`. Returns the count of successful increments.
+ *
+ * Per-row UPDATE in try-catch so a single FTS-corrupted row can't abort the
+ * scan. Cross-project IDs are silently ignored by the WHERE clause.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {Iterable<number>} ids
+ * @param {string} project
+ * @returns {number} count of rows incremented
+ */
+export function bumpCitationAccess(db, ids, project) {
+  if (!db || !ids || !project) return 0;
+  const idList = Array.isArray(ids) ? ids : [...ids];
+  if (idList.length === 0) return 0;
+  const stmt = db.prepare(`
+    UPDATE observations SET access_count = access_count + 1, last_accessed_at = ?
+    WHERE id = ? AND project = ?
+  `);
+  const now = Date.now();
+  let n = 0;
+  for (const id of idList) {
+    try {
+      const result = stmt.run(now, id, project);
+      if (result.changes > 0) n++;
+    } catch (e) { debugCatch(e, `bumpCitationAccess-id-${id}`); }
+  }
+  return n;
+}

package/lib/low-signal-patterns.mjs

@@ -58,3 +58,82 @@ export function buildNotLowSignalSql(alias = '') {
   const clauses = LOW_SIGNAL_PATTERNS.map(({ like }) => `${p}title NOT LIKE '${like}'`);
   return '(\n    ' + clauses.join('\n    AND ') + '\n  )';
 }
+
+// Cached singleton — isNoiseObservation is called once per observation insert.
+const _LOW_SIG_RE = buildLowSignalRegex();
+
+/**
+ * Detect narrative that is raw tool-output passthrough, not human/LLM prose (P2).
+ *
+ * `buildImmediateObservation` constructs narrative as
+ * `episode.entries.map(e => e.desc).join('; ')` where each desc is
+ * "cmd → stdout/stderr" from `scripts/post-tool-use.sh`. Such narratives
+ * have characteristic fingerprints (arrows, stack traces, diffs, test
+ * failure banners, absent sentence prose) that Haiku/user-written narratives
+ * don't. This check treats passthrough narratives as zero-signal for the
+ * purposes of isNoiseObservation.
+ *
+ * @param {string} narrative
+ * @returns {boolean} true = raw tool output, not substantive narrative
+ */
+function _isLikelyToolOutputPassthrough(narrative) {
+  if (!narrative || narrative.length < 80) return false;
+  // post-tool-use.sh formats entries as "cmd → output"; presence of " → " in
+  // a long narrative is near-diagnostic of raw entry-desc passthrough.
+  if (/ → /.test(narrative)) return true;
+  // Stack-trace fingerprints that never appear in curated narratives.
+  if (/\n\s+at .+:\d+:\d+/.test(narrative)) return true;
+  if (/node:internal\//.test(narrative)) return true;
+  // Raw diff output.
+  if (/(^|\n)diff --git |(^|\n)@@ -\d/.test(narrative)) return true;
+  // Test-runner failure banners.
+  if (/(^|\n)\s*FAIL\s+|AssertionError|TypeError: |SyntaxError: /.test(narrative)) return true;
+  // Absent sentence prose + multi-"; " is the buildImmediateObservation join signature.
+  const hasSentenceBreaks = /\. [A-Z]/.test(narrative);
+  const semiJoins = (narrative.match(/; /g) || []).length;
+  if (!hasSentenceBreaks && semiJoins >= 2) return true;
+  return false;
+}
+
+/**
+ * Write-side noise filter (P0/P2). Returns true when an observation has a
+ * LOW_SIGNAL title AND no recoverable downstream signal — caller should skip
+ * insertion.
+ *
+ * Contract: a low-signal title is kept if ANY of these carry signal:
+ *   - lesson_learned set and not 'none'
+ *   - importance >= 2
+ *   - facts has >=1 non-empty string
+ *   - narrative >= 40 chars AND not raw stderr / tool-output passthrough (P2)
+ *
+ * Opt-out: env `CLAUDE_MEM_KEEP_LOW_SIGNAL=1` disables filter (preserves
+ * pre-v2.36 behavior — every observation is inserted regardless of signal).
+ *
+ * @param {object} obs Observation shape: { title, facts, narrative, lessonLearned|lesson_learned, importance }
+ * @param {object} [env=process.env] Environment (injected for testability)
+ * @returns {boolean} true = noise, caller should drop
+ */
+export function isNoiseObservation(obs, env = process.env) {
+  if (env && env.CLAUDE_MEM_KEEP_LOW_SIGNAL === '1') return false;
+  const title = (obs && obs.title) || '';
+  if (!_LOW_SIG_RE.test(title)) return false;
+
+  const lesson = obs.lessonLearned ?? obs.lesson_learned;
+  if (lesson && String(lesson).trim() && String(lesson).trim().toLowerCase() !== 'none') return false;
+
+  if ((obs.importance ?? 1) >= 2) return false;
+
+  if (Array.isArray(obs.facts) &&
+      obs.facts.filter(f => typeof f === 'string' && f.trim().length > 0).length >= 1) {
+    return false;
+  }
+
+  const narrative = (obs.narrative || '').trim();
+  if (narrative.length >= 40 &&
+      !/^Error[: ]/i.test(narrative) &&
+      !_isLikelyToolOutputPassthrough(narrative)) {
+    return false;
+  }
+
+  return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.35.0",
+  "version": "2.36.0",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {
@@ -50,6 +50,7 @@
     "lib/doctor-drift.mjs",
     "lib/stats-quality.mjs",
     "lib/low-signal-patterns.mjs",
+    "lib/citation-tracker.mjs",
     "registry.mjs",
     "registry-retriever.mjs",
     "registry-indexer.mjs",

package/source-files.mjs

@@ -37,6 +37,7 @@ export const SOURCE_FILES = [
   'lib/doctor-drift.mjs',
   'lib/stats-quality.mjs',
   'lib/low-signal-patterns.mjs',
+  'lib/citation-tracker.mjs',
   // v2.32 invited-memory: memdir primitives + adopt/unadopt CLI
   'memdir.mjs',
   'adopt-content.mjs',