claude-recall 0.27.0 → 0.27.1

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

@@ -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
@@ -71,6 +81,15 @@ 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.
 
+If the release notes mention new or changed hooks (a `hooksVersion` bump), also re-run `claude-recall setup --install` in each active project. It's safe to run any time: when your hooks are already current it's a no-op and touches nothing.
+
+> **Registered before v0.27.x?** Older versions auto-registered the MCP server with an `npx`-based command, which re-resolves the package on every server start and can be shadowed by stale project-local installs. Switch to the direct binary form (run in each affected project):
+>
+> ```bash
+> claude mcp remove claude-recall
+> claude mcp add claude-recall -- claude-recall mcp start
+> ```
+
 For Pi, run `pi update npm:claude-recall` and restart Pi.
 
 > **Seeing `error: unknown command 'upgrade'`?** Your installed version predates 0.23.2 (the release that added the `upgrade` command). Bootstrap once with `npm install -g claude-recall@latest`, then all future upgrades use `claude-recall upgrade`.

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

@@ -943,7 +943,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 +1339,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 +1436,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 +1493,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 +1524,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 +1608,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 +1708,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) {

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/package.json

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

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');
 }