claude-recall 0.29.2 → 0.30.0

package/README.md

@@ -123,7 +123,7 @@ tail -5 ~/.claude-recall/hook-logs/hook-dispatcher.log
 
 The log should show a `scope [...] → project=your-project` line; `claude-recall kiro doctor` gives a fuller health report.
 
-> **Capture uses Kiro's own LLM — no API key needed.** To decide what's worth remembering, the capture hook classifies each prompt with Kiro's model via a headless `kiro-cli chat --no-interactive` call (through a bundled bare `claude-recall-classifier` agent). So natural statements like "my favourite color is green" are captured without any `ANTHROPIC_API_KEY` and without the `store_memory` MCP tool — which matters under enterprise governance that blocks the MCP server. It runs in a detached background worker, so your turn is never blocked; it spends ~0.06 Kiro credits per prompt. Precedence: `ANTHROPIC_API_KEY` (if you set one) → Kiro's LLM → a regex fallback. Tune with `CLAUDE_RECALL_KIRO_MODEL` (default `claude-haiku-4.5`). Details in [docs/kiro-llm-capture.md](docs/kiro-llm-capture.md).
+> **Capture uses Kiro's own LLM — no API key needed.** To decide what's worth remembering, the capture hook classifies each prompt with Kiro's model via a headless `kiro-cli chat --no-interactive` call (through a bundled bare `claude-recall-classifier` agent). So natural statements like "my favourite color is green" are captured without any `ANTHROPIC_API_KEY` and without the `store_memory` MCP tool — which matters under enterprise governance that blocks the MCP server. It runs in a detached background worker, so your turn is never blocked; it spends ~0.06 Kiro credits per prompt. **Under Kiro the included LLM is used first even if you happen to have `ANTHROPIC_API_KEY` set** — so a key exported for other tools won't quietly spend your Anthropic credits. Order: Kiro's LLM → `ANTHROPIC_API_KEY` (if present) → regex; set `CLAUDE_RECALL_PREFER_API_KEY=1` to force your key first (e.g. for a stronger model you pay for). Tune the Kiro model with `CLAUDE_RECALL_KIRO_MODEL` (default `claude-haiku-4.5`). Details in [docs/kiro-llm-capture.md](docs/kiro-llm-capture.md).
 
 **Option B — MCP tools only (no hooks, works in Kiro's default agent).**
 
@@ -562,8 +562,9 @@ Runtime behavior can be tuned via environment variables. Defaults are chosen so
 | Variable                                 | Default | Effect                                                                                                   |
 | ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
 | `CLAUDE_RECALL_DB_PATH`                  | `~/.claude-recall/` | Database directory.                                                                          |
-| `ANTHROPIC_API_KEY`                      | _(unset)_ | Enables LLM-based classification (Haiku). Under Kiro, falls back to Kiro's own headless LLM when missing; otherwise falls back to regex.        |
+| `ANTHROPIC_API_KEY`                      | _(unset)_ | LLM classification via Haiku. Not required — Claude Code provides it to its hooks, and under Kiro the included LLM is used instead (and is preferred even if this is set). Regex is the final fallback. |
 | `CLAUDE_RECALL_KIRO_MODEL`               | `claude-haiku-4.5` | Model for Kiro-LLM capture classification. Raise to `claude-sonnet-4.6` for steadier judgement at more credits. See [docs/kiro-llm-capture.md](docs/kiro-llm-capture.md). |
+| `CLAUDE_RECALL_PREFER_API_KEY`           | _(unset)_ | Under Kiro, force `ANTHROPIC_API_KEY`-based classification ahead of Kiro's included LLM (uses your Anthropic credits — e.g. for a stronger model). No effect under Claude Code. |
 | `CLAUDE_RECALL_KIRO_LLM_TIMEOUT_MS`      | `30000` | Hard cap on the headless `kiro-cli` classify call before the capture worker gives up and falls back to regex. |
 | `CLAUDE_RECALL_LOAD_BUDGET_TOKENS`       | `2000`  | Token budget for the `load_rules` payload. Rules are emitted in priority order (corrections → preferences by citation → devops by citation → failures) and dropped rules surface via `search_memory`. |
 | `CLAUDE_RECALL_AUTO_DEMOTE`              | `false` | When `true`, auto-demote rules on MCP boot where `load_count >= CLAUDE_RECALL_DEMOTE_MIN_LOADS`, `cite_count = 0`, and age `> CLAUDE_RECALL_DEMOTE_MIN_AGE_DAYS`. Still reversible via `rules promote <id>`. |

package/dist/cli/commands/kiro-commands.js

@@ -480,7 +480,9 @@ class KiroCommands {
             line('⚠', 'kiro-cli not on PATH — capture cannot reach Kiro\'s LLM and falls back to regex.');
         }
         if (process.env.ANTHROPIC_API_KEY) {
-            line('•', 'ANTHROPIC_API_KEY is set — it takes precedence over the Kiro LLM for capture.');
+            line('•', process.env.CLAUDE_RECALL_PREFER_API_KEY
+                ? 'ANTHROPIC_API_KEY set + CLAUDE_RECALL_PREFER_API_KEY — capture uses your key (your Anthropic credits) before the Kiro LLM.'
+                : 'ANTHROPIC_API_KEY is set but under Kiro the included LLM is used first, so it won\'t spend your Anthropic credits. Set CLAUDE_RECALL_PREFER_API_KEY to force the key.');
         }
         // --- Hook activity ---
         console.log('\nRecent hook activity');

package/dist/hooks/shared.js

@@ -143,14 +143,18 @@ function classifyContentRegex(text) {
     return null;
 }
 /**
- * Classify text content — LLM-first, regex fallback.
+ * Classify text content — LLM-first, regex fallback. No API key is ever
+ * required: each runtime brings its own LLM.
+ *
  * Precedence:
- *   1. Claude Haiku via ANTHROPIC_API_KEY (Claude Code sets this automatically).
- *   2. Kiro's headless LLM (`kiro-cli chat --no-interactive`) when running under
- *      Kiro — no API key needed. Gated on CLAUDE_RECALL_KIRO_CLASSIFIER, which
- *      the kiro-capture-worker sets; the classify call is ~3s so it only runs
- *      from that detached worker, never inline. See docs/kiro-llm-capture.md.
- *   3. Regex patterns, if neither LLM path yields a result.
+ *   - Under Claude Code: Claude Haiku via ANTHROPIC_API_KEY (Claude Code
+ *     provides this to its hooks) → regex.
+ *   - Under Kiro (CLAUDE_RECALL_KIRO_CLASSIFIER set by the kiro-capture-worker):
+ *     Kiro's own headless LLM (`kiro-cli chat --no-interactive`) → ANTHROPIC_
+ *     API_KEY if present → regex. Kiro's included LLM is preferred so a stray
+ *     key doesn't spend the user's Anthropic credits; CLAUDE_RECALL_PREFER_API_
+ *     KEY flips the order. The Kiro call is ~3s, so it runs only from the
+ *     detached worker, never inline. See docs/kiro-llm-capture.md.
  */
 async function classifyContent(text) {
     // Guard the LLM paths the same way the regex path is guarded: a question or
@@ -167,16 +171,32 @@ async function classifyContent(text) {
     return result;
 }
 async function classifyContentInner(text) {
-    const llmResult = await (0, llm_classifier_1.classifyWithLLM)(text);
-    if (llmResult)
-        return llmResult;
-    if (process.env.CLAUDE_RECALL_KIRO_CLASSIFIER) {
-        // Dynamic import keeps kiro-classifier (and child_process) out of the
-        // module graph for every non-Kiro hook invocation.
-        const { classifyWithKiro } = await Promise.resolve().then(() => __importStar(require('./kiro-classifier')));
-        const kiroResult = await classifyWithKiro(text);
-        if (kiroResult)
-            return kiroResult;
+    const underKiro = !!process.env.CLAUDE_RECALL_KIRO_CLASSIFIER;
+    const preferApiKey = !!process.env.CLAUDE_RECALL_PREFER_API_KEY;
+    const tryApiKey = () => (0, llm_classifier_1.classifyWithLLM)(text);
+    // Dynamic import keeps kiro-classifier (and child_process) out of the module
+    // graph for every non-Kiro hook invocation.
+    const tryKiro = async () => (await Promise.resolve().then(() => __importStar(require('./kiro-classifier')))).classifyWithKiro(text);
+    // Order the two LLM backends. Under Kiro, prefer Kiro's INCLUDED LLM over a
+    // stray ANTHROPIC_API_KEY: a key exported for other tools should not silently
+    // spend the user's Anthropic credits when Kiro already ships an LLM. Set
+    // CLAUDE_RECALL_PREFER_API_KEY to force the key first (e.g. to use a stronger
+    // model you pay for). Under Claude Code the Kiro backend isn't available, so
+    // the key path is the only LLM classifier.
+    const backends = [];
+    if (underKiro && !preferApiKey) {
+        backends.push(tryKiro, tryApiKey);
+    }
+    else if (underKiro) {
+        backends.push(tryApiKey, tryKiro);
+    }
+    else {
+        backends.push(tryApiKey);
+    }
+    for (const backend of backends) {
+        const result = await backend();
+        if (result)
+            return result;
     }
     return classifyContentRegex(text);
 }

package/docs/kiro-llm-capture.md

@@ -93,9 +93,13 @@ Kiro userPromptSubmit
         └─ regex fallback       (only if both above yield nothing)
 ```
 
-Capture precedence under Kiro becomes: **your own `ANTHROPIC_API_KEY` if you set
-one → Kiro's headless LLM → regex as a last resort.** In the governance-locked,
-no-key setup the Kiro LLM is the primary path and regex is just a safety net.
+Capture precedence under Kiro: **Kiro's included LLM → `ANTHROPIC_API_KEY` if
+present → regex as a last resort.** The Kiro LLM comes first *even when a key is
+set*, so a key exported for other tools never silently spends the user's
+Anthropic credits — Kiro already ships an LLM. `CLAUDE_RECALL_PREFER_API_KEY=1`
+flips the order back to key-first for anyone who deliberately wants to pay for a
+stronger model. (Under Claude Code there is no Kiro backend, so the key path is
+the only LLM classifier — Claude Code provides the key to its hooks.)
 
 ### Output parsing
 
@@ -112,6 +116,7 @@ returns `null`, degrading to regex — a hook must never throw.
 | `CLAUDE_RECALL_KIRO_CLASSIFIER` | *(set by the worker)* | Enables the Kiro-LLM path in `classifyContent`. Set automatically by `kiro-capture-worker`; never needed by hand. |
 | `CLAUDE_RECALL_KIRO_MODEL` | `claude-haiku-4.5` | Model for the classify call. Raise to `claude-sonnet-4.6` for steadier judgement at ~3× the credits. |
 | `CLAUDE_RECALL_KIRO_LLM_TIMEOUT_MS` | `30000` | Hard cap on the headless call before the worker gives up and falls back to regex. |
+| `CLAUDE_RECALL_PREFER_API_KEY` | *(unset)* | Force `ANTHROPIC_API_KEY`-based classification ahead of Kiro's included LLM (opt-in; uses your Anthropic credits). |
 
 ## Caveats
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-recall",
-  "version": "0.29.2",
+  "version": "0.30.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": {