claude-recall 0.28.6 → 0.28.8

package/README.md

@@ -105,7 +105,23 @@ 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`.
+> **⚠️ After `kiro setup` or `--merge-into`: start ONE fresh conversation per project (no `--resume`).** Kiro snapshots the agent config into each conversation **at creation** — `--resume` restores that snapshot and ignores agent-config changes made since. So conversations created *before* you wired claude-recall will **never** run its hooks, no matter how often you resume them or restart Kiro. Start one fresh conversation after wiring; every conversation created from then on carries the hooks, **including when resumed** (`--resume` works normally afterwards — this is a one-time rollover per project).
+
+The rollover, concretely (add your usual flags, e.g. `--classic`, `--trust-all-tools`):
+
+```bash
+cd ~/path/to/your-project
+kiro-cli chat --agent <your-agent>
+```
+
+In that session state something memorable (e.g. `recall the deploy pipeline uses helm`), exit, then verify it was captured:
+
+```bash
+claude-recall search "helm"
+tail -5 ~/.claude-recall/hook-logs/hook-dispatcher.log
+```
+
+The log should show a `scope [...] → project=your-project` line; `claude-recall kiro doctor` gives a fuller health report.
 
 > **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.
 
@@ -129,12 +145,12 @@ With Option B the agent has the memory tools (`load_rules`, `store_memory`, `sea
 
 **Not available under Kiro** with either option (Kiro's hooks expose no transcript): transcript-based failure detection and session-end auto-checkpoints.
 
-> **Project scoping & `--resume`.** Memories scope to the **working directory Kiro reports for the session**. `kiro --resume` (with no conversation id) continues your *most-recent conversation* and restores **its** directory — which may be a different project than the one your shell is in. So a resumed session captures into the project of the conversation you're continuing, not wherever you launched Kiro. That's usually what you want (memories follow the conversation), but if you bounce between projects it can surprise you.
+> **Project scoping & `--resume`.** Memories scope to the **working directory Kiro reports for the session** — normally the directory you launched Kiro from. `kiro --resume` resumes the most recent conversation *from the current directory* (it's per-project), so scoping and `--resume` naturally agree. Just remember the snapshot rule above: only conversations **created after** wiring run the hooks.
 >
-> To force a fixed project regardless of what `--resume` restores, pin it with `CLAUDE_RECALL_PROJECT_ID`. A per-project shell alias makes it seamless:
+> To force a fixed project id regardless of directory, pin it with `CLAUDE_RECALL_PROJECT_ID`. A per-project shell alias makes it seamless:
 >
 > ```bash
-> alias kiro-epic='CLAUDE_RECALL_PROJECT_ID=epic-workflow-cicd kiro-cli chat --agent mcp-agent-env --resume'
+> alias kiro-myproj='CLAUDE_RECALL_PROJECT_ID=my-project kiro-cli chat --agent <your-agent> --resume'
 > ```
 >
 > `claude-recall kiro doctor` always prints the resolved project (and whether it's pinned) so you can confirm where memories are landing before trusting it.
@@ -506,6 +522,8 @@ claude-recall hook run memory-sync           # Stop + PreCompact hook (syncs rul
 
 Each project gets isolated memory based on its working directory. **Project ID** is derived from the `cwd` passed by the agent. Universal memories (no project scope) are available everywhere. Switching projects switches memory automatically.
 
+To pin the project id explicitly — e.g. one logical project spanning several directories (worktrees, subrepos) — set `CLAUDE_RECALL_PROJECT_ID` (see [Environment Variables](#environment-variables)).
+
 Database location: `~/.claude-recall/claude-recall.db` (shared file, scoped by `project_id` column).
 
 ---
@@ -555,7 +573,7 @@ Runtime behavior can be tuned via environment variables. Defaults are chosen so
 | `CLAUDE_RECALL_ENFORCE_MODE`             | `on`    | Set to `off` to bypass the search-enforcer hook.                                                         |
 | `CLAUDE_RECALL_LLM_TIMEOUT_MS`           | `5000`  | Timeout for hook-context LLM calls (classification, hindsight hints). Hooks fall back to regex when it fires. |
 | `CLAUDE_RECALL_STOP_DEBOUNCE_MS`         | `300000` | Debounce for the heavy Stop-hook pipeline (episodes, session extraction, promotion). Citations still scan every turn. `0` disables. |
-| `CLAUDE_RECALL_PROJECT_ID`               | *(cwd)*  | Pin the project scope to a fixed id, overriding working-directory detection. Useful when `kiro --resume` restores a different project's directory than you intend. |
+| `CLAUDE_RECALL_PROJECT_ID`               | *(cwd)*  | Pin the project scope to a fixed id, overriding working-directory detection. Useful when one logical project spans several directories (worktrees, subrepos). |
 
 ---
 

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

@@ -185,10 +185,11 @@ class HookCommands {
             // happened to inherit. Both Claude Code and Kiro include `cwd`; for CC
             // it equals process.cwd() so this is a no-op, but for Kiro it pins
             // scoping to the session's working directory. Without this a memory
-            // captured while working on project A could land in project B (e.g. a
-            // `kiro --resume`d session whose cwd differs from the shell's), and
-            // capture (userPromptSubmit) and injection (agentSpawn) could even
-            // disagree. Project memories must scope to ONE deterministic project.
+            // captured while working on project A could land in project B (any
+            // session whose declared cwd differs from what this subprocess
+            // inherited), and capture (userPromptSubmit) and injection
+            // (agentSpawn) could even disagree. Project memories must scope to
+            // ONE deterministic project.
             try {
                 const { ConfigService } = await Promise.resolve().then(() => __importStar(require('../../services/config')));
                 const cfg = ConfigService.getInstance();

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

@@ -220,8 +220,15 @@ class KiroCommands {
         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.`);
+        console.log('⚠️  IMPORTANT — one-time rollover per project: Kiro snapshots the agent');
+        console.log('config into each conversation AT CREATION, and --resume restores that');
+        console.log('snapshot. Conversations created BEFORE this merge will never run the');
+        console.log(`memory hooks. In each project, start ONE fresh conversation (no --resume):`);
+        console.log('');
+        console.log(`kiro-cli chat --agent ${safeName}`);
+        console.log('');
+        console.log('Every conversation created from now on carries the hooks — including');
+        console.log('when resumed, so your normal --resume workflow works from then on.');
         process.exit(0);
     }
     /** Action body, separated from commander wiring so tests can call it directly. */
@@ -261,6 +268,11 @@ class KiroCommands {
         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('⚠️  Kiro snapshots the agent config into each conversation at creation —');
+        console.log('conversations created before this setup never run the hooks, even when');
+        console.log('resumed. Start ONE fresh conversation (no --resume) per project; every');
+        console.log('conversation from then on carries the hooks, including when resumed.');
+        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);
@@ -404,7 +416,7 @@ class KiroCommands {
             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).');
+            line('⚠', 'no kiro.log — Kiro hooks have never fired. Kiro snapshots agent config into each conversation at creation, so conversations created before wiring never run hooks (even resumed). Start ONE fresh conversation (no --resume) in each project.');
         }
         if (cd) {
             line('✓', `capture hook last ran${KiroCommands.fmtAge(cd.ageMs)}: ${cd.line.replace(/^\[[^\]]+\]\s*/, '')}`);

package/dist/services/config.js

@@ -99,9 +99,9 @@ class ConfigService {
                 name: process.env.CLAUDE_PROJECT_NAME,
                 // Explicit project pin. Overrides cwd-based scoping entirely — set it
                 // to force every memory into one project regardless of which directory
-                // the runtime reports (e.g. `kiro --resume` restores the resumed
-                // conversation's directory, which may not be the project you mean to
-                // work in). CLAUDE_RECALL_PROJECT_ID is the documented name;
+                // the runtime reports (useful when one logical project spans several
+                // directories, or to keep scoping stable across worktrees/subdirs).
+                // CLAUDE_RECALL_PROJECT_ID is the documented name;
                 // CLAUDE_PROJECT_ID is honored for backward compatibility.
                 id: process.env.CLAUDE_RECALL_PROJECT_ID || process.env.CLAUDE_PROJECT_ID
             },

package/package.json

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