claude-recall 0.25.1 → 0.26.0

package/dist/hooks/memory-stop-hook.js

@@ -42,12 +42,50 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleMemoryStop = handleMemoryStop;
 const shared_1 = require("./shared");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const memory_1 = require("../services/memory");
 const config_1 = require("../services/config");
 const failure_detectors_1 = require("./failure-detectors");
+const llm_classifier_1 = require("./llm-classifier");
 const outcome_storage_1 = require("../services/outcome-storage");
 const event_processors_1 = require("../shared/event-processors");
 const MAX_STORE = 3;
+/**
+ * Debounce state for the heavy pipeline. Claude Code fires Stop after EVERY
+ * assistant turn, not at session end — without a debounce the full pipeline
+ * (episode insert, up to two Haiku calls, failure scan, promotion cycle,
+ * prune) runs per turn. Citations are still scanned every turn (cheap, and
+ * they keep cite_count — the anti-demotion signal — fresh).
+ */
+const STOP_DEBOUNCE_MS = (() => {
+    const raw = parseInt(process.env.CLAUDE_RECALL_STOP_DEBOUNCE_MS || '300000', 10); // 5 min
+    return Number.isFinite(raw) && raw >= 0 ? raw : 300000;
+})();
+function stopStateFile(sessionId) {
+    return path.join((0, shared_1.hookStateDir)(), `memory-stop-${sessionId.replace(/[^a-zA-Z0-9-]/g, '_')}.json`);
+}
+function shouldRunHeavyPipeline(sessionId) {
+    if (STOP_DEBOUNCE_MS === 0)
+        return true; // debounce disabled
+    const file = stopStateFile(sessionId);
+    try {
+        const state = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (typeof state.lastHeavyRun === 'number' && Date.now() - state.lastHeavyRun < STOP_DEBOUNCE_MS) {
+            return false;
+        }
+    }
+    catch {
+        // Missing/corrupt state file → treat as never run
+    }
+    try {
+        fs.writeFileSync(file, JSON.stringify({ lastHeavyRun: Date.now() }));
+    }
+    catch {
+        // Non-fatal: worst case the pipeline runs again next turn
+    }
+    return true;
+}
 async function handleMemoryStop(input) {
     const transcriptPath = input?.transcript_path ?? '';
     if (!transcriptPath) {
@@ -59,14 +97,14 @@ async function handleMemoryStop(input) {
         (0, shared_1.hookLog)('memory-stop', 'No transcript entries found');
         return;
     }
-    // Create an episode for this session
+    // Debounced: run only the cheap citation scan on most turns
+    const sessionId = input?.session_id || 'default';
+    if (!shouldRunHeavyPipeline(sessionId)) {
+        scanForCitations(transcriptPath);
+        return;
+    }
     const outcomeStorage = outcome_storage_1.OutcomeStorage.getInstance();
     const projectId = config_1.ConfigService.getInstance().getProjectId();
-    const episodeId = outcomeStorage.createEpisode({
-        project_id: projectId,
-        session_id: input?.session_id,
-        source: 'memory-stop',
-    });
     // Extract user-only texts, filter, then batch-classify in one API call
     const textsWithIndex = [];
     for (let i = 0; i < entries.length; i++) {
@@ -79,10 +117,19 @@ async function handleMemoryStop(input) {
     }
     if (textsWithIndex.length === 0) {
         (0, shared_1.hookLog)('memory-stop', 'No classifiable text in transcript entries');
-        // Still scan for citations — assistant messages may contain them
+        // Still scan for citations — assistant messages may contain them.
+        // No episode was created yet, so this early return leaves no dangling row.
         scanForCitations(transcriptPath);
         return;
     }
+    // Create an episode for this session — AFTER the early returns so the
+    // frequent no-classifiable-text path doesn't leave permanently
+    // outcome-less episode rows.
+    const episodeId = outcomeStorage.createEpisode({
+        project_id: projectId,
+        session_id: input?.session_id,
+        source: 'memory-stop',
+    });
     const results = await (0, shared_1.classifyBatch)(textsWithIndex.map((t) => t.text));
     let stored = 0;
     for (let i = 0; i < results.length; i++) {
@@ -156,7 +203,7 @@ async function handleMemoryStop(input) {
         outcome_summary: `${stored} memories, ${allFailures.length} failures (${toolFailures.length} from tool events)`,
     });
     // Generate candidate lessons from high-confidence failures
-    generateCandidateLessons(allFailures, episodeId, projectId);
+    await generateCandidateLessons(allFailures, episodeId, projectId);
     // Run promotion cycle
     try {
         const { PromotionEngine } = await Promise.resolve().then(() => __importStar(require('../services/promotion-engine')));
@@ -241,7 +288,7 @@ function scanForCitations(transcriptPath) {
                 try {
                     outcome_storage_1.OutcomeStorage.getInstance().recordHelpful(bestKey);
                 }
-                catch { }
+                catch { /* best-effort — ignore */ }
                 (0, shared_1.hookLog)('memory-stop', `Citation matched: "${cite.substring(0, 50)}" → rule ${bestKey} (containment=${bestScore.toFixed(3)})`);
             }
             else {
@@ -304,7 +351,7 @@ function extractRuleContent(value) {
 /**
  * Scan the last 200 transcript entries for failure signals and store up to 3.
  */
-function detectAndStoreFailures(transcriptPath, episodeId) {
+function detectAndStoreFailures(transcriptPath, _episodeId) {
     try {
         const entries = (0, shared_1.readTranscriptTail)(transcriptPath, 200);
         if (entries.length === 0) {
@@ -378,17 +425,42 @@ function getToolFailureEvents(outcomeStorage) {
         return [];
     }
 }
+/** lesson_kind values extractHindsightHint may legitimately return. */
+const VALID_LESSON_KINDS = new Set([
+    'rule', 'preference', 'anti_pattern', 'workflow', 'debug_fix', 'failure_preventer',
+]);
 /**
  * Generate candidate lessons from high-confidence failures.
  * Deduplicates against existing lessons and increments evidence count for similar ones.
+ *
+ * The lesson text must be failure-specific. Detectors emit a constant
+ * what_should_do ("Check command syntax..."), so using it verbatim made every
+ * unrelated failure "similar" to every other — evidence counts inflated across
+ * unrelated failures and the promotion engine could only ever promote generic
+ * boilerplate. Prefer an LLM hindsight hint; without one, ground the generic
+ * remedy in what actually failed so similarity matching compares failures,
+ * not the shared remedy string.
  */
-function generateCandidateLessons(failures, episodeId, projectId) {
+async function generateCandidateLessons(failures, episodeId, projectId) {
     try {
         const outcomeStorage = outcome_storage_1.OutcomeStorage.getInstance();
         for (const f of failures) {
             if (f.confidence < 0.7)
                 continue;
-            const similar = outcomeStorage.findSimilarLessons(f.content.what_should_do, projectId);
+            let lessonText = `${f.content.what_should_do} (failure: ${f.content.what_failed})`;
+            let lessonKind = 'failure_preventer';
+            let appliesWhen = extractTagsFromContext(f.content.context);
+            const hint = await (0, llm_classifier_1.extractHindsightHint)(`${f.content.what_failed}${f.content.why_failed ? ` — ${f.content.why_failed}` : ''}`, f.content.context || '');
+            if (hint) {
+                lessonText = hint.hint_text;
+                if (VALID_LESSON_KINDS.has(hint.hint_kind)) {
+                    lessonKind = hint.hint_kind;
+                }
+                if (hint.applies_when.length > 0) {
+                    appliesWhen = hint.applies_when;
+                }
+            }
+            const similar = outcomeStorage.findSimilarLessons(lessonText, projectId);
             if (similar.length > 0) {
                 outcomeStorage.incrementEvidenceCount(similar[0].id);
             }
@@ -396,9 +468,9 @@ function generateCandidateLessons(failures, episodeId, projectId) {
                 outcomeStorage.createCandidateLesson({
                     project_id: projectId,
                     episode_id: episodeId,
-                    lesson_text: f.content.what_should_do,
-                    lesson_kind: 'failure_preventer',
-                    applies_when: extractTagsFromContext(f.content.context),
+                    lesson_text: lessonText,
+                    lesson_kind: lessonKind,
+                    applies_when: appliesWhen,
                     outcome_type: 'negative',
                     reward_band: -1,
                     confidence: f.confidence,

package/dist/hooks/post-compact-reload.js

@@ -39,7 +39,7 @@ function formatRules(rules) {
     }
     return sections.join('\n\n');
 }
-async function handlePostCompactReload(input) {
+async function handlePostCompactReload(_input) {
     try {
         const projectId = config_1.ConfigService.getInstance().getProjectId();
         const rules = memory_1.MemoryService.getInstance().loadActiveRules(projectId);

package/dist/hooks/shared.js

@@ -41,6 +41,8 @@ exports.jaccardSimilarity = jaccardSimilarity;
 exports.isDuplicate = isDuplicate;
 exports.storeMemory = storeMemory;
 exports.searchExisting = searchExisting;
+exports.claudeRecallDir = claudeRecallDir;
+exports.hookStateDir = hookStateDir;
 exports.safeErrorMessage = safeErrorMessage;
 exports.hookLog = hookLog;
 exports.readTranscriptTail = readTranscriptTail;
@@ -194,6 +196,24 @@ function searchExisting(query) {
     const memoryService = memory_1.MemoryService.getInstance();
     return memoryService.search(query);
 }
+/**
+ * Base data directory — same as the database. The env override keeps tests
+ * (and custom setups) away from the real ~/.claude-recall.
+ */
+function claudeRecallDir() {
+    return process.env.CLAUDE_RECALL_DB_PATH || path.join(os.homedir(), '.claude-recall');
+}
+/**
+ * Directory for per-session hook state files (pending failures, debounce
+ * markers). Created on demand.
+ */
+function hookStateDir() {
+    const dir = path.join(claudeRecallDir(), 'hook-state');
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
 /**
  * Extract a safe error message without exposing stack traces or internal paths.
  */
@@ -209,7 +229,7 @@ function safeErrorMessage(err) {
  */
 function hookLog(hookName, message) {
     try {
-        const logDir = path.join(os.homedir(), '.claude-recall', 'hook-logs');
+        const logDir = path.join(claudeRecallDir(), 'hook-logs');
         if (!fs.existsSync(logDir)) {
             fs.mkdirSync(logDir, { recursive: true });
         }

package/dist/hooks/tool-outcome-watcher.js

@@ -53,7 +53,6 @@ exports.shouldCaptureFailure = shouldCaptureFailure;
 exports.handleToolFailure = handleToolFailure;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const os = __importStar(require("os"));
 const shared_1 = require("./shared");
 const memory_1 = require("../services/memory");
 const outcome_storage_1 = require("../services/outcome-storage");
@@ -84,7 +83,7 @@ const MCP_ERROR_PATTERNS = [
 ];
 // --- State management (Bash fix pairing only) ---
 function getStateDir() {
-    return path.join(os.homedir(), '.claude-recall', 'hook-state');
+    return (0, shared_1.hookStateDir)();
 }
 function getStatePath(sessionId) {
     return path.join(getStateDir(), `${sessionId}-failures.json`);
@@ -306,8 +305,10 @@ async function handleBashSuccess(command, sessionId) {
         if (!matched && (0, shared_1.jaccardSimilarity)(pf.command, command) >= FIX_JACCARD_THRESHOLD) {
             try {
                 const memoryService = memory_1.MemoryService.getInstance();
-                memoryService.update(pf.memoryKey, {
-                    value: { what_should_do: `Fix: ${truncate(command, 200)}` },
+                // Merge, don't replace — the failure memory's what_failed/why_failed
+                // fields are the counterfactual context the fix enriches
+                memoryService.mergeIntoValue(pf.memoryKey, {
+                    what_should_do: `Fix: ${truncate(command, 200)}`,
                 });
                 recordOutcomeEvent('Bash', { command }, `Success after previous failure: ${truncate(pf.command, 100)}`, 0);
                 (0, shared_1.hookLog)(HOOK_NAME, `Paired fix: "${truncate(command, 60)}" → ${pf.memoryKey}`);
@@ -330,7 +331,6 @@ async function handleWriteToolOutcome(input) {
     const output = input.tool_output ?? '';
     const toolName = input.tool_name;
     const filePath = input.tool_input?.file_path ?? '';
-    const sessionId = input.session_id ?? 'unknown';
     // Check for error patterns
     const errorMatch = WRITE_ERROR_PATTERNS.find(p => p.test(output));
     if (errorMatch) {
@@ -365,7 +365,6 @@ async function handleWriteToolOutcome(input) {
 async function handleMcpToolOutcome(input) {
     const output = input.tool_output ?? '';
     const toolName = input.tool_name;
-    const sessionId = input.session_id ?? 'unknown';
     // Skip Claude Recall's own tools to avoid self-referential loops
     if (toolName.includes('claude-recall') || toolName.includes('claude_recall'))
         return;

package/dist/mcp/prompts-handler.js

@@ -14,7 +14,11 @@ class PromptsHandler {
     constructor() {
         this.logger = logging_1.LoggingService.getInstance();
         this.memoryService = memory_1.MemoryService.getInstance();
-        this.memoryStorage = this.memoryService.storage;
+        this.memoryStorage = this.memoryService.getStorage();
+    }
+    /** Build a spec-conformant text message. */
+    textMessage(text) {
+        return { role: 'user', content: { type: 'text', text } };
     }
     /**
      * Handle prompts/list request
@@ -166,14 +170,11 @@ class PromptsHandler {
         return {
             description: 'User coding preferences automatically injected',
             messages: [
-                {
-                    role: 'system',
-                    content: `# User Coding Preferences
+                this.textMessage(`# User Coding Preferences
 
 ${preferencesText}
 
-Apply these preferences when generating code or making suggestions.`
-                }
+Apply these preferences when generating code or making suggestions.`)
             ]
         };
     }
@@ -195,14 +196,11 @@ Apply these preferences when generating code or making suggestions.`
                 ? `Project knowledge about ${topic}`
                 : 'All project knowledge',
             messages: [
-                {
-                    role: 'system',
-                    content: `# Project Knowledge
+                this.textMessage(`# Project Knowledge
 
 ${contextText}
 
-Use this information when working with the project.`
-                }
+Use this information when working with the project.`)
             ]
         };
     }
@@ -220,14 +218,11 @@ Use this information when working with the project.`
         return {
             description: 'Recent correction patterns to avoid mistakes',
             messages: [
-                {
-                    role: 'system',
-                    content: `# Correction Patterns
+                this.textMessage(`# Correction Patterns
 
 ${correctionsText}
 
-Avoid these patterns when generating code.`
-                }
+Avoid these patterns when generating code.`)
             ]
         };
     }
@@ -247,14 +242,11 @@ Avoid these patterns when generating code.`
         return {
             description: `Full context for: ${task}`,
             messages: [
-                {
-                    role: 'system',
-                    content: `# Relevant Context
+                this.textMessage(`# Relevant Context
 
 ${contextText}
 
-Use this context when working on: ${task}`
-                }
+Use this context when working on: ${task}`)
             ]
         };
     }
@@ -270,9 +262,7 @@ Use this context when working on: ${task}`
         return {
             description: 'Analyze conversation for preference extraction',
             messages: [
-                {
-                    role: 'system',
-                    content: `You are analyzing a conversation to extract user coding preferences.
+                this.textMessage(`You are analyzing a conversation to extract user coding preferences.
 
 Extract any preferences about:
 - Programming languages and frameworks
@@ -293,12 +283,8 @@ Return a JSON array with format:
   }
 ]
 
-Be conservative - only extract clear, explicit preferences.`
-                },
-                {
-                    role: 'user',
-                    content: `Analyze this conversation for preferences:\n\n${conversation}`
-                }
+Be conservative - only extract clear, explicit preferences.`),
+                this.textMessage(`Analyze this conversation for preferences:\n\n${conversation}`)
             ]
         };
     }
@@ -468,20 +454,17 @@ Be conservative - only extract clear, explicit preferences.`
         return {
             description: topic ? `Active rules about ${topic}` : `All active rules (${totalRules} total)`,
             messages: [
-                {
-                    role: 'system',
-                    content: body
-                        ? `# Active Rules\n\nApply these rules when working on this project.\n\n${body}`
-                        : 'No active rules found. This may be a new project.'
-                }
+                this.textMessage(body
+                    ? `# Active Rules\n\nApply these rules when working on this project.\n\n${body}`
+                    : 'No active rules found. This may be a new project.')
             ]
         };
     }
     /**
      * Get session-review prompt — summarizes session outcomes and lessons
      */
-    async getSessionReviewPrompt(sessionId) {
-        let sections = [];
+    async getSessionReviewPrompt(_sessionId) {
+        const sections = [];
         try {
             const outcomeStorage = outcome_storage_1.OutcomeStorage.getInstance();
             const projectId = config_1.ConfigService.getInstance().getProjectId();
@@ -508,12 +491,9 @@ Be conservative - only extract clear, explicit preferences.`
         return {
             description: 'Session outcome review and lessons learned',
             messages: [
-                {
-                    role: 'system',
-                    content: sections.length > 0
-                        ? `# Session Review\n\n${sections.join('\n\n')}`
-                        : '# Session Review\n\nNo outcome data available yet.'
-                }
+                this.textMessage(sections.length > 0
+                    ? `# Session Review\n\n${sections.join('\n\n')}`
+                    : '# Session Review\n\nNo outcome data available yet.')
             ]
         };
     }
@@ -524,10 +504,7 @@ Be conservative - only extract clear, explicit preferences.`
         return {
             description: 'Error',
             messages: [
-                {
-                    role: 'system',
-                    content: `Error: ${message}`
-                }
+                this.textMessage(`Error: ${message}`)
             ]
         };
     }

package/dist/mcp/resources-handler.js

@@ -13,7 +13,7 @@ class ResourcesHandler {
     constructor() {
         this.logger = logging_1.LoggingService.getInstance();
         this.memoryService = memory_1.MemoryService.getInstance();
-        this.memoryStorage = this.memoryService.storage;
+        this.memoryStorage = this.memoryService.getStorage();
     }
     /**
      * Handle resources/list request