claude-recall 0.7.0 → 0.7.2

package/.claude/CLAUDE.md

@@ -84,6 +84,58 @@ Claude Recall provides these MCP tools (access via `mcp__claude-recall__*`):
 - **`mcp__claude-recall__get_stats`**: View memory statistics
 - **`mcp__claude-recall__clear_context`**: Clear session context
 
+## Intelligence & Evolution (v0.7.0+)
+
+### Automatic Failure Learning
+
+Claude Recall now **automatically captures failures with counterfactual reasoning**:
+- **What failed**: The approach or action that didn't work
+- **Why it failed**: Root cause analysis (file not found, permission denied, etc.)
+- **What should be done instead**: Counterfactual suggestion (the right approach)
+- **Preventative checks**: Steps to prevent the failure from recurring
+
+**No manual storage needed** - failures are auto-detected from:
+- Error messages and exceptions
+- User corrections ("That didn't work", "Failed", "Error")
+
+### Sophistication Tracking
+
+Every memory is **automatically classified by sophistication level**:
+- **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 your agent's evolution: `npx claude-recall evolution`
+
+### New CLI Commands (v0.7.0+)
+
+**View memory evolution metrics:**
+```bash
+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
+```
+
+Shows:
+- Progression score (0-100)
+- Sophistication breakdown (L1-L4 percentages)
+- Confidence trends (improving/stable/declining)
+- Failure rate trends (improving/stable/worsening)
+
+**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
+```
+
+Shows:
+- What failed and why
+- What should have been done instead
+- Preventative checks to avoid recurrence
+- Alternative approaches to consider
+
 ## Memory Types
 
 Memories are categorized by type (sorted by priority):
@@ -181,6 +233,87 @@ Confirm: "✓ Stored preference"
 5. **Use broad search terms**: Include task type + language + preferences + success/failure/correction
 6. **Close the loop**: Pre-action search → Execute → Post-action outcome storage
 
+## Project Scoping (v0.7.2+)
+
+Claude Recall now supports **project-specific memory isolation** to keep universal preferences separate from project-specific information.
+
+### Three Memory Scopes
+
+1. **Universal** (`scope='universal'`): Available in all projects
+   - User says: "Remember everywhere: I prefer TypeScript with strict mode"
+   - Stored as universal memory, accessible from any project
+
+2. **Project** (`scope='project'`): Only available in current project
+   - User says: "For this project, we use PostgreSQL"
+   - Stored with project_id, only accessible from this project
+
+3. **Unscoped** (`scope=null`, default): Available everywhere (backward compatible)
+   - User says: "I prefer Jest for testing"
+   - Stored without scope, works like v0.7.1 and earlier
+
+### Auto-Detection
+
+When storing memories, the system automatically detects scope from user language:
+
+**Universal indicators**:
+- "remember everywhere"
+- "for all projects"
+- "globally"
+- "always use"
+
+**Project indicators**:
+- "for this project"
+- "project-specific"
+- "only here"
+- "in this project"
+
+**Default**: If no indicator, memory is unscoped (available everywhere)
+
+### How Search Works
+
+**Default behavior** (project + universal):
+```
+mcp__claude-recall__search("database")
+```
+Returns: Current project memories + universal memories + unscoped memories
+
+**Global search** (all projects):
+```
+mcp__claude-recall__search("database", filters: { globalSearch: true })
+```
+Returns: All memories from all projects
+
+### CLI Usage
+
+```bash
+# Current project stats
+npx claude-recall stats
+
+# Global stats (all projects)
+npx claude-recall stats --global
+
+# Search current project
+npx claude-recall search "database"
+
+# Search specific project
+npx claude-recall search "database" --project my-app
+
+# Search all projects
+npx claude-recall search "database" --global
+```
+
+### Use Cases
+
+**Universal memories**: Preferences that apply across all your work
+- Coding style: "Always use TypeScript with strict mode"
+- Tools: "Prefer Jest for testing"
+- Conventions: "Name files with kebab-case"
+
+**Project memories**: Project-specific details
+- Database: "This project uses PostgreSQL"
+- API: "Base URL is https://api.example.com"
+- Build: "Run npm run build:prod for production"
+
 ## Advanced: Optional Context-Manager Agent
 
 For complex multi-step research, a `context-manager` agent is available at `.claude/agents/context-manager.md`.

package/README.md

@@ -28,6 +28,13 @@ Every time you start a new conversation with Claude, you're starting from scratc
 - **Optional agent** - Advanced context-manager agent available for complex workflows
 - **Correction priority** - User corrections given highest priority (never repeat mistakes)
 
+### 🧠 Intelligence & Evolution (v0.7.0+)
+- **Sophistication tracking** - Measures agent progression from basic tool use to compositional reasoning
+- **Failure learning** - Captures what failed, why it failed, and what should be done instead (counterfactual reasoning)
+- **Evolution metrics** - View progression score, confidence trends, and failure rates over time
+- **Structured memories** - Rich Title/Description/Content format for better human readability
+- **Automatic classification** - Memories auto-classified by sophistication level (L1-L4)
+
 ### 🔒 Privacy & Security First
 - **100% Local** - All memories stored locally in SQLite (~/.claude-recall/)
 - **No cloud sync** - Your data never leaves your machine
@@ -386,6 +393,148 @@ claude-recall clear --force               # Clear everything
 claude-recall capture user-prompt '{"content":"your message here"}'
 ```
 
+### Intelligence & Evolution Commands (v0.7.0+)
+
+```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
+```
+
+**Example `evolution` output:**
+```
+📈 Memory Evolution
+
+Analysis Period: Last 30 days
+Total Memories: 145
+Progression Score: 67/100
+
+Sophistication Breakdown:
+  Procedural (L1):      45 ( 31.0%)
+  Self-Reflection (L2): 38 ( 26.2%)
+  Adaptive (L3):        52 ( 35.9%)
+  Compositional (L4):   10 (  6.9%)
+
+Average Confidence: 0.78 ↗
+Failure Rate: 12.4% ↘
+
+○ Agent developing adaptive patterns
+```
+
+**Example `failures` output:**
+```
+❌ Failure Memories (Counterfactual Learning)
+
+1. Avoid: Reading file without existence check
+   What Failed: Attempted to read config.json directly
+   Why Failed: File does not exist at expected location
+   Should Do: Verify file path exists before reading. Use fs.existsSync()
+   Preventative Checks:
+     - Verify file exists before reading (fs.existsSync)
+     - Handle ENOENT errors gracefully
+
+2. Avoid: Session-based authentication
+   What Failed: Session-based auth implementation
+   Why Failed: User reported: Doesn't scale across multiple servers
+   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
+
+## Project Scoping (v0.7.2+)
+
+Claude Recall now supports **project-specific memory isolation** while keeping universal preferences available everywhere.
+
+### How It Works
+
+- **Single global database**: `~/.claude-recall/claude-recall.db`
+- **Three memory scopes**:
+  - **Universal**: Available in all projects (coding preferences, tools)
+  - **Project**: Only available in the specific project
+  - **Unscoped** (default): Available everywhere (backward compatible)
+- **Project ID**: Automatically detected from directory name
+
+### Storing Memories
+
+**Universal memories** (available everywhere):
+```
+User: "Remember everywhere: I prefer TypeScript with strict mode"
+Claude: [Stores with scope='universal']
+```
+
+**Project-specific memories**:
+```
+User: "For this project, we use SQLite for the database"
+Claude: [Stores with scope='project', project_id='my-app']
+```
+
+**Default** (unscoped, works like before):
+```
+User: "I prefer Jest for testing"
+Claude: [Stores with scope=null, available everywhere]
+```
+
+### Searching with Scopes
+
+**Default** (current project + universal):
+```bash
+npx claude-recall search "database"
+# Returns: Current project memories + universal memories + unscoped
+```
+
+**Specific project**:
+```bash
+npx claude-recall search "database" --project my-app
+# Returns: my-app memories + universal memories + unscoped
+```
+
+**All projects**:
+```bash
+npx claude-recall search "database" --global
+# Returns: All memories from all projects
+```
+
+### Stats with Scopes
+
+**Current project**:
+```bash
+npx claude-recall stats
+# Shows: Memories for current project (claude-recall) + universal + unscoped
+```
+
+**All projects**:
+```bash
+npx claude-recall stats --global
+# Shows: All memories across all projects
+```
+
+### Use Cases
+
+**Universal memories** (scope='universal'):
+- Coding style preferences: "Always use TypeScript with strict mode"
+- Tool preferences: "Prefer Jest for testing"
+- File naming conventions: "Name markdown files with lowercase-dash-case"
+
+**Project-specific memories** (scope='project'):
+- Database choice: "This project uses PostgreSQL"
+- API endpoints: "API base URL is https://api.example.com"
+- Build commands: "Run npm run build:prod for production"
+
+**Unscoped memories** (scope=null, default):
+- Backward compatible
+- Works like v0.7.1 and earlier
+- Available everywhere unless you explicitly scope them
+
 ## Memory Management
 
 Claude Recall automatically manages memory to prevent unlimited database growth, with user notifications:

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

@@ -67,13 +67,28 @@ class ClaudeRecallCLI {
     /**
      * Show memory statistics
      */
-    showStats() {
-        const stats = this.memoryService.getStats();
+    showStats(options) {
+        let stats;
         const configService = config_1.ConfigService.getInstance();
         const config = configService.getConfig();
         const maxMemories = config.database.compaction?.maxMemories || 10000;
+        if (options?.global) {
+            // Show stats for all memories
+            stats = this.memoryService.getStats();
+            console.log('\n📊 Claude Recall Statistics (All Projects)\n');
+        }
+        else if (options?.project) {
+            // Show stats for specific project + universal
+            stats = this.getProjectStats(options.project);
+            console.log(`\n📊 Claude Recall Statistics (Project: ${options.project})\n`);
+        }
+        else {
+            // Show stats for current project + universal
+            const projectId = configService.getProjectId();
+            stats = this.getProjectStats(projectId);
+            console.log(`\n📊 Claude Recall Statistics (Project: ${projectId})\n`);
+        }
         const usagePercent = (stats.total / maxMemories) * 100;
-        console.log('\n📊 Claude Recall Statistics\n');
         console.log(`Total Memories: ${stats.total}/${maxMemories} (${usagePercent.toFixed(1)}%)`);
         // Simple status indicator
         if (usagePercent >= 90) {
@@ -95,6 +110,24 @@ class ClaudeRecallCLI {
         console.log('\n');
         this.logger.info('CLI', 'Stats displayed', stats);
     }
+    /**
+     * Get stats for a specific project (includes universal and unscoped memories)
+     */
+    getProjectStats(projectId) {
+        const allMemories = this.memoryService.search('');
+        const projectMemories = allMemories.filter(m => m.project_id === projectId ||
+            m.scope === 'universal' ||
+            m.project_id === null);
+        // Calculate byType breakdown
+        const byType = {};
+        for (const mem of projectMemories) {
+            byType[mem.type] = (byType[mem.type] || 0) + 1;
+        }
+        return {
+            total: projectMemories.length,
+            byType
+        };
+    }
     /**
      * Show skills evolution breakdown
      */
@@ -254,7 +287,27 @@ class ClaudeRecallCLI {
      */
     search(query, options) {
         const limit = options.limit || 10;
-        const results = this.memoryService.search(query);
+        // Determine search scope
+        let results;
+        if (options.global) {
+            // Global search: all memories
+            results = this.memoryService.search(query);
+        }
+        else if (options.project) {
+            // Project-specific search: project + universal
+            results = this.memoryService.findRelevant({
+                query,
+                projectId: options.project
+            });
+        }
+        else {
+            // Default: current project + universal
+            const config = config_1.ConfigService.getInstance();
+            results = this.memoryService.findRelevant({
+                query,
+                projectId: config.getProjectId()
+            });
+        }
         const topResults = results.slice(0, limit);
         if (options.json) {
             // Format for hook consumption - include relevance_score field
@@ -566,11 +619,15 @@ async function main() {
         .description('Search memories by query')
         .option('-l, --limit <number>', 'Maximum results to show', '10')
         .option('--json', 'Output as JSON')
+        .option('--project <id>', 'Filter by project ID (includes universal memories)')
+        .option('--global', 'Search all projects and memories')
         .action((query, options) => {
         const cli = new ClaudeRecallCLI(program.opts());
         cli.search(query, {
             limit: parseInt(options.limit),
-            json: options.json
+            json: options.json,
+            project: options.project,
+            global: options.global
         });
         process.exit(0);
     });
@@ -578,9 +635,14 @@ async function main() {
     program
         .command('stats')
         .description('Show memory statistics')
-        .action(() => {
+        .option('--project <id>', 'Filter by project ID')
+        .option('--global', 'Show all memories across all projects')
+        .action((options) => {
         const cli = new ClaudeRecallCLI(program.opts());
-        cli.showStats();
+        cli.showStats({
+            project: options.project,
+            global: options.global
+        });
         process.exit(0);
     });
     // Evolution command

package/dist/mcp/memory-capture-middleware.js

@@ -190,10 +190,10 @@ class MemoryCaptureMiddleware {
                 });
             }
         }
-        // PRIORITY 1: Check for explicit "remember" commands
-        const rememberRegex = /(?:remember|Remember)\s+(?:that\s+)?(.+?)(?:[.!?]|$)/gi;
-        const rememberMatches = content.matchAll(rememberRegex);
-        for (const match of rememberMatches) {
+        // PRIORITY 1: Check for explicit "remember" or "recall" commands
+        const explicitMemoryRegex = /(?:remember|Remember|recall|Recall)\s+(?:that\s+)?(.+?)(?:[.!?]|$)/gi;
+        const explicitMemoryMatches = content.matchAll(explicitMemoryRegex);
+        for (const match of explicitMemoryMatches) {
             const memoryContent = match[1].trim();
             if (memoryContent) {
                 memories.push({
@@ -201,7 +201,7 @@ class MemoryCaptureMiddleware {
                     content: memoryContent,
                     data: {
                         raw: memoryContent,
-                        source: 'explicit_remember_command',
+                        source: 'explicit_memory_command',
                         confidence: 1.0
                     },
                     confidence: 1.0, // Always highest confidence
@@ -230,7 +230,8 @@ class MemoryCaptureMiddleware {
             const matches = content.matchAll(regex);
             for (const match of matches) {
                 // Skip if this was already captured as explicit memory
-                if (match[0].toLowerCase().includes('remember'))
+                const lower = match[0].toLowerCase();
+                if (lower.includes('remember') || lower.includes('recall'))
                     continue;
                 memories.push({
                     type: pattern.type,

package/dist/mcp/tools/memory-tools.js

@@ -86,6 +86,11 @@ class MemoryTools {
                         metadata: {
                             type: 'object',
                             description: 'Optional metadata for the memory'
+                        },
+                        scope: {
+                            type: 'string',
+                            enum: ['universal', 'project'],
+                            description: 'Memory scope: "universal" (available in all projects) or "project" (current project only). Default: unscoped (available everywhere for backward compatibility)'
                         }
                     },
                     required: ['content']
@@ -139,7 +144,11 @@ class MemoryTools {
                                 },
                                 projectId: {
                                     type: 'string',
-                                    description: 'Filter by project ID'
+                                    description: 'Filter by project ID (includes universal memories)'
+                                },
+                                globalSearch: {
+                                    type: 'boolean',
+                                    description: 'Search all projects (ignores projectId filter)'
                                 }
                             }
                         },
@@ -264,7 +273,7 @@ class MemoryTools {
     }
     async handleStoreMemory(input, context) {
         try {
-            const { content, metadata } = input;
+            const { content, metadata, scope } = input;
             if (!content || typeof content !== 'string') {
                 throw new Error('Content is required and must be a string');
             }
@@ -280,8 +289,9 @@ class MemoryTools {
                 type: 'conversation',
                 context: {
                     sessionId: context.sessionId,
-                    projectId: context.projectId,
-                    timestamp: context.timestamp
+                    projectId: scope === 'project' ? context.projectId : undefined,
+                    timestamp: context.timestamp,
+                    scope: scope || null
                 }
             });
             this.logger.info('MemoryTools', 'Memory stored successfully', {
@@ -379,8 +389,15 @@ class MemoryTools {
                     if (filters.type && result.type !== filters.type) {
                         return false;
                     }
-                    if (filters.projectId && result.project_id !== filters.projectId) {
-                        return false;
+                    // Global search: include all memories
+                    if (filters.globalSearch) {
+                        return true;
+                    }
+                    // Project-scoped search: include project + universal + unscoped memories
+                    if (filters.projectId) {
+                        return result.project_id === filters.projectId ||
+                            result.scope === 'universal' ||
+                            result.project_id === null;
                     }
                     return true;
                 });

package/dist/memory/schema.sql

@@ -14,10 +14,12 @@ CREATE TABLE IF NOT EXISTS memories (
   superseded_by TEXT,
   superseded_at INTEGER,
   confidence_score REAL,
-  sophistication_level INTEGER DEFAULT 1
+  sophistication_level INTEGER DEFAULT 1,
+  scope TEXT CHECK(scope IN ('universal', 'project', NULL))
 );
 
 CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project_id);
+CREATE INDEX IF NOT EXISTS idx_memories_scope_project ON memories(scope, project_id);
 CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(type);
 CREATE INDEX IF NOT EXISTS idx_memories_timestamp ON memories(timestamp);
 CREATE INDEX IF NOT EXISTS idx_memories_preference_key ON memories(preference_key, is_active);

package/dist/memory/storage.js

@@ -82,10 +82,10 @@ class MemoryStorage {
         const stmt = this.db.prepare(`
       INSERT OR REPLACE INTO memories
       (key, value, type, project_id, file_path, timestamp, relevance_score, access_count,
-       preference_key, is_active, superseded_by, superseded_at, confidence_score, sophistication_level)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       preference_key, is_active, superseded_by, superseded_at, confidence_score, sophistication_level, scope)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
-        stmt.run(memory.key, JSON.stringify(memory.value), memory.type, memory.project_id || null, memory.file_path || null, memory.timestamp || Date.now(), memory.relevance_score || 1.0, memory.access_count || 0, memory.preference_key || null, memory.is_active !== undefined ? (memory.is_active ? 1 : 0) : 1, memory.superseded_by || null, memory.superseded_at || null, memory.confidence_score || null, memory.sophistication_level || 1);
+        stmt.run(memory.key, JSON.stringify(memory.value), memory.type, memory.project_id || null, memory.file_path || null, memory.timestamp || Date.now(), memory.relevance_score || 1.0, memory.access_count || 0, memory.preference_key || null, memory.is_active !== undefined ? (memory.is_active ? 1 : 0) : 1, memory.superseded_by || null, memory.superseded_at || null, memory.confidence_score || null, memory.sophistication_level || 1, memory.scope || null);
         // Force a WAL checkpoint to ensure the data is written to the main database file
         // This ensures that other processes (like CLI) can see the changes immediately
         this.db.pragma('wal_checkpoint(TRUNCATE)');
@@ -133,8 +133,9 @@ class MemoryStorage {
         let query = 'SELECT * FROM memories WHERE 1=1';
         const params = [];
         if (context.project_id) {
-            query += ' AND project_id = ?';
-            params.push(context.project_id);
+            // Include project-specific OR universal OR unscoped (NULL) memories
+            query += ' AND (project_id = ? OR scope = ? OR project_id IS NULL)';
+            params.push(context.project_id, 'universal');
         }
         if (context.file_path) {
             query += ' AND file_path = ?';

package/dist/services/config.js

@@ -144,7 +144,12 @@ class ConfigService {
         return path.join(this.config.logging.directory, logName);
     }
     getProjectId() {
-        return this.config.project.id || this.config.project.rootDir;
+        if (this.config.project.id) {
+            return this.config.project.id;
+        }
+        // Use directory name (basename) instead of full path
+        const rootDir = this.config.project.rootDir;
+        return path.basename(rootDir);
     }
     updateConfig(updates) {
         this.config = this.mergeConfig(this.config, updates);

package/dist/services/memory.js

@@ -35,14 +35,17 @@ class MemoryService {
                 const percent = ((stats.total / maxMemories) * 100).toFixed(0);
                 console.log(`⚠️  Memory usage at ${percent}% (${stats.total}/${maxMemories})`);
             }
+            // Detect scope (v0.8.0)
+            const scope = this.detectScope(request);
             const memory = {
                 key: request.key,
                 value: request.value,
                 type: request.type,
-                project_id: request.context?.projectId || this.config.getProjectId(),
+                project_id: scope === 'universal' ? undefined : (request.context?.projectId || this.config.getProjectId()),
                 file_path: request.context?.filePath,
                 timestamp: request.context?.timestamp || Date.now(),
-                relevance_score: request.relevanceScore || 1.0
+                relevance_score: request.relevanceScore || 1.0,
+                scope: scope
             };
             // Auto-classify sophistication level (v0.7.0)
             memory.sophistication_level = this.evolution.classifySophistication(memory);
@@ -354,6 +357,37 @@ class MemoryService {
             return false;
         }
     }
+    /**
+     * Detect memory scope from request (v0.8.0)
+     * @private
+     */
+    detectScope(request) {
+        // Check explicit scope in context
+        if (request.context?.scope) {
+            return request.context.scope;
+        }
+        // Extract content for analysis
+        const content = typeof request.value === 'string'
+            ? request.value
+            : JSON.stringify(request.value);
+        const lowerContent = content.toLowerCase();
+        // Explicit user indicators for universal scope
+        if (lowerContent.includes('remember everywhere') ||
+            lowerContent.includes('for all projects') ||
+            lowerContent.includes('globally') ||
+            lowerContent.includes('always use')) {
+            return 'universal';
+        }
+        // Explicit user indicators for project scope
+        if (lowerContent.includes('for this project') ||
+            lowerContent.includes('project-specific') ||
+            lowerContent.includes('only here') ||
+            lowerContent.includes('in this project')) {
+            return 'project';
+        }
+        // Default: unscoped (null) for backward compatibility
+        return null;
+    }
     /**
      * Close database connection
      */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-recall",
-  "version": "0.7.0",
-  "description": "Persistent memory for Claude Code with automatic capture, failure learning, and sophistication tracking via MCP server",
+  "version": "0.7.2",
+  "description": "Persistent memory for Claude Code with automatic capture, failure learning, sophistication tracking, and project scoping via MCP server",
   "main": "dist/index.js",
   "bin": {
     "claude-recall": "dist/cli/claude-recall-cli.js"