claude-recall 0.31.0 → 0.32.0

package/README.md

@@ -206,7 +206,7 @@ claude-recall checkpoint save --completed "API layer" --remaining "wire the UI"
 claude-recall checkpoint load
 ```
 
-Auto-checkpoints are also saved on session exit in Claude Code and Pi (Pi has no `--resume`, so this is its main recovery path). Extraction uses Haiku via `ANTHROPIC_API_KEY`; without a key, only manual checkpoints work. A quality gate refuses to overwrite a manual checkpoint with a fabricated one when the task was already complete.
+Auto-checkpoints are also saved on session exit in Claude Code and Pi (Pi has no `--resume`, so this is its main recovery path). Extraction runs on your **Claude subscription** (headless `claude -p`) — like capture, no API key needed; an exported `ANTHROPIC_API_KEY` is only a fallback. The same applies to the other background LLM features (failure hindsight hints, end-of-session lesson extraction). A quality gate refuses to overwrite a manual checkpoint with a fabricated one when the task was already complete.
 
 ### Troubleshooting
 
@@ -387,7 +387,7 @@ Defaults work out of the box; tune via environment variables as needed.
 | Variable                                 | Default | Effect                                                                                                   |
 | ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
 | `CLAUDE_RECALL_DB_PATH`                  | `~/.claude-recall/` | Database directory.                                                                          |
-| `ANTHROPIC_API_KEY`                      | _(unset)_ | Optional personal API key for Haiku-based classification. **Never required and never provided by Claude Code** — capture uses each runtime's own LLM first (Claude subscription via `claude -p`; Kiro credits via `kiro-cli`). A key you exported is only consulted as a fallback, or first with `CLAUDE_RECALL_PREFER_API_KEY=1`. Regex is the final fallback. |
+| `ANTHROPIC_API_KEY`                      | _(unset)_ | Optional personal API key for Haiku-based LLM features. **Never required and never provided by Claude Code** — capture, checkpoint extraction, hindsight hints, and session lessons all use each runtime's own LLM first (Claude subscription via `claude -p`; Kiro credits via `kiro-cli`). A key you exported is only consulted as a fallback, or first with `CLAUDE_RECALL_PREFER_API_KEY=1`. Regex is the final fallback. |
 | `CLAUDE_RECALL_CC_MODEL`                 | `haiku` | Dedicated model for capture classification under Claude Code (passed to `claude -p --model`) — independent of your interactive session model. |
 | `CLAUDE_RECALL_CC_LLM_TIMEOUT_MS`        | `30000` | Hard cap on the headless `claude -p` classify call before the capture worker gives up and falls through. |
 | `CLAUDE_RECALL_KIRO_MODEL`               | `claude-haiku-4.5` | Dedicated model for Kiro-LLM capture classification — **independent of your interactive Kiro chat model**. Raise to `claude-sonnet-4.6` for steadier judgement at more credits. See [docs/kiro-llm-capture.md](docs/kiro-llm-capture.md). |

package/dist/hooks/cc-capture.js

@@ -30,7 +30,9 @@ async function handleCcCapture(input) {
     // Recursion guard: if we're already inside a classifier's nested headless
     // session (claude -p or kiro-cli fired hooks of its own), do NOT spawn
     // another worker — that would classify the classify prompt, forever.
-    if (process.env.CLAUDE_RECALL_CC_CLASSIFIER || process.env.CLAUDE_RECALL_KIRO_CLASSIFIER) {
+    if (process.env.CLAUDE_RECALL_NESTED
+        || process.env.CLAUDE_RECALL_CC_CLASSIFIER
+        || process.env.CLAUDE_RECALL_KIRO_CLASSIFIER) {
         return;
     }
     const prompt = input?.prompt ?? '';

package/dist/hooks/cc-classifier.js

@@ -57,6 +57,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.completeWithClaudeCli = completeWithClaudeCli;
 exports.classifyWithClaudeCli = classifyWithClaudeCli;
 const child_process_1 = require("child_process");
 const os = __importStar(require("os"));
@@ -65,18 +66,28 @@ const kiro_classifier_1 = require("./kiro-classifier");
 const DEFAULT_MODEL = 'haiku';
 const DEFAULT_TIMEOUT_MS = 30000;
 /**
- * Classify a prompt by invoking Claude Code's headless mode. Returns null on
- * any failure (claude not on PATH, timeout, non-zero exit, unparseable output)
- * so the caller falls back to the next backend. Never throws.
+ * Run one headless `claude -p` completion on the user's Claude SUBSCRIPTION
+ * and return raw stdout, or null on any failure (claude not on PATH, timeout,
+ * non-zero exit). Never throws. This is the generic primitive: capture
+ * classification wraps it below, and llm-classifier routes its secondary
+ * features (hindsight hints, session extraction, checkpoint extraction,
+ * batch classification) through it so none of them require an API key either.
  */
-function classifyWithClaudeCli(text) {
+function completeWithClaudeCli(prompt, opts = {}) {
     const model = process.env.CLAUDE_RECALL_CC_MODEL || DEFAULT_MODEL;
-    const timeoutMs = parseInt(process.env.CLAUDE_RECALL_CC_LLM_TIMEOUT_MS || '', 10);
-    const timeout = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS;
+    const envTimeout = parseInt(process.env.CLAUDE_RECALL_CC_LLM_TIMEOUT_MS || '', 10);
+    const timeout = opts.timeoutMs
+        ?? (Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : DEFAULT_TIMEOUT_MS);
     // Force subscription auth: with ANTHROPIC_API_KEY set, `claude -p` bills the
-    // key instead of the login — the exact behavior this classifier exists to
-    // avoid. CLAUDE_RECALL_CC_CLASSIFIER rides along as the recursion guard.
-    const env = { ...process.env, CLAUDE_RECALL_CC_CLASSIFIER: '1' };
+    // key instead of the login — the exact behavior this backend exists to
+    // avoid. CLAUDE_RECALL_NESTED marks the child as a nested headless session
+    // (every CLI-backend consumer checks it before spawning — recursion guard);
+    // CLAUDE_RECALL_CC_CLASSIFIER rides along for the capture-hook guard too.
+    const env = {
+        ...process.env,
+        CLAUDE_RECALL_CC_CLASSIFIER: '1',
+        CLAUDE_RECALL_NESTED: '1',
+    };
     delete env.ANTHROPIC_API_KEY;
     return new Promise((resolve) => {
         let settled = false;
@@ -91,7 +102,7 @@ function classifyWithClaudeCli(text) {
             // args array (no shell) — the user's text is a single argv entry, so no
             // shell escaping or injection is possible. cwd is the temp dir so the
             // nested session loads no project settings or hooks.
-            child = (0, child_process_1.spawn)('claude', ['-p', '--model', model, (0, kiro_classifier_1.buildClassifyPrompt)(text)], { cwd: os.tmpdir(), env, stdio: ['ignore', 'pipe', 'ignore'] });
+            child = (0, child_process_1.spawn)('claude', ['-p', '--model', model, prompt], { cwd: os.tmpdir(), env, stdio: ['ignore', 'pipe', 'ignore'] });
         }
         catch (err) {
             (0, shared_1.hookLog)('cc-classifier', `spawn threw: ${(0, shared_1.safeErrorMessage)(err)}`);
@@ -121,22 +132,34 @@ function classifyWithClaudeCli(text) {
                 (0, shared_1.hookLog)('cc-classifier', `claude -p exited ${code}`);
                 return done(null);
             }
-            const result = (0, kiro_classifier_1.extractClassification)(stdout);
-            if (!result) {
-                // Distinguish a deliberate "none" verdict from unparseable output —
-                // "the model said not a rule" and "the call broke" are different
-                // diagnoses when reading the log.
-                (0, shared_1.hookLog)('cc-classifier', /"type"\s*:\s*"none"/.test(stdout)
-                    ? 'classified as none (not a durable rule)'
-                    : 'no parseable classification in claude -p output');
-            }
-            else {
-                // Same observability contract as kiro-classifier: spell out which
-                // backend ran and on whose account, so "which LLM classified this?"
-                // is always answerable from the log.
-                (0, shared_1.hookLog)('cc-classifier', `classified via claude -p (model=${model}, Claude subscription, no API key): ${result.type} — ${result.extract.slice(0, 60)}`);
-            }
-            done(result);
+            done(stdout);
         });
     });
 }
+/**
+ * Classify a prompt by invoking Claude Code's headless mode. Returns null on
+ * any failure (claude not on PATH, timeout, non-zero exit, unparseable output)
+ * so the caller falls back to the next backend. Never throws.
+ */
+async function classifyWithClaudeCli(text) {
+    const model = process.env.CLAUDE_RECALL_CC_MODEL || DEFAULT_MODEL;
+    const stdout = await completeWithClaudeCli((0, kiro_classifier_1.buildClassifyPrompt)(text));
+    if (stdout === null)
+        return null;
+    const result = (0, kiro_classifier_1.extractClassification)(stdout);
+    if (!result) {
+        // Distinguish a deliberate "none" verdict from unparseable output —
+        // "the model said not a rule" and "the call broke" are different
+        // diagnoses when reading the log.
+        (0, shared_1.hookLog)('cc-classifier', /"type"\s*:\s*"none"/.test(stdout)
+            ? 'classified as none (not a durable rule)'
+            : 'no parseable classification in claude -p output');
+    }
+    else {
+        // Same observability contract as kiro-classifier: spell out which
+        // backend ran and on whose account, so "which LLM classified this?"
+        // is always answerable from the log.
+        (0, shared_1.hookLog)('cc-classifier', `classified via claude -p (model=${model}, Claude subscription, no API key): ${result.type} — ${result.extract.slice(0, 60)}`);
+    }
+    return result;
+}

package/dist/hooks/llm-classifier.js

@@ -16,9 +16,17 @@ exports.extractHindsightHint = extractHindsightHint;
 exports.extractSessionLearningsWithLLM = extractSessionLearningsWithLLM;
 exports.extractCheckpointWithLLM = extractCheckpointWithLLM;
 exports.classifyBatchWithLLM = classifyBatchWithLLM;
+const cc_classifier_1 = require("./cc-classifier");
 // Lazy singleton — avoid import cost when API key is absent
 let clientInstance; // undefined = not yet checked
 const MODEL = 'claude-haiku-4-5-20251001';
+/**
+ * Per-call cap for `claude -p` in these SECONDARY features. Unlike capture
+ * (detached worker, 30s budget), hindsight hints / session extraction / batch
+ * classification run INLINE in the Stop hook (~40s total budget, possibly
+ * several calls) — a hung CLI must not eat the whole hook.
+ */
+const SECONDARY_CLI_TIMEOUT_MS = 10000;
 const SYSTEM_PROMPT = `You are a memory classifier for a developer tool. Classify user text into one of these types:
 
 - correction: User durably correcting how something should ALWAYS be done ("no, use X not Y", "wrong, it should be..."). Correcting a one-off action in the current task is NOT durable — only store it if the rule generalizes beyond this moment.
@@ -113,11 +121,74 @@ function getClient() {
     }
 }
 /**
- * Parse a JSON response, stripping markdown fences if present.
+ * Parse a JSON response, stripping markdown fences if present. Falls back to
+ * slicing the first balanced-looking JSON region — `claude -p` occasionally
+ * wraps output in prose or a trailing fence the strict strip misses.
  */
 function parseJSON(text) {
     const cleaned = text.trim().replace(/^```(?:json)?\s*/, '').replace(/\s*```$/, '');
-    return JSON.parse(cleaned);
+    try {
+        return JSON.parse(cleaned);
+    }
+    catch (err) {
+        const starts = [cleaned.indexOf('{'), cleaned.indexOf('[')].filter((i) => i !== -1);
+        if (starts.length === 0)
+            throw err;
+        const start = Math.min(...starts);
+        const end = Math.max(cleaned.lastIndexOf('}'), cleaned.lastIndexOf(']'));
+        if (end <= start)
+            throw err;
+        return JSON.parse(cleaned.slice(start, end + 1));
+    }
+}
+/**
+ * Run one completion for the SECONDARY LLM features (hindsight hints, session
+ * extraction, checkpoint extraction, batch classification) and return raw
+ * text, or null when no backend is available.
+ *
+ * Backend order matches capture: the user's Claude SUBSCRIPTION (headless
+ * `claude -p`) before a personally-exported ANTHROPIC_API_KEY, flipped by
+ * CLAUDE_RECALL_PREFER_API_KEY. So running out of Anthropic API credits — or
+ * never having a key at all — does not disable these features on any machine
+ * with the `claude` binary (Claude Code itself, or Pi running alongside it).
+ *
+ * The CLI backend is skipped inside a nested headless session
+ * (CLAUDE_RECALL_NESTED): if `claude -p` fires user-scope hooks of its own,
+ * those hooks must not spawn further `claude -p` calls.
+ */
+async function completeText(systemPrompt, userContent, maxTokens) {
+    const viaApi = async () => {
+        const client = getClient();
+        if (!client)
+            return null;
+        try {
+            const response = await client.messages.create({
+                model: MODEL,
+                max_tokens: maxTokens,
+                system: systemPrompt,
+                messages: [{ role: 'user', content: userContent }],
+            });
+            const content = response.content?.[0];
+            return content?.type === 'text' ? content.text : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    // `claude -p` takes a single argument (no system-prompt channel), so
+    // instruction and payload are combined — same shape as the Kiro backend.
+    const viaCli = () => process.env.CLAUDE_RECALL_NESTED
+        ? Promise.resolve(null)
+        : (0, cc_classifier_1.completeWithClaudeCli)(`${systemPrompt}\n\n${userContent}`, { timeoutMs: SECONDARY_CLI_TIMEOUT_MS });
+    const backends = process.env.CLAUDE_RECALL_PREFER_API_KEY
+        ? [viaApi, viaCli]
+        : [viaCli, viaApi];
+    for (const backend of backends) {
+        const text = await backend();
+        if (text !== null && text.trim().length > 0)
+            return text;
+    }
+    return null;
 }
 /**
  * Classify a single text using Claude Haiku.
@@ -159,20 +230,11 @@ async function classifyWithLLM(text) {
  * callers fall back to grounding the detector's generic remedy text.
  */
 async function extractHindsightHint(failureDescription, context) {
-    const client = getClient();
-    if (!client)
+    const text = await completeText('You extract actionable hindsight lessons from failures. Given a failure description and context, produce a JSON object with: hint_text (imperative rule to prevent recurrence), hint_kind (one of: rule, preference, anti_pattern, workflow, debug_fix, failure_preventer), applies_when (array of 1-3 situation tags). Respond with ONLY valid JSON.', `Failure: ${failureDescription}\nContext: ${context}`, 300);
+    if (!text)
         return null;
     try {
-        const response = await client.messages.create({
-            model: MODEL,
-            max_tokens: 300,
-            system: 'You extract actionable hindsight lessons from failures. Given a failure description and context, produce a JSON object with: hint_text (imperative rule to prevent recurrence), hint_kind (one of: rule, preference, anti_pattern, workflow, debug_fix, failure_preventer), applies_when (array of 1-3 situation tags). Respond with ONLY valid JSON.',
-            messages: [{ role: 'user', content: `Failure: ${failureDescription}\nContext: ${context}` }],
-        });
-        const content = response.content?.[0];
-        if (content?.type !== 'text')
-            return null;
-        const result = parseJSON(content.text);
+        const result = parseJSON(text);
         if (!result.hint_text || !result.hint_kind)
             return null;
         return {
@@ -220,24 +282,15 @@ Return [] if nothing durable was learned. Max 10 items. Each content should be a
  * Returns null if no API key or on any failure.
  */
 async function extractSessionLearningsWithLLM(summary, existingMemories) {
-    const client = getClient();
-    if (!client)
+    const memList = existingMemories.length > 0
+        ? existingMemories.map(m => `- ${m}`).join('\n')
+        : '(none)';
+    const systemPrompt = SESSION_EXTRACTION_PROMPT + `\n\nEXISTING MEMORIES (do not duplicate):\n${memList}`;
+    const text = await completeText(systemPrompt, summary, 1000);
+    if (!text)
         return null;
     try {
-        const memList = existingMemories.length > 0
-            ? existingMemories.map(m => `- ${m}`).join('\n')
-            : '(none)';
-        const systemPrompt = SESSION_EXTRACTION_PROMPT + `\n\nEXISTING MEMORIES (do not duplicate):\n${memList}`;
-        const response = await client.messages.create({
-            model: MODEL,
-            max_tokens: 1000,
-            system: systemPrompt,
-            messages: [{ role: 'user', content: summary }],
-        });
-        const content = response.content?.[0];
-        if (content?.type !== 'text')
-            return null;
-        const results = parseJSON(content.text);
+        const results = parseJSON(text);
         if (!Array.isArray(results))
             return null;
         const validTypes = ['project-knowledge', 'preference', 'devops', 'failure'];
@@ -304,23 +357,14 @@ Examples of BAD output (DO NOT DO THIS):
 {"completed":"explored architecture","remaining":"document findings","blockers":"none"} # FABRICATED — there was no documentation task
 {"completed":"finished everything","remaining":"finish everything","blockers":"none"}   # nonsense filler`;
 async function extractCheckpointWithLLM(conversationSummary) {
-    const client = getClient();
-    if (!client)
-        return null;
     if (!conversationSummary || conversationSummary.trim().length < 30) {
         return null;
     }
+    const text = await completeText(CHECKPOINT_EXTRACTION_PROMPT, conversationSummary, 600);
+    if (!text)
+        return null;
     try {
-        const response = await client.messages.create({
-            model: MODEL,
-            max_tokens: 600,
-            system: CHECKPOINT_EXTRACTION_PROMPT,
-            messages: [{ role: 'user', content: conversationSummary }],
-        });
-        const content = response.content?.[0];
-        if (content?.type !== 'text')
-            return null;
-        const result = parseJSON(content.text);
+        const result = parseJSON(text);
         if (typeof result !== 'object' || result === null)
             return null;
         return {
@@ -336,25 +380,16 @@ async function extractCheckpointWithLLM(conversationSummary) {
 async function classifyBatchWithLLM(texts) {
     if (texts.length === 0)
         return [];
-    const client = getClient();
-    if (!client)
+    // JSON array, not delimiter-joined text: a user message that happened to
+    // contain the old "---ITEM---" marker desynced item counts and silently
+    // dropped the entire batch to the regex fallback. JSON boundaries can't
+    // be forged by content.
+    const joined = JSON.stringify(texts);
+    const text = await completeText(BATCH_SYSTEM_PROMPT, joined, texts.length * 200);
+    if (!text)
         return null;
     try {
-        // JSON array, not delimiter-joined text: a user message that happened to
-        // contain the old "---ITEM---" marker desynced item counts and silently
-        // dropped the entire batch to the regex fallback. JSON boundaries can't
-        // be forged by content.
-        const joined = JSON.stringify(texts);
-        const response = await client.messages.create({
-            model: MODEL,
-            max_tokens: texts.length * 200,
-            system: BATCH_SYSTEM_PROMPT,
-            messages: [{ role: 'user', content: joined }],
-        });
-        const content = response.content?.[0];
-        if (content?.type !== 'text')
-            return null;
-        const results = parseJSON(content.text);
+        const results = parseJSON(text);
         if (!Array.isArray(results) || results.length !== texts.length)
             return null;
         return results.map((r) => {

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

@@ -448,13 +448,17 @@ const VALID_LESSON_KINDS = new Set([
 async function generateCandidateLessons(failures, episodeId, projectId) {
     try {
         const outcomeStorage = outcome_storage_1.OutcomeStorage.getInstance();
+        // Each hint is an LLM call (via the subscription CLI it can take seconds),
+        // and this loop runs INLINE in the Stop hook's ~40s budget — cap the LLM
+        // calls per run; failures past the cap keep the grounded generic lesson.
+        let hintBudget = 5;
         for (const f of failures) {
             if (f.confidence < 0.7)
                 continue;
             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 || '');
+            const hint = hintBudget-- > 0 ? await (0, llm_classifier_1.extractHindsightHint)(`${f.content.what_failed}${f.content.why_failed ? ` — ${f.content.why_failed}` : ''}`, f.content.context || '') : null;
             if (hint) {
                 lessonText = hint.hint_text;
                 if (VALID_LESSON_KINDS.has(hint.hint_kind)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-recall",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Persistent memory for Claude Code and Pi with native Skills integration, automatic capture, failure learning, and project scoping",
   "main": "dist/index.js",
   "bin": {