claude-recall 0.28.0 → 0.28.2

package/README.md

@@ -71,7 +71,7 @@ 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.
+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.**
 
@@ -97,6 +97,18 @@ and inside the Kiro chat, switch to the agent:
 
 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.
+
+> **⚠️ Restart Kiro after `kiro setup` or `--merge-into`.** Hooks bind when an agent *activates* — a Kiro session that was already running keeps its old wiring and will behave as if it has no memory. Exit Kiro and start it again (or `/agent swap` away and back). Verify hooks are firing with `tail ~/.claude-recall/hook-logs/kiro.log`.
+
+> **Tip:** export `ANTHROPIC_API_KEY` in the shell you launch Kiro from. Hooks then use Claude Haiku to classify what's worth remembering; without it a conservative regex fallback runs, which catches explicit phrasings ("remember ...", "always ...", "never ...", "I prefer ...") but misses subtler ones.
+
 **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):
@@ -144,7 +156,13 @@ Per-runtime notes:
 > 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`.
+> **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>
@@ -338,6 +356,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
@@ -379,6 +402,7 @@ claude-recall mcp cleanup --all          # Stop all stale MCP servers
 claude-recall setup                      # Show activation instructions
 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/commands/kiro-commands.js

@@ -49,6 +49,33 @@ const repair_1 = require("./repair");
  * 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',
@@ -56,36 +83,146 @@ class KiroCommands {
             // Also load any servers the user configured in .kiro/settings/mcp.json
             includeMcpJson: true,
             mcpServers: {
-                'claude-recall': {
-                    command: mcpCommand,
-                    args: mcpArgs,
-                    timeout: 120000,
-                },
+                'claude-recall': KiroCommands.buildMcpServerEntry(mcpCommand, mcpArgs),
             },
             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 },
-                ],
-            },
+            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) {
@@ -99,11 +236,7 @@ class KiroCommands {
         }
         // 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'];
+        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.');
@@ -138,12 +271,24 @@ class KiroCommands {
             .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')
+            .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) => {
-            KiroCommands.runSetup(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

@@ -90,17 +90,37 @@ function formatRulesForContext() {
         + rules.failures.length + rules.devops.length;
     return { body: sections.join('\n\n'), total };
 }
+/**
+ * Standing instruction so the agent KNOWS it has persistent memory. Without
+ * this, a session with no stored rules yet answers "I have no memory between
+ * conversations" and never calls store_memory when the user says
+ * "remember ..." — the exact failure observed on first use.
+ */
+const KIRO_MEMORY_DIRECTIVE = 'You have PERSISTENT MEMORY across sessions via Claude Recall (MCP server "claude-recall": ' +
+    'load_rules, store_memory, search_memory, delete_memory, save_checkpoint, load_checkpoint). ' +
+    'When the user says "remember ...", "store this", "recall ...", states a preference, or corrects you, ' +
+    'call store_memory (tell them what you will store). Use search_memory before decisions when past ' +
+    'context might apply. Memories are scoped per project and shared with the user\'s other coding agents.';
 /**
  * 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.
+ * context from turn one without any tool call or enforcement. The memory
+ * directive is always emitted, even with an empty database — capability
+ * awareness must not depend on having memories already.
  */
 async function handleKiroAgentSpawn(_input) {
     try {
-        const { body, total } = formatRulesForContext();
-        const parts = [];
-        if (body) {
-            parts.push(directives_1.LOAD_RULES_DIRECTIVE, '---', body);
+        const parts = [KIRO_MEMORY_DIRECTIVE];
+        let total = 0;
+        try {
+            const rules = formatRulesForContext();
+            total = rules.total;
+            if (rules.body) {
+                parts.push(directives_1.LOAD_RULES_DIRECTIVE, '---', rules.body);
+            }
+        }
+        catch (err) {
+            (0, shared_1.hookLog)(HOOK_NAME, `agentSpawn rule load failed (directive still emitted): ${(0, shared_1.safeErrorMessage)(err)}`);
         }
         // Surface a pending task checkpoint the same way load_rules hints at one
         try {
@@ -112,12 +132,8 @@ async function handleKiroAgentSpawn(_input) {
             }
         }
         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`);
+        (0, shared_1.hookLog)(HOOK_NAME, `agentSpawn: injected memory directive + ${total} rule(s) into Kiro context`);
     }
     catch (err) {
         // Never block agent startup

package/dist/hooks/shared.js

@@ -73,7 +73,11 @@ const CORRECTION_PATTERNS = [
     { regex: /\bstop\s+(doing|using|adding)\s+(.+)/i, confidence: 0.75 },
 ];
 const PREFERENCE_PATTERNS = [
-    { regex: /\bremember\s+(?:that|this|to)\s+(.+)/i, confidence: 0.8 },
+    // "remember ..." is an explicit store request in any phrasing — "remember
+    // that X", "remember to X", but also "remember my favourite color is green".
+    // The interrogative/question-mark guards below keep "do you remember that
+    // config file?" out.
+    { regex: /\bremember\s+(?:that\s+|this\s+|to\s+)?(.+)/i, confidence: 0.8 },
     { regex: /\bfrom\s+now\s+on[,.]?\s+(.+)/i, confidence: 0.8 },
     { regex: /\bgoing\s+forward[,.]?\s+(.+)/i, confidence: 0.8 },
     { regex: /\balways\s+(.+)/i, confidence: 0.75 },

package/package.json

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