claude-recall 0.27.0 → 0.28.0

package/.claude/skills/memory-management/SKILL.md

@@ -131,9 +131,9 @@ memories to form a skill (3+ for most types, 5+ for preferences). If so, it writ
 a SKILL.md file that Claude Code loads automatically.
 
 **CLI commands:**
-- `npx claude-recall skills list` — see generated skills
-- `npx claude-recall skills generate --force` — force regeneration
-- `npx claude-recall skills clean --force` — remove all auto-generated skills
+- `claude-recall skills list` — see generated skills
+- `claude-recall skills generate --force` — force regeneration
+- `claude-recall skills clean --force` — remove all auto-generated skills
 
 ## Automatic Capture Hooks
 
@@ -158,7 +158,7 @@ Claude Recall registers hooks on six Claude Code events for automatic capture, j
 - Auto-checkpoint quality gate: refuses to save when the LLM detects the task was already complete — manual checkpoints stay sticky
 - Always exits 0 — hooks never block Claude
 
-**Setup:** Run `npx claude-recall setup --install` to register hooks in `.claude/settings.json`. After any upgrade, re-run `setup --install` in each project so newly-added hook events get registered (claude-recall uses a `hooksVersion` field to signal when registration has changed).
+**Setup:** Run `claude-recall setup --install` to register hooks in `.claude/settings.json`. After an upgrade whose release notes mention new or changed hooks (a `hooksVersion` bump), re-run it in each active project — it's idempotent, so when hooks are already current it's a no-op and touches nothing.
 
 ## Example Workflows
 

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**.
 
@@ -49,6 +49,16 @@ claude mcp add claude-recall -- claude-recall mcp start
 
 Restart Claude Code. Ask *"Load my rules"* to verify — Claude should call `load_rules`.
 
+Prefer it active in **every** project? Register the MCP server once at user scope instead of per project (memories stay isolated per project either way — scoping comes from the working directory, not the install):
+
+```bash
+claude mcp add --scope user claude-recall -- claude-recall mcp start
+```
+
+Hook-based auto-capture remains a per-project opt-in via `claude-recall setup --install` (it writes to that project's `.claude/settings.json`).
+
+> **Do NOT add claude-recall as a project dependency** (`npm install claude-recall` inside a project). All projects share one database at `~/.claude-recall/` and whatever binary touches it runs schema migrations — multiple project-local copies at different versions fight over the same file. Worse, `npx claude-recall` prefers a project-local copy over your up-to-date global one, so a stale local install silently shadows every upgrade. One global binary; per-project *activation* only.
+
 > **Hit `EACCES: permission denied`?** Your global npm is owned by root. Either `sudo npm install -g claude-recall` once, or do the permanent fix described in [Upgrading](#upgrading) below.
 
 ### Install for Pi
@@ -59,19 +69,80 @@ pi install npm:claude-recall
 
 That's it. Ask Pi to *"Load my rules"* to verify.
 
+### Install for Kiro CLI
+
+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.
+
+**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:
+
+- **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.
 
-For Pi, run `pi update npm:claude-recall` and restart Pi.
+> **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
+> ```
 
 > **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`.
 
@@ -109,19 +180,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.
 
@@ -306,7 +377,8 @@ 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 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
@@ -943,7 +944,7 @@ class ClaudeRecallCLI {
         else if (!hasPi) {
             console.log('Claude Code MCP:');
             console.log('  Status: Not registered');
-            console.log('  Command: claude mcp add claude-recall claude-recall mcp start');
+            console.log('  Command: claude mcp add claude-recall -- claude-recall mcp start');
         }
         else {
             // Pi is present; show Claude Code MCP as optional
@@ -1339,24 +1340,32 @@ async function main() {
             installSkillsAndHook();
         }
         else {
-            // Show activation instructions
+            // Show activation instructions. Registration uses the global
+            // `claude-recall` binary, NOT `npx ... @latest`: npx resolves through
+            // any stale project-local install (shadow trap) and @latest hits the
+            // registry on every server spawn. Consecutive commands are printed
+            // flush-left as one contiguous block so they can be copy-pasted in
+            // one go.
             console.log('\n✅ Claude Recall Setup\n');
             console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-            console.log('📌 ACTIVATE CLAUDE RECALL:');
+            console.log('📌 ACTIVATE CLAUDE RECALL (run in each project):');
             console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
             console.log('');
-            console.log('  claude mcp add claude-recall -- npx -y claude-recall@latest mcp start');
+            console.log('claude-recall setup --install');
+            console.log('claude mcp add claude-recall -- claude-recall mcp start');
             console.log('');
             console.log('  Then restart Claude Code (exit and re-enter the session).');
             console.log('');
             console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
             console.log('');
-            console.log('🔄 Already registered? Remove and re-add:');
-            console.log('  claude mcp remove claude-recall');
-            console.log('  claude mcp add claude-recall -- npx -y claude-recall@latest mcp start');
+            console.log('🔄 Registered under an old npx-based command? Remove and re-add:');
             console.log('');
-            console.log('🛑 Stop old instance:');
-            console.log('  npx claude-recall mcp stop');
+            console.log('claude mcp remove claude-recall');
+            console.log('claude mcp add claude-recall -- claude-recall mcp start');
+            console.log('');
+            console.log('🛑 Stop a running old instance:');
+            console.log('');
+            console.log('claude-recall mcp stop');
             console.log('');
         }
         process.exit(0);
@@ -1428,7 +1437,7 @@ async function main() {
         }
         if (!settingsPath) {
             console.log('❌ No .claude/settings.json found in directory tree');
-            console.log('   Run: npx claude-recall repair\n');
+            console.log('   Run: claude-recall repair\n');
             return;
         }
         console.log(`✅ Found settings: ${settingsPath}`);
@@ -1485,7 +1494,7 @@ async function main() {
             }
         }
         if (hasIssues) {
-            console.log('\n⚠️  Issues found. Run: npx claude-recall repair\n');
+            console.log('\n⚠️  Issues found. Run: claude-recall repair\n');
         }
         else {
             console.log('\n✅ All hooks OK!\n');
@@ -1516,7 +1525,7 @@ async function main() {
         }
         if (!enforcerPath) {
             console.log('❌ Could not find search_enforcer.py');
-            console.log('   Run: npx claude-recall repair\n');
+            console.log('   Run: claude-recall repair\n');
             return;
         }
         console.log(`📍 Enforcer: ${enforcerPath}`);
@@ -1600,7 +1609,7 @@ async function main() {
         }
         else {
             console.log('❌ Some tests failed. Check hook configuration.\n');
-            console.log('Run: npx claude-recall repair\n');
+            console.log('Run: claude-recall repair\n');
         }
     }
     // Hooks command group
@@ -1700,7 +1709,7 @@ async function main() {
         console.log('\n📋 Auto-Generated Skills\n');
         if (skills.length === 0) {
             console.log('No auto-generated skills found.\n');
-            console.log('Run `npx claude-recall skills generate` to create skills from memories.\n');
+            console.log('Run `claude-recall skills generate` to create skills from memories.\n');
         }
         else {
             for (const skill of skills) {
@@ -1805,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,149 @@
+"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 {
+    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': {
+                    command: mcpCommand,
+                    args: mcpArgs,
+                    timeout: 120000,
+                },
+            },
+            tools: ['*'],
+            // Read-only memory tools run without prompting; store/delete still ask
+            allowedTools: [
+                '@claude-recall/load_rules',
+                '@claude-recall/search_memory',
+                '@claude-recall/load_checkpoint',
+            ],
+            hooks: {
+                // 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 },
+                ],
+            },
+        };
+    }
+    /** 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 onPath = (0, repair_1.resolveOnPath)('claude-recall');
+        const cliScript = path.resolve(__dirname, '..', 'claude-recall-cli.js');
+        const hookCmd = onPath ? 'claude-recall hook run' : `node ${cliScript} hook run`;
+        const mcpCommand = onPath ? 'claude-recall' : 'node';
+        const mcpArgs = onPath ? ['mcp', 'start'] : [cliScript, 'mcp', 'start'];
+        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')
+            .option('--global', 'Write to ~/.kiro/agents (all projects) instead of ./.kiro/agents')
+            .option('--force', 'Overwrite an existing recall.json')
+            .action((options) => {
+            KiroCommands.runSetup(options);
+        });
+    }
+}
+exports.KiroCommands = KiroCommands;

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

@@ -102,7 +102,7 @@ class MCPCommands {
         else {
             console.log();
             console.log(chalk_1.default.yellow('⚠ Project not registered in registry'));
-            console.log(chalk_1.default.gray('  Run `npx claude-recall project register` to register'));
+            console.log(chalk_1.default.gray('  Run `claude-recall project register` to register'));
         }
         console.log();
     }
@@ -135,7 +135,7 @@ class MCPCommands {
                 console.log(`  ${chalk_1.default.gray(server.projectId.padEnd(40))} PID: ${chalk_1.default.gray(server.pid)} (not running)`);
             }
             console.log();
-            console.log(chalk_1.default.yellow(`💡 Run 'npx claude-recall mcp cleanup' to remove stale PID files`));
+            console.log(chalk_1.default.yellow(`💡 Run 'claude-recall mcp cleanup' to remove stale PID files`));
             console.log();
         }
         // Show registered projects that don't have running servers
@@ -147,7 +147,7 @@ class MCPCommands {
                 console.log(`  ${chalk_1.default.gray(projectId.padEnd(40))} v${entry.version}`);
             }
             console.log();
-            console.log(chalk_1.default.gray(`💡 Run 'npx claude-recall project list' for detailed registry info`));
+            console.log(chalk_1.default.gray(`💡 Run 'claude-recall project list' for detailed registry info`));
             console.log();
         }
     }
@@ -214,7 +214,7 @@ class MCPCommands {
             await new Promise(resolve => setTimeout(resolve, 2000));
         }
         console.log('\nTo start the server, run:');
-        console.log(chalk_1.default.cyan('  npx claude-recall mcp start'));
+        console.log(chalk_1.default.cyan('  claude-recall mcp start'));
         console.log();
         console.log(chalk_1.default.gray('Note: The MCP server is normally started automatically by Claude Code.'));
         console.log(chalk_1.default.gray('      You only need to run this manually for debugging purposes.'));

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

@@ -189,7 +189,7 @@ class ProjectCommands {
         if (projects.length === 0) {
             console.log(chalk_1.default.gray('No projects registered.'));
             console.log();
-            console.log(chalk_1.default.yellow('💡 Run `npx claude-recall project register` to register the current project'));
+            console.log(chalk_1.default.yellow('💡 Run `claude-recall project register` to register the current project'));
             console.log();
             return;
         }
@@ -226,7 +226,7 @@ class ProjectCommands {
         if (!entry) {
             console.log(chalk_1.default.yellow(`⚠ Project not found: ${targetProjectId}`));
             console.log();
-            console.log(chalk_1.default.gray('Run `npx claude-recall project list` to see registered projects'));
+            console.log(chalk_1.default.gray('Run `claude-recall project list` to see registered projects'));
             console.log();
             return;
         }

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.0",
+  "version": "0.28.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": {

package/scripts/postinstall.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-console.log('\n🚀 Setting up Claude Recall v0.9.x...\n');
+console.log('\n🚀 Setting up Claude Recall...\n');
 
 const { execSync } = require('child_process');
 
@@ -53,22 +53,20 @@ try {
     console.log(`📁 Created database directory: ${dbDir}`);
   }
 
-  // Register MCP server using official Claude CLI
-  try {
-    try {
-      execSync('claude mcp remove claude-recall', { stdio: 'ignore' });
-    } catch (e) {
-      // Ignore if not registered
-    }
-
-    execSync('claude mcp add claude-recall -- npx claude-recall mcp start', {
-      stdio: 'inherit'
-    });
-    console.log('✅ Registered Claude Recall MCP server');
-  } catch (mcpError) {
-    console.log('⚠️  Could not auto-register MCP server.');
-    console.log('   Run manually: claude mcp add claude-recall -- npx claude-recall mcp start');
-  }
+  // MCP registration: instructions only, no auto-registration.
+  //
+  // Earlier versions ran `claude mcp remove` + `claude mcp add ... npx ...`
+  // here on EVERY install/upgrade. That was wrong three ways:
+  //   • it silently REPLACED whatever registration the user had — including
+  //     the correct `claude-recall mcp start` form the README recommends —
+  //     with an npx-based one (registry lookup per server spawn, and npx
+  //     resolves through stale project-local installs);
+  //   • `claude mcp add` registers at LOCAL scope for whatever cwd npm
+  //     happened to run postinstall in — for `npm install -g` that is not
+  //     the user's project at all;
+  //   • a postinstall mutating user configuration unprompted is the same
+  //     overreach class the 0.24.0 audit fixes removed for hooks.
+  // Registration is now a conscious per-project step (printed below).
 
   // Auto-register project
   try {
@@ -112,10 +110,10 @@ try {
   // unrelated PreToolUse hooks). When `npm install -g` was run from $HOME it
   // even clobbered the user's GLOBAL Claude Code settings at ~/.claude/settings.json.
   //
-  // The MCP registration above is enough for memory tools to work. Hook-based
-  // auto-capture and search enforcement now require an explicit
-  // `claude-recall setup` invocation by the user, which is conscious and
-  // produces a diff the user can see.
+  // MCP registration (instructions printed below) is enough for memory tools
+  // to work. Hook-based auto-capture and search enforcement require an
+  // explicit `claude-recall setup --install` invocation by the user, which is
+  // conscious and produces a diff the user can see.
 
   // Conservative repair on upgrade: fix broken absolute hook paths in
   // ~/.claude/settings.json AND every project's .claude/settings.json under
@@ -146,25 +144,27 @@ try {
 
   console.log('\n✅ Installation complete!\n');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  console.log('📌 ACTIVATE CLAUDE RECALL:');
+  console.log('📌 ACTIVATE CLAUDE RECALL — run in each project where you want it:');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   console.log('');
-  console.log('  1. Register the MCP server (if the auto-register above failed):');
-  console.log('       claude mcp add claude-recall -- npx -y claude-recall@latest mcp start');
-  console.log('');
-  console.log('  2. (Optional) Enable hook-based auto-capture and search enforcement');
-  console.log('     in the CURRENT project. This writes to .claude/settings.json — review');
-  console.log('     the diff before committing:');
-  console.log('       npx claude-recall setup');
+  // Contiguous flush-left block: both commands copy-paste in one go
+  console.log('claude-recall setup --install');
+  console.log('claude mcp add claude-recall -- claude-recall mcp start');
   console.log('');
   console.log('  Then restart Claude Code.');
   console.log('');
+  console.log('  (`setup --install` writes hooks/skills to .claude/settings.json —');
+  console.log('   review the diff before committing. Idempotent: re-runs are no-ops');
+  console.log('   when already current.)');
+  console.log('');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   console.log('');
   console.log('💡 Your memories persist across conversations and restarts.\n');
 
 } catch (error) {
   console.error('❌ Error during setup:', error.message);
-  console.log('\nPlease run manually:');
-  console.log('  claude mcp add claude-recall -- npx claude-recall mcp start');
+  console.log('\nActivate manually in each project:');
+  console.log('');
+  console.log('claude-recall setup --install');
+  console.log('claude mcp add claude-recall -- claude-recall mcp start');
 }