claude-recall 0.29.1 → 0.30.0

package/README.md

@@ -103,7 +103,7 @@ You get: active rules injected into context automatically at agent start (no too
 claude-recall kiro setup --merge-into <agent-name>
 ```
 
-This finds the agent config (workspace `.kiro/agents/` first, then `~/.kiro/agents/`; `--global` to target the global one directly), writes a timestamped backup, and appends the claude-recall pieces — MCP server, pre-approved read-only tools, and the four hooks — without touching anything the agent already had. Idempotent: re-running changes nothing. If the agent restricts tools with an explicit list, `@claude-recall` is added to it.
+This finds the agent config (workspace `.kiro/agents/` first, then `~/.kiro/agents/`; `--global` to target the global one directly), writes a timestamped backup, and appends the claude-recall pieces — MCP server, pre-approved read-only tools, and the four hooks — while leaving your own config untouched. It only rewrites claude-recall's own entries: superseded ones from an older version are swapped for the current wiring (any unrelated hook you have on the same event is preserved). Idempotent: on an already-current agent, re-running changes nothing. If the agent restricts tools with an explicit list, `@claude-recall` is added to it.
 
 > **⚠️ After `kiro setup` or `--merge-into`: start ONE fresh conversation per project (no `--resume`).** Kiro snapshots the agent config into each conversation **at creation** — `--resume` restores that snapshot and ignores agent-config changes made since. So conversations created *before* you wired claude-recall will **never** run its hooks, no matter how often you resume them or restart Kiro. Start one fresh conversation after wiring; every conversation created from then on carries the hooks, **including when resumed** (`--resume` works normally afterwards — this is a one-time rollover per project).
 
@@ -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).**
 
@@ -175,7 +175,7 @@ Per-runtime notes:
 
 - **Claude Code** — nothing else needed; registrations point at the `claude-recall` command, not a pinned path. If the release notes mention new or changed hooks (a `hooksVersion` bump), also re-run `claude-recall setup --install` in each active project — safe any time; a no-op when hooks are already current.
 - **Pi** — run `pi update npm:claude-recall` and restart Pi.
-- **Kiro CLI** — nothing else needed; the agent config points at the `claude-recall` command. If the release notes mention changes to the Kiro agent template, re-run `claude-recall kiro setup --force` in each project that uses it.
+- **Kiro CLI** — the agent config points at the `claude-recall` command, so the binary upgrade alone applies to hook *behaviour*. But when the release notes change the agent *template* (new hooks, the classifier agent, revised wiring — e.g. the **0.29.x** Kiro-LLM capture), re-run setup once so the agent picks it up: `claude-recall kiro setup --force` for the standalone `recall` agent, or `claude-recall kiro setup --merge-into <agent>` for an agent you merged into. That also writes the `claude-recall-classifier` agent and strips any superseded hooks. Then start one fresh conversation per project (the snapshot rollover above). `claude-recall kiro doctor` confirms the result.
 
 > **Claude Code registered before v0.27.x?** Older versions auto-registered the MCP server with an `npx`-based command, which re-resolves the package on every server start and can be shadowed by stale project-local installs. Switch to the direct binary form (run in each affected project):
 >
@@ -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

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isConversationalNotRule = isConversationalNotRule;
 exports.readStdin = readStdin;
 exports.classifyContentRegex = classifyContentRegex;
 exports.classifyContent = classifyContent;
@@ -90,6 +91,17 @@ const PREFERENCE_PATTERNS = [
 // corrections ("no worries, that looks good").
 const INTERROGATIVE_START = /^(do|does|did|can|could|would|should|shall|is|are|was|were|will|have|has|what|why|how|when|where|who|which)\b/i;
 const PLEASANTRY_NO = /^no\s+(worries|problem|problems|prob|thanks|thank|rush|need|biggie|sweat|pressure)\b/i;
+/**
+ * True when a prompt reads as conversation rather than a storable rule: it ends
+ * with a question mark, opens with an interrogative, or is a "no worries"-style
+ * pleasantry. Applied to EVERY classifier path (regex, Haiku, Kiro) — the LLMs
+ * otherwise trust their own judgement and have stored questions like "what
+ * memories do you have?" as preferences.
+ */
+function isConversationalNotRule(text) {
+    const trimmed = text.trim();
+    return trimmed.endsWith('?') || INTERROGATIVE_START.test(trimmed) || PLEASANTRY_NO.test(trimmed);
+}
 // Failure, devops, and project-knowledge patterns removed — single-keyword
 // matches ("error", "git", "build") are too broad for regex. These types
 // require context that only the LLM classifier can assess. When the LLM is
@@ -108,9 +120,8 @@ function readStdin() {
  * Returns the highest-confidence match, prioritizing corrections > preferences.
  */
 function classifyContentRegex(text) {
-    const trimmed = text.trim();
     // Interrogatives and pleasantries are conversation, not rules
-    if (trimmed.endsWith('?') || INTERROGATIVE_START.test(trimmed) || PLEASANTRY_NO.test(trimmed)) {
+    if (isConversationalNotRule(text)) {
         return null;
     }
     // Priority order: correction > preference > failure > devops > project-knowledge
@@ -132,26 +143,60 @@ 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) {
-    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;
+    // Guard the LLM paths the same way the regex path is guarded: a question or
+    // pleasantry is conversation, never a rule. Haiku/Kiro don't apply this on
+    // their own and have stored prompts like "what memories do you have?".
+    if (isConversationalNotRule(text))
+        return null;
+    const result = await classifyContentInner(text);
+    // Reject if the classifier echoed a question instead of distilling a rule:
+    // a stored directive is declarative, so a '?' in the extract signals a
+    // conversational false positive (e.g. an LLM regurgitating the prompt).
+    if (result && result.extract.includes('?'))
+        return null;
+    return result;
+}
+async function classifyContentInner(text) {
+    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.1",
+  "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": {