claude-recall 0.33.0 → 0.34.1

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
@@ -162,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 | ✓ | ✓ |  |
@@ -325,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.
 
 ---
 
@@ -395,6 +396,7 @@ Defaults work out of the box; tune via environment variables as needed.
 | `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)_ | **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/claude-recall-cli.js

@@ -406,6 +406,12 @@ class ClaudeRecallCLI {
             console.error('\nCheck your connection, then run `claude-recall upgrade` again.');
             process.exit(1);
         }
+        // `latest` is interpolated into an npm argument (via a shell on Windows) —
+        // accept only a plausible semver string from the registry response.
+        if (!/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(latest)) {
+            console.error(`❌ Unexpected version string from the registry: "${latest}"`);
+            process.exit(1);
+        }
         console.log(`Installed: ${current}`);
         console.log(`Latest:    ${latest}`);
         const needsInstall = current !== latest;
@@ -413,7 +419,11 @@ class ClaudeRecallCLI {
             console.log(`\n📦 Upgrading ${current} → ${latest}...\n`);
             // Run npm install -g, streaming output so the user sees progress / errors live.
             // shell: true on Windows — npm is npm.cmd there and a bare spawnSync ENOENTs.
-            const install = spawnSync('npm', ['install', '-g', 'claude-recall@latest'], {
+            // Pin the exact version `npm view` just resolved instead of `@latest`:
+            // right after a publish, the dist-tag replica npm installs from can lag
+            // the metadata endpoint `npm view` read — `@latest` then silently
+            // reinstalls the OLD version with exit 0 (observed live on 0.34.0).
+            const install = spawnSync('npm', ['install', '-g', `claude-recall@${latest}`], {
                 stdio: 'inherit',
                 shell: process.platform === 'win32',
             });
@@ -429,7 +439,9 @@ class ClaudeRecallCLI {
             if (install.status !== 0) {
                 // npm prints its own error — add the practical remediation on top
                 console.error('\n❌ Install failed.');
-                console.error('\nMost common cause: your global npm prefix is owned by root (EACCES).');
+                console.error(`\nIf npm said it can't find claude-recall@${latest} (ETARGET): the release`);
+                console.error('is minutes old and the registry is still propagating — wait a minute and re-run.');
+                console.error('\nMost common cause otherwise: your global npm prefix is owned by root (EACCES).');
                 console.error('\nQuick fix:');
                 console.error('  sudo npm install -g claude-recall');
                 console.error('\nPermanent fix (no more sudo for any global install on this machine):');
@@ -440,6 +452,26 @@ class ClaudeRecallCLI {
                 console.error('\nThen re-run: claude-recall upgrade');
                 process.exit(install.status ?? 1);
             }
+            // Trust but verify: confirm the globally installed version actually IS
+            // `latest` before claiming success. The success message used to report
+            // intent, not fact — a propagation race left 0.33.0 installed while the
+            // command printed "✓ Upgraded to 0.34.0".
+            let installedNow = '';
+            try {
+                const ls = JSON.parse(execSync('npm ls -g claude-recall --json', {
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                }));
+                installedNow = ls?.dependencies?.['claude-recall']?.version ?? '';
+            }
+            catch { /* verification is best-effort; fall through to the mismatch path */ }
+            if (installedNow !== latest) {
+                console.error(`\n❌ Install reported success but the global version is ${installedNow || 'unreadable'}, not ${latest}.`);
+                console.error('   This usually means the npm registry is still propagating a very recent');
+                console.error('   release. Wait a minute, then re-run: claude-recall upgrade');
+                console.error(`   Or install the exact version directly: npm install -g claude-recall@${latest}`);
+                process.exit(1);
+            }
             // Kill any running MCP servers so Claude Code respawns them with the new binary
             console.log('\n🧹 Cleaning up running MCP servers (Claude Code respawns them on next tool call)...');
             try {

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/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/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.
 
 ---
 

package/package.json

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