thumbgate 1.3.0 → 1.4.0

package/scripts/hybrid-feedback-context.js

@@ -17,6 +17,7 @@
 const fs = require('fs');
 const path = require('path');
 const { resolveFeedbackDir } = require('./feedback-paths');
+const { readJsonl } = require('./fs-utils');
 
 // ---------------------------------------------------------------------------
 // Paths
@@ -62,39 +63,12 @@ const POS = new Set([
   'success', 'pass', 'passed', 'great', 'excellent', 'perfect', 'works',
 ]);
 
+const HYBRID_JSONL_READ_LIMIT = 400;
+
 // ---------------------------------------------------------------------------
 // Low-level helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Read last maxLines of a JSONL file in reverse, then re-reverse so oldest-first.
- */
-function readJsonl(filePath, maxLines) {
-  const limit = maxLines !== undefined ? maxLines : 400;
-  if (!fs.existsSync(filePath)) return [];
-  let raw;
-  try {
-    raw = fs.readFileSync(filePath, 'utf8').trimEnd();
-  } catch (_) {
-    return [];
-  }
-  if (!raw) return [];
-  const lines = raw.split('\n');
-  const slice = lines.slice(-limit);
-  const parsed = [];
-  for (let i = slice.length - 1; i >= 0; i--) {
-    const line = slice[i].trim();
-    if (!line) continue;
-    try {
-      parsed.push(JSON.parse(line));
-    } catch (_) {
-      // skip malformed
-    }
-  }
-  parsed.reverse(); // back to chronological order
-  return parsed;
-}
-
 /**
  * Normalize text: strip /Users/ paths, port numbers, lowercase.
  */
@@ -208,10 +182,10 @@ function buildHybridState(opts) {
   const pendingSyncPath = o.pendingSyncPath || process.env.THUMBGATE_PENDING_SYNC || paths.pendingSync;
   const attributedFeedbackPath = o.attributedFeedbackPath || process.env.THUMBGATE_ATTRIBUTED_FEEDBACK || paths.attributedFeedback;
 
-  const feedbackEntries = readJsonl(feedbackLogPath);
-  const inboxEntries = readJsonl(inboxPath);
-  const pendingSyncEntries = readJsonl(pendingSyncPath);
-  const attributedEntries = readJsonl(attributedFeedbackPath);
+  const feedbackEntries = readJsonl(feedbackLogPath, HYBRID_JSONL_READ_LIMIT);
+  const inboxEntries = readJsonl(inboxPath, HYBRID_JSONL_READ_LIMIT);
+  const pendingSyncEntries = readJsonl(pendingSyncPath, HYBRID_JSONL_READ_LIMIT);
+  const attributedEntries = readJsonl(attributedFeedbackPath, HYBRID_JSONL_READ_LIMIT);
 
   // Deduplicate by id across all sources
   const seen = new Set();

package/scripts/intervention-policy.js

@@ -4,6 +4,7 @@
 const fs = require('fs');
 const path = require('path');
 const { resolveFeedbackDir } = require('./feedback-paths');
+const { getDecisionLogPath, readDecisionLog, collapseDecisionTimeline } = require('./decision-journal');
 
 const LABELS = ['allow', 'recall', 'verify', 'warn', 'deny'];
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -323,14 +324,64 @@ function buildDiagnosticExample(entry) {
   };
 }
 
+function deriveLabelFromDecisionOutcome(outcome) {
+  const status = normalizeText(outcome && outcome.outcome);
+  const actualDecision = normalizeText(outcome && outcome.actualDecision);
+  if (status === 'blocked' || status === 'rolled_back' || actualDecision === 'deny') return 'deny';
+  if (status === 'warned' || status === 'overridden' || actualDecision === 'warn') return 'warn';
+  if (status === 'accepted' || status === 'completed') return 'allow';
+  if (status === 'aborted') return 'warn';
+  return null;
+}
+
+function buildDecisionExample(action) {
+  const evaluation = action && action.evaluation ? action.evaluation : null;
+  const latestOutcome = action && Array.isArray(action.outcomes) && action.outcomes.length > 0
+    ? action.outcomes[action.outcomes.length - 1]
+    : null;
+  const label = deriveLabelFromDecisionOutcome(latestOutcome);
+  if (!evaluation || !latestOutcome || !label) return null;
+
+  const recommendation = evaluation.recommendation || {};
+  const blastRadius = evaluation.blastRadius || {};
+  const toolInput = evaluation.toolInput && typeof evaluation.toolInput === 'object' ? evaluation.toolInput : {};
+  const changedFiles = Array.isArray(evaluation.changedFiles) ? evaluation.changedFiles : [];
+  const tokens = buildFeatureTokens([
+    'kind:decision',
+    `tool:${evaluation.toolName || latestOutcome.toolName || 'unknown'}`,
+    `decision:${recommendation.decision || 'allow'}`,
+    `execution:${recommendation.executionMode || 'auto_execute'}`,
+    `owner:${recommendation.decisionOwner || 'agent'}`,
+    `reversibility:${recommendation.reversibility || 'reviewable'}`,
+    recommendation.riskBand ? `risk:${recommendation.riskBand}` : null,
+    blastRadius.severity ? `blast:${blastRadius.severity}` : null,
+    latestOutcome.outcome ? `outcome:${latestOutcome.outcome}` : null,
+    latestOutcome.actor ? `actor:${latestOutcome.actor}` : null,
+    ...extractCommandTokens(toolInput.command || ''),
+    ...changedFiles.flatMap((filePath) => extractFileTokens(filePath)),
+    ...tokenizeText([recommendation.summary, latestOutcome.notes].filter(Boolean).join(' '), 10).map((token) => `decisiontok:${token}`),
+  ]);
+
+  if (!tokens.length) return null;
+  return {
+    id: latestOutcome.actionId || evaluation.actionId || null,
+    source: 'decision',
+    label,
+    timestamp: latestOutcome.timestamp || evaluation.timestamp || new Date().toISOString(),
+    tokens,
+  };
+}
+
 function buildExamplesFromFeedbackDir(feedbackDir) {
   const resolvedDir = resolveFeedbackDir({ feedbackDir });
   const feedbackEntries = readJSONL(path.join(resolvedDir, 'feedback-log.jsonl'));
   const auditEntries = readJSONL(path.join(resolvedDir, 'audit-trail.jsonl'));
   const diagnosticEntries = readJSONL(path.join(resolvedDir, 'diagnostic-log.jsonl'));
+  const decisionEntries = readDecisionLog(getDecisionLogPath(resolvedDir));
+  const decisions = collapseDecisionTimeline(decisionEntries);
 
   const examples = [];
-  const sourceCounts = { feedback: 0, audit: 0, diagnostic: 0 };
+  const sourceCounts = { feedback: 0, audit: 0, diagnostic: 0, decision: 0 };
 
   for (const entry of feedbackEntries) {
     const example = buildFeedbackExample(entry);
@@ -350,6 +401,12 @@ function buildExamplesFromFeedbackDir(feedbackDir) {
     sourceCounts.diagnostic += 1;
     examples.push(example);
   }
+  for (const action of decisions) {
+    const example = buildDecisionExample(action);
+    if (!example) continue;
+    sourceCounts.decision += 1;
+    examples.push(example);
+  }
 
   examples.sort((left, right) => {
     return Date.parse(left.timestamp || 0) - Date.parse(right.timestamp || 0);

package/scripts/lesson-db.js

@@ -14,6 +14,7 @@
 
 const path = require('node:path');
 const fs = require('node:fs');
+const { readJsonl } = require('./fs-utils');
 
 const PROJECT_ROOT = path.join(__dirname, '..');
 const DEFAULT_DB_PATH = path.join(PROJECT_ROOT, '.claude', 'memory', 'lessons.sqlite');
@@ -495,8 +496,8 @@ function backfillFromJsonl(db, feedbackDir) {
   const feedbackLogPath = path.join(feedbackDir, 'feedback-log.jsonl');
   const memoryLogPath = path.join(feedbackDir, 'memory-log.jsonl');
 
-  const feedbackEntries = readJsonlSafe(feedbackLogPath);
-  const memoryEntries = readJsonlSafe(memoryLogPath);
+  const feedbackEntries = readJsonl(feedbackLogPath);
+  const memoryEntries = readJsonl(memoryLogPath);
 
   // Index memories by sourceFeedbackId for joining
   const memoryByFeedbackId = new Map();
@@ -581,22 +582,6 @@ function safeParseTags(tagsStr) {
   }
 }
 
-function readJsonlSafe(filePath) {
-  if (!fs.existsSync(filePath)) return [];
-  const raw = fs.readFileSync(filePath, 'utf-8').trim();
-  if (!raw) return [];
-  return raw
-    .split('\n')
-    .map((line) => {
-      try {
-        return JSON.parse(line);
-      } catch {
-        return null;
-      }
-    })
-    .filter(Boolean);
-}
-
 module.exports = {
   initDB,
   upsertLesson,

package/scripts/lesson-inference.js

@@ -17,6 +17,7 @@
 const fs = require('fs');
 const path = require('path');
 const { resolveFeedbackDir } = require('./feedback-paths');
+const { ensureParentDir, readJsonl } = require('./fs-utils');
 const {
   buildStableId,
   extractFilePaths,
@@ -39,15 +40,6 @@ function getLessonBaseUrl() {
 function getLessonsPath() { return path.join(getFeedbackDir(), LESSONS_FILE); }
 function getRecentLessonPath() { return path.join(getFeedbackDir(), RECENT_LESSON_FILE); }
 
-function readJsonl(fp) {
-  if (!fs.existsSync(fp)) return [];
-  const raw = fs.readFileSync(fp, 'utf-8').trim();
-  if (!raw) return [];
-  return raw.split('\n').map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
-}
-
-function ensureDir(p) { const d = path.dirname(p); if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true }); }
-
 // ---------------------------------------------------------------------------
 // 1. Surrounding Message Context Extraction
 // ---------------------------------------------------------------------------
@@ -146,7 +138,7 @@ function createLesson({ feedbackId, signal, inferredLesson, triggerMessage, prio
   lesson.link = `${getLessonBaseUrl()}/lessons#${lesson.id}`;
 
   const lessonsPath = getLessonsPath();
-  ensureDir(lessonsPath);
+  ensureParentDir(lessonsPath);
   fs.appendFileSync(lessonsPath, JSON.stringify(lesson) + '\n');
 
   // Update recent lesson for statusbar
@@ -165,6 +157,55 @@ function getRecentLesson() {
   try { return JSON.parse(fs.readFileSync(p, 'utf-8')); } catch { return null; }
 }
 
+function isNegativeSignal(signal) {
+  return signal === 'negative' || signal === 'down';
+}
+
+function isPositiveSignal(signal) {
+  return signal === 'positive' || signal === 'up';
+}
+
+function selectStatusbarLesson() {
+  const lessons = readJsonl(getLessonsPath())
+    .slice()
+    .sort((a, b) => new Date(b.createdAt || 0) - new Date(a.createdAt || 0));
+  const latestNegative = lessons.find((lesson) => isNegativeSignal(lesson.signal));
+  if (latestNegative) return latestNegative;
+  const latestPositive = lessons.find((lesson) => isPositiveSignal(lesson.signal));
+  if (latestPositive) return latestPositive;
+  return getRecentLesson();
+}
+
+function getLessonKind(lesson = {}) {
+  const normalizedTitle = String(lesson.lesson || '').trim();
+  if (isNegativeSignal(lesson.signal) || /^MISTAKE:/i.test(normalizedTitle)) return 'mistake';
+  if (isPositiveSignal(lesson.signal) || /^SUCCESS:/i.test(normalizedTitle)) return 'success';
+  if (/^LEARNING:/i.test(normalizedTitle)) return 'learning';
+  if (/^PREFERENCE:/i.test(normalizedTitle)) return 'preference';
+  return 'lesson';
+}
+
+function stripLessonPrefix(lessonText = '') {
+  return String(lessonText || '').replace(/^(MISTAKE|SUCCESS|LEARNING|PREFERENCE):\s*/i, '').trim();
+}
+
+function formatLessonTimestamp(createdAt = '') {
+  const parsed = new Date(createdAt);
+  if (!Number.isFinite(parsed.getTime())) return '';
+  return parsed.toISOString().slice(0, 16).replace('T', ' ') + 'Z';
+}
+
+function buildStatusbarLessonLabel(lesson = {}) {
+  const kind = getLessonKind(lesson);
+  const prefix = kind === 'mistake'
+    ? 'Latest mistake'
+    : kind === 'success'
+      ? 'Latest success'
+      : 'Latest lesson';
+  const timestamp = formatLessonTimestamp(lesson.createdAt);
+  return timestamp ? `${prefix} ${timestamp}` : prefix;
+}
+
 /**
  * Search lessons by query text.
  */
@@ -196,6 +237,59 @@ function getLessonStats() {
   return { total: lessons.length, positive, negative, avgConfidence };
 }
 
+// ---------------------------------------------------------------------------
+// 2b. Context Stuffing — dump all lessons for injection into agent context
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns ALL lessons condensed for context-window injection.
+ * Bypasses RAG/search — just stuff everything into context.
+ * For most projects (20-200 lessons), this is 1K-10K tokens.
+ * @param {object} opts
+ * @param {number} opts.maxTokenBudget - approximate token budget (default 10000)
+ * @param {string} opts.signal - filter by 'positive' or 'negative'
+ * @param {string} opts.format - 'compact' (default) or 'full'
+ * @returns {{ lessons: string, count: number, truncated: boolean }}
+ */
+function getAllLessonsForContext({ maxTokenBudget = 10000, signal, format = 'compact' } = {}) {
+  let lessons = readJsonl(getLessonsPath());
+  if (signal) lessons = lessons.filter((l) => l.signal === signal || (signal === 'negative' && l.signal === 'down') || (signal === 'positive' && l.signal === 'up'));
+
+  // Sort by confidence descending — most important lessons first
+  lessons.sort((a, b) => (b.confidence || 0) - (a.confidence || 0));
+
+  const lines = [];
+  let approxTokens = 0;
+  let truncated = false;
+
+  for (const l of lessons) {
+    let line;
+    if (format === 'compact') {
+      const sig = l.signal === 'positive' || l.signal === 'up' ? 'DO' : 'AVOID';
+      line = `[${sig}] ${l.lesson || l.inferredLesson || ''}`;
+    } else {
+      line = JSON.stringify({ signal: l.signal, lesson: l.lesson || l.inferredLesson, confidence: l.confidence, tags: l.tags, createdAt: l.createdAt });
+    }
+
+    const lineTokens = Math.ceil(line.length / 4); // rough token estimate
+    if (approxTokens + lineTokens > maxTokenBudget) {
+      truncated = true;
+      break;
+    }
+
+    lines.push(line);
+    approxTokens += lineTokens;
+  }
+
+  return {
+    lessons: lines.join('\n'),
+    count: lines.length,
+    totalAvailable: lessons.length,
+    truncated,
+    approxTokens,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // 3. Statusbar Data Provider
 // ---------------------------------------------------------------------------
@@ -205,19 +299,21 @@ function getLessonStats() {
  * Returns the most recent lesson with link, formatted for display.
  */
 function getStatusbarLessonData() {
-  const recent = getRecentLesson();
+  const recent = selectStatusbarLesson();
   if (!recent) return { hasLesson: false, text: null, link: null };
 
-  const emoji = (recent.signal === 'negative' || recent.signal === 'down') ? '👎' : '👍';
-  const truncated = recent.lesson.length > 60 ? recent.lesson.slice(0, 57) + '...' : recent.lesson;
+  const normalizedLesson = stripLessonPrefix(recent.lesson || '');
+  const truncated = normalizedLesson.length > 48 ? normalizedLesson.slice(0, 45) + '...' : normalizedLesson;
 
   return {
     hasLesson: true,
-    text: `${emoji} ${truncated}`,
+    text: truncated,
     link: recent.link,
     lessonId: recent.id,
     confidence: recent.confidence,
     createdAt: recent.createdAt,
+    label: buildStatusbarLessonLabel(recent),
+    kind: getLessonKind(recent),
   };
 }
 
@@ -306,10 +402,92 @@ function consumePhrase(lower, original, phrases) {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// 6. LLM-Powered Structured Lesson Extraction
+// ---------------------------------------------------------------------------
+
+const LLM_LESSON_SYSTEM_PROMPT = `You are a lesson extraction engine for an AI coding agent safety system called ThumbGate.
+
+Given a conversation window and a feedback signal (positive or negative), extract a structured lesson.
+
+Return ONLY valid JSON matching this exact schema:
+{
+  "trigger": { "condition": "<when this lesson applies>", "type": "<one of: debugging, implementation, question, error-report, constraint>" },
+  "action": { "type": "<do or avoid>", "description": "<specific action to take or avoid>" },
+  "confidence": <0.0 to 1.0>,
+  "scope": "<global, file-level, or project-level>",
+  "tags": ["<relevant tags>"]
+}
+
+Guidelines:
+- Be specific and actionable. "Avoid: editing files without reading them first" is better than "Avoid: bad edits".
+- confidence should reflect how clear the lesson is from the conversation context.
+- tags should include tool names, file types, or domain areas mentioned.
+- Do NOT include any text outside the JSON object.`;
+
+async function inferStructuredLessonLLM(conversationWindow, signal, context) {
+  const { isAvailable, callClaude, MODELS } = require('./llm-client');
+  if (!isAvailable()) return null;
+
+  const normalizedWindow = Array.isArray(conversationWindow) ? conversationWindow : [];
+  if (normalizedWindow.length === 0 && !context) return null;
+
+  const windowText = normalizedWindow
+    .slice(-10)
+    .map((m) => `[${m.role}]: ${(m.content || '').slice(0, 400)}`)
+    .join('\n')
+    .slice(0, 4000);
+
+  const userPrompt = [
+    `Signal: ${signal === 'positive' || signal === 'up' ? 'positive (thumbs up — something worked well)' : 'negative (thumbs down — something went wrong)'}`,
+    context ? `User context: ${context}` : '',
+    `\nConversation:\n${windowText}`,
+  ].filter(Boolean).join('\n');
+
+  const raw = await callClaude({
+    systemPrompt: LLM_LESSON_SYSTEM_PROMPT,
+    userPrompt,
+    model: MODELS.FAST,
+    maxTokens: 512,
+  });
+
+  if (!raw) return null;
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed.trigger || !parsed.action) return null;
+
+    const filePaths = extractFilePaths(normalizedWindow);
+    const toolCalls = extractToolCalls(normalizedWindow);
+    const errorPatterns = extractErrors(normalizedWindow);
+    const userMessages = normalizedWindow.filter((m) => m.role === 'user');
+    const assistantMessages = normalizedWindow.filter((m) => m.role === 'assistant');
+    const lastUser = userMessages[userMessages.length - 1]?.content || '';
+    const lastAssistant = assistantMessages[assistantMessages.length - 1]?.content || '';
+
+    return {
+      format: 'if-then-v1-llm',
+      trigger: parsed.trigger,
+      action: parsed.action,
+      signal: signal === 'positive' || signal === 'up' ? 'positive' : 'negative',
+      confidence: Math.max(0, Math.min(1, Number(parsed.confidence) || 0.5)),
+      scope: parsed.scope || inferScope(filePaths, toolCalls),
+      examples: [{ userIntent: lastUser.slice(0, 300), assistantAction: lastAssistant.slice(0, 300), outcome: signal === 'positive' || signal === 'up' ? 'approved' : 'rejected' }],
+      metadata: { toolsUsed: toolCalls, filesInvolved: filePaths.slice(0, 10), errorPatterns: errorPatterns.slice(0, 5), conversationLength: normalizedWindow.length, inferredAt: new Date().toISOString(), llmModel: MODELS.FAST },
+      tags: Array.isArray(parsed.tags) ? parsed.tags : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
 module.exports = {
   inferFromSurroundingMessages, createLesson, getRecentLesson,
-  searchLessons, getLessonStats, getStatusbarLessonData,
+  searchLessons, getLessonStats, getStatusbarLessonData, getAllLessonsForContext,
   getLessonsPath, getRecentLessonPath,
-  inferStructuredLesson, extractTrigger, extractAction, extractToolCalls,
+  selectStatusbarLesson, getLessonKind, stripLessonPrefix,
+  formatLessonTimestamp, buildStatusbarLessonLabel,
+  inferStructuredLesson, inferStructuredLessonLLM,
+  extractTrigger, extractAction, extractToolCalls,
   extractFilePaths, extractErrors, calculateConfidence, inferScope,
 };

package/scripts/lesson-retrieval.js

@@ -3,11 +3,10 @@
 
 /**
  * Per-action lesson retrieval.
- * Given a tool name + context, returns the top-K most relevant lessons
- * using keyword matching + recency decay + signal weighting.
+ * v2: backward retrieval + bigram Jaccard fuzzy matching
  */
 
-const RECENCY_DECAY_DAYS = 30; // lessons older than this get down-weighted
+const RECENCY_DECAY_DAYS = 30;
 
 function retrieveRelevantLessons(toolName, actionContext, options = {}) {
   const { maxResults = 5, feedbackDir } = options;
@@ -20,13 +19,13 @@ function retrieveRelevantLessons(toolName, actionContext, options = {}) {
   const memories = readJSONL(paths.MEMORY_LOG_PATH, { maxLines: 200 });
   if (memories.length === 0) return [];
 
-  // Score each memory against the current action
+  const actionSig = buildActionSignature(toolName, actionContext);
+
   const scored = memories.map((mem) => ({
     ...mem,
-    relevanceScore: scoreRelevance(mem, toolName, actionContext),
+    relevanceScore: scoreRelevance(mem, toolName, actionContext, actionSig),
   }));
 
-  // Sort by relevance, return top-K
   return scored
     .filter((m) => m.relevanceScore > 0.1)
     .sort((a, b) => b.relevanceScore - a.relevanceScore)
@@ -42,43 +41,74 @@ function retrieveRelevantLessons(toolName, actionContext, options = {}) {
     }));
 }
 
-function scoreRelevance(memory, toolName, actionContext) {
+function buildActionSignature(toolName, actionContext) {
+  const toolLower = (toolName || '').toLowerCase();
+  const contextLower = (actionContext || '').toLowerCase();
+  const sigPaths = extractPaths(actionContext);
+  const tokens = tokenize(contextLower);
+  const ngramSet = textBigrams(contextLower);
+  return { toolLower, contextLower, paths: sigPaths, tokens, ngramSet };
+}
+
+function textBigrams(text) {
+  const normalized = (text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  const set = new Set();
+  for (let i = 0; i < normalized.length - 1; i++) {
+    set.add(normalized.slice(i, i + 2));
+  }
+  return set;
+}
+
+function bigramJaccard(setA, setB) {
+  if (setA.size === 0 && setB.size === 0) return 1;
+  if (setA.size === 0 || setB.size === 0) return 0;
+  let intersection = 0;
+  for (const item of setA) {
+    if (setB.has(item)) intersection++;
+  }
+  const union = setA.size + setB.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+function scoreRelevance(memory, toolName, actionContext, actionSig) {
+  const sig = actionSig || buildActionSignature(toolName, actionContext);
   let score = 0;
 
-  const memText = `${memory.title || ''} ${memory.content || ''} ${(memory.tags || []).join(' ')}`.toLowerCase();
-  const contextLower = (actionContext || '').toLowerCase();
-  const toolLower = (toolName || '').toLowerCase();
+  const memText = ((memory.title || '') + ' ' + (memory.content || '') + ' ' + (memory.tags || []).join(' ')).toLowerCase();
 
-  // 1. Tool name match (high weight)
-  if (memory.metadata?.toolsUsed?.some((t) => t.toLowerCase() === toolLower)) score += 0.4;
-  if (memText.includes(toolLower)) score += 0.2;
+  if (memory.metadata?.toolsUsed?.some((t) => t.toLowerCase() === sig.toolLower)) score += 0.4;
+  if (memText.includes(sig.toolLower)) score += 0.2;
 
-  // 2. File path overlap
-  const contextPaths = extractPaths(actionContext);
   const memPaths = memory.metadata?.filesInvolved || extractPaths(memText);
-  const pathOverlap = contextPaths.filter((p) =>
+  const pathOverlap = sig.paths.filter((p) =>
     memPaths.some((mp) => mp.includes(p) || p.includes(mp)),
   );
   if (pathOverlap.length > 0) score += 0.3;
 
-  // 3. Keyword overlap (TF-IDF-lite)
-  const contextTokens = tokenize(contextLower);
   const memTokens = tokenize(memText);
-  const overlap = contextTokens.filter((t) => memTokens.includes(t));
+  const overlap = sig.tokens.filter((t) => memTokens.includes(t));
   score += Math.min(overlap.length * 0.05, 0.3);
 
-  // 4. Signal weighting — negative lessons are more important to surface
+  // Fuzzy n-gram matching (only when there is already signal)
+  if (score > 0) {
+    const memBigrams = textBigrams(memText);
+    const fuzzyScore = bigramJaccard(sig.ngramSet, memBigrams);
+    score += fuzzyScore * 0.2;
+  }
+
   if (memory.tags?.includes('negative')) score += 0.1;
 
-  // 5. Recency decay
   if (memory.timestamp) {
     const ageMs = Date.now() - new Date(memory.timestamp).getTime();
     const ageDays = ageMs / (1000 * 60 * 60 * 24);
     const decay = Math.max(0, 1 - ageDays / RECENCY_DECAY_DAYS);
-    score *= 0.5 + 0.5 * decay; // 50% base + 50% recency
+    score *= 0.5 + 0.5 * decay;
   }
 
-  // 6. Structured rule bonus — IF/THEN rules are more actionable
   if (memory.structuredRule) score += 0.15;
 
   return score;
@@ -92,4 +122,10 @@ function tokenize(text) {
   return (text || '').split(/[\s.,;:!?()\[\]{}"'`]+/).filter((t) => t.length > 3);
 }
 
-module.exports = { retrieveRelevantLessons, scoreRelevance };
+module.exports = {
+  retrieveRelevantLessons,
+  scoreRelevance,
+  buildActionSignature,
+  textBigrams,
+  bigramJaccard,
+};

package/scripts/llm-client.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+'use strict';
+
+const MODELS = {
+  FAST: 'claude-haiku-4-5-20251001',
+  SMART: 'claude-sonnet-4-6',
+};
+
+const DEFAULT_MODEL = MODELS.FAST;
+const DEFAULT_MAX_TOKENS = 1024;
+
+let _client = null;
+
+function isAvailable() {
+  return Boolean(process.env.ANTHROPIC_API_KEY);
+}
+
+function getClient() {
+  if (_client) return _client;
+  if (!isAvailable()) return null;
+  try {
+    const Anthropic = require('@anthropic-ai/sdk');
+    _client = new Anthropic();
+    return _client;
+  } catch {
+    return null;
+  }
+}
+
+function stripCodeFences(text) {
+  if (!text) return text;
+  const fenced = text.match(/^```(?:json)?\s*\n?([\s\S]*?)```\s*$/);
+  return fenced ? fenced[1].trim() : text.trim();
+}
+
+async function callClaude({ systemPrompt, userPrompt, model, maxTokens } = {}) {
+  const client = getClient();
+  if (!client) return null;
+
+  try {
+    const response = await client.messages.create({
+      model: model || DEFAULT_MODEL,
+      max_tokens: maxTokens || DEFAULT_MAX_TOKENS,
+      system: systemPrompt || undefined,
+      messages: [{ role: 'user', content: userPrompt }],
+    });
+
+    const text = response.content
+      .filter((b) => b.type === 'text')
+      .map((b) => b.text)
+      .join('');
+
+    return stripCodeFences(text);
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { isAvailable, callClaude, stripCodeFences, MODELS };