claude-recall 0.32.0 → 0.34.0

package/README.md

@@ -28,7 +28,7 @@ That's the whole workflow. A background hook classified your prompt with an LLM
 >
 > **Agent:** Installing vitest with **pnpm** *(applied from memory: "Use pnpm, not npm")* …
 
-Your rules are injected at session start and again right before each relevant tool call — at the moment of decision, not 50,000 tokens upstream. This works across agents too: correct Claude Code on Tuesday, and Kiro applies it on Friday.
+Your rules are injected at session start and kept alive mid-session — just-in-time before each relevant tool call (Claude Code, Pi), or as a periodic refresh (Kiro) — at the moment of decision, not 50,000 tokens upstream. This works across agents too: correct Claude Code on Tuesday, and Kiro applies it on Friday.
 
 **And you can audit what it knows at any time:**
 
@@ -45,7 +45,7 @@ $ claude-recall search "pnpm"
 ## Features
 
 - **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
+- **Applied where it counts** — rules load at session start and are re-surfaced mid-session: just-in-time before each tool call (Claude Code, Pi) or as a periodic refresh every N prompts (Kiro)
 - **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
 - **Outcome-aware** — tracks whether rules actually help (tool results, test cycles, re-asks) and promotes validated lessons into active rules
@@ -92,6 +92,8 @@ tail -5 ~/.claude-recall/hook-logs/cc-classifier.log   # which model ran, what w
 claude-recall search "something you said"
 ```
 
+Design details (the `claude -p` key-precedence gotcha, recursion guards, which features run on the subscription): [docs/cc-llm-capture.md](docs/cc-llm-capture.md).
+
 ### Pi
 
 ```bash
@@ -160,7 +162,8 @@ Once installed, Claude Recall works in the background (CC = Claude Code):
 |---|---|:-:|:-:|:-:|
 | **Session start** | Active rules are injected into the agent's context | ✓ | ✓ | ✓ |
 | **As you type** | Prompts are classified; durable preferences/corrections are stored | ✓ | ✓ | ✓ |
-| **Before each tool call** | Relevant rules are re-surfaced next to the action (just-in-time injection) | ✓ | ✓ | ✓ |
+| **Before each tool call** | Relevant rules are re-surfaced next to the action (just-in-time injection) | ✓ | ✓ |  |
+| **Every 15 prompts** | Active rules are re-injected so long sessions can't silently lose them (interval configurable) |  |  | ✓ |
 | **Tool outcomes** | Failures are recorded; Bash failures are paired with their eventual fix | ✓ | ✓ | ✓ |
 | **Re-ask detection** | Frustration signals (*"still broken"*) are recorded as outcome events | ✓ | ✓ | ✓ |
 | **Before context compression** | Important context is captured before the window shrinks | ✓ | ✓ |  |
@@ -169,7 +172,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 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.
+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 regex as the fallback. **An exported `ANTHROPIC_API_KEY` is never touched** unless you explicitly opt in with `CLAUDE_RECALL_PREFER_API_KEY=1`. No API key is ever required; no configuration needed.
 
 ```bash
 # Verify it's working
@@ -206,7 +209,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 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.
+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 and no key touched. The same applies to the other background LLM features (failure hindsight hints, end-of-session lesson extraction). Pi-only machines without the `claude` binary can opt in to an `ANTHROPIC_API_KEY` with `CLAUDE_RECALL_PREFER_API_KEY=1`. A quality gate refuses to overwrite a manual checkpoint with a fabricated one when the task was already complete.
 
 ### Troubleshooting
 
@@ -323,7 +326,7 @@ action → outcome event → episode → candidate lesson → promotion → acti
                                                     outcome resolved per injected rule
 ```
 
-Failures become candidate lessons (deduplicated by similarity); lessons seen 2+ times (or once, if severe) are promoted to active rules; every just-in-time injection is recorded and resolved against the tool's outcome, building per-rule effectiveness data over time.
+Failures become candidate lessons (deduplicated by similarity); lessons seen 2+ times (or once, if severe) are promoted to active rules; every just-in-time injection (Claude Code, Pi) is recorded and resolved against the tool's outcome, building per-rule effectiveness data over time.
 
 ---
 
@@ -387,12 +390,13 @@ 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 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. |
+| `ANTHROPIC_API_KEY`                      | _(unset)_ | Optional personal API key for Haiku-based LLM features. **Never required, never provided by Claude Code, and never touched unless you opt in** with `CLAUDE_RECALL_PREFER_API_KEY=1` — capture, checkpoint extraction, hindsight hints, and session lessons all run on each runtime's own LLM (Claude subscription via `claude -p`; Kiro credits via `kiro-cli`), with regex as the 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)_ | 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_PREFER_API_KEY`           | _(unset)_ | **The only switch that enables the `ANTHROPIC_API_KEY` backend** (and prefers it first). For Pi-only machines without the `claude` binary, or a stronger model you deliberately pay for. Applies to all LLM features, under Claude Code, Kiro, and Pi. |
 | `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_REFRESH_INTERVAL`         | `15`    | **Kiro only.** Re-inject the active rules into context every N prompts, so marathon sessions can't silently lose them to context rollover (Kiro has no post-compaction event). `0` disables. |
 | `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>`. |
 | `CLAUDE_RECALL_DEMOTE_MIN_LOADS`         | `20`    | Minimum load count before a rule qualifies for auto-demotion.                                            |

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

@@ -44,7 +44,7 @@ const repair_1 = require("./repair");
  * `claude-recall kiro setup` writes a Kiro custom agent config
  * (.kiro/agents/recall.json) wiring the same shared memory database into
  * Kiro CLI: MCP tools, rules auto-loaded into context at agentSpawn,
- * just-in-time rule injection on preToolUse, user-prompt capture, and tool
+ * user-prompt capture with a periodic mid-session rule refresh, and tool
  * outcome tracking. See src/hooks/kiro-hooks.ts for the adapter details and
  * kiro.dev/docs/cli/custom-agents for the config format.
  */
@@ -81,23 +81,31 @@ class KiroCommands {
         fs.writeFileSync(p, JSON.stringify(KiroCommands.buildClassifierAgentConfig(), null, 2) + '\n');
         return p;
     }
-    /** The four lifecycle hook entries (shared by fresh config and merge). */
+    /**
+     * The lifecycle hook entries (shared by fresh config and merge).
+     *
+     * No preToolUse entry: Kiro ignores preToolUse stdout (exit codes gate the
+     * tool; only exit-2 stderr reaches the LLM — kiro.dev/docs/cli/hooks), so
+     * the kiro-rule-injector wired there by versions ≤0.33 never reached the
+     * model. Mid-session injection rides userPromptSubmit instead (the periodic
+     * rule refresh inside kiro-capture); stale kiro-rule-injector entries are
+     * stripped on merge.
+     */
     static buildHookEntries(hookCmd) {
         return {
             // stdout of agentSpawn is added to context → rules present from turn one
             agentSpawn: [
                 { command: `${hookCmd} kiro-agent-spawn`, timeout_ms: 10000 },
             ],
-            // Capture. kiro-capture spawns a detached worker that classifies the
-            // prompt via Kiro's own headless LLM (no ANTHROPIC_API_KEY needed) and
-            // stores in the background — see src/hooks/kiro-classifier.ts. The hook
-            // itself returns in milliseconds, so the short timeout is ample.
+            // Capture + periodic rule refresh. kiro-capture spawns a detached worker
+            // that classifies the prompt via Kiro's own headless LLM (no
+            // ANTHROPIC_API_KEY needed) and stores in the background — see
+            // src/hooks/kiro-classifier.ts. The hook itself returns in milliseconds,
+            // so the short timeout is ample. Its stdout is added to context, which
+            // also carries the every-N-prompts rule re-injection for long sessions.
             userPromptSubmit: [
                 { command: `${hookCmd} kiro-capture`, timeout_ms: 8000 },
             ],
-            preToolUse: [
-                { matcher: '*', command: `${hookCmd} kiro-rule-injector`, timeout_ms: 5000 },
-            ],
             postToolUse: [
                 { matcher: '*', command: `${hookCmd} kiro-tool-outcome`, timeout_ms: 5000 },
             ],
@@ -106,7 +114,7 @@ class KiroCommands {
     static buildAgentConfig(hookCmd, mcpCommand, mcpArgs) {
         return {
             name: 'recall',
-            description: 'Kiro agent with Claude Recall persistent memory: rules auto-loaded at start, just-in-time injection per tool call, automatic capture of corrections and outcomes.',
+            description: 'Kiro agent with Claude Recall persistent memory: rules auto-loaded at start, periodic mid-session rule refresh, automatic capture of corrections and outcomes.',
             // Also load any servers the user configured in .kiro/settings/mcp.json
             includeMcpJson: true,
             mcpServers: {
@@ -162,7 +170,6 @@ class KiroCommands {
         const handlerMarkers = {
             agentSpawn: 'kiro-agent-spawn',
             userPromptSubmit: 'kiro-capture',
-            preToolUse: 'kiro-rule-injector',
             postToolUse: 'kiro-tool-outcome',
         };
         // Superseded claude-recall hooks to strip from an event before wiring the
@@ -170,28 +177,41 @@ class KiroCommands {
         // across versions. Pre-0.29 wired userPromptSubmit to `correction-detector`
         // directly; 0.29 replaced it with `kiro-capture`. Leaving the old entry
         // makes BOTH fire, double-capturing (often as near-duplicate memories).
+        // Versions ≤0.33 wired preToolUse to `kiro-rule-injector`, whose stdout
+        // Kiro never adds to context — a per-tool-call no-op, removed entirely.
         // Only our own commands (containing 'claude-recall' / 'hook run') are
         // touched — a user's unrelated hook on the same event is preserved.
         const supersededMarkers = {
             userPromptSubmit: ['correction-detector'],
+            preToolUse: ['kiro-rule-injector'],
         };
         const isOurCommand = (cmd) => cmd.includes('claude-recall') || cmd.includes('hook run');
-        for (const [event, entries] of Object.entries(KiroCommands.buildHookEntries(hookCmd))) {
-            if (!Array.isArray(config.hooks[event])) {
-                config.hooks[event] = [];
-            }
+        const entriesByEvent = KiroCommands.buildHookEntries(hookCmd);
+        // Visit superseded-only events too (e.g. preToolUse, which we no longer
+        // wire but must still clean up), without inventing empty hook arrays in
+        // configs that never had them.
+        const allEvents = new Set([...Object.keys(entriesByEvent), ...Object.keys(supersededMarkers)]);
+        for (const event of allEvents) {
+            const entries = entriesByEvent[event] ?? [];
             const marker = handlerMarkers[event];
             // Strip superseded entries first (but never the current marker).
-            for (const stale of supersededMarkers[event] ?? []) {
-                if (stale === marker)
-                    continue;
-                const before = config.hooks[event].length;
-                config.hooks[event] = config.hooks[event].filter((h) => !(typeof h?.command === 'string' && h.command.includes(stale) && isOurCommand(h.command)));
-                const removed = before - config.hooks[event].length;
-                if (removed > 0) {
-                    changes.push(`hooks.${event}: removed ${removed} superseded ${stale} entr${removed === 1 ? 'y' : 'ies'}`);
+            if (Array.isArray(config.hooks[event])) {
+                for (const stale of supersededMarkers[event] ?? []) {
+                    if (stale === marker)
+                        continue;
+                    const before = config.hooks[event].length;
+                    config.hooks[event] = config.hooks[event].filter((h) => !(typeof h?.command === 'string' && h.command.includes(stale) && isOurCommand(h.command)));
+                    const removed = before - config.hooks[event].length;
+                    if (removed > 0) {
+                        changes.push(`hooks.${event}: removed ${removed} superseded ${stale} entr${removed === 1 ? 'y' : 'ies'}`);
+                    }
                 }
             }
+            if (entries.length === 0)
+                continue;
+            if (!Array.isArray(config.hooks[event])) {
+                config.hooks[event] = [];
+            }
             const alreadyWired = config.hooks[event].some((h) => typeof h?.command === 'string' && h.command.includes(marker));
             if (alreadyWired) {
                 changes.push(`hooks.${event}: ${marker} already wired — skipped`);

package/dist/hooks/kiro-hooks.js

@@ -12,11 +12,15 @@
  *      understand. fs_write inputs use `path`, mapped to `file_path`.
  *   2. PostToolUse carries `tool_response` (an object), not a `tool_output`
  *      string.
- *   3. Hook stdout is added directly to the agent's context — no
- *      hookSpecificOutput JSON envelope — and the agentSpawn event gives a
- *      context slot at session start, which we use to load active rules
- *      up front (Claude Code needs the search-enforcer dance for this;
- *      Kiro gets it for free).
+ *   3. Hook stdout reaches the model's context ONLY on agentSpawn and
+ *      userPromptSubmit (no hookSpecificOutput JSON envelope). preToolUse
+ *      stdout is IGNORED — exit codes gate the tool call, and only exit-2
+ *      stderr is shown to the LLM; postToolUse stdout is ignored too
+ *      (kiro.dev/docs/cli/hooks, verified empirically 2026-07-13). So all
+ *      context injection rides agentSpawn (rules up front at session start)
+ *      and userPromptSubmit (periodic mid-session refresh, see
+ *      emitRuleRefresh). Claude Code needs the search-enforcer dance for
+ *      this; Kiro gets it for free.
  *
  * userPromptSubmit needs no adapter: Kiro sends { prompt, session_id, cwd },
  * exactly what correction-detector expects — wire it directly.
@@ -26,6 +30,39 @@
  * only assistant_response (no transcript file), so transcript-based failure
  * detectors and session extraction don't run under Kiro.
  */
+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.normalizeKiroInput = normalizeKiroInput;
 exports.handleKiroAgentSpawn = handleKiroAgentSpawn;
@@ -34,11 +71,12 @@ exports.handleKiroToolOutcome = handleKiroToolOutcome;
 exports.handleKiroCapture = handleKiroCapture;
 exports.handleKiroCaptureWorker = handleKiroCaptureWorker;
 const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const shared_1 = require("./shared");
 const directives_1 = require("../shared/directives");
 const memory_1 = require("../services/memory");
 const config_1 = require("../services/config");
-const rule_injector_1 = require("./rule-injector");
 const tool_outcome_watcher_1 = require("./tool-outcome-watcher");
 const correction_detector_1 = require("./correction-detector");
 const memory_tools_1 = require("../mcp/tools/memory-tools");
@@ -98,7 +136,7 @@ function formatRulesForContext() {
  * Standing instruction so the agent KNOWS it has persistent memory — and,
  * critically, that capture happens via BACKGROUND HOOKS independent of the MCP
  * tools. Under enterprise Kiro governance the claude-recall MCP server is
- * dropped from the toolset, but the userPromptSubmit/preToolUse/postToolUse
+ * dropped from the toolset, but the agentSpawn/userPromptSubmit/postToolUse
  * hooks still write to and read from the local DB. Without the "even without
  * the tools" clause the agent answers "I can't store that, I have no memory
  * tools" — technically true of the TOOL, but false of the system, since the
@@ -155,22 +193,18 @@ async function handleKiroAgentSpawn(_input) {
     }
 }
 /**
- * preToolUse — just-in-time rule injection. Same ranking/recording core as
- * the Claude Code rule-injector, but emits plain text: Kiro adds hook stdout
- * to context directly (no hookSpecificOutput envelope).
+ * preToolUse — DEPRECATED no-op. This used to emit just-in-time rule
+ * injections, on the assumption that Kiro adds preToolUse stdout to context.
+ * It does not: preToolUse stdout is ignored — exit codes gate the tool call
+ * and only exit-2 stderr reaches the LLM (kiro.dev/docs/cli/hooks, verified
+ * empirically 2026-07-13) — so nothing this handler printed ever reached the
+ * model, while every emission was falsely recorded as an injection. Mid-session
+ * injection now rides userPromptSubmit (emitRuleRefresh). The handler stays
+ * registered so agent configs wired by older versions keep exiting 0;
+ * `kiro setup` no longer wires it and strips stale entries on re-run.
  */
-async function handleKiroRuleInjector(input) {
-    try {
-        const normalized = normalizeKiroInput(input);
-        const context = await (0, rule_injector_1.computeInjection)(normalized?.tool_name ?? '', normalized?.tool_input ?? {}, '');
-        if (context) {
-            process.stdout.write(context + '\n');
-        }
-    }
-    catch (err) {
-        // Best-effort — never block the tool call
-        (0, shared_1.hookLog)(HOOK_NAME, `rule-injector error: ${(0, shared_1.safeErrorMessage)(err)}`);
-    }
+async function handleKiroRuleInjector(_input) {
+    (0, shared_1.hookLog)(HOOK_NAME, 'kiro-rule-injector is deprecated (Kiro ignores preToolUse stdout) — no-op; re-run `claude-recall kiro setup` to unwire it');
 }
 /**
  * postToolUse — outcome capture and Bash fix-pairing, delegated to the shared
@@ -184,6 +218,84 @@ async function handleKiroToolOutcome(input) {
         (0, shared_1.hookLog)(HOOK_NAME, `tool-outcome error: ${(0, shared_1.safeErrorMessage)(err)}`);
     }
 }
+/**
+ * Mid-session rule refresh — the Kiro answer to long-session context loss.
+ * Rules enter context once at agentSpawn; when Kiro later compacts or rolls
+ * the conversation, they silently vanish and nothing re-injects them (Kiro has
+ * no post-compaction event, and preToolUse stdout is ignored — see
+ * handleKiroRuleInjector). userPromptSubmit stdout IS added to context
+ * same-turn, so every CLAUDE_RECALL_REFRESH_INTERVAL prompts (default 15,
+ * 0 disables) we re-emit the active rules from here.
+ *
+ * The prompt counter is per-session (keyed by session_id) in hook-state/;
+ * stale counter files are pruned on each session's first prompt.
+ */
+const DEFAULT_REFRESH_INTERVAL = 15;
+const REFRESH_STATE_PREFIX = 'kiro-refresh-';
+const REFRESH_STATE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+function refreshInterval() {
+    const raw = process.env.CLAUDE_RECALL_REFRESH_INTERVAL;
+    if (raw === undefined || raw.trim() === '')
+        return DEFAULT_REFRESH_INTERVAL;
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n))
+        return DEFAULT_REFRESH_INTERVAL;
+    return n > 0 ? n : 0;
+}
+/** Increment the per-session prompt counter and return the new count. */
+function bumpPromptCount(sessionId) {
+    const safeId = sessionId.replace(/[^a-zA-Z0-9_-]/g, '_') || 'default';
+    const file = path.join((0, shared_1.hookStateDir)(), `${REFRESH_STATE_PREFIX}${safeId}.json`);
+    let count = 0;
+    try {
+        count = JSON.parse(fs.readFileSync(file, 'utf8')).count ?? 0;
+    }
+    catch { /* first prompt of the session, or unreadable — start fresh */ }
+    count++;
+    fs.writeFileSync(file, JSON.stringify({ count, updated: Date.now() }));
+    if (count === 1)
+        pruneStaleRefreshState();
+    return count;
+}
+/** Best-effort removal of counter files from long-dead sessions. */
+function pruneStaleRefreshState() {
+    try {
+        const dir = (0, shared_1.hookStateDir)();
+        const cutoff = Date.now() - REFRESH_STATE_MAX_AGE_MS;
+        for (const name of fs.readdirSync(dir)) {
+            if (!name.startsWith(REFRESH_STATE_PREFIX))
+                continue;
+            const p = path.join(dir, name);
+            try {
+                if (fs.statSync(p).mtimeMs < cutoff)
+                    fs.unlinkSync(p);
+            }
+            catch { /* another process won the race — fine */ }
+        }
+    }
+    catch { /* pruning is housekeeping, never let it interfere */ }
+}
+function emitRuleRefresh(input) {
+    try {
+        const interval = refreshInterval();
+        if (interval === 0)
+            return;
+        const count = bumpPromptCount(String(input?.session_id ?? 'default'));
+        if (count % interval !== 0)
+            return;
+        const rules = formatRulesForContext();
+        if (!rules.body)
+            return;
+        process.stdout.write(`🔄 Recall: periodic rule refresh (prompt ${count} this session). ` +
+            'Earlier rule injections may have been compacted out of your context — continue applying these:\n\n' +
+            rules.body + '\n');
+        (0, shared_1.hookLog)(HOOK_NAME, `refresh: re-injected ${rules.total} rule(s) at prompt ${count} (interval ${interval})`);
+    }
+    catch (err) {
+        // The refresh is an enhancement — never let it break capture
+        (0, shared_1.hookLog)(HOOK_NAME, `refresh error: ${(0, shared_1.safeErrorMessage)(err)}`);
+    }
+}
 /**
  * userPromptSubmit — the synchronous gate Kiro waits on. Under Kiro there is no
  * ANTHROPIC_API_KEY, so classification uses Kiro's own headless LLM
@@ -195,8 +307,12 @@ async function handleKiroToolOutcome(input) {
  * it over stdin, and returns in milliseconds. The worker performs the slow Kiro
  * classify call and stores the memory in the background. Same pattern as
  * session-end-checkpoint. See docs/kiro-llm-capture.md.
+ *
+ * It also owns the mid-session rule refresh (emitRuleRefresh above): the
+ * refresh must count EVERY prompt, so it runs before the capture pre-checks.
  */
 async function handleKiroCapture(input) {
+    emitRuleRefresh(input);
     const prompt = input?.prompt ?? '';
     // Cheap pre-checks mirror correction-detector so we don't spawn a worker (and
     // spend Kiro credits) on input that could never be stored.

package/dist/hooks/llm-classifier.js

@@ -5,10 +5,10 @@
  * 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.
+ * is why this backend is STRICTLY OPT-IN (CLAUDE_RECALL_PREFER_API_KEY): the
+ * default chains use each runtime's included LLM only (claude -p / kiro-cli —
+ * see cc-classifier.ts and kiro-classifier.ts), and an exported key is never
+ * spent silently. Falls back gracefully (returns null) when unavailable.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.classifyWithLLM = classifyWithLLM;
@@ -146,11 +146,12 @@ function parseJSON(text) {
  * 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).
+ * Backend policy matches capture: the user's Claude SUBSCRIPTION (headless
+ * `claude -p`) is the only default backend — a personally-exported
+ * ANTHROPIC_API_KEY is STRICTLY OPT-IN via CLAUDE_RECALL_PREFER_API_KEY and
+ * never consulted otherwise, not even as a fallback. The opt-in exists for
+ * Pi-only users (no `claude` binary; their key is how they run Pi itself)
+ * and anyone deliberately paying for a stronger model.
  *
  * The CLI backend is skipped inside a nested headless session
  * (CLAUDE_RECALL_NESTED): if `claude -p` fires user-scope hooks of its own,
@@ -182,7 +183,7 @@ async function completeText(systemPrompt, userContent, maxTokens) {
         : (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];
+        : [viaCli];
     for (const backend of backends) {
         const text = await backend();
         if (text !== null && text.trim().length > 0)

package/dist/hooks/shared.js

@@ -166,18 +166,17 @@ function classifyContentRegex(text) {
  * 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.
+ *     headless `claude -p` on the user's Claude SUBSCRIPTION → 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.
+ *     → regex.
+ *   - Inline callers: straight to 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.
+ * The ANTHROPIC_API_KEY path is STRICTLY OPT-IN via
+ * CLAUDE_RECALL_PREFER_API_KEY — an exported key is never consulted
+ * otherwise, not even as a fallback. (It is always a personal key the user
+ * exported — Claude Code does NOT provide one from the subscription.)
+ * See docs/cc-llm-capture.md and docs/kiro-llm-capture.md.
  */
 async function classifyContent(text) {
     // Guard the LLM paths the same way the regex path is guarded: a question or
@@ -202,30 +201,25 @@ async function classifyContentInner(text) {
     // 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);
     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.
+    // Pick the LLM backends. The ANTHROPIC_API_KEY path is STRICTLY OPT-IN
+    // (CLAUDE_RECALL_PREFER_API_KEY): claude-recall was built for runtimes that
+    // bring their own LLM — Kiro via `kiro-cli chat --no-interactive` (Kiro
+    // credits), Claude Code via `claude -p` (the user's Claude subscription) —
+    // and a key exported for other tools must NEVER be spent silently, not even
+    // as a fallback. Without the opt-in, the chain is included LLM → regex.
+    // The opt-in exists for Pi-only users (no `claude` binary; their key is how
+    // they run Pi itself) and anyone deliberately paying for a stronger model.
+    // The CLI backends only run inside their detached capture workers (which
+    // set the *_CLASSIFIER env vars) — inline hook paths go straight to regex,
+    // since a ~4s CLI call can't block a turn.
     const backends = [];
-    if (underKiro && !preferApiKey) {
-        backends.push(tryKiro, tryApiKey);
-    }
-    else if (underKiro) {
-        backends.push(tryApiKey, tryKiro);
-    }
-    else if (underCc && !preferApiKey) {
-        backends.push(tryCc, tryApiKey);
+    if (preferApiKey)
+        backends.push(tryApiKey);
+    if (underKiro) {
+        backends.push(tryKiro);
     }
     else if (underCc) {
-        backends.push(tryApiKey, tryCc);
-    }
-    else {
-        backends.push(tryApiKey);
+        backends.push(tryCc);
     }
     for (const backend of backends) {
         const result = await backend();

package/docs/2025-08-07-launch-article-linkedin.md

@@ -0,0 +1,83 @@
+<!--
+Archived: the original Claude Recall launch article, published on LinkedIn by
+Raoul Biagioni on August 7, 2025. Preserved verbatim as a historical record of
+the project's origin. NOTE: it predates most of what Claude Recall is today —
+Pi and Kiro support, the outcome-aware learning loop, LLM-based capture, the
+no-API-key/subscription architecture — so treat it as origin story, not docs.
+-->
+
+# Why I Spent My Weekend Teaching a Goldfish-Brained AI to Remember
+
+**Raoul Biagioni** — ♾️ AI Development Specialist | Agentic Engineer | Enabling AI-driven Business Innovation
+
+*Published on LinkedIn, August 7, 2025*
+
+---
+
+Claude Code forgets what you just told it. Not just between sessions. Even 10 messages into a conversation.
+
+But what if it didn't?
+
+## The Problem That Sparked a Solution
+
+Over the past six months, I watched myself explain the same codebase preferences to Claude over and over again.
+
+PostgreSQL for data. TypeScript strict mode. Tests directory for saving tests.
+
+Not just in new sessions. Even 20 conversation turns later, as the context window fills up, Claude starts forgetting what we discussed at the beginning.
+
+That's when I decided: Claude Code needs a memory.
+
+## Building Claude Recall: A Memory That Actually Works
+
+Sure, there are memory solutions out there. xmem requires an external vector database for storing memory. Mem0 (OpenMemory) needs Chrome extensions and API keys to connect across tools.
+
+But I wanted something different: truly local, minimal dependencies, and built directly into Claude Code using MCP. No browser extensions. No vector DB setup. No API keys. Just `npm install claude-recall` and you're done.
+
+Here's what I built in 72 hours of coding:
+
+### 🧠 Smart Capture
+
+- Hooks that watch every tool Claude uses (118-line robust implementation)
+- Patterns detected automatically from your workflow
+- Zero configuration needed
+
+### ⚡ Smart Retrieval
+
+- MCP server provides memory tools directly to Claude
+- Pattern-based intent detection from natural language
+- Context-aware memory filtering and relevance scoring
+
+### 🔧 The Tech Stack
+
+Claude Recall consists of three main components: A JavaScript hook that intercepts Claude's tool usage (file reads, bash commands, etc.), a Node.js MCP server to expose memory search and retrieval tools to Claude, and a SQLite database that stores captured patterns and preferences locally.
+
+When Claude performs an action, the hook captures it and sends it to the pattern detector. The detector uses regex-based pattern matching to identify things like file locations, tool preferences, and coding styles with confidence scores. Patterns scoring above 0.8 are stored in SQLite. During Claude sessions, the MCP server provides tools that Claude can call to search and retrieve these stored memories based on context and relevance scoring.
+
+## Real Results From Real Conversations
+
+**Before Claude Recall (message #25 in same chat):**
+
+- "What database do we use?" → Claude searches everywhere
+- "Where's the auth logic?" → Claude searches everywhere
+- "Write a test" → Claude saves the test in the project root
+
+**After Claude Recall (message #100, still remembers):**
+
+- "What database do we use?" → "PostgreSQL, as always"
+- "Where's the auth logic?" → "src/services/auth.ts:42"
+- "Write a test" → Claude saves the test in tests/
+
+## The Reality Check
+
+I'm conscious that in the fast-evolving GenAI ecosystem, many projects are quickly destined to oblivion. I have no doubt that the problem I described and solved for myself will be solved better by someone else soon. But here's the thing: I had an absolute blast building Claude Recall with the help of Claude Code by Anthropic, and the amazing AI Orchestration Platform Claude-Flow by Reuven Cohen from Agentics Foundation.
+
+Sometimes the best tools are the ones you build for yourself, not because they'll change the world, but because they solve your specific problem right now.
+
+> 💡 **Key Takeaway:** We're living in the stone age of AI assistants. They're powerful but goldfish-brained — forgetting context even within the same conversation. That changes now.
+
+🔗 Link: in the comments.
+
+💬 Question for you: What's the ONE thing you wish your AI assistant would remember?
+
+#AITools #DeveloperProductivity #OpenSource #ClaudeAI

package/docs/2026-07-follow-up-article-draft.md

@@ -0,0 +1,68 @@
+<!--
+DRAFT v2 — reader-first rewrite of the one-year follow-up (July 2026).
+v1 (deleted) was structured around the author's broken-promise confession;
+this version is structured around what the READER gets: three things they can
+check/fix about their own agent's memory today, whether or not they install
+anything. The tool enters late, the "when NOT to bother" section is explicit,
+and the CTA offers a fair trade (2 commands, 1 week, reversible) for honest
+answers to: does it work / am I over-promising / is it worth it at all.
+Facts verified against v0.33.0 on 2026-07-10: write-time dedup (live-tested),
+prune-on-boot, demotion (manual/opt-in — hence "can demote"), Kiro→CC shared
+DB (live-tested), claude -p key-over-subscription precedence (live-tested).
+-->
+
+# Your Coding Agent Finally Has Memory. Here's Where It Still Fails You.
+
+**Raoul Biagioni** — *Draft v2, July 2026*
+
+---
+
+You've told your coding agent "use pnpm, not npm" at least five times. This year that was finally supposed to stop: Claude Code now ships auto-memory, on by default. It watches your corrections and writes itself notes.
+
+Genuinely good. I build in this space and I'll say it plainly: for a lot of people, the built-in memory is enough.
+
+But if you live in a coding agent daily, there are three failure modes it leaves wide open — and you'll hit all three without ever getting an error message. Whether or not you try my tool, you'll want to know they exist.
+
+## 1. Agent memory rots — silently
+
+Built-in memory is great for the first twenty sessions. Then the notes pile up: contradictory entries, "yesterday" written three weeks ago, fixes referencing files you've deleted. Past a point, your agent isn't remembering — it's confidently misremembering, and stale notes are worse than no notes, because you don't think to double-check something the agent states as known fact.
+
+**Check it yourself today:** open your project's auto-memory file and read what your agent believes about your codebase. If you've been at it more than a month, I'd bet money something in there is wrong.
+
+## 2. Your corrections don't travel
+
+Correct Claude Code on Tuesday; Kiro makes the same mistake on Friday. Every agent keeps its own notebook, so a team (or a person) using more than one agent re-teaches every preference once per tool. The more agents you run, the more your corrections fragment.
+
+## 3. Your exported API key may be quietly paying for things
+
+This one surprised me, and it generalizes beyond memory tools: **if you have `ANTHROPIC_API_KEY` exported for some other tool, `claude -p` — and anything built on it — will silently bill that key instead of your Claude subscription.** Two wallets, one of them draining without you deciding anything. Audit your environment; you may be paying twice for AI you already subscribe to.
+
+## What I built against these
+
+A year ago I wrote here about giving my "goldfish-brained" agent a memory. That tool, Claude Recall, has since become specifically an answer to the three problems above:
+
+- **Anti-rot:** it de-duplicates on write, prunes on every boot, and can demote rules that stop earning their keep — designed for session 200, not session 5.
+- **One brain, every agent:** a single local SQLite file shared by Claude Code, Pi, and Kiro. Correct one agent; the others apply it.
+- **Never your API key:** it runs on the login your agent already has (Claude subscription, Kiro credits). An exported key is untouched unless you explicitly opt in.
+
+Local, no cloud, no telemetry, and you can read every stored memory with one command — or wipe them.
+
+Setup is two commands: `npm install -g claude-recall`, then one setup command per project. Uninstalling is one.
+
+## When you should NOT bother
+
+Fair is fair: if you use a single agent, a couple of sessions a week, on one or two projects — the built-in memory is probably enough for you. Don't install another tool for a problem you don't feel.
+
+## What I'm asking — and what you get
+
+Here's the trade. I built this for myself, which means I genuinely don't know if it holds up in your workflow. So if the three failure modes above sound familiar, run it for a week next to the built-in memory and tell me the truth:
+
+1. **Does it work as expected** — right things captured, surfaced at the right moment?
+2. **Am I over-promising** — where does this article outrun your actual experience?
+3. **Is it worth it at all** — or is the built-in memory quietly good enough?
+
+What you get in return: a memory that survives, travels, and never touches your key — if I'm right. And if I'm wrong, you've spent two commands finding out, and your feedback directly decides what gets built next. Either answer is useful to me; only one of us is guessing right now.
+
+Link and quick-start in the comments. Tell me which of the three failure modes you've hit.
+
+#AITools #DeveloperProductivity #OpenSource #ClaudeAI #AIMemory

package/docs/2026-07-follow-up-article-linkedin-tight.md

@@ -0,0 +1,46 @@
+<!--
+Tight LinkedIn version (~430 words) of docs/2026-07-follow-up-article-draft.md
+(reader-first v2). Same three failure modes, same honest opt-out, same CTA —
+compressed for feed reading. Not yet published.
+-->
+
+# Your Coding Agent Finally Has Memory. Here's Where It Still Fails You.
+
+Claude Code ships auto-memory, on by default. Your agent watches your corrections, writes itself notes, and remembers them next session.
+
+Genuinely good. For many people it's enough.
+
+But if you live in a coding agent daily, it leaves three failure modes wide open — and you'll hit all three without ever seeing an error.
+
+**1. Agent memory rots — silently.**
+Great for twenty sessions. Then the notes pile up: contradictions, "yesterday" written three weeks ago, fixes referencing deleted files — and only the first 200 lines even load at startup. Your agent stops remembering and starts confidently *mis*remembering. Anthropic knows: they shipped a periodic cleanup pass ("Auto Dream") for exactly this — a tidy-up of the same self-written notes, so a wrong note that reads plausibly stays believed. Check it yourself: open your auto-memory file and read what your agent believes about your codebase. To be clear, *no* memory system captures perfectly — mine included. The real question is what happens to the mistakes afterwards: dedup, pruning, retiring rules that stop earning their keep — or nothing.
+
+**2. Your corrections don't travel.**
+Correct Claude Code on Tuesday; Kiro repeats the mistake on Friday. Every agent keeps its own notebook, so every preference gets re-taught once per tool.
+
+**3. Your exported API key may be quietly paying for things.**
+If `ANTHROPIC_API_KEY` is exported for some other tool, headless Claude (`claude -p` — and every script or hook built on it) bills that key instead of your Claude subscription. Not a bug: Anthropic's docs say the env key *"takes precedence over subscription authentication"* — the interactive app asks you which to use; automation doesn't ask. Two wallets, one draining without you deciding anything. Audit your env.
+
+**Claude Recall** — my open-source memory engine for coding agents — is built specifically against these three.
+
+Some of you saw me launch it here last summer as a weekend hack: Claude-Code-only, regex-based capture, held together with enthusiasm. Today's version (v0.33) is a different animal — same local-first idea, now grown into what the weekend hack couldn't be:
+
+▸ **Anti-rot:** de-duplicates on write, prunes on every boot, can demote rules that stop earning their keep. Built for session 200, not session 5.
+▸ **One brain, every agent:** a single local SQLite file shared by Claude Code, Pi, and Kiro. Correct one; the others apply it.
+▸ **Never your API key:** runs on the login your agent already has. Your key is untouched unless you explicitly opt in.
+
+Local. No cloud. No telemetry. Two commands to install; one to remove.
+
+**When NOT to bother:** one agent, a few sessions a week, one or two projects → the built-in memory is probably enough. Don't install a tool for a problem you don't feel.
+
+**The ask.** I built this for myself — I genuinely don't know if it holds up in *your* workflow. If the three failure modes sound familiar: run it for a week next to the built-in memory and tell me the truth.
+
+1. Does it work as expected?
+2. Am I over-promising?
+3. Is it worth it at all — or is built-in quietly enough?
+
+Either answer is useful. Only one of us is guessing right now.
+
+Link in the comments. Which of the three have you hit?
+
+#AITools #DeveloperProductivity #OpenSource #ClaudeAI #AIMemory

package/docs/cc-llm-capture.md

@@ -0,0 +1,147 @@
+# Using your Claude subscription for memory capture (no API key)
+
+The Claude Code counterpart to [kiro-llm-capture.md](kiro-llm-capture.md): how
+claude-recall's LLM features run on the user's **Claude subscription** — the
+same login that powers their interactive session — instead of a personal
+`ANTHROPIC_API_KEY`.
+
+## The problem
+
+Claude Recall's LLM classifier originally called Claude Haiku through the
+Anthropic SDK, which needs `ANTHROPIC_API_KEY` — a **personal pay-as-you-go
+key**. For a long time the docs claimed Claude Code "provides the key to its
+hooks." That was false: Claude Code does not mint a key from the user's
+subscription; hooks merely inherit the user's environment. So the key path
+only ever worked for users who had exported their own key, and it silently
+spent **their API credits** — a separate wallet from the Claude subscription
+they were already paying for.
+
+The failure mode that exposed all of this: a user's exported key ran out of
+credits. Every SDK call failed silently, capture degraded to the regex
+fallback, and the regex promptly stored four junk memories in one session —
+while the user reasonably believed "the LLM" was doing the classifying.
+
+## The finding
+
+**`claude -p "<prompt>"` is a headless one-shot completion that runs on the
+user's Claude Code login** — the direct analogue of the earlier
+`kiro-cli chat --no-interactive` discovery. A background worker can shell out
+to it to classify text with no API key and no extra cost beyond the
+subscription usage the user already has.
+
+One gotcha made this non-trivial, and it's the most important line in the
+implementation:
+
+> **`claude -p` prefers `ANTHROPIC_API_KEY` over subscription auth when the
+> key is present in the environment.**
+
+So a stray exported key — possibly dead, possibly billing a wallet the user
+forgot about — would silently hijack every headless call. The fix:
+`completeWithClaudeCli()` **strips `ANTHROPIC_API_KEY` from the child env**,
+forcing subscription auth unconditionally. (Verified live: with a
+credits-exhausted key in the env, `claude -p` returned
+`Credit balance is too low`; with the key stripped, the same call succeeded on
+the login.)
+
+## The design
+
+```
+Claude Code UserPromptSubmit
+        │
+        ▼
+  hook run correction-detector      (name unchanged in settings.json;
+        │                            returns in <100 ms)
+        │  spawn detached, pipe payload via stdin
+        ▼
+  hook run cc-capture-worker        (background, survives parent exit)
+        │  sets CLAUDE_RECALL_CC_CLASSIFIER=1
+        ▼
+  handleCorrectionDetector → classifyContent()
+        │
+        ├─ classifyWithClaudeCli()  → claude -p --model haiku "<prompt>"
+        │                             (subscription auth, key stripped)
+        └─ regex fallback
+
+  (classifyWithLLM() / ANTHROPIC_API_KEY exists but is OPT-IN only —
+   see below; it is never in the default chain)
+```
+
+Precedence mirrors Kiro: **the runtime's included LLM → regex.** An exported
+`ANTHROPIC_API_KEY` is **never consulted by default — not even as a
+fallback**; `CLAUDE_RECALL_PREFER_API_KEY=1` is the one switch that enables
+(and prefers) it. The registered hook name (`hook run correction-detector`)
+was deliberately kept, so existing `settings.json` files work with no
+re-setup — only the dispatch behind it changed.
+
+**Trade-off:** the synchronous `📌 Recall: auto-captured …` echo is gone.
+A cold `claude -p` takes ~4 s, far too slow to block the user's prompt, so
+capture is silent and lands a few seconds later — the same contract Kiro has
+always had. Verify via `~/.claude-recall/hook-logs/cc-classifier.log`
+(`classified via claude -p (model=…, Claude subscription, no API key)`) or
+`claude-recall search`.
+
+### Recursion guard
+
+The nested headless session is itself a Claude Code session. If the user has
+claude-recall hooks registered at **user scope** (`~/.claude/settings.json`),
+the classify call would fire those hooks, which would spawn another worker,
+which would run another `claude -p` — forever. Two layers prevent this:
+
+1. `claude -p` children run with `cwd = os.tmpdir()`, so **project**
+   settings/hooks never load.
+2. Children are marked with `CLAUDE_RECALL_NESTED=1` (plus the legacy
+   `CLAUDE_RECALL_CC_CLASSIFIER=1`). The capture hook refuses to spawn a
+   worker, and the secondary-feature backend refuses to invoke the CLI, when
+   either marker is present.
+
+### Beyond capture: the secondary features (0.32.0)
+
+`completeWithClaudeCli()` is a generic completion primitive, and the four
+features that previously knew only the key path now route through it with the
+same precedence:
+
+| Feature | Runs in | Without any key, now |
+| --- | --- | --- |
+| Auto-checkpoint extraction | Session-exit worker (CC + **Pi** — Pi's only recovery path, it has no `--resume`) | Works via `claude -p` |
+| Failure hindsight hints | Stop hook, inline | Works via `claude -p` |
+| End-of-session lesson extraction | Stop hook, inline | Works via `claude -p` |
+| Batch classification | Stop hook, inline | Works via `claude -p` |
+
+Two budget rules keep the inline ones inside the Stop hook's ~40 s window
+(capture doesn't need them — it runs in a detached worker):
+
+- each secondary CLI call is capped at **10 s** (vs the worker's 30 s), and
+- hindsight-hint generation is capped at **5 LLM calls per run** (the loop
+  over detected failures is otherwise unbounded; failures past the cap keep
+  the grounded generic lesson text).
+
+Under **Pi** these functions run in-process, so Pi benefits automatically on
+any machine with the `claude` binary installed alongside. Under **Kiro** the
+Stop-hook features mostly don't run (no transcript in its hooks), and capture
+uses the Kiro backend.
+
+### Configuration
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `CLAUDE_RECALL_CC_MODEL` | `haiku` | Model passed to `claude -p --model` — a dedicated classifier model, independent of the user's interactive session model. |
+| `CLAUDE_RECALL_CC_LLM_TIMEOUT_MS` | `30000` | Hard cap on the capture worker's `claude -p` call. (Secondary features use a fixed 10 s per call.) |
+| `CLAUDE_RECALL_PREFER_API_KEY` | *(unset)* | **The only switch that enables the `ANTHROPIC_API_KEY` backend** (and prefers it first) — without it an exported key is never touched, not even as a fallback. For Pi-only machines without the `claude` binary, or a stronger model you deliberately pay for. Applies to capture and the secondary features, on every runtime. |
+| `CLAUDE_RECALL_NESTED` | *(set on `claude -p` children)* | Recursion marker — never set it by hand. |
+
+## Caveats
+
+- **Requires the `claude` binary on `PATH`.** Absent (e.g. a bare CI box, or a
+  Pi-only machine), the CLI backend errors out and the chain falls through to
+  regex — or to an `ANTHROPIC_API_KEY` if you opted in with
+  `CLAUDE_RECALL_PREFER_API_KEY=1`. No crash, no exception.
+- **Subscription usage.** Each classified prompt is one small Haiku call
+  against the user's Claude plan limits. That is the deliberate trade — the
+  user's existing plan instead of a second wallet.
+- **Latency.** ~4 s cold per call. Fine in a detached worker; the reason the
+  inline features carry the 10 s cap and hint budget.
+- **Consistency.** Same probabilistic caveat as the Kiro backend: the
+  classifier is an LLM judgement call. The classify prompt carries a
+  "standalone rule" test with negative examples precisely because early
+  versions stored one-off task instructions ("first fix the sentence") as
+  corrections.

package/docs/kiro-llm-capture.md

@@ -9,7 +9,7 @@ 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`.)
+subscription auth — see [cc-llm-capture.md](cc-llm-capture.md).)
 
 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
@@ -89,20 +89,24 @@ Kiro userPromptSubmit
         ▼
   handleCorrectionDetector → classifyContent()
         │
-        ├─ classifyWithLLM()   → ANTHROPIC_API_KEY (unset under Kiro) → null
         ├─ classifyWithKiro()  → kiro-cli chat --no-interactive --agent
         │                         claude-recall-classifier --model claude-haiku-4.5
         │                         → {"type","confidence","extract"}
-        └─ regex fallback       (only if both above yield nothing)
+        └─ regex fallback       (only if the above yields nothing)
+
+  (classifyWithLLM() / ANTHROPIC_API_KEY exists but is OPT-IN only —
+   never in the default chain)
 ```
 
-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 the same pattern applies with `claude -p` on
-the user's subscription as the included LLM — see `src/hooks/cc-classifier.ts`.)
+Capture precedence under Kiro: **Kiro's included LLM → regex as a last
+resort.** An exported `ANTHROPIC_API_KEY` is **never consulted by default —
+not even as a fallback** — 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` is the one explicit switch that enables (and
+prefers) the key, for anyone who deliberately wants to pay for a stronger
+model. (Under Claude Code the same pattern applies with `claude -p` on the
+user's subscription as the included LLM — see
+[cc-llm-capture.md](cc-llm-capture.md).)
 
 ### Output parsing
 
@@ -119,7 +123,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, passed explicitly as `--model`. This is a **dedicated classifier model, independent of the user's interactive Kiro chat model** (e.g. `auto`) — the headless call always uses this value. 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). |
+| `CLAUDE_RECALL_PREFER_API_KEY` | *(unset)* | **The only switch that enables the `ANTHROPIC_API_KEY` backend** — without it an exported key is never touched, not even as a fallback. |
 
 ## Caveats
 

package/docs/kiro.md

@@ -30,7 +30,7 @@ and inside the Kiro chat, switch to the agent:
 /agent swap recall
 ```
 
-You get: active rules injected into context automatically at agent start (no tool call needed), just-in-time rule injection before each tool call, automatic capture of corrections/preferences from your prompts, tool-outcome tracking with Bash fix-pairing, and the full MCP tool surface (read-only tools pre-approved).
+You get: active rules injected into context automatically at agent start (no tool call needed), a periodic mid-session rule refresh (see below), automatic capture of corrections/preferences from your prompts, tool-outcome tracking with Bash fix-pairing, and the full MCP tool surface (read-only tools pre-approved).
 
 ### Merging into an agent you already use
 
@@ -40,7 +40,13 @@ Don't want to swap agents? Merge Claude Recall into your own:
 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 — 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.
+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 three hooks (`agentSpawn`, `userPromptSubmit`, `postToolUse`) — 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.
+
+### Mid-session rule refresh (long sessions)
+
+Rules enter context once, at agent start. In a long session Kiro eventually compacts or rolls the conversation and the rules silently vanish — Kiro exposes no post-compaction event to re-inject them (Claude Code has one, and claude-recall uses it there). So under Kiro, claude-recall re-injects the active rules **every 15 prompts** via the `userPromptSubmit` hook, whose stdout Kiro adds directly to context. Tune or disable with `CLAUDE_RECALL_REFRESH_INTERVAL` (`0` = off).
+
+> **Note for configs wired by ≤0.33:** older versions also added a `preToolUse` rule injector. Kiro ignores `preToolUse` stdout — exit codes gate the tool call, and only exit-2 stderr reaches the model ([kiro.dev/docs/cli/hooks](https://kiro.dev/docs/cli/hooks)) — so that hook never actually injected anything. It is now a harmless no-op; re-run `claude-recall kiro setup --merge-into <agent>` once and the stale entry is stripped automatically.
 
 ---
 
@@ -74,7 +80,7 @@ To decide what's worth remembering, the capture hook classifies each prompt via
 
 **The classifier uses a dedicated, fixed model — not your chat model.** It always runs the model in `CLAUDE_RECALL_KIRO_MODEL` (default `claude-haiku-4.5`, chosen because classification is cheap and high-volume), **independent of your interactive Kiro chat model** (e.g. `auto`). This keeps classification cost predictable no matter what your chat is set to. Set `CLAUDE_RECALL_KIRO_MODEL` to any model from `kiro-cli chat --list-models` to change it. Every successful classification is logged to `~/.claude-recall/hook-logs/kiro-classifier.log` as `classified via kiro-cli (model=…, Kiro credits, no API key)`, so you can always see which model ran.
 
-**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).
+**An exported `ANTHROPIC_API_KEY` is never touched** — a key exported for other tools won't quietly spend your Anthropic credits, not even as a fallback. Order: Kiro's LLM → regex. Setting `CLAUDE_RECALL_PREFER_API_KEY=1` is the one explicit switch that enables (and prefers) your key, e.g. for a stronger model you pay for.
 
 Design details, latency measurements, and output-parsing internals: [kiro-llm-capture.md](kiro-llm-capture.md).
 

package/package.json

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