claude-recall 0.30.2 → 0.31.0

package/README.md

@@ -14,11 +14,13 @@ It works with **Claude Code**, **[Pi](https://github.com/mariozechner/pi)**, and
 
 > **You:** use pnpm here, not npm
 
+Seconds later, silently in the background (`~/.claude-recall/hook-logs/cc-classifier.log`):
+
 ```text
-📌 Recall: auto-captured correction — Use pnpm, not npm
+classified via claude -p (model=haiku, Claude subscription, no API key): correction — Use pnpm, not npm
 ```
 
-That one line did everything. A hook classified your prompt with an LLM, decided it was a durable rule (not chit-chat), and stored it locally. No "remember this" incantation, no tool call, no config file to edit.
+That's the whole workflow. A background hook classified your prompt with an LLM — **the agent's own LLM** (your Claude subscription under Claude Code, Kiro's credits under Kiro; no API key involved) — decided it was a durable rule and stored it locally. No "remember this" incantation, no tool call, no config file to edit.
 
 **Friday — brand-new session, no shared history:**
 
@@ -42,7 +44,7 @@ $ claude-recall search "pnpm"
 
 ## Features
 
-- **Automatic capture** — an LLM classifier detects preferences, corrections, and project facts in your normal prompts (regex fallback when no LLM is available)
+- **Automatic capture** — an LLM classifier detects preferences, corrections, and project facts in your normal prompts, running on **the agent's own LLM** (Claude subscription / Kiro credits — never a separate API key), with regex fallback when no LLM is available
 - **Applied where it counts** — rules load at session start *and* are re-surfaced just-in-time before each tool call
 - **Project-scoped** — each project gets its own memory namespace; switch directories and the agent switches context
 - **Learns from failures** — records what broke, why, and what fixed it, so mistakes aren't repeated
@@ -83,6 +85,13 @@ claude mcp add --scope user claude-recall -- claude-recall mcp start
 
 Hook-based auto-capture remains a per-project opt-in via `claude-recall setup --install`.
 
+**Capture runs on your Claude subscription — no API key.** The capture hook classifies each prompt via a headless `claude -p` call on the same login that powers your session, in a detached background worker (your turn is never blocked; capture is silent and lands a few seconds later). If you happen to have `ANTHROPIC_API_KEY` exported for other tools, it is deliberately **not** used unless you set `CLAUDE_RECALL_PREFER_API_KEY=1` — a stray key shouldn't quietly spend your Anthropic API credits. Verify captures any time:
+
+```bash
+tail -5 ~/.claude-recall/hook-logs/cc-classifier.log   # which model ran, what was stored
+claude-recall search "something you said"
+```
+
 ### Pi
 
 ```bash
@@ -106,9 +115,38 @@ Already living in a custom agent of your own? Merge Claude Recall into it instea
 claude-recall kiro setup --merge-into <agent-name>
 ```
 
-> **⚠️ One-time rollover:** after `kiro setup` or `--merge-into`, start **one fresh conversation** (no `--resume`). Kiro snapshots the agent config when a conversation is *created*, so older conversations never see the new hooks — even resumed or after a restart. After that one fresh start, `--resume` works normally.
+> **⚠️ You must start ONE fresh conversation after setup — this is the most common reason "it does nothing."**
+>
+> After `kiro setup` or `--merge-into`, start **one new conversation without `--resume`**:
+>
+> ```bash
+> kiro-cli chat --agent recall        # or: --agent <your-agent> if you merged
+> ```
+>
+> Kiro snapshots the agent config at the moment a conversation is *created*. Any conversation that already existed — including one you reach with `--resume` or after restarting Kiro — was snapshotted **before** claude-recall was wired in, so it will **never** run the hooks and capture will silently do nothing. Once you've started that one fresh conversation, every conversation from then on carries the hooks and `--resume` works normally. This is a one-time rollover, once per project.
+>
+> Confirm the wiring is live before you rely on it:
+>
+> ```bash
+> claude-recall kiro doctor           # green checks = hooks are active for this project
+> ```
+
+**Capture runs on Kiro's own LLM — no API key, no personal subscription.** It classifies each prompt with a dedicated fixed model (default `claude-haiku-4.5`, independent of your chat model) and costs **~0.06 Kiro credits per prompt** — cheap, but note it's *every* prompt, so budget accordingly across a team.
+
+**What to expect from capture — read this so it doesn't feel broken:**
+
+- **It's silent and asynchronous.** Capture runs in a background worker so it never blocks your turn — which also means there's **no "captured ✓" message** in the Kiro chat. Stating a preference and seeing nothing happen is normal.
+- **It's a best-effort LLM judgement, not a guarantee.** The classifier decides what's a durable rule vs. chit-chat; it won't catch every phrasing, and near-identical wording can occasionally be judged differently. State preferences plainly ("use pnpm here, not npm") for the best hit rate.
+- **There's a ~3s lag.** A preference you just stated isn't queryable for a couple of seconds while the worker finishes.
+
+**To verify capture actually worked** — from a second terminal (Kiro's chat can't shell out):
+
+```bash
+claude-recall search "pnpm"                             # did the rule land?
+tail -5 ~/.claude-recall/hook-logs/kiro-classifier.log  # what the classifier decided, and which model ran
+```
 
-Capture under Kiro runs on **Kiro's own LLM** — no `ANTHROPIC_API_KEY`, no personal Anthropic subscription. It uses a dedicated fixed classifier model (default `claude-haiku-4.5`, independent of your chat model), costs ~0.06 Kiro credits per prompt, and never blocks your turn. Verify with `claude-recall kiro doctor`.
+Or, from **inside the Kiro session**, just ask the agent to recall it (*"what do you remember about my package manager?"*) — it reads the same DB and will surface the stored rule if capture succeeded.
 
 **Everything else Kiro** — MCP-only mode, project scoping and `--resume`, the classifier internals, enterprise-governance notes, troubleshooting: **[docs/kiro.md](docs/kiro.md)**.
 
@@ -131,7 +169,7 @@ Once installed, Claude Recall works in the background (CC = Claude Code):
 | **Session exit** | An auto-checkpoint (`{completed, remaining, blockers}`) is saved for next time | ✓ | ✓ |  |
 | **End of session** | Failure patterns become candidate lessons; validated ones are promoted to rules | ✓ | ✓ |  |
 
-Classification uses an LLM wherever one is available — Claude Code provides `ANTHROPIC_API_KEY` to its hooks; Kiro uses its own included LLM — with silent regex fallback. No configuration needed.
+Classification runs on each runtime's **own** LLM — Claude Code via headless `claude -p` on your subscription; Kiro via `kiro-cli chat --no-interactive` on Kiro credits — with `ANTHROPIC_API_KEY` (if you exported one *and* opted in) and regex as fallbacks. No API key is ever required; no configuration needed.
 
 ```bash
 # Verify it's working
@@ -349,9 +387,11 @@ 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)_ | 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. |
+| `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. |
+| `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). |
-| `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_PREFER_API_KEY`           | _(unset)_ | Force `ANTHROPIC_API_KEY`-based classification ahead of the runtime's included LLM (uses your Anthropic API credits — e.g. for a model you pay for). Applies under both Claude Code and Kiro. |
 | `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/hook-commands.js

@@ -37,6 +37,7 @@ exports.HookCommands = void 0;
 const shared_1 = require("../../hooks/shared");
 const AVAILABLE_HOOKS = [
     'correction-detector',
+    'cc-capture-worker',
     'memory-stop',
     'memory-sync',
     'precompact-preserve',
@@ -70,8 +71,17 @@ class HookCommands {
     static async runOne(name, input) {
         switch (name) {
             case 'correction-detector': {
-                const { handleCorrectionDetector } = await Promise.resolve().then(() => __importStar(require('../../hooks/correction-detector')));
-                await handleCorrectionDetector(input);
+                // Kept as the registered name in every existing settings.json, but
+                // capture no longer classifies inline: the handler spawns a detached
+                // cc-capture-worker so the ~4s `claude -p` subscription classifier
+                // never blocks the user's turn. See src/hooks/cc-capture.ts.
+                const { handleCcCapture } = await Promise.resolve().then(() => __importStar(require('../../hooks/cc-capture')));
+                await handleCcCapture(input);
+                break;
+            }
+            case 'cc-capture-worker': {
+                const { handleCcCaptureWorker } = await Promise.resolve().then(() => __importStar(require('../../hooks/cc-capture')));
+                await handleCcCaptureWorker(input);
                 break;
             }
             case 'memory-stop': {
@@ -141,7 +151,7 @@ class HookCommands {
                 break;
             }
             // Kiro CLI adapters — see src/hooks/kiro-hooks.ts. Kiro's
-            // userPromptSubmit needs no adapter: wire `correction-detector` directly.
+            // userPromptSubmit wires `kiro-capture` (detached-worker capture).
             case 'kiro-agent-spawn': {
                 const { handleKiroAgentSpawn } = await Promise.resolve().then(() => __importStar(require('../../hooks/kiro-hooks')));
                 await handleKiroAgentSpawn(input);

package/dist/hooks/cc-capture.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Claude Code capture — detached-worker pattern for UserPromptSubmit.
+ *
+ * Classification under Claude Code now prefers the user's SUBSCRIPTION (via
+ * headless `claude -p`, see cc-classifier.ts) over an ANTHROPIC_API_KEY. That
+ * call is ~4s cold — too slow to run inline while Claude Code blocks the
+ * user's prompt on the hook. So the registered hook (`hook run
+ * correction-detector`, unchanged in settings.json) spawns a DETACHED worker,
+ * pipes the payload to it over stdin, and returns in milliseconds — the same
+ * pattern as Kiro's kiro-capture (kiro-hooks.ts) and session-end-checkpoint.
+ *
+ * Trade-off: the synchronous "📌 Recall: auto-captured …" echo is gone —
+ * capture is silent and lands ~4s later. Verify via
+ * ~/.claude-recall/hook-logs/cc-classifier.log or `claude-recall search`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleCcCapture = handleCcCapture;
+exports.handleCcCaptureWorker = handleCcCaptureWorker;
+const child_process_1 = require("child_process");
+const shared_1 = require("./shared");
+const correction_detector_1 = require("./correction-detector");
+const HOOK_NAME = 'cc-capture';
+/**
+ * The inline half — fires on UserPromptSubmit, spawns the worker, returns
+ * immediately. Pre-checks mirror correction-detector so we don't spawn a
+ * process (or spend subscription usage) on input that could never be stored.
+ */
+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) {
+        return;
+    }
+    const prompt = input?.prompt ?? '';
+    if (prompt.length < 20 || prompt.length > 2000)
+        return;
+    if (prompt.startsWith('```') || prompt.startsWith('{'))
+        return;
+    try {
+        const cliPath = process.argv[1]; // absolute path to claude-recall-cli.js
+        const child = (0, child_process_1.spawn)(process.execPath, [cliPath, 'hook', 'run', 'cc-capture-worker'], { detached: true, stdio: ['pipe', 'ignore', 'ignore'] });
+        child.on('error', (err) => {
+            (0, shared_1.hookLog)(HOOK_NAME, `capture worker spawn error: ${err?.message ?? err}`);
+        });
+        if (child.stdin) {
+            child.stdin.on('error', (err) => {
+                (0, shared_1.hookLog)(HOOK_NAME, `capture worker stdin error: ${err?.message ?? err}`);
+            });
+            child.stdin.write(JSON.stringify(input));
+            child.stdin.end();
+        }
+        child.unref();
+        (0, shared_1.hookLog)(HOOK_NAME, `capture: spawned detached worker (pid=${child.pid})`);
+    }
+    catch (err) {
+        (0, shared_1.hookLog)(HOOK_NAME, `capture spawn failed: ${(0, shared_1.safeErrorMessage)(err)}`);
+    }
+}
+/**
+ * cc-capture-worker — the background half. Enables the Claude-CLI classifier
+ * path (CLAUDE_RECALL_CC_CLASSIFIER) and delegates to the standard
+ * correction-detector, which classifies via `claude -p` (subscription) →
+ * ANTHROPIC_API_KEY → regex, and stores. Runs detached, so output goes
+ * nowhere and capture is silent.
+ */
+async function handleCcCaptureWorker(input) {
+    process.env.CLAUDE_RECALL_CC_CLASSIFIER = '1';
+    try {
+        await (0, correction_detector_1.handleCorrectionDetector)(input);
+    }
+    catch (err) {
+        (0, shared_1.hookLog)(HOOK_NAME, `capture worker error: ${(0, shared_1.safeErrorMessage)(err)}`);
+    }
+}

package/dist/hooks/cc-classifier.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * Claude-Code-LLM memory classifier.
+ *
+ * Mirrors kiro-classifier for the Claude Code runtime: `claude -p "<prompt>"`
+ * is a headless one-shot completion that runs on the user's Claude Code
+ * SUBSCRIPTION auth (the same login powering their interactive session) — no
+ * ANTHROPIC_API_KEY, no separate pay-as-you-go credits. This makes the "each
+ * runtime brings its own LLM" promise true under Claude Code, not just Kiro.
+ *
+ * Two hard-won details:
+ *
+ *  1. `claude -p` prefers ANTHROPIC_API_KEY over subscription auth when the
+ *     key is present in the environment. A stray key exported for other tools
+ *     (possibly dead or out of credits) would silently hijack the call — so
+ *     the key is STRIPPED from the child env to force subscription auth.
+ *  2. The child inherits CLAUDE_RECALL_CC_CLASSIFIER=1 (set by the capture
+ *     worker), so if the nested headless session fires claude-recall hooks of
+ *     its own, handleCcCapture sees the flag and refuses to spawn another
+ *     worker — no recursion. The call also runs from the OS temp dir so the
+ *     current project's hooks/settings don't load at all.
+ *
+ * Cold latency is ~4s, so this runs only from a DETACHED worker
+ * (cc-capture-worker), never inline on the user's turn.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyWithClaudeCli = classifyWithClaudeCli;
+const child_process_1 = require("child_process");
+const os = __importStar(require("os"));
+const shared_1 = require("./shared");
+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.
+ */
+function classifyWithClaudeCli(text) {
+    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;
+    // 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' };
+    delete env.ANTHROPIC_API_KEY;
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        let child;
+        try {
+            // 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'] });
+        }
+        catch (err) {
+            (0, shared_1.hookLog)('cc-classifier', `spawn threw: ${(0, shared_1.safeErrorMessage)(err)}`);
+            return done(null);
+        }
+        const timer = setTimeout(() => {
+            (0, shared_1.hookLog)('cc-classifier', `timeout after ${timeout}ms — killing claude -p`);
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already gone */ }
+            done(null);
+        }, timeout);
+        let stdout = '';
+        child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            // ENOENT = claude not on PATH; anything else = spawn failure
+            (0, shared_1.hookLog)('cc-classifier', `claude error: ${err?.code ?? ''} ${err?.message ?? err}`);
+            done(null);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (settled)
+                return;
+            if (code !== 0) {
+                (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);
+        });
+    });
+}

package/dist/hooks/kiro-classifier.js

@@ -16,6 +16,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLASSIFIER_AGENT = void 0;
+exports.buildClassifyPrompt = buildClassifyPrompt;
 exports.extractClassification = extractClassification;
 exports.classifyWithKiro = classifyWithKiro;
 const child_process_1 = require("child_process");
@@ -36,21 +37,32 @@ const VALID_TYPES = new Set([
  * single INPUT argument (no separate system prompt), so instruction + payload
  * are combined. Mirrors the contract of llm-classifier's SYSTEM_PROMPT so
  * downstream thresholds/dedup behave identically regardless of which LLM ran.
+ *
+ * Exported for cc-classifier: `claude -p` is the same single-argument headless
+ * shape, so both CLI backends share one prompt (and one parser, below).
  */
-function buildPrompt(text) {
+function buildClassifyPrompt(text) {
     return ('You are a memory classifier for a developer tool. Classify the USER MESSAGE ' +
         'into exactly one type and respond with ONLY minified JSON — no markdown, no ' +
         'prose, no code fence:\n' +
         '{"type":"correction|preference|failure|devops|project-knowledge|none","confidence":0.0-1.0,"extract":"<concise imperative rule to remember, or empty>"}\n\n' +
         'Types:\n' +
-        '- correction: user correcting a mistake ("no, use X not Y")\n' +
+        '- correction: user durably correcting how something should ALWAYS be done ("no, use X not Y"). Correcting a one-off action in the current task is NOT durable.\n' +
         '- preference: a reusable directive about how the user wants things done ("I prefer X", "we use tabs", "my favourite color is green"). Must apply beyond this one message.\n' +
         '- failure: something broke ("build failed")\n' +
         '- devops: durable CI/CD, git, deployment, or Docker rules\n' +
         '- project-knowledge: architecture, stack, database, or API facts\n' +
-        '- none: questions, chitchat, task instructions, observations, or anything not worth remembering across sessions\n\n' +
+        '- none: questions, chitchat, task instructions, meta-conversation, sentence fragments, observations, or anything not worth remembering across sessions\n\n' +
+        'THE STANDALONE TEST — apply before choosing correction/preference/devops: a durable rule must make complete sense on its own, read cold in a future session with no knowledge of this chat. If the message needs the surrounding conversation to be understood, use "none".\n' +
+        '- Reject text referencing the current moment with no standalone subject ("this", "that", "the sentence", "here", "it", "first", "now").\n' +
+        '- Reject one-off imperatives aimed at the task in progress ("fix the sentence", "change that", "do X first") even when forceful.\n' +
+        '- Reject sentence fragments and mid-thought clauses ("is used in practice", "then run the setup command").\n' +
+        '- Reject meta-conversation about this tool or what to write/do next.\n\n' +
         'Be conservative: when in doubt use "none" with confidence 0. Use confidence >= 0.75 for correction/preference/devops. ' +
         'extract must be a clean standalone rule (e.g. "Favourite colour is green"), or empty when type is none.\n\n' +
+        'Examples: "we use pnpm, not npm" → {"type":"preference","confidence":0.9,"extract":"Use pnpm, not npm"}; ' +
+        '"first fix the sentence" → {"type":"none","confidence":0,"extract":""}; ' +
+        '"then run claude-recall kiro setup" → {"type":"none","confidence":0,"extract":""}.\n\n' +
         'USER MESSAGE: ' + text);
 }
 /** Strip ANSI/VT control sequences that kiro-cli writes around its output. */
@@ -119,7 +131,7 @@ function classifyWithKiro(text) {
                 '--no-interactive',
                 '--agent', exports.CLASSIFIER_AGENT,
                 '--model', model,
-                buildPrompt(text),
+                buildClassifyPrompt(text),
             ], { stdio: ['ignore', 'pipe', 'ignore'] });
         }
         catch (err) {
@@ -152,7 +164,12 @@ function classifyWithKiro(text) {
             }
             const result = extractClassification(stdout);
             if (!result) {
-                (0, shared_1.hookLog)('kiro-classifier', 'no parseable classification in kiro-cli output');
+                // 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)('kiro-classifier', /"type"\s*:\s*"none"/.test(stdout)
+                    ? 'classified as none (not a durable rule)'
+                    : 'no parseable classification in kiro-cli output');
             }
             else {
                 // Log success too, not just failures — otherwise a successful Kiro

package/dist/hooks/llm-classifier.js

@@ -1,9 +1,14 @@
 "use strict";
 /**
- * LLM-powered memory classification using Claude Haiku.
+ * LLM-powered memory classification using Claude Haiku via the Anthropic API.
  *
- * Picks up ANTHROPIC_API_KEY from the environment (Claude Code sets it
- * automatically for child processes). Falls back gracefully when unavailable.
+ * Requires ANTHROPIC_API_KEY in the environment — a personal pay-as-you-go
+ * API key the user exported themselves. Claude Code does NOT mint one from
+ * the user's subscription (hooks just inherit the user's environment), which
+ * is why this is a FALLBACK backend: the capture workers prefer each
+ * runtime's included LLM (claude -p / kiro-cli — see cc-classifier.ts and
+ * kiro-classifier.ts) and only land here when a key is present. Falls back
+ * gracefully (returns null) when unavailable.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.classifyWithLLM = classifyWithLLM;
@@ -16,45 +21,65 @@ let clientInstance; // undefined = not yet checked
 const MODEL = 'claude-haiku-4-5-20251001';
 const SYSTEM_PROMPT = `You are a memory classifier for a developer tool. Classify user text into one of these types:
 
-- correction: User correcting a mistake ("no, use X not Y", "wrong, it should be...")
-- preference: User stating a clear, reusable directive about how they want things done going forward ("we use tabs", "always use TypeScript", "I prefer X"). Must be a rule that applies beyond this conversation. NOT observations, complaints, questions, debugging statements, or one-off instructions like "fix this" or "tell me about X"
+- 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.
+- preference: User stating a clear, reusable directive about how they want things done going forward ("we use tabs", "always use TypeScript", "I prefer X"). Must be a rule that applies beyond this conversation.
 - failure: Something broke or failed ("build failed", "error in deployment")
 - devops: CI/CD, deployment, Docker, git workflow patterns. ONLY durable rules — not transient operational events like "sandbox rebuilt" or "background task exited"
 - project-knowledge: Architecture, stack, database, API patterns
-- none: Casual conversation, questions, code snippets, or anything not worth remembering
+- none: Casual conversation, questions, code snippets, one-off task instructions, meta-conversation, sentence fragments, or anything not worth remembering across sessions
 
 Respond with ONLY valid JSON (no markdown fences). Format:
 {"type":"<type>","confidence":<0.0-1.0>,"extract":"<the key fact to remember, concise>"}
 
+THE STANDALONE TEST — apply this BEFORE classifying anything as correction/preference/devops:
+A durable rule must make complete sense on its own, read cold in a future session with NO knowledge of this conversation. If the text needs the surrounding chat to be understood, it is "none".
+- Reject text that references the current task or moment with no concrete standalone subject: "this", "that", "the sentence", "here", "it", "again", "first", "now".
+- Reject one-off imperatives aimed at the task in progress ("fix the sentence", "change that", "add a line", "do X first") — even when phrased forcefully. A preference describes what the user ALWAYS wants, not what to do right now.
+- Reject sentence fragments and mid-thought clauses (e.g. "is used in practice", "then run the setup command"). A rule is a complete directive, not a snippet.
+- Reject meta-conversation about this tool, this chat, or what to write/say/do next.
+
 Rules:
 - Be very conservative — when in doubt, classify as "none". Only store things worth remembering across sessions
 - Questions, observations, complaints, task instructions, and sentence fragments are "none" — not preferences
-- If the text doesn't make sense as a standalone rule or directive, classify as "none"
 - confidence >= 0.7 for corrections and preferences
 - confidence >= 0.6 for other types
 - "none" type should have confidence 0.0
-- extract should be a clean, imperative statement of the rule/fact (e.g. "Use tabs for indentation")
-- If the text is a question, greeting, or code block, classify as "none"`;
+- extract should be a clean, imperative statement of the rule/fact, understandable standalone (e.g. "Use tabs for indentation")
+- If the text is a question, greeting, or code block, classify as "none"
+
+Examples:
+- "we use pnpm here, not npm" → {"type":"preference","confidence":0.9,"extract":"Use pnpm, not npm"}
+- "always run tests before pushing" → {"type":"preference","confidence":0.85,"extract":"Run tests before pushing"}
+- "first fix the sentence" → {"type":"none","confidence":0.0,"extract":""}
+- "is used in practice" → {"type":"none","confidence":0.0,"extract":""}
+- "then run claude-recall kiro setup" → {"type":"none","confidence":0.0,"extract":""}
+- "what memories do you have?" → {"type":"none","confidence":0.0,"extract":""}`;
 const BATCH_SYSTEM_PROMPT = `You are a memory classifier for a developer tool. You will receive a JSON array of texts. Classify each into one of these types:
 
-- correction: User correcting a mistake ("no, use X not Y", "wrong, it should be...")
-- preference: User stating a clear, reusable directive about how they want things done going forward ("we use tabs", "always use TypeScript", "I prefer X"). Must be a rule that applies beyond this conversation. NOT observations, complaints, questions, debugging statements, or one-off instructions like "fix this" or "tell me about X"
+- 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.
+- preference: User stating a clear, reusable directive about how they want things done going forward ("we use tabs", "always use TypeScript", "I prefer X"). Must be a rule that applies beyond this conversation.
 - failure: Something broke or failed ("build failed", "error in deployment")
 - devops: CI/CD, deployment, Docker, git workflow patterns. ONLY durable rules — not transient operational events like "sandbox rebuilt" or "background task exited"
 - project-knowledge: Architecture, stack, database, API patterns
-- none: Casual conversation, questions, code snippets, or anything not worth remembering
+- none: Casual conversation, questions, code snippets, one-off task instructions, meta-conversation, sentence fragments, or anything not worth remembering across sessions
 
 Respond with ONLY a valid JSON array (no markdown fences). One object per input text, in order:
 [{"type":"<type>","confidence":<0.0-1.0>,"extract":"<the key fact to remember, concise>"}, ...]
 
+THE STANDALONE TEST — apply this BEFORE classifying anything as correction/preference/devops:
+A durable rule must make complete sense on its own, read cold in a future session with NO knowledge of this conversation. If a text needs the surrounding chat to be understood, it is "none".
+- Reject text that references the current task or moment with no concrete standalone subject: "this", "that", "the sentence", "here", "it", "again", "first", "now".
+- Reject one-off imperatives aimed at the task in progress ("fix the sentence", "change that", "add a line", "do X first") — even when phrased forcefully.
+- Reject sentence fragments and mid-thought clauses (e.g. "is used in practice", "then run the setup command").
+- Reject meta-conversation about this tool, this chat, or what to write/say/do next.
+
 Rules:
 - Be very conservative — when in doubt, classify as "none". Only store things worth remembering across sessions
 - Questions, observations, complaints, task instructions, and sentence fragments are "none" — not preferences
-- If the text doesn't make sense as a standalone rule or directive, classify as "none"
 - confidence >= 0.7 for corrections and preferences
 - confidence >= 0.6 for other types
 - "none" type should have confidence 0.0
-- extract should be a clean, imperative statement of the rule/fact
+- extract should be a clean, imperative statement of the rule/fact, understandable standalone
 - If a text is a question, greeting, or code block, classify as "none"`;
 /**
  * Lazy-init the Anthropic client. Returns null if SDK or API key unavailable.

package/dist/hooks/shared.js

@@ -67,9 +67,16 @@ const llm_classifier_1 = require("./llm-classifier");
 // "I want", "I use" — were deleted rather than promoted because they match
 // ordinary conversation far too often.)
 const CORRECTION_PATTERNS = [
-    { regex: /^no[,.]?\s+(.+)/i, confidence: 0.8 },
+    // "no ..." only counts as a correction when the remainder carries a durable-
+    // rule signal (use/not/instead/always/...). Without the lookahead, one-off
+    // task imperatives were stored: "no first fix the sentence" became the
+    // correction "first fix the sentence".
+    { regex: /^no[,.]?\s+(?=.*\b(?:use|not|instead|never|always|don'?t|stop|should|must)\b)(.+)/i, confidence: 0.8 },
     { regex: /^wrong[,.]?\s+(.+)/i, confidence: 0.8 },
-    { regex: /\bnever\s+(.+)/i, confidence: 0.75 },
+    // "never" must start the message or a sentence. Mid-clause "never" fired on
+    // QUOTED text the user was discussing: pasting "it never touches your token
+    // allowance" stored "touches your token allowance..." as a correction.
+    { regex: /(?:^|[.!?;:]\s+)never\s+(.+)/i, confidence: 0.75 },
     { regex: /\bdon'?t\s+ever\s+(.+)/i, confidence: 0.8 },
     { regex: /\bstop\s+(doing|using|adding)\s+(.+)/i, confidence: 0.75 },
 ];
@@ -80,7 +87,16 @@ const PREFERENCE_PATTERNS = [
     // no-MCP) capture path, which matters under enterprise Kiro governance that
     // blocks the MCP tools. The interrogative/question-mark guards below keep
     // "do you remember that config file?" / "do you recall X?" out.
-    { regex: /\b(?:remember|recall)\s+(?:that\s+|this\s+|to\s+)?(.+)/i, confidence: 0.8 },
+    //
+    // Two hazards from talking ABOUT this tool (both observed in the wild):
+    //   1. The product name: "claude-recall" / "claude recall" contains the
+    //      trigger word — "how claude recall is used" stored "is used...". The
+    //      lookbehind skips "recall" when preceded by "claude-"/"claude ".
+    //   2. Non-imperative uses where "recall" is a noun/subject followed by a
+    //      copula or auxiliary ("the recall is broken") — an imperative
+    //      "remember/recall X" is never followed by a bare auxiliary, so the
+    //      negative lookahead rejects those.
+    { regex: /(?<!claude[- ])\b(?:remember|recall)\s+(?:that\s+|this\s+|to\s+)?(?!(?:is|was|are|were|has|have|had|does|did|will|would|can|could|should|may|might)\b)(.+)/i, confidence: 0.8 },
     { regex: /\bfrom\s+now\s+on[,.]?\s+(.+)/i, confidence: 0.8 },
     { regex: /\bgoing\s+forward[,.]?\s+(.+)/i, confidence: 0.8 },
     { regex: /\balways\s+(.+)/i, confidence: 0.75 },
@@ -146,15 +162,22 @@ function classifyContentRegex(text) {
  * Classify text content — LLM-first, regex fallback. No API key is ever
  * required: each runtime brings its own LLM.
  *
- * Precedence:
- *   - 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.
+ * Precedence (the included-LLM backends run only inside the detached capture
+ * workers, which set the *_CLASSIFIER env vars — a ~4s CLI call can't run
+ * inline on a turn):
+ *   - Under Claude Code (CLAUDE_RECALL_CC_CLASSIFIER set by cc-capture-worker):
+ *     headless `claude -p` on the user's Claude SUBSCRIPTION → ANTHROPIC_API_KEY
+ *     if present → regex.
+ *   - Under Kiro (CLAUDE_RECALL_KIRO_CLASSIFIER set by kiro-capture-worker):
+ *     Kiro's own headless LLM (`kiro-cli chat --no-interactive`, Kiro credits)
+ *     → ANTHROPIC_API_KEY if present → regex.
+ *   - Inline callers (memory-stop batch, etc.): ANTHROPIC_API_KEY → regex.
+ *
+ * The included LLM is preferred so a stray exported key doesn't silently
+ * spend the user's Anthropic API credits; CLAUDE_RECALL_PREFER_API_KEY flips
+ * the order. NOTE: ANTHROPIC_API_KEY is always a personal key the user
+ * exported — Claude Code does NOT provide one from the subscription.
+ * 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
@@ -172,17 +195,22 @@ async function classifyContent(text) {
 }
 async function classifyContentInner(text) {
     const underKiro = !!process.env.CLAUDE_RECALL_KIRO_CLASSIFIER;
+    const underCc = !!process.env.CLAUDE_RECALL_CC_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.
+    // Dynamic imports keep the CLI classifiers (and child_process) out of the
+    // module graph for hook invocations that don't run in a capture worker.
     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 tryCc = async () => (await Promise.resolve().then(() => __importStar(require('./cc-classifier')))).classifyWithClaudeCli(text);
+    // Order the LLM backends. Each runtime's INCLUDED LLM comes before a stray
+    // ANTHROPIC_API_KEY: a key exported for other tools should not silently
+    // spend the user's Anthropic API credits when the runtime already provides
+    // an LLM — Kiro via `kiro-cli chat --no-interactive` (Kiro credits), Claude
+    // Code via `claude -p` (the user's Claude subscription). Set
+    // CLAUDE_RECALL_PREFER_API_KEY to force the key first (e.g. to use a
+    // stronger model you pay for). The CLI backends only run inside their
+    // detached capture workers (which set the *_CLASSIFIER env vars) — inline
+    // hook paths stay key → regex, since a ~4s CLI call can't block a turn.
     const backends = [];
     if (underKiro && !preferApiKey) {
         backends.push(tryKiro, tryApiKey);
@@ -190,6 +218,12 @@ async function classifyContentInner(text) {
     else if (underKiro) {
         backends.push(tryApiKey, tryKiro);
     }
+    else if (underCc && !preferApiKey) {
+        backends.push(tryCc, tryApiKey);
+    }
+    else if (underCc) {
+        backends.push(tryApiKey, tryCc);
+    }
     else {
         backends.push(tryApiKey);
     }

package/docs/kiro-llm-capture.md

@@ -4,9 +4,12 @@
 
 Claude Recall captures memories with an LLM classifier: it reads each user
 prompt and decides whether it contains a durable preference, correction, or
-project fact worth storing. That classifier normally calls Claude Haiku through
-`ANTHROPIC_API_KEY`, which Claude Code sets automatically for its hook
-subprocesses.
+project fact worth storing. At the time of this finding, that classifier called
+Claude Haiku through `ANTHROPIC_API_KEY` — a personal API key the user had
+exported themselves. (Claude Code does **not** mint a key from the user's
+subscription; hooks merely inherit the environment. The headless-CLI approach
+documented here was later applied back to Claude Code via `claude -p` on
+subscription auth — see `src/hooks/cc-classifier.ts`.)
 
 Kiro CLI does **not** set `ANTHROPIC_API_KEY`. So under Kiro the classifier fell
 back to a conservative regex that only fires on explicit phrasings
@@ -98,8 +101,8 @@ present → regex as a last resort.** The Kiro LLM comes first *even when a key
 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.)
+stronger model. (Under Claude Code the same pattern applies with `claude -p` on
+the user's subscription as the included LLM — see `src/hooks/cc-classifier.ts`.)
 
 ### Output parsing
 

package/package.json

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