claude-recall 0.27.1 → 0.28.1

package/README.md

@@ -5,7 +5,7 @@
 Claude Recall is a **local memory engine** that gives coding agents something they're missing by default:
 **the ability to learn from you over time.**
 
-Works with **Claude Code** (via MCP server + hooks) and **[Pi](https://github.com/mariozechner/pi)** (via native extension). Both share the same local database — a preference learned in one agent is available in the other.
+Works with **Claude Code** (via MCP server + hooks), **[Pi](https://github.com/mariozechner/pi)** (via native extension), and **[Kiro CLI](https://kiro.dev/cli/)** (via custom agent + hooks). All three share the same local database — a preference learned in one agent is available in the others.
 
 Your preferences, project structure, workflows, corrections, and coding style are captured automatically and applied in future sessions — **securely stored on your machine**.
 
@@ -69,30 +69,96 @@ pi install npm:claude-recall
 
 That's it. Ask Pi to *"Load my rules"* to verify.
 
+### Install for Kiro CLI
+
+Requires claude-recall **≥ 0.28.0** (`claude-recall --version` to check; `claude-recall upgrade` to update). Uses the same global binary (install it once per machine as above). Two ways to wire it in — full integration is what most people want.
+
+**Option A — full integration (recommended): memory + hooks via a custom agent.**
+
+In your shell, in the project directory, **before** starting Kiro:
+
+```bash
+claude-recall kiro setup
+```
+
+This writes a Kiro custom agent at `.kiro/agents/recall.json` (use `--global` for `~/.kiro/agents` so it's available in every project). It does **not** touch your `mcp.json` — the agent config carries its own `mcpServers` entry for claude-recall, so no separate MCP registration is needed. It also sets `includeMcpJson: true`, so any other servers you have in `mcp.json` keep working alongside it.
+
+Then start Kiro from your shell:
+
+```bash
+kiro
+```
+
+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). Memories are shared with Claude Code and Pi: same database, same per-project scoping.
+
+**Already have a custom agent you live in?** Don't swap — merge Claude Recall into it instead:
+
+```bash
+claude-recall kiro setup --merge-into <agent-name>
+```
+
+This finds the agent config (workspace `.kiro/agents/` first, then `~/.kiro/agents/`; `--global` to target the global one directly), writes a timestamped backup, and appends the claude-recall pieces — MCP server, pre-approved read-only tools, and the four hooks — without touching anything the agent already had. Idempotent: re-running changes nothing. If the agent restricts tools with an explicit list, `@claude-recall` is added to it.
+
+**Option B — MCP tools only (no hooks, works in Kiro's default agent).**
+
+If you don't want a custom agent, register just the MCP server in Kiro's config instead. Create or merge into `.kiro/settings/mcp.json` (project) or `~/.kiro/settings/mcp.json` (all projects):
+
+```json
+{
+  "mcpServers": {
+    "claude-recall": {
+      "command": "claude-recall",
+      "args": ["mcp", "start"],
+      "autoApprove": ["load_rules", "search_memory", "load_checkpoint"]
+    }
+  }
+}
+```
+
+With Option B the agent has the memory tools (`load_rules`, `store_memory`, `search_memory`, checkpoints) but nothing happens automatically — no rules at session start, no auto-capture. Ask it to *"load my rules"*.
+
+**Not available under Kiro** with either option (Kiro's hooks expose no transcript): transcript-based failure detection and session-end auto-checkpoints.
+
 ### Shared Database
 
-Both agents use the same database at `~/.claude-recall/claude-recall.db`, scoped per project by working directory. A correction learned in one agent is available in the other.
+All runtimes (Claude Code, Pi, Kiro CLI) use the same database at `~/.claude-recall/claude-recall.db`, scoped per project by working directory. A correction learned in one agent is available in the others.
 
 ### Upgrading
 
+One command upgrades the shared binary for **all** runtimes (Claude Code, Pi, and Kiro use the same global install):
+
 ```bash
 claude-recall upgrade
 ```
 
-One command. Checks the registry, refreshes the global binary, clears any running MCP servers — Claude Code respawns them on the next tool call, picking up the new version. **No `claude mcp add` re-run needed** — existing registrations point at the `claude-recall` command, not a pinned path.
+It checks the registry, refreshes the global binary, and clears any running MCP servers — they respawn on the next tool call with the new version.
+
+Per-runtime notes:
 
-If the release notes mention new or changed hooks (a `hooksVersion` bump), also re-run `claude-recall setup --install` in each active project. It's safe to run any time: when your hooks are already current it's a no-op and touches nothing.
+- **Claude Code** — nothing else needed; registrations point at the `claude-recall` command, not a pinned path. If the release notes mention new or changed hooks (a `hooksVersion` bump), also re-run `claude-recall setup --install` in each active project — safe any time; a no-op when hooks are already current.
+- **Pi** — run `pi update npm:claude-recall` and restart Pi.
+- **Kiro CLI** — nothing else needed; the agent config points at the `claude-recall` command. If the release notes mention changes to the Kiro agent template, re-run `claude-recall kiro setup --force` in each project that uses it.
 
-> **Registered before v0.27.x?** Older versions auto-registered the MCP server with an `npx`-based command, which re-resolves the package on every server start and can be shadowed by stale project-local installs. Switch to the direct binary form (run in each affected project):
+> **Claude Code registered before v0.27.x?** Older versions auto-registered the MCP server with an `npx`-based command, which re-resolves the package on every server start and can be shadowed by stale project-local installs. Switch to the direct binary form (run in each affected project):
 >
 > ```bash
 > claude mcp remove claude-recall
 > claude mcp add claude-recall -- claude-recall mcp start
 > ```
 
-For Pi, run `pi update npm:claude-recall` and restart Pi.
-
-> **Seeing `error: unknown command 'upgrade'`?** Your installed version predates 0.23.2 (the release that added the `upgrade` command). Bootstrap once with `npm install -g claude-recall@latest`, then all future upgrades use `claude-recall upgrade`.
+> **Seeing `error: unknown command '<anything>'`?** Your installed global binary is older than the docs you're reading — commands ship with releases (`kiro` needs ≥ 0.28.0, `compact` ≥ 0.26.0, `upgrade` ≥ 0.23.2). Fix:
+>
+> ```bash
+> claude-recall upgrade
+> ```
+>
+> If `upgrade` itself is the unknown command (pre-0.23.2 install), bootstrap once with `npm install -g claude-recall@latest`.
 
 <details>
 <summary><b>If the install step reports <code>EACCES: permission denied</code></b></summary>
@@ -128,19 +194,19 @@ The prefix fix only tells npm *where* to install; it doesn't install anything it
 
 Once installed, Claude Recall works automatically in the background. Each row below is tagged with the runtime it applies to so you can skip what doesn't apply to you.
 
-| When | What happens | CC | Pi |
-|---|---|:-:|:-:|
-| **Session start** | Active rules are loaded before the first action and injected into the agent's context | ✓ | ✓ |
-| **As you work** | Every prompt is classified for corrections and preferences. Natural statements like *"we use tabs here"* are detected and stored | ✓ | ✓ |
-| **Before each tool call / agent turn** | **Just-in-time rule injection** — relevant rules are surfaced as a `<system-reminder>` block adjacent to the action so the agent sees them at the moment of decision (not 50,000 tokens upstream). Per-tool-call in CC; per-turn in Pi | ✓ | ✓ |
-| **Tool outcomes** | Tool results (Bash, Edit, Write, etc.) are captured. Failures are stored; Bash failures are paired with their successful fixes | ✓ | ✓ |
-| **Reask detection** | Frustration signals (*"still broken"*, *"that didn't work"*) are recorded as outcome events | ✓ | ✓ |
-| **Before context compression** | Aggressive memory sweep captures important context before the window shrinks | ✓ | ✓ |
-| **After context compression** | Rules are automatically re-injected into the new context so they're not lost | ✓ |   |
-| **Sub-agent spawned** | Active rules are injected into the sub-agent's context. Sub-agent outcomes (completed/failed/killed) are captured | ✓ |   |
-| **Rules sync** | Top 30 rules are exported as typed `.md` files to Claude Code's native memory directory | ✓ |   |
-| **Session exit** | **Auto-checkpoint** — the most recent task is extracted into a `{completed, remaining, blockers}` snapshot and saved for the next session. Critical for Pi (no `--resume` flag); safety net for CC users who exit without resuming | ✓ | ✓ |
-| **End of session** | Session episodes are created, candidate lessons are extracted from failures, and validated patterns are promoted into active rules | ✓ | ✓ |
+| When | What happens | CC | Pi | Kiro |
+|---|---|:-:|:-:|:-:|
+| **Session start** | Active rules are loaded before the first action and injected into the agent's context. Under Kiro this is fully automatic — rules land in context at `agentSpawn`, no tool call needed | ✓ | ✓ | ✓ |
+| **As you work** | Every prompt is classified for corrections and preferences. Natural statements like *"we use tabs here"* are detected and stored | ✓ | ✓ | ✓ |
+| **Before each tool call / agent turn** | **Just-in-time rule injection** — relevant rules are surfaced adjacent to the action so the agent sees them at the moment of decision (not 50,000 tokens upstream). Per-tool-call in CC and Kiro; per-turn in Pi | ✓ | ✓ | ✓ |
+| **Tool outcomes** | Tool results (Bash, Edit, Write, etc.) are captured. Failures are stored; Bash failures are paired with their successful fixes | ✓ | ✓ | ✓ |
+| **Reask detection** | Frustration signals (*"still broken"*, *"that didn't work"*) are recorded as outcome events | ✓ | ✓ | ✓ |
+| **Before context compression** | Aggressive memory sweep captures important context before the window shrinks | ✓ | ✓ |   |
+| **After context compression** | Rules are automatically re-injected into the new context so they're not lost | ✓ |   |   |
+| **Sub-agent spawned** | Active rules are injected into the sub-agent's context. Sub-agent outcomes (completed/failed/killed) are captured | ✓ |   |   |
+| **Rules sync** | Top 30 rules are exported as typed `.md` files to Claude Code's native memory directory | ✓ |   |   |
+| **Session exit** | **Auto-checkpoint** — the most recent task is extracted into a `{completed, remaining, blockers}` snapshot and saved for the next session. Critical for Pi (no `--resume` flag); safety net for CC users who exit without resuming. Kiro surfaces existing checkpoints at agent start but doesn't auto-create them (no transcript in its hooks) | ✓ | ✓ |   |
+| **End of session** | Session episodes are created, candidate lessons are extracted from failures, and validated patterns are promoted into active rules | ✓ | ✓ |   |
 
 Classification and checkpoint extraction use Claude Haiku (via `ANTHROPIC_API_KEY`) with silent regex fallback. No configuration needed.
 
@@ -286,6 +352,11 @@ Manual `checkpoint save` is the explicit path. **Auto-checkpoint** is the safety
 ### Troubleshooting
 
 ```bash
+# "error: unknown command 'kiro'" (or any other command)?
+# Your global binary is older than the feature — upgrade it:
+claude-recall --version                  # What you have
+claude-recall upgrade                    # Get current
+
 # "Are my hooks installed?"
 claude-recall status                     # Shows hook registration status
 claude-recall hooks check                # Verify hook files exist and are valid
@@ -325,7 +396,9 @@ claude-recall mcp cleanup --all          # Stop all stale MCP servers
 ```bash
 # ── Setup & Diagnostics ─────────────────────────────────────────────
 claude-recall setup                      # Show activation instructions
-claude-recall setup --install            # Install skills + hooks
+claude-recall setup --install            # Install skills + hooks (Claude Code, current project)
+claude-recall kiro setup                 # Write Kiro custom agent (.kiro/agents/recall.json); --global for all projects
+claude-recall kiro setup --merge-into <agent>  # Merge Claude Recall into an existing Kiro agent (backup + append-only + idempotent)
 claude-recall upgrade                    # One-shot upgrade: global binary + clear stale MCP servers
 claude-recall status                     # Installation and system status
 claude-recall repair                     # Fix broken claude-recall hook paths (conservative: preserves user customizations)

package/dist/cli/claude-recall-cli.js

@@ -48,6 +48,7 @@ const skill_generator_1 = require("../services/skill-generator");
 const mcp_commands_1 = require("./commands/mcp-commands");
 const project_commands_1 = require("./commands/project-commands");
 const hook_commands_1 = require("./commands/hook-commands");
+const kiro_commands_1 = require("./commands/kiro-commands");
 const repair_1 = require("./commands/repair");
 // v14 = add PreToolUse rule-injector + Post resolver for JITRI.
 // Bump when the hook block template changes — setup skips the settings
@@ -1813,6 +1814,8 @@ async function main() {
     project_commands_1.ProjectCommands.register(program);
     // Hook commands (automatic memory capture)
     hook_commands_1.HookCommands.register(program);
+    // Kiro CLI integration
+    kiro_commands_1.KiroCommands.register(program);
     // Migration commands
     // Search command
     program

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

@@ -50,6 +50,9 @@ const AVAILABLE_HOOKS = [
     'session-end-checkpoint',
     'session-end-checkpoint-worker',
     'bash-failure-watcher',
+    'kiro-agent-spawn',
+    'kiro-rule-injector',
+    'kiro-tool-outcome',
 ];
 /**
  * Hook CLI Commands
@@ -135,6 +138,23 @@ class HookCommands {
                 await handleRuleInjectionResolver(input);
                 break;
             }
+            // Kiro CLI adapters — see src/hooks/kiro-hooks.ts. Kiro's
+            // userPromptSubmit needs no adapter: wire `correction-detector` directly.
+            case 'kiro-agent-spawn': {
+                const { handleKiroAgentSpawn } = await Promise.resolve().then(() => __importStar(require('../../hooks/kiro-hooks')));
+                await handleKiroAgentSpawn(input);
+                break;
+            }
+            case 'kiro-rule-injector': {
+                const { handleKiroRuleInjector } = await Promise.resolve().then(() => __importStar(require('../../hooks/kiro-hooks')));
+                await handleKiroRuleInjector(input);
+                break;
+            }
+            case 'kiro-tool-outcome': {
+                const { handleKiroToolOutcome } = await Promise.resolve().then(() => __importStar(require('../../hooks/kiro-hooks')));
+                await handleKiroToolOutcome(input);
+                break;
+            }
             default:
                 console.error(`Unknown hook: ${name}`);
                 console.error(`Available: ${AVAILABLE_HOOKS.join(', ')}`);
@@ -149,14 +169,16 @@ class HookCommands {
             .description(`Run one or more hook handlers in a single process (${AVAILABLE_HOOKS.slice(0, 3).join(' | ')} | ...)`)
             .action(async (names) => {
             // Read stdin synchronously BEFORE dynamic import to avoid data loss;
-            // every handler receives the same event payload.
+            // every handler receives the same event payload. An empty/unreadable
+            // stdin degrades to {} instead of aborting — lifecycle events with no
+            // payload (e.g. Kiro agentSpawn variants) must still run the handler.
             let input;
             try {
                 input = (0, shared_1.readStdin)();
             }
             catch (err) {
-                (0, shared_1.hookLog)('hook-dispatcher', `stdin read failed: ${(0, shared_1.safeErrorMessage)(err)}`);
-                process.exit(0);
+                (0, shared_1.hookLog)('hook-dispatcher', `stdin read failed (continuing with empty payload): ${(0, shared_1.safeErrorMessage)(err)}`);
+                input = {};
             }
             for (const name of names) {
                 try {

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

@@ -0,0 +1,294 @@
+"use strict";
+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.KiroCommands = void 0;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const repair_1 = require("./repair");
+/**
+ * Kiro CLI integration commands.
+ *
+ * `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
+ * outcome tracking. See src/hooks/kiro-hooks.ts for the adapter details and
+ * kiro.dev/docs/cli/custom-agents for the config format.
+ */
+class KiroCommands {
+    /** The claude-recall mcpServers entry (shared by fresh config and merge). */
+    static buildMcpServerEntry(mcpCommand, mcpArgs) {
+        return {
+            command: mcpCommand,
+            args: mcpArgs,
+            timeout: 120000,
+        };
+    }
+    /** The four lifecycle hook entries (shared by fresh config and 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 },
+            ],
+            // Kiro's userPromptSubmit payload matches correction-detector exactly
+            userPromptSubmit: [
+                { command: `${hookCmd} correction-detector`, timeout_ms: 8000 },
+            ],
+            preToolUse: [
+                { matcher: '*', command: `${hookCmd} kiro-rule-injector`, timeout_ms: 5000 },
+            ],
+            postToolUse: [
+                { matcher: '*', command: `${hookCmd} kiro-tool-outcome`, timeout_ms: 5000 },
+            ],
+        };
+    }
+    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.',
+            // Also load any servers the user configured in .kiro/settings/mcp.json
+            includeMcpJson: true,
+            mcpServers: {
+                'claude-recall': KiroCommands.buildMcpServerEntry(mcpCommand, mcpArgs),
+            },
+            tools: ['*'],
+            allowedTools: [...KiroCommands.ALLOWED_TOOLS],
+            hooks: KiroCommands.buildHookEntries(hookCmd),
+        };
+    }
+    /**
+     * Merge claude-recall into an EXISTING agent config, append-don't-replace:
+     *   - mcpServers.claude-recall added only if absent (never overwrites)
+     *   - allowedTools entries appended, deduplicated
+     *   - hook entries appended per lifecycle array, skipped when an entry for
+     *     the same claude-recall handler is already present (idempotent)
+     *   - an explicit `tools` list (no '*') gains '@claude-recall'
+     * Returns a summary of what changed; mutates `config` in place.
+     */
+    static mergeIntoAgentConfig(config, hookCmd, mcpCommand, mcpArgs) {
+        const changes = [];
+        // mcpServers
+        if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+            config.mcpServers = {};
+        }
+        if (config.mcpServers['claude-recall']) {
+            changes.push('mcpServers.claude-recall: already present — left untouched');
+        }
+        else {
+            config.mcpServers['claude-recall'] = KiroCommands.buildMcpServerEntry(mcpCommand, mcpArgs);
+            changes.push('mcpServers.claude-recall: added');
+        }
+        // allowedTools (dedup append)
+        if (!Array.isArray(config.allowedTools)) {
+            config.allowedTools = [];
+        }
+        const addedTools = KiroCommands.ALLOWED_TOOLS.filter(t => !config.allowedTools.includes(t));
+        config.allowedTools.push(...addedTools);
+        changes.push(addedTools.length > 0
+            ? `allowedTools: added ${addedTools.join(', ')}`
+            : 'allowedTools: already present — nothing added');
+        // tools: only when the agent restricts tools with an explicit list.
+        // '*' or '@claude-recall' already grants access; an absent field is left
+        // alone (the agent's default tool policy governs).
+        if (Array.isArray(config.tools) && !config.tools.includes('*') && !config.tools.includes('@claude-recall')) {
+            config.tools.push('@claude-recall');
+            changes.push('tools: added @claude-recall (explicit tool list detected)');
+        }
+        // hooks (append per lifecycle; skip when our handler is already wired)
+        if (!config.hooks || typeof config.hooks !== 'object') {
+            config.hooks = {};
+        }
+        const handlerMarkers = {
+            agentSpawn: 'kiro-agent-spawn',
+            userPromptSubmit: 'correction-detector',
+            preToolUse: 'kiro-rule-injector',
+            postToolUse: 'kiro-tool-outcome',
+        };
+        for (const [event, entries] of Object.entries(KiroCommands.buildHookEntries(hookCmd))) {
+            if (!Array.isArray(config.hooks[event])) {
+                config.hooks[event] = [];
+            }
+            const marker = handlerMarkers[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`);
+            }
+            else {
+                config.hooks[event].push(...entries);
+                changes.push(`hooks.${event}: added ${marker}`);
+            }
+        }
+        return changes;
+    }
+    /** Resolve hook/MCP command forms (portable PATH form, absolute fallback). */
+    static resolveCommands() {
+        const onPath = (0, repair_1.resolveOnPath)('claude-recall');
+        const cliScript = path.resolve(__dirname, '..', 'claude-recall-cli.js');
+        return {
+            onPath: !!onPath,
+            hookCmd: onPath ? 'claude-recall hook run' : `node ${cliScript} hook run`,
+            mcpCommand: onPath ? 'claude-recall' : 'node',
+            mcpArgs: onPath ? ['mcp', 'start'] : [cliScript, 'mcp', 'start'],
+        };
+    }
+    /**
+     * Merge claude-recall into an existing agent config file. Lookup follows
+     * Kiro's own precedence: workspace .kiro/agents first, then ~/.kiro/agents
+     * (--global restricts to the global directory). Fail-safe: a missing agent
+     * or malformed JSON changes nothing and exits 1; a timestamped backup is
+     * written before any mutation.
+     */
+    static runMergeInto(agentName, options) {
+        const safeName = agentName.replace(/\.json$/, '');
+        const candidates = options.global
+            ? [path.join(os.homedir(), '.kiro', 'agents', `${safeName}.json`)]
+            : [
+                path.join(process.cwd(), '.kiro', 'agents', `${safeName}.json`),
+                path.join(os.homedir(), '.kiro', 'agents', `${safeName}.json`),
+            ];
+        const agentPath = candidates.find(p => fs.existsSync(p));
+        if (!agentPath) {
+            console.error(`❌ Agent "${safeName}" not found. Looked in:`);
+            for (const p of candidates)
+                console.error(`   ${p}`);
+            console.error('   (workspace agents take precedence; use --global to target ~/.kiro/agents only)');
+            process.exit(1);
+        }
+        const raw = fs.readFileSync(agentPath, 'utf8');
+        let config;
+        try {
+            config = JSON.parse(raw);
+        }
+        catch {
+            console.error(`❌ ${agentPath} is not valid JSON — refusing to modify it.`);
+            console.error('   Fix the file (or recreate the agent) and re-run.');
+            process.exit(1);
+            return; // unreachable; satisfies control-flow analysis
+        }
+        const { hookCmd, mcpCommand, mcpArgs, onPath } = KiroCommands.resolveCommands();
+        if (!onPath) {
+            console.log('⚠️  claude-recall not on PATH — merged commands will use absolute paths (breaks if the install moves).');
+        }
+        // Structural change detection — the summary strings are for humans
+        const before = JSON.stringify(config);
+        const changes = KiroCommands.mergeIntoAgentConfig(config, hookCmd, mcpCommand, mcpArgs);
+        const changed = JSON.stringify(config) !== before;
+        if (!changed) {
+            console.log(`✅ ${agentPath} already has Claude Recall fully wired — nothing to do.`);
+            process.exit(0);
+        }
+        const backupPath = `${agentPath}.bak.${new Date().toISOString().replace(/[:.]/g, '-')}`;
+        fs.writeFileSync(backupPath, raw);
+        fs.writeFileSync(agentPath, JSON.stringify(config, null, 2) + '\n');
+        console.log(`✅ Merged Claude Recall into: ${agentPath}`);
+        console.log(`   Backup: ${backupPath}`);
+        console.log('');
+        for (const c of changes)
+            console.log(`   • ${c}`);
+        console.log('');
+        console.log('Kiro hot-reloads agent configs on save — the changes apply to your next');
+        console.log(`interaction with the "${safeName}" agent, no restart needed.`);
+        process.exit(0);
+    }
+    /** Action body, separated from commander wiring so tests can call it directly. */
+    static runSetup(options) {
+        const baseDir = options.global
+            ? path.join(os.homedir(), '.kiro', 'agents')
+            : path.join(process.cwd(), '.kiro', 'agents');
+        const agentPath = path.join(baseDir, 'recall.json');
+        if (fs.existsSync(agentPath) && !options.force) {
+            console.log(`✅ ${agentPath} already exists — leaving it untouched (use --force to overwrite).`);
+            process.exit(0);
+        }
+        // Prefer the portable PATH form; absolute dist path only as fallback
+        // (same policy as Claude Code hook installation — move-proof commands)
+        const { hookCmd, mcpCommand, mcpArgs, onPath } = KiroCommands.resolveCommands();
+        if (!onPath) {
+            console.log('⚠️  claude-recall not on PATH — the agent config will use absolute paths (breaks if the install moves).');
+            console.log('   `npm install -g claude-recall` gives move-proof commands.');
+        }
+        fs.mkdirSync(baseDir, { recursive: true });
+        const config = KiroCommands.buildAgentConfig(hookCmd, mcpCommand, mcpArgs);
+        fs.writeFileSync(agentPath, JSON.stringify(config, null, 2) + '\n');
+        console.log(`✅ Wrote Kiro agent config: ${agentPath}`);
+        console.log('');
+        console.log('No mcp.json changes needed — the agent config carries its own claude-recall');
+        console.log('MCP server entry (and includeMcpJson keeps your other servers working).');
+        console.log('');
+        console.log('1. Start Kiro from your shell:');
+        console.log('');
+        console.log('kiro');
+        console.log('');
+        console.log('2. Inside the Kiro chat, switch to the agent:');
+        console.log('');
+        console.log('/agent swap recall');
+        console.log('');
+        console.log('Rules load into context automatically at agent start; corrections and');
+        console.log('preferences you state are captured; memories are shared with Claude Code');
+        console.log('(same database, same per-project scoping).');
+        console.log('');
+        console.log('Not available under Kiro: transcript-based failure detection and');
+        console.log('session-end checkpoints (Kiro exposes no transcript to hooks).');
+        process.exit(0);
+    }
+    static register(program) {
+        const kiroCmd = program
+            .command('kiro')
+            .description('Kiro CLI integration');
+        kiroCmd
+            .command('setup')
+            .description('Write a Kiro custom agent (.kiro/agents/recall.json) with Claude Recall memory wired in, or merge into an existing agent')
+            .option('--global', 'Target ~/.kiro/agents (all projects) instead of ./.kiro/agents')
+            .option('--force', 'Overwrite an existing recall.json (ignored with --merge-into)')
+            .option('--merge-into <agent>', 'Merge Claude Recall into an existing agent config instead of creating the "recall" agent (backup written first; append-only; idempotent)')
+            .action((options) => {
+            if (options.mergeInto) {
+                KiroCommands.runMergeInto(options.mergeInto, { global: options.global });
+            }
+            else {
+                KiroCommands.runSetup(options);
+            }
+        });
+    }
+}
+exports.KiroCommands = KiroCommands;
+/** Read-only memory tools that run without prompting; store/delete still ask. */
+KiroCommands.ALLOWED_TOOLS = [
+    '@claude-recall/load_rules',
+    '@claude-recall/search_memory',
+    '@claude-recall/load_checkpoint',
+];

package/dist/hooks/kiro-hooks.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Kiro CLI hook adapters.
+ *
+ * Kiro CLI's hook contract (kiro.dev/docs/cli/hooks) is nearly identical to
+ * Claude Code's: hooks receive JSON on stdin with hook_event_name, cwd,
+ * session_id, tool_name, tool_input. These adapters bridge the three
+ * differences:
+ *
+ *   1. Tool names are Kiro-internal (execute_bash, fs_write, fs_read) —
+ *      mapped to the Claude Code names our handlers and the rule ranker
+ *      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).
+ *
+ * userPromptSubmit needs no adapter: Kiro sends { prompt, session_id, cwd },
+ * exactly what correction-detector expects — wire it directly.
+ *
+ * Known v1 gaps (accepted): Kiro provides no tool_use_id, so rule-injection →
+ * outcome correlation is weaker than under Claude Code; the stop event carries
+ * only assistant_response (no transcript file), so transcript-based failure
+ * detectors and session extraction don't run under Kiro.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeKiroInput = normalizeKiroInput;
+exports.handleKiroAgentSpawn = handleKiroAgentSpawn;
+exports.handleKiroRuleInjector = handleKiroRuleInjector;
+exports.handleKiroToolOutcome = handleKiroToolOutcome;
+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 memory_tools_1 = require("../mcp/tools/memory-tools");
+const HOOK_NAME = 'kiro';
+/** Kiro built-in tool names → the Claude Code names our handlers understand. */
+const KIRO_TOOL_NAME_MAP = {
+    execute_bash: 'Bash',
+    shell: 'Bash',
+    fs_write: 'Write',
+    fs_read: 'Read',
+};
+/**
+ * Normalize a Kiro hook payload to the Claude Code shape. Pure and
+ * non-destructive — returns a shallow copy; unknown tool names (use_aws,
+ * @mcp-server tools, ...) pass through unchanged.
+ */
+function normalizeKiroInput(input) {
+    if (!input || typeof input !== 'object')
+        return input;
+    const normalized = { ...input };
+    if (typeof input.tool_name === 'string' && KIRO_TOOL_NAME_MAP[input.tool_name]) {
+        normalized.tool_name = KIRO_TOOL_NAME_MAP[input.tool_name];
+    }
+    // Kiro file tools use `path`; our handlers key on `file_path`
+    if (input.tool_input && typeof input.tool_input === 'object'
+        && typeof input.tool_input.path === 'string' && input.tool_input.file_path === undefined) {
+        normalized.tool_input = { ...input.tool_input, file_path: input.tool_input.path };
+    }
+    // PostToolUse: tool_response (object) → tool_output (string)
+    if (input.tool_response !== undefined && input.tool_output === undefined) {
+        normalized.tool_output = typeof input.tool_response === 'string'
+            ? input.tool_response
+            : JSON.stringify(input.tool_response);
+    }
+    return normalized;
+}
+/** Format active rules as markdown sections (mirrors the Pi extension). */
+function formatRulesForContext() {
+    const projectId = config_1.ConfigService.getInstance().getProjectId();
+    const rules = memory_1.MemoryService.getInstance().loadActiveRules(projectId);
+    const section = (title, items) => {
+        if (items.length === 0)
+            return null;
+        return `## ${title}\n` + items.map(m => `- ${(0, memory_tools_1.formatRuleValue)(m.value)}`).join('\n');
+    };
+    const sections = [
+        section('Preferences', rules.preferences),
+        section('Corrections', rules.corrections),
+        section('Failures', rules.failures),
+        section('DevOps Rules', rules.devops),
+    ].filter((s) => s !== null);
+    const total = rules.preferences.length + rules.corrections.length
+        + rules.failures.length + rules.devops.length;
+    return { body: sections.join('\n\n'), total };
+}
+/**
+ * agentSpawn — runs once when a Kiro agent activates. Whatever we print is
+ * added to the agent's context, so this IS the load_rules call: rules are in
+ * context from turn one without any tool call or enforcement.
+ */
+async function handleKiroAgentSpawn(_input) {
+    try {
+        const { body, total } = formatRulesForContext();
+        const parts = [];
+        if (body) {
+            parts.push(directives_1.LOAD_RULES_DIRECTIVE, '---', body);
+        }
+        // Surface a pending task checkpoint the same way load_rules hints at one
+        try {
+            const projectId = config_1.ConfigService.getInstance().getProjectId();
+            const checkpoint = memory_1.MemoryService.getInstance().loadCheckpoint(projectId);
+            if (checkpoint) {
+                parts.push(`📌 A task checkpoint exists for this project (updated ${new Date(checkpoint.updated_at).toLocaleString()}). ` +
+                    `Remaining: ${checkpoint.remaining.substring(0, 200)}`);
+            }
+        }
+        catch { /* checkpoint hint is best-effort */ }
+        if (parts.length === 0) {
+            (0, shared_1.hookLog)(HOOK_NAME, 'agentSpawn: no active rules or checkpoint — nothing injected');
+            return;
+        }
+        process.stdout.write(parts.join('\n\n') + '\n');
+        (0, shared_1.hookLog)(HOOK_NAME, `agentSpawn: injected ${total} rule(s) into Kiro context`);
+    }
+    catch (err) {
+        // Never block agent startup
+        (0, shared_1.hookLog)(HOOK_NAME, `agentSpawn error: ${(0, shared_1.safeErrorMessage)(err)}`);
+    }
+}
+/**
+ * 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).
+ */
+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)}`);
+    }
+}
+/**
+ * postToolUse — outcome capture and Bash fix-pairing, delegated to the shared
+ * tool-outcome-watcher after payload normalization.
+ */
+async function handleKiroToolOutcome(input) {
+    try {
+        await (0, tool_outcome_watcher_1.handleToolOutcomeWatcher)(normalizeKiroInput(input));
+    }
+    catch (err) {
+        (0, shared_1.hookLog)(HOOK_NAME, `tool-outcome error: ${(0, shared_1.safeErrorMessage)(err)}`);
+    }
+}

package/dist/hooks/rule-injector.js

@@ -25,6 +25,7 @@
  * citation-detection regex.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeInjection = computeInjection;
 exports.handleRuleInjector = handleRuleInjector;
 const shared_1 = require("./shared");
 const memory_1 = require("../services/memory");
@@ -80,72 +81,79 @@ function formatInjection(matches, toolName) {
         `but defer to safety and correctness if any conflict.\n${lines.join('\n')}\n` +
         `</recalled-memory>`);
 }
-async function handleRuleInjector(input) {
-    const toolName = input?.tool_name ?? '';
-    const toolInput = input?.tool_input ?? {};
-    const toolUseId = input?.tool_use_id ?? '';
-    if (!toolName) {
-        // Nothing to do — print empty JSON so CC parses it cleanly
-        process.stdout.write('{}\n');
-        return;
-    }
+/**
+ * Runtime-agnostic core: rank active rules against this tool call, record
+ * the injections for outcome resolution, and return the formatted context
+ * block — or null when there is nothing to inject. Emitters wrap this per
+ * runtime (Claude Code wants a hookSpecificOutput JSON envelope; Kiro adds
+ * raw stdout to context).
+ */
+async function computeInjection(toolName, toolInput, toolUseId) {
+    if (!toolName)
+        return null;
     // Skip the hook for our own tools so we don't recursively inject rules
     // about claude-recall into claude-recall calls. The agent already has
     // claude-recall context when calling its own tools.
     if (toolName.startsWith('mcp__claude-recall__') || toolName.startsWith('mcp__claude_recall')) {
-        process.stdout.write('{}\n');
-        return;
+        return null;
+    }
+    const projectId = config_1.ConfigService.getInstance().getProjectId();
+    const memoryService = memory_1.MemoryService.getInstance();
+    // Fetch all active rules for this project. We pass them all to the ranker
+    // because the ranking function is fast and we want sticky rules to surface
+    // even when token overlap is low.
+    const activeRules = memoryService.loadActiveRules(projectId);
+    const allRules = [
+        ...activeRules.preferences,
+        ...activeRules.corrections,
+        ...activeRules.failures,
+        ...activeRules.devops,
+    ].map(m => ({
+        key: m.key,
+        type: m.type,
+        value: m.value,
+        is_active: m.is_active !== false,
+        timestamp: m.timestamp,
+        project_id: m.project_id,
+    }));
+    if (allRules.length === 0) {
+        (0, shared_1.hookLog)('rule-injector', `No active rules for project ${projectId} (tool=${toolName})`);
+        return null;
+    }
+    const matches = (0, rule_retrieval_1.rankRulesForToolCall)(toolName, toolInput, allRules);
+    if (matches.length === 0) {
+        (0, shared_1.hookLog)('rule-injector', `No relevant rules for ${toolName} (scanned ${allRules.length})`);
+        return null;
     }
+    // Record each injection so PostToolUse can resolve it with the outcome
     try {
-        const projectId = config_1.ConfigService.getInstance().getProjectId();
-        const memoryService = memory_1.MemoryService.getInstance();
-        // Fetch all active rules for this project. We pass them all to the ranker
-        // because the ranking function is fast and we want sticky rules to surface
-        // even when token overlap is low.
-        const activeRules = memoryService.loadActiveRules(projectId);
-        const allRules = [
-            ...activeRules.preferences,
-            ...activeRules.corrections,
-            ...activeRules.failures,
-            ...activeRules.devops,
-        ].map(m => ({
-            key: m.key,
-            type: m.type,
-            value: m.value,
-            is_active: m.is_active !== false,
-            timestamp: m.timestamp,
-            project_id: m.project_id,
-        }));
-        if (allRules.length === 0) {
-            (0, shared_1.hookLog)('rule-injector', `No active rules for project ${projectId} (tool=${toolName})`);
-            process.stdout.write('{}\n');
-            return;
+        const outcomeStorage = outcome_storage_1.OutcomeStorage.getInstance();
+        for (const m of matches) {
+            outcomeStorage.recordRuleInjection({
+                rule_key: m.rule.key,
+                tool_name: toolName,
+                tool_use_id: toolUseId,
+                project_id: projectId,
+                match_score: m.score,
+                matched_tokens: m.matchedTokens,
+            });
         }
-        const matches = (0, rule_retrieval_1.rankRulesForToolCall)(toolName, toolInput, allRules);
-        if (matches.length === 0) {
-            (0, shared_1.hookLog)('rule-injector', `No relevant rules for ${toolName} (scanned ${allRules.length})`);
+    }
+    catch (err) {
+        // Non-critical — failure to record shouldn't block the injection itself
+        (0, shared_1.hookLog)('rule-injector', `Failed to record injections: ${err.message}`);
+    }
+    (0, shared_1.hookLog)('rule-injector', `Injected ${matches.length} rule(s) for ${toolName} (top score=${matches[0].score.toFixed(3)})`);
+    return formatInjection(matches, toolName);
+}
+async function handleRuleInjector(input) {
+    try {
+        const additionalContext = await computeInjection(input?.tool_name ?? '', input?.tool_input ?? {}, input?.tool_use_id ?? '');
+        if (!additionalContext) {
+            // Nothing to inject — print empty JSON so CC parses it cleanly
             process.stdout.write('{}\n');
             return;
         }
-        // Record each injection so PostToolUse can resolve it with the outcome
-        try {
-            const outcomeStorage = outcome_storage_1.OutcomeStorage.getInstance();
-            for (const m of matches) {
-                outcomeStorage.recordRuleInjection({
-                    rule_key: m.rule.key,
-                    tool_name: toolName,
-                    tool_use_id: toolUseId,
-                    project_id: projectId,
-                    match_score: m.score,
-                    matched_tokens: m.matchedTokens,
-                });
-            }
-        }
-        catch (err) {
-            // Non-critical — failure to record shouldn't block the injection itself
-            (0, shared_1.hookLog)('rule-injector', `Failed to record injections: ${err.message}`);
-        }
-        const additionalContext = formatInjection(matches, toolName);
         const output = {
             hookSpecificOutput: {
                 hookEventName: 'PreToolUse',
@@ -153,7 +161,6 @@ async function handleRuleInjector(input) {
             },
         };
         process.stdout.write(JSON.stringify(output) + '\n');
-        (0, shared_1.hookLog)('rule-injector', `Injected ${matches.length} rule(s) for ${toolName} (top score=${matches[0].score.toFixed(3)})`);
     }
     catch (err) {
         (0, shared_1.hookLog)('rule-injector', `Error: ${err.message}`);

package/package.json

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