claude-recall 0.20.13 → 0.20.15

package/.claude/skills/auto-preferences/SKILL.md

@@ -8,14 +8,14 @@ source: claude-recall
 
 # Preferences
 
-Auto-generated from 5 memories. Last updated: 2026-04-09.
+Auto-generated from 5 memories. Last updated: 2026-04-10.
 
 ## Rules
 
-- Session test preference 1775768726677
-- Test preference 1775768726629-2
-- Test preference 1775768726629-1
-- Test preference 1775768726629-0
+- Session test preference 1775821892450
+- Test preference 1775821892400-2
+- Test preference 1775821892400-1
+- Test preference 1775821892400-0
 - Test memory content
 
 ---

package/.claude/skills/auto-preferences/manifest.json

@@ -1,13 +1,13 @@
 {
   "topicId": "preferences",
-  "sourceHash": "6deab3a85a84a13804c09fd95225d54f4d11e646d8109ec83cd968d1b7af771e",
+  "sourceHash": "9b2ae714e4bdd82091b4fcc5347c2b1a8a2a10d3be57ca57877e943e380a5457",
   "memoryCount": 5,
-  "generatedAt": "2026-04-09T21:05:26.692Z",
+  "generatedAt": "2026-04-10T11:51:32.469Z",
   "memoryKeys": [
-    "memory_1775768726678_aa8631cqc",
-    "memory_1775768726653_3tkihcis0",
-    "memory_1775768726640_ii27bz2av",
-    "memory_1775768726630_p95bn61ba",
-    "memory_1775768726593_fb0syx1bo"
+    "memory_1775821892451_dzjdxx6ef",
+    "memory_1775821892427_462vxb2gq",
+    "memory_1775821892416_8taocju9a",
+    "memory_1775821892402_3x8ksma5p",
+    "memory_1775821892372_4khhv0wc2"
   ]
 }

package/README.md

@@ -142,17 +142,76 @@ action → outcome event → episode → candidate lesson → promotion → acti
 
 ## CLI Reference
 
-### Common Commands
+### Health Check (run these first)
 
 ```bash
-claude-recall stats                  # Memory statistics
-claude-recall search "query"         # Search memories
-claude-recall failures               # View failure memories
-claude-recall outcomes               # Outcome-aware learning status
-claude-recall outcomes --section lessons  # Just candidate lessons
-claude-recall export backup.json     # Export memories to JSON
-claude-recall import backup.json     # Import memories from JSON
-claude-recall --version              # Check version
+claude-recall --version              # Confirm installed version
+claude-recall status                 # Installation health: hooks, MCP, DB path, project ID
+claude-recall stats                  # What's in the DB for this project
+claude-recall stats --global         # What's in the DB across ALL projects
+```
+
+### Inspecting Memories
+
+```bash
+claude-recall search "query"             # Search current project's memories
+claude-recall search "query" --global    # Search across all projects
+claude-recall search "query" --json      # Machine-readable output
+claude-recall search "query" --project <id>  # Search a specific project
+
+claude-recall failures                   # View failure memories (current project)
+claude-recall failures --limit 20        # Show more
+
+claude-recall outcomes                   # Outcome-aware learning status
+claude-recall outcomes --section lessons # Just candidate lessons
+claude-recall outcomes --section stats   # Retrieval/helpfulness stats per memory
+claude-recall outcomes --limit 20        # More items per section
+
+claude-recall monitor                    # Memory search monitoring stats
+```
+
+### Managing Memories
+
+```bash
+claude-recall store "content"                # Store a memory (default type: preference)
+claude-recall store "content" -t correction  # Store with specific type
+claude-recall export backup.json             # Export all memories to JSON
+claude-recall import backup.json             # Import memories from JSON
+claude-recall clear --force                  # Delete all memories (irreversible)
+```
+
+### Troubleshooting
+
+```bash
+# "Are my hooks installed?"
+claude-recall status                     # Shows hook registration status
+claude-recall hooks check                # Verify hook files exist and are valid
+
+# "Is the MCP server running?"
+claude-recall mcp status                 # Current project's server status
+claude-recall mcp ps                     # List all running servers
+
+# "Which project does this directory map to?"
+claude-recall project show               # Shows project ID for current directory
+claude-recall project list               # All registered projects
+
+# "Why do I see memories from other projects?"
+claude-recall search "query"             # Scoped to current project (default)
+claude-recall search "query" --global    # Explicitly cross-project
+
+# "How do I check what the DB actually contains?"
+sqlite3 ~/.claude-recall/claude-recall.db "SELECT type, COUNT(*) FROM memories GROUP BY type"
+sqlite3 ~/.claude-recall/claude-recall.db "SELECT type, COUNT(*) FROM memories WHERE project_id = '<id>' GROUP BY type"
+
+# "Hook logs — what did the hooks actually do?"
+tail -20 ~/.claude-recall/hook-logs/tool-outcome-watcher.log
+tail -20 ~/.claude-recall/hook-logs/memory-stop.log
+tail -20 ~/.claude-recall/hook-logs/correction-detector.log
+
+# "Something is broken, start fresh"
+claude-recall repair                     # Clean up old hooks, reinstall skills
+claude-recall setup --install            # Reinstall skills + hooks
+claude-recall mcp cleanup --all          # Stop all stale MCP servers
 ```
 
 <details>
@@ -164,11 +223,18 @@ claude-recall setup                      # Show activation instructions
 claude-recall setup --install            # Install skills + hooks
 claude-recall status                     # Installation and system status
 claude-recall repair                     # Clean up old hooks, install skills
+claude-recall hooks check                # Verify hook files exist and are valid
+claude-recall hooks test-enforcement     # Test if search enforcer hook works
 
 # ── Memory ───────────────────────────────────────────────────────────
-claude-recall stats                      # Memory statistics
-claude-recall search "query"             # Search memories
+claude-recall stats                      # Memory statistics (current project)
+claude-recall stats --global             # Memory statistics (all projects)
+claude-recall search "query"             # Search memories (current project)
+claude-recall search "query" --global    # Search memories (all projects)
+claude-recall search "query" --json      # Output as JSON
+claude-recall search "query" --project <id>  # Search specific project
 claude-recall store "content"            # Store memory directly
+claude-recall store "content" -t <type>  # Store with type (preference, correction, failure, devops, project-knowledge)
 claude-recall export backup.json         # Export memories to JSON
 claude-recall import backup.json         # Import memories from JSON
 claude-recall clear --force              # Clear all memories
@@ -176,6 +242,7 @@ claude-recall failures                   # View failure memories
 claude-recall failures --limit 20        # Limit results
 claude-recall outcomes                   # Outcome-aware learning status
 claude-recall outcomes --section lessons # Just candidate lessons
+claude-recall outcomes --section stats   # Retrieval/helpfulness stats
 claude-recall outcomes --limit 20        # More items per section
 claude-recall monitor                    # Memory search monitoring stats
 
@@ -199,8 +266,16 @@ claude-recall mcp cleanup --all          # Stop all servers
 claude-recall project show               # Current project info
 claude-recall project list               # All registered projects
 claude-recall project register           # Register current project
+claude-recall project unregister [id]    # Unregister a project
 claude-recall project clean              # Remove stale registry entries
 
+# ── Database Migration ──────────────────────────────────────────────
+claude-recall migrate check              # Check if migration needed
+claude-recall migrate schema             # Show current schema version
+claude-recall migrate export             # Export pre-migration backup
+claude-recall migrate import             # Import from backup
+claude-recall migrate complete           # Run pending migrations
+
 # ── Auto-Capture Hooks (run automatically, registered via setup --install) ──
 claude-recall hook run correction-detector   # UserPromptSubmit hook
 claude-recall hook run memory-stop           # Stop hook

package/dist/hooks/tool-outcome-watcher.js

@@ -49,6 +49,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleBashFailureWatcher = void 0;
 exports.handleToolOutcomeWatcher = handleToolOutcomeWatcher;
+exports.shouldCaptureFailure = shouldCaptureFailure;
 exports.handleToolFailure = handleToolFailure;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -195,6 +196,37 @@ async function handleToolOutcomeWatcher(input) {
 }
 // Backward compatibility alias
 exports.handleBashFailureWatcher = handleToolOutcomeWatcher;
+/**
+ * Quality filter: should this bash failure be captured as a memory?
+ * Returns false for exploratory probes, command-not-found, and other low-signal failures.
+ */
+function shouldCaptureFailure(command, exitCode, output) {
+    // Very short commands (ls, cd, etc.) — not worth capturing
+    if (command.trim().length < 5)
+        return false;
+    // Exploratory probes: commands ending in 2>/dev/null are intentionally suppressing errors
+    if (/2>\s*\/dev\/null\s*$/.test(command))
+        return false;
+    // Command-existence checks: which, type, command -v
+    const trimmed = command.trim();
+    if (/^(which|type)\s+/i.test(trimmed))
+        return false;
+    if (/^command\s+-v\s+/i.test(trimmed))
+        return false;
+    // Command not found (exit code 127 or output contains "command not found")
+    if (exitCode === '127')
+        return false;
+    if (/command not found/i.test(output))
+        return false;
+    // No useful output — nothing to learn from
+    const cleanOutput = output.replace(/\(no output\)/gi, '').trim();
+    if (cleanOutput.length < 10 && !/^(npm|npx|node|python|pip|cargo|go|make|docker|git)\s/.test(trimmed))
+        return false;
+    // EISDIR / "Is a directory" — file read probes
+    if (/is a directory/i.test(output) || /EISDIR/i.test(output))
+        return false;
+    return true;
+}
 // --- Bash handler (original bash-failure-watcher logic) ---
 async function handleBashOutcome(input) {
     const command = input.tool_input?.command;
@@ -215,6 +247,11 @@ async function handleBashOutcome(input) {
     }
 }
 async function handleBashFailure(command, exitCode, output, sessionId) {
+    // Quality filter — skip low-signal failures
+    if (!shouldCaptureFailure(command, exitCode, output)) {
+        (0, shared_1.hookLog)(HOOK_NAME, `Skipped low-quality failure: ${truncate(command, 60)} (exit ${exitCode})`);
+        return;
+    }
     // Dedup check
     const existing = (0, shared_1.searchExisting)(command);
     if ((0, shared_1.isDuplicate)(command, existing, 0.7)) {

package/dist/memory/storage.js

@@ -230,6 +230,77 @@ class MemoryStorage {
         });
         return crypto.createHash('sha256').update(canonical).digest('hex');
     }
+    /**
+     * Find a same-type memory whose text content is a near-duplicate (Jaccard >= 0.85).
+     * Returns the key of the matching memory, or null if none found.
+     */
+    findFuzzyDuplicate(memory) {
+        const newText = this.extractText(memory.value).toLowerCase();
+        if (newText.length < 40)
+            return null; // Too short to fuzzy-match reliably
+        // Scope fuzzy dedup to same type AND same project (or both null/universal)
+        const projectFilter = memory.project_id
+            ? 'AND project_id = ?'
+            : 'AND (project_id IS NULL OR project_id = \'\')';
+        const params = [memory.type, memory.key];
+        if (memory.project_id)
+            params.push(memory.project_id);
+        const candidates = this.db.prepare(`SELECT key, value FROM memories WHERE type = ? AND key != ? ${projectFilter}`).all(...params);
+        for (const candidate of candidates) {
+            let candidateText;
+            try {
+                const parsed = JSON.parse(candidate.value);
+                candidateText = this.extractText(parsed).toLowerCase();
+            }
+            catch {
+                candidateText = candidate.value.toLowerCase();
+            }
+            if (this.jaccardSimilarity(newText, candidateText) >= 0.65) {
+                return candidate.key;
+            }
+        }
+        return null;
+    }
+    extractText(value) {
+        if (typeof value === 'string')
+            return value;
+        if (value && typeof value === 'object') {
+            // Collect all leaf string values, ignoring JSON keys
+            const leaves = [];
+            const collect = (obj) => {
+                if (typeof obj === 'string') {
+                    leaves.push(obj);
+                    return;
+                }
+                if (obj && typeof obj === 'object') {
+                    for (const v of Object.values(obj))
+                        collect(v);
+                }
+            };
+            collect(value);
+            return leaves.join(' ');
+        }
+        return String(value);
+    }
+    jaccardSimilarity(a, b) {
+        const tokenize = (s) => {
+            const words = s.replace(/[^a-z0-9\s]/g, ' ').split(/\s+/).filter(Boolean);
+            return new Set(words.filter(w => !MemoryStorage.STOP_WORDS.has(w)));
+        };
+        const wordsA = tokenize(a);
+        const wordsB = tokenize(b);
+        if (wordsA.size === 0 && wordsB.size === 0)
+            return 1;
+        if (wordsA.size === 0 || wordsB.size === 0)
+            return 0;
+        let intersection = 0;
+        for (const w of wordsA) {
+            if (wordsB.has(w))
+                intersection++;
+        }
+        const union = wordsA.size + wordsB.size - intersection;
+        return union === 0 ? 0 : intersection / union;
+    }
     save(memory) {
         const contentHash = this.computeContentHash(memory.value, memory.type);
         // Write-time dedup: check if identical content already exists under a different key
@@ -240,6 +311,13 @@ class MemoryStorage {
             this.db.pragma('wal_checkpoint(TRUNCATE)');
             return;
         }
+        // Fuzzy dedup: check if a same-type memory with very similar content exists
+        const fuzzyMatch = this.findFuzzyDuplicate(memory);
+        if (fuzzyMatch) {
+            this.db.prepare('UPDATE memories SET timestamp = ?, access_count = access_count + 1 WHERE key = ?').run(Date.now(), fuzzyMatch);
+            this.db.pragma('wal_checkpoint(TRUNCATE)');
+            return;
+        }
         const stmt = this.db.prepare(`
       INSERT OR REPLACE INTO memories
       (key, value, type, project_id, file_path, timestamp, relevance_score, access_count,
@@ -541,3 +619,9 @@ class MemoryStorage {
     }
 }
 exports.MemoryStorage = MemoryStorage;
+MemoryStorage.STOP_WORDS = new Set([
+    'a', 'an', 'the', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from', 'as',
+    'and', 'or', 'but', 'not', 'no', 'do', 'does', 'did', 'this', 'that',
+    'it', 'its', 'via', 'can', 'should', 'will', 'would', 'may', 'might',
+]);

package/package.json

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