claude-recall 0.7.3 → 0.7.5

package/.claude/CLAUDE.md

@@ -1,3 +1,10 @@
+# Claude Recall - Skills Integration
+
+**Note**: Claude Recall now uses Claude Code Skills for better memory management.
+See [.claude/skills/memory-management/SKILL.md](./.claude/skills/memory-management/SKILL.md) for details.
+
+---
+
 # Claude Recall - Memory-First Development with Learning Loop
 
 This file provides instructions to Claude Code when working with projects that use Claude Recall for persistent memory.

package/README.md

@@ -94,7 +94,22 @@ npm uninstall -g claude-recall
 
 Claude Recall works on **Windows, Linux, and macOS**. Native binaries (SQLite) compile automatically for your platform during `npm install`.
 
-**WSL Users:** Use local installation only. Global installation on Windows + WSL usage causes binary conflicts ("invalid ELF header" errors).
+**WSL Users - Special Case:**
+
+If you use **both Windows and WSL** for the same project (e.g., Electron app runs on Windows, but Claude Code runs in WSL):
+
+**Problem**: Installing locally creates Windows binaries, but WSL needs Linux binaries → "invalid ELF header" errors.
+
+**Solution**: Install globally in WSL only:
+```bash
+# From WSL:
+npm install -g claude-recall
+
+# Verify:
+claude-recall --version
+```
+
+**Important**: Global installation does NOT affect project-specific memory scoping! See [How Project Scoping Works](#how-project-scoping-works-installation-location) below.
 
 **Everyone else:** Both local and global work, but local is still recommended for the benefits above.
 
@@ -371,40 +386,39 @@ Claude Recall stores different types of memories (sorted by priority):
 
 ## CLI Commands
 
-### Essential Commands
-```bash
-# View statistics
-claude-recall stats
+All commands can be run from your terminal or **within Claude Code sessions** (Claude can execute them using the Bash tool).
 
-# Search memories
-claude-recall search "database configuration"
+### Memory Operations
 
-# Export memories
-claude-recall export memories.json
-
-# Import memories
-claude-recall import memories.json
+**Search memories:**
+```bash
+npx claude-recall search "database"
+npx claude-recall search "auth" --limit 20           # Show up to 20 results
+npx claude-recall search "config" --project my-app   # Filter by project + universal
+npx claude-recall search "testing" --global          # Search all projects
+npx claude-recall search "api" --json                # Output as JSON
+```
 
-# Clear memories (use with caution)
-claude-recall clear --type preferences  # Clear only preferences
-claude-recall clear --force               # Clear everything
+**View statistics:**
+```bash
+npx claude-recall stats                    # Current project + universal + unscoped
+npx claude-recall stats --project my-app   # Specific project + universal
+npx claude-recall stats --global           # All projects
+```
 
-# Test memory capture (for debugging)
-claude-recall capture user-prompt '{"content":"your message here"}'
+**Store memory directly:**
+```bash
+npx claude-recall store "I prefer TypeScript with strict mode"
+npx claude-recall store "Use PostgreSQL" --type project-knowledge
 ```
 
-### Intelligence & Evolution Commands (v0.7.0+)
+### Intelligence & Evolution (v0.7.0+)
 
+**View memory evolution and sophistication metrics:**
 ```bash
-# View memory evolution and sophistication metrics
-claude-recall evolution
-claude-recall evolution --days 60           # Analyze last 60 days
-claude-recall evolution --project my-app    # Filter by project
-
-# View failure memories with counterfactual learning
-claude-recall failures
-claude-recall failures --limit 20           # Show 20 most recent
-claude-recall failures --project my-app     # Filter by project
+npx claude-recall evolution                    # Last 30 days
+npx claude-recall evolution --days 60          # Last 60 days
+npx claude-recall evolution --project my-app   # Filter by project
 ```
 
 **Example `evolution` output:**
@@ -427,6 +441,19 @@ Failure Rate: 12.4% ↘
 ○ Agent developing adaptive patterns
 ```
 
+**Sophistication Levels:**
+- **L1 Procedural**: Basic tool use, simple actions
+- **L2 Self-Reflection**: Error checking, corrections, learning from failures
+- **L3 Adaptive**: Systematic workflows, devops patterns
+- **L4 Compositional**: Multi-constraint reasoning, complex decision-making
+
+**View failure memories with counterfactual learning:**
+```bash
+npx claude-recall failures                    # Last 10 failures
+npx claude-recall failures --limit 20         # Show 20 most recent
+npx claude-recall failures --project my-app   # Filter by project
+```
+
 **Example `failures` output:**
 ```
 ❌ Failure Memories (Counterfactual Learning)
@@ -445,11 +472,166 @@ Failure Rate: 12.4% ↘
    Should Do: Use JWT tokens instead
 ```
 
-**Sophistication Levels:**
-- **L1 Procedural**: Basic tool use, simple actions
-- **L2 Self-Reflection**: Error checking, corrections, learning from failures
-- **L3 Adaptive**: Systematic workflows, devops patterns
-- **L4 Compositional**: Multi-constraint reasoning, complex decision-making
+### Data Management
+
+**Export/import memories:**
+```bash
+npx claude-recall export memories.json          # Export all memories
+npx claude-recall export backup.json --json     # Export as JSON
+npx claude-recall import memories.json          # Import memories
+```
+
+**Clear memories (use with caution):**
+```bash
+npx claude-recall clear --force                 # Clear everything (requires --force)
+```
+
+### MCP Server Commands
+
+**What are MCP commands?**
+The MCP (Model Context Protocol) server is how Claude Code communicates with Claude Recall. When you install claude-recall, it automatically configures `~/.claude.json` to start the MCP server.
+
+**Process Management (v0.7.4+):**
+```bash
+# Start/stop
+npx claude-recall mcp start              # Start MCP server (auto-started by Claude Code)
+npx claude-recall mcp stop               # Stop running server gracefully
+npx claude-recall mcp restart            # Restart server
+npx claude-recall mcp test               # Test MCP server functionality
+
+# Monitoring
+npx claude-recall mcp status             # Show server status for current project
+npx claude-recall mcp ps                 # List all running MCP servers (all projects)
+
+# Cleanup
+npx claude-recall mcp cleanup            # Remove stale PID files and processes
+npx claude-recall mcp cleanup --dry-run  # Preview cleanup actions
+npx claude-recall mcp cleanup --all      # Stop all MCP servers (all projects)
+```
+
+**When to use:**
+- **Auto-started**: Claude Code automatically starts the MCP server on launch
+- **Manual management**: Stop, restart, or cleanup stale servers as needed
+- **Troubleshooting**: Use `mcp ps` to see running servers, `mcp cleanup` to remove zombies
+- **Testing**: Use `mcp test` to verify the server responds correctly
+
+### Utilities
+
+**Check installation status:**
+```bash
+npx claude-recall status        # Show installation and system status
+npx claude-recall --version     # Show version
+```
+
+**Monitoring (advanced):**
+```bash
+npx claude-recall monitor                      # View search monitoring stats
+npx claude-recall test-memory-search           # Test if Claude searches before file creation
+```
+
+**Migration (if upgrading from old versions):**
+```bash
+npx claude-recall migrate       # Migrate from file-watcher to MCP architecture
+```
+
+### Global Options
+
+All commands support:
+- `--verbose` - Enable verbose logging
+- `--config <path>` - Use custom config file
+- `-h, --help` - Show help for any command
+
+## Project Management (v0.7.5+)
+
+Claude Recall maintains a **project registry** to track all projects using it, enabling better organization and visibility across multiple projects.
+
+### Auto-Registration
+
+Projects are automatically registered when:
+- The MCP server starts (every time Claude Code connects)
+- You run `npm install claude-recall` locally
+- You manually run `npx claude-recall project register`
+
+The registry stores:
+- Project path
+- Claude Recall version
+- Registration date
+- Last activity timestamp
+
+### Project Commands
+
+**List all registered projects:**
+```bash
+npx claude-recall project list              # Human-friendly output
+npx claude-recall project list --json       # JSON format
+```
+
+Shows:
+- Project name and path
+- Claude Recall version
+- Last activity
+- MCP server status (active/inactive)
+
+**Show project details:**
+```bash
+npx claude-recall project show              # Current project
+npx claude-recall project show my-project   # Specific project
+```
+
+Displays:
+- Registry information (path, version, timestamps)
+- MCP server status (running/stopped, PID)
+
+**Register a project:**
+```bash
+npx claude-recall project register          # Current directory
+npx claude-recall project register --path /path/to/project
+```
+
+**Unregister a project:**
+```bash
+npx claude-recall project unregister        # Current project
+npx claude-recall project unregister my-project
+```
+
+**Note**: Unregistering does NOT remove memories or MCP configuration - only the registry entry.
+
+**Clean up stale entries:**
+```bash
+npx claude-recall project clean             # Remove projects not seen in 30 days
+npx claude-recall project clean --days 60   # Custom threshold
+npx claude-recall project clean --dry-run   # Preview without changes
+```
+
+### Enhanced MCP Commands
+
+MCP commands now show registry information:
+
+```bash
+npx claude-recall mcp status    # Shows registry info + MCP status
+npx claude-recall mcp ps        # Lists all servers with version info
+```
+
+### Registry Storage
+
+Registry stored at: `~/.claude-recall/projects.json`
+
+Format:
+```json
+{
+  "version": 1,
+  "projects": {
+    "my-project": {
+      "path": "/full/path/to/my-project",
+      "registeredAt": "2025-11-09T...",
+      "version": "0.7.5",
+      "lastSeen": "2025-11-09T..."
+    }
+  }
+}
+```
+
+**Note**: The registry is separate from your memory database. Cleaning the registry does NOT affect your stored memories.
 
 ## Project Scoping (v0.7.2+)
 
@@ -535,6 +717,71 @@ npx claude-recall stats --global
 - Works like v0.7.1 and earlier
 - Available everywhere unless you explicitly scope them
 
+### How Project Scoping Works (Installation Location)
+
+**Important**: Where you install claude-recall (global vs local) does NOT affect project-specific memory scoping!
+
+**What Determines Project Scope:**
+
+1. ✅ **Claude Code's working directory** - Where you run Claude Code
+2. ✅ **Database scoping logic** - Filters memories by project_id
+3. ❌ **Installation location** - Doesn't matter for scoping
+
+**How It Works:**
+
+```
+# Claude Code runs in this directory:
+/home/user/projects/my-app
+
+# Project ID detected from directory name:
+project_id = "my-app"
+
+# Memories stored/searched with that project_id:
+- "For this project, use PostgreSQL" → stored with project_id="my-app"
+- "Remember everywhere: I prefer TypeScript" → stored with scope="universal"
+
+# Same behavior whether claude-recall is:
+# - Installed globally: /usr/local/lib/node_modules/claude-recall
+# - Installed locally: ./node_modules/claude-recall
+```
+
+**Database Location (Always Global):**
+
+Whether you install globally or locally, the database is **always** at:
+```
+~/.claude-recall/claude-recall.db
+```
+
+This single database contains:
+- Project-specific memories for each project (isolated by project_id)
+- Universal memories (available in all projects)
+- Unscoped memories (backward compatible)
+
+**Example: Two Projects, One Installation**
+
+```bash
+# Project A:
+cd ~/projects/project-a
+# Claude Code detects: project_id = "project-a"
+# Memories: isolated to project-a + universal + unscoped
+
+# Project B:
+cd ~/projects/project-b
+# Claude Code detects: project_id = "project-b"
+# Memories: isolated to project-b + universal + unscoped
+
+# Same global installation, proper isolation!
+```
+
+**WSL Users:**
+
+This is why **global installation in WSL** works perfectly for project scoping:
+- Code location: `/home/user/.nvm/.../bin/claude-recall` (global)
+- Project detection: Based on Claude Code's `cwd`, NOT installation path
+- Memory isolation: Each project gets its own memories + universal preferences
+
+Global installation actually **helps** WSL users by avoiding binary conflicts while maintaining perfect project isolation!
+
 ## Memory Management
 
 Claude Recall automatically manages memory to prevent unlimited database growth, with user notifications:

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

@@ -47,6 +47,8 @@ const search_monitor_1 = require("../services/search-monitor");
 const live_test_1 = require("./commands/live-test");
 const queue_integration_1 = require("../services/queue-integration");
 const memory_evolution_1 = require("../services/memory-evolution");
+const mcp_commands_1 = require("./commands/mcp-commands");
+const project_commands_1 = require("./commands/project-commands");
 const program = new commander_1.Command();
 class ClaudeRecallCLI {
     constructor(options) {
@@ -548,7 +550,7 @@ async function main() {
     // MCP command
     const mcpCmd = program
         .command('mcp')
-        .description('MCP server commands');
+        .description('MCP server commands (start, stop, status, cleanup, ps, restart)');
     mcpCmd
         .command('start')
         .description('Start Claude Recall as an MCP server')
@@ -609,6 +611,10 @@ async function main() {
             process.exit(1);
         }
     });
+    // Register MCP process management commands
+    mcp_commands_1.MCPCommands.register(mcpCmd);
+    // Project management commands
+    project_commands_1.ProjectCommands.register(program);
     // Migration commands
     migrate_1.MigrateCommand.register(program);
     // Register live test command

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

@@ -0,0 +1,248 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPCommands = void 0;
+const process_manager_1 = require("../../services/process-manager");
+const config_1 = require("../../services/config");
+const project_registry_1 = require("../../services/project-registry");
+const chalk_1 = __importDefault(require("chalk"));
+/**
+ * MCP Process Management Commands
+ *
+ * Provides CLI commands for managing MCP server processes:
+ * - status: Show MCP server status
+ * - ps: List all running MCP servers
+ * - stop: Stop MCP server
+ * - restart: Restart MCP server
+ * - cleanup: Clean up stale PID files and processes
+ */
+class MCPCommands {
+    constructor() {
+        this.processManager = process_manager_1.ProcessManager.getInstance();
+        this.config = config_1.ConfigService.getInstance();
+        this.projectRegistry = project_registry_1.ProjectRegistry.getInstance();
+    }
+    static register(mcpCmd) {
+        const commands = new MCPCommands();
+        // mcp status - Show current project's MCP server status
+        mcpCmd
+            .command('status')
+            .description('Show MCP server status for current project')
+            .action(async () => {
+            await commands.showStatus();
+        });
+        // mcp ps - List all running MCP servers
+        mcpCmd
+            .command('ps')
+            .description('List all running MCP servers across all projects')
+            .action(async () => {
+            await commands.listServers();
+        });
+        // mcp stop - Stop MCP server
+        mcpCmd
+            .command('stop')
+            .description('Stop MCP server')
+            .option('--project <id>', 'Stop specific project server (default: current project)')
+            .option('--force', 'Force kill (SIGKILL) instead of graceful shutdown (SIGTERM)')
+            .action(async (options) => {
+            await commands.stopServer(options);
+        });
+        // mcp restart - Restart MCP server
+        mcpCmd
+            .command('restart')
+            .description('Restart MCP server for current project')
+            .option('--force', 'Force kill before restart')
+            .action(async (options) => {
+            await commands.restartServer(options);
+        });
+        // mcp cleanup - Clean up stale processes and PID files
+        mcpCmd
+            .command('cleanup')
+            .description('Clean up stale PID files and processes')
+            .option('--dry-run', 'Show what would be cleaned without making changes')
+            .option('--all', 'Stop all running MCP servers')
+            .option('--force', 'Force kill processes')
+            .action(async (options) => {
+            await commands.cleanup(options);
+        });
+    }
+    /**
+     * Show status of MCP server for current project
+     */
+    async showStatus() {
+        const projectId = this.config.getProjectId();
+        const status = this.processManager.getServerStatus(projectId);
+        const registryEntry = this.projectRegistry.get(projectId);
+        console.log(chalk_1.default.cyan('\n📊 MCP Server Status\n'));
+        console.log(`Project:  ${chalk_1.default.yellow(projectId)}`);
+        console.log(`Status:   ${status.isRunning ? chalk_1.default.green('✓ Running') : chalk_1.default.gray('✗ Stopped')}`);
+        if (status.pid !== null) {
+            console.log(`PID:      ${chalk_1.default.yellow(status.pid)}`);
+            if (!status.isRunning) {
+                console.log(chalk_1.default.gray(`          (stale PID file exists)`));
+            }
+        }
+        console.log(`PID File: ${chalk_1.default.gray(status.pidFile)}`);
+        // Show registry information if available
+        if (registryEntry) {
+            console.log();
+            console.log(chalk_1.default.bold('Registry Info:'));
+            console.log(`  Version:      ${chalk_1.default.gray(registryEntry.version)}`);
+            console.log(`  Path:         ${chalk_1.default.gray(registryEntry.path)}`);
+            console.log(`  Registered:   ${chalk_1.default.gray(new Date(registryEntry.registeredAt).toLocaleString())}`);
+            console.log(`  Last Seen:    ${chalk_1.default.gray(new Date(registryEntry.lastSeen).toLocaleString())}`);
+        }
+        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();
+    }
+    /**
+     * List all running MCP servers across projects
+     */
+    async listServers() {
+        const servers = this.processManager.getAllRunningServers();
+        const registeredProjects = this.projectRegistry.list();
+        console.log(chalk_1.default.cyan('\n📋 MCP Servers & Registered Projects\n'));
+        if (servers.length === 0 && registeredProjects.length === 0) {
+            console.log(chalk_1.default.gray('No MCP servers or registered projects found.'));
+            console.log();
+            return;
+        }
+        const runningServers = servers.filter(s => s.isRunning);
+        const staleServers = servers.filter(s => !s.isRunning);
+        if (runningServers.length > 0) {
+            console.log(chalk_1.default.green(`✓ Running (${runningServers.length}):`));
+            for (const server of runningServers) {
+                const registryEntry = this.projectRegistry.get(server.projectId);
+                const versionInfo = registryEntry ? ` [v${registryEntry.version}]` : '';
+                console.log(`  ${chalk_1.default.yellow(server.projectId.padEnd(40))} PID: ${chalk_1.default.cyan(server.pid)}${chalk_1.default.gray(versionInfo)}`);
+            }
+            console.log();
+        }
+        if (staleServers.length > 0) {
+            console.log(chalk_1.default.gray(`✗ Stale (${staleServers.length}):`));
+            for (const server of staleServers) {
+                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();
+        }
+        // Show registered projects that don't have running servers
+        const runningProjectIds = new Set(runningServers.map(s => s.projectId));
+        const inactiveProjects = registeredProjects.filter(({ projectId }) => !runningProjectIds.has(projectId));
+        if (inactiveProjects.length > 0) {
+            console.log(chalk_1.default.gray(`📂 Registered but Inactive (${inactiveProjects.length}):`));
+            for (const { projectId, entry } of inactiveProjects) {
+                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();
+        }
+    }
+    /**
+     * Stop MCP server
+     */
+    async stopServer(options) {
+        const projectId = options.project || this.config.getProjectId();
+        const status = this.processManager.getServerStatus(projectId);
+        console.log(chalk_1.default.cyan('\n🛑 Stopping MCP Server\n'));
+        console.log(`Project: ${chalk_1.default.yellow(projectId)}`);
+        if (!status.isRunning) {
+            if (status.pid !== null) {
+                console.log(chalk_1.default.yellow('⚠ Server not running, but stale PID file exists'));
+                console.log('Removing stale PID file...');
+                this.processManager.removePidFile(projectId);
+                console.log(chalk_1.default.green('✓ Stale PID file removed'));
+            }
+            else {
+                console.log(chalk_1.default.gray('✗ Server not running'));
+            }
+            console.log();
+            return;
+        }
+        const signal = options.force ? 'SIGKILL' : 'SIGTERM';
+        console.log(`Sending ${signal} to PID ${chalk_1.default.yellow(status.pid)}...`);
+        try {
+            this.processManager.killProcess(status.pid, options.force || false);
+            this.processManager.removePidFile(projectId);
+            // Give it a moment to shut down
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            // Verify it stopped
+            const newStatus = this.processManager.getServerStatus(projectId);
+            if (!newStatus.isRunning) {
+                console.log(chalk_1.default.green('✓ Server stopped successfully'));
+            }
+            else {
+                console.log(chalk_1.default.yellow('⚠ Server may still be running. Try --force flag.'));
+            }
+        }
+        catch (error) {
+            console.log(chalk_1.default.red(`✗ Failed to stop server: ${error}`));
+        }
+        console.log();
+    }
+    /**
+     * Restart MCP server
+     */
+    async restartServer(options) {
+        const projectId = this.config.getProjectId();
+        const status = this.processManager.getServerStatus(projectId);
+        console.log(chalk_1.default.cyan('\n🔄 Restarting MCP Server\n'));
+        console.log(`Project: ${chalk_1.default.yellow(projectId)}`);
+        if (status.isRunning) {
+            console.log('Stopping current server...');
+            await this.stopServer({ force: options.force });
+            // Wait a bit longer for graceful shutdown
+            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();
+        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.'));
+        console.log();
+    }
+    /**
+     * Clean up stale PID files and optionally stop all servers
+     */
+    async cleanup(options) {
+        console.log(chalk_1.default.cyan('\n🧹 MCP Server Cleanup\n'));
+        if (options.dryRun) {
+            console.log(chalk_1.default.yellow('DRY RUN MODE - No changes will be made\n'));
+        }
+        if (options.all) {
+            console.log(chalk_1.default.yellow('⚠ Stopping ALL MCP servers...\n'));
+            const stopped = this.processManager.stopAllServers(options.dryRun || false, options.force || false);
+            if (options.dryRun) {
+                console.log(chalk_1.default.gray(`Would stop ${stopped} server(s)`));
+            }
+            else {
+                console.log(chalk_1.default.green(`✓ Stopped ${stopped} server(s)`));
+            }
+        }
+        else {
+            console.log('Cleaning up stale PID files...\n');
+            const cleaned = this.processManager.cleanupStalePidFiles(options.dryRun || false);
+            if (cleaned === 0) {
+                console.log(chalk_1.default.green('✓ No stale PID files found'));
+            }
+            else {
+                if (options.dryRun) {
+                    console.log(chalk_1.default.gray(`\nWould remove ${cleaned} stale PID file(s)`));
+                }
+                else {
+                    console.log(chalk_1.default.green(`\n✓ Removed ${cleaned} stale PID file(s)`));
+                }
+            }
+        }
+        console.log();
+    }
+}
+exports.MCPCommands = MCPCommands;