claude-recall 0.28.1 → 0.28.3

package/README.md

@@ -105,6 +105,10 @@ 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):

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

@@ -265,10 +265,165 @@ class KiroCommands {
         console.log('session-end checkpoints (Kiro exposes no transcript to hooks).');
         process.exit(0);
     }
+    /**
+     * Read a Kiro agent config and report whether claude-recall is wired
+     * (MCP server + which lifecycle hooks). Returns null if the file is missing
+     * or unparseable.
+     */
+    static inspectAgent(agentPath) {
+        let config;
+        try {
+            config = JSON.parse(fs.readFileSync(agentPath, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+        const mcp = !!(config.mcpServers && config.mcpServers['claude-recall']);
+        const hooks = [];
+        if (config.hooks && typeof config.hooks === 'object') {
+            for (const [event, entries] of Object.entries(config.hooks)) {
+                if (Array.isArray(entries) && entries.some((h) => typeof h?.command === 'string' && h.command.includes('claude-recall'))) {
+                    hooks.push(event);
+                }
+            }
+        }
+        return { name: config.name || path.basename(agentPath, '.json'), mcp, hooks };
+    }
+    /** Last non-empty line of a hook log + how long ago, or null if none. */
+    static lastLogLine(logPath) {
+        try {
+            const lines = fs.readFileSync(logPath, 'utf8').split('\n').filter(l => l.trim());
+            if (lines.length === 0)
+                return null;
+            const line = lines[lines.length - 1];
+            const m = line.match(/^\[([^\]]+)\]/);
+            let ageMs = null;
+            if (m) {
+                const t = Date.parse(m[1]);
+                if (!Number.isNaN(t))
+                    ageMs = Date.now() - t;
+            }
+            return { line, ageMs };
+        }
+        catch {
+            return null;
+        }
+    }
+    static fmtAge(ageMs) {
+        if (ageMs === null)
+            return '';
+        const min = Math.round(ageMs / 60000);
+        if (min < 1)
+            return ' (just now)';
+        if (min < 60)
+            return ` (${min}m ago)`;
+        const h = Math.round(min / 60);
+        if (h < 48)
+            return ` (${h}h ago)`;
+        return ` (${Math.round(h / 24)}d ago)`;
+    }
+    /**
+     * `claude-recall kiro doctor` — read-only diagnostic. Answers the questions
+     * that otherwise take a support round-trip: is the binary current and on
+     * PATH, is a key available for LLM capture, does the DB have memories, which
+     * Kiro agents have claude-recall wired, and are the hooks actually firing.
+     */
+    static runDoctor() {
+        const line = (marker, text) => console.log(`  ${marker} ${text}`);
+        console.log('\n🩺 Claude Recall — Kiro diagnostic\n');
+        // --- Install ---
+        console.log('Install');
+        let version = 'unknown';
+        try {
+            version = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', '..', '..', 'package.json'), 'utf8')).version;
+        }
+        catch { /* leave unknown */ }
+        line('•', `version: ${version}`);
+        const onPath = (0, repair_1.resolveOnPath)('claude-recall');
+        line(onPath ? '✓' : '⚠', onPath
+            ? `on PATH: ${onPath}`
+            : 'not on PATH — hooks/agent commands will use absolute paths (break if the install moves)');
+        line(process.env.ANTHROPIC_API_KEY ? '✓' : '•', process.env.ANTHROPIC_API_KEY
+            ? 'ANTHROPIC_API_KEY set — hooks use Claude Haiku for classification'
+            : 'ANTHROPIC_API_KEY not set — hooks use the regex fallback (explicit "remember/recall/always/never/I prefer …" still captured)');
+        // --- Database ---
+        console.log('\nDatabase (this project)');
+        try {
+            // Lazy require so a broken DB can't stop the earlier sections printing
+            const { MemoryService } = require('../../services/memory');
+            const { ConfigService } = require('../../services/config');
+            const ms = MemoryService.getInstance();
+            const projectId = ConfigService.getInstance().getProjectId();
+            const stats = ms.getStats();
+            line('✓', `project: ${projectId}`);
+            line('•', `total memories (all projects): ${stats.total}`);
+            const rules = ms.loadActiveRules(projectId);
+            const ruleCount = rules.preferences.length + rules.corrections.length + rules.failures.length + rules.devops.length;
+            line(ruleCount > 0 ? '✓' : '•', `active rules for this project: ${ruleCount}`);
+        }
+        catch (err) {
+            line('⚠', `could not open database: ${err.message}`);
+        }
+        // --- Kiro agents ---
+        console.log('\nKiro agents with Claude Recall wired');
+        const agentDirs = [
+            { label: 'workspace', dir: path.join(process.cwd(), '.kiro', 'agents') },
+            { label: 'global', dir: path.join(os.homedir(), '.kiro', 'agents') },
+        ];
+        let anyWired = false;
+        for (const { label, dir } of agentDirs) {
+            if (!fs.existsSync(dir))
+                continue;
+            const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+            for (const f of files) {
+                const info = KiroCommands.inspectAgent(path.join(dir, f));
+                if (!info || (!info.mcp && info.hooks.length === 0))
+                    continue;
+                anyWired = true;
+                const bits = [
+                    info.mcp ? 'MCP' : null,
+                    info.hooks.length ? `hooks: ${info.hooks.join(', ')}` : null,
+                ].filter(Boolean).join(' | ');
+                line('✓', `${info.name} (${label}) — ${bits}`);
+            }
+        }
+        if (!anyWired) {
+            line('⚠', 'none found. Run `claude-recall kiro setup` (new agent) or');
+            line(' ', '        `claude-recall kiro setup --merge-into <agent>` (existing agent).');
+        }
+        // --- Hook activity ---
+        console.log('\nRecent hook activity');
+        const dir = process.env.CLAUDE_RECALL_DB_PATH || path.join(os.homedir(), '.claude-recall');
+        const logDir = path.join(dir, 'hook-logs');
+        const kiro = KiroCommands.lastLogLine(path.join(logDir, 'kiro.log'));
+        const cd = KiroCommands.lastLogLine(path.join(logDir, 'correction-detector.log'));
+        if (kiro) {
+            line('✓', `kiro hooks last ran${KiroCommands.fmtAge(kiro.ageMs)}: ${kiro.line.replace(/^\[[^\]]+\]\s*/, '')}`);
+        }
+        else {
+            line('⚠', 'no kiro.log — Kiro hooks have never fired. After `kiro setup`/`--merge-into`, RESTART Kiro (hooks bind at agent activation).');
+        }
+        if (cd) {
+            line('✓', `capture hook last ran${KiroCommands.fmtAge(cd.ageMs)}: ${cd.line.replace(/^\[[^\]]+\]\s*/, '')}`);
+        }
+        // --- Governance note ---
+        console.log('\nNotes');
+        line('•', 'If Kiro\'s startup banner omits "claude-recall" from loaded servers, your org likely');
+        line(' ', '  restricts MCP to a trusted registry. Hooks still work (capture + injection go straight');
+        line(' ', '  to the local DB) — only the interactive MCP tools need an admin to allowlist claude-recall.');
+        console.log('');
+        process.exit(0);
+    }
     static register(program) {
         const kiroCmd = program
             .command('kiro')
             .description('Kiro CLI integration');
+        kiroCmd
+            .command('doctor')
+            .description('Diagnose the Kiro integration: install, database, wired agents, and whether hooks are firing')
+            .action(() => {
+            KiroCommands.runDoctor();
+        });
         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')

package/dist/hooks/correction-detector.js

@@ -43,8 +43,14 @@ async function handleCorrectionDetector(input) {
         (0, shared_1.hookLog)('correction-detector', `Reask signal detection error: ${(0, shared_1.safeErrorMessage)(err)}`);
     }
     const result = await (0, shared_1.classifyContent)(prompt);
-    if (!result)
+    if (!result) {
+        // Terse trace so "did the hook fire?" is answerable from the log alone:
+        // absence of any line = hook never ran; "no rule detected" = ran but the
+        // prompt wasn't a storable rule; "Captured X" = ran and stored. Prompt
+        // text is NOT logged (privacy) — only its length.
+        (0, shared_1.hookLog)('correction-detector', `no rule detected in prompt (len=${prompt.length})`);
         return;
+    }
     // Reject short/garbage extracts and raw dumps (not clean rules)
     if (result.extract.length < 10 || result.extract.length > 200)
         return;

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,13 @@ 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 ..." / "recall ..." are explicit store requests in any phrasing —
+    // "remember that X", "remember to X", "remember my favourite color is green",
+    // "recall my favourite color is green". This is the resilient (no-LLM,
+    // no-MCP) capture path, which matters under enterprise Kiro governance that
+    // blocks the MCP tools. The interrogative/question-mark guards below keep
+    // "do you remember that config file?" / "do you recall X?" out.
+    { regex: /\b(?:remember|recall)\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.1",
+  "version": "0.28.3",
   "description": "Persistent memory for Claude Code and Pi with native Skills integration, automatic capture, failure learning, and project scoping",
   "main": "dist/index.js",
   "bin": {
@@ -105,6 +105,6 @@
     "@anthropic-ai/sdk": "^0.110.0",
     "better-sqlite3": "^12.2.0",
     "chalk": "^5.5.0",
-    "commander": "^15.0.0"
+    "commander": "^14.0.3"
   }
 }