claude-recall 0.22.1 → 0.23.0

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

@@ -8,15 +8,15 @@ source: claude-recall
 
 # Preferences
 
-Auto-generated from 5 memories. Last updated: 2026-04-11.
+Auto-generated from 5 memories. Last updated: 2026-04-22.
 
 ## Rules
 
-- Session test preference 1775902182248
-- Test preference 1775902182184-2
-- Test preference 1775902182184-1
-- Test preference 1775902182184-0
-- Test memory content
+- integration-fixture session 1776885821647
+- integration-fixture preference 1776885821594-2
+- integration-fixture preference 1776885821594-1
+- integration-fixture preference 1776885821594-0
+- integration-fixture memory 1776885821539
 
 ---
 *Auto-generated by Claude Recall. Regenerate: `npx claude-recall skills generate`*

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

@@ -1,13 +1,13 @@
 {
   "topicId": "preferences",
-  "sourceHash": "a383c0d6502023d06954eb49fcab8886dc5181d5e59666f6c74a381221e44f87",
+  "sourceHash": "886f098b1a582616f10443d10ec5877b85152231a370636321f2f3f8dc37b2dc",
   "memoryCount": 5,
-  "generatedAt": "2026-04-11T10:09:42.271Z",
+  "generatedAt": "2026-04-22T19:23:41.665Z",
   "memoryKeys": [
-    "memory_1775902182249_x5rzzep7s",
-    "memory_1775902182226_9uo2kaw57",
-    "memory_1775902182211_pl5fzrb85",
-    "memory_1775902182185_q6f9widp3",
-    "memory_1775902182147_olowsptz3"
+    "memory_1776885821648_8b5enno4p",
+    "memory_1776885821623_73b897xzl",
+    "memory_1776885821611_admiwaa2s",
+    "memory_1776885821596_ii942py46",
+    "memory_1776885821543_yk1wyjqkz"
   ]
 }

package/README.md

@@ -18,6 +18,7 @@ Your preferences, project structure, workflows, corrections, and coding style ar
 - **Failure Learning** — captures what failed, why, and what to do instead — so the agent doesn't repeat mistakes
 - **Outcome-Aware Learning** — tracks action outcomes (all tool results, test cycles, user corrections), synthesizes candidate lessons, and promotes validated patterns into active rules automatically
 - **Skill Crystallization** — auto-generates `.claude/skills/auto-*/` files from accumulated memories, using Anthropic's [Agent Skills](https://agentskills.io/) open standard
+- **Rule Hygiene** — token-budgeted `load_rules` payload, citation-aware auto-demotion of rules that never earn citations, and retroactive dedup for near-duplicates
 - **Local-Only** — SQLite on your machine, no telemetry, no cloud, works fully offline
 
 ---
@@ -336,6 +337,17 @@ claude-recall outcomes --section stats   # Retrieval/helpfulness stats
 claude-recall outcomes --limit 20        # More items per section
 claude-recall monitor                    # Memory search monitoring stats
 
+# ── Rule Hygiene ─────────────────────────────────────────────────────
+claude-recall rules demote [--dry-run]              # Demote rules loaded >=N times but never cited
+claude-recall rules demote --min-loads 20           # Tune load-count threshold (default 20)
+claude-recall rules demote --min-age-days 7         # Minimum age before demotion (default 7)
+claude-recall rules promote <id>                    # Restore an auto-demoted or auto-deduped rule
+claude-recall rules dedup [--dry-run]               # Collapse near-duplicate rules (Jaccard >= threshold)
+claude-recall rules dedup --threshold 0.8           # Stricter similarity (default 0.65)
+
+# ── Cleanup (destructive — always --dry-run first) ─────────────────
+claude-recall cleanup test-pollution [--dry-run]    # Delete legacy test-fixture rows
+
 # ── Task Checkpoints ────────────────────────────────────────────────
 claude-recall checkpoint save --completed <text> --remaining <text> [--blockers <text>] [--notes <text>] [--project <id>]
 claude-recall checkpoint load [--project <id>] [--json]
@@ -417,6 +429,25 @@ Global installation does **not** affect project scoping — project ID is still
 
 ---
 
+## Environment Variables
+
+Runtime behavior can be tuned via environment variables. Defaults are chosen so out-of-the-box behavior stays close to historical output; opt in as needed.
+
+| Variable                                 | Default | Effect                                                                                                   |
+| ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `CLAUDE_RECALL_DB_PATH`                  | `~/.claude-recall/` | Database directory.                                                                          |
+| `ANTHROPIC_API_KEY`                      | _(unset)_ | Enables LLM-based classification (Haiku). Falls back to regex silently when missing.                   |
+| `CLAUDE_RECALL_LOAD_BUDGET_TOKENS`       | `2000`  | Token budget for the `load_rules` payload. Rules are emitted in priority order (corrections → preferences by citation → devops by citation → failures) and dropped rules surface via `search_memory`. |
+| `CLAUDE_RECALL_AUTO_DEMOTE`              | `false` | When `true`, auto-demote rules on MCP boot where `load_count >= CLAUDE_RECALL_DEMOTE_MIN_LOADS`, `cite_count = 0`, and age `> CLAUDE_RECALL_DEMOTE_MIN_AGE_DAYS`. Still reversible via `rules promote <id>`. |
+| `CLAUDE_RECALL_DEMOTE_MIN_LOADS`         | `20`    | Minimum load count before a rule qualifies for auto-demotion.                                            |
+| `CLAUDE_RECALL_DEMOTE_MIN_AGE_DAYS`      | `7`     | Minimum rule age before auto-demotion can fire (avoids demoting brand-new rules).                        |
+| `CLAUDE_RECALL_AUTO_CLEANUP`             | `false` | Auto-kill stale MCP processes on start (otherwise reports and exits).                                    |
+| `CLAUDE_RECALL_COMPACT_THRESHOLD`        | `10MB`  | DB size at which automatic compaction kicks in.                                                          |
+| `CLAUDE_RECALL_MAX_MEMORIES`             | `10000` | Memory-row soft cap.                                                                                     |
+| `CLAUDE_RECALL_ENFORCE_MODE`             | `on`    | Set to `off` to bypass the search-enforcer hook.                                                         |
+
+---
+
 ## Development & Contributions
 
 PRs welcome — Claude Recall is open to contributors.

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

@@ -261,6 +261,99 @@ class ClaudeRecallCLI {
         });
         this.logger.info('CLI', 'Failures displayed', { count: displayFailures.length });
     }
+    /**
+     * Demote rules loaded often but never cited — excludes them from future load_rules payloads.
+     * Rules remain searchable via search_memory and can be restored with `rules promote <id>`.
+     */
+    demoteRules(options) {
+        const minLoads = options.minLoads ?? 20;
+        const minAgeDays = options.minAgeDays ?? 7;
+        const dryRun = options.dryRun ?? false;
+        const demoted = this.memoryService.autoDemoteStaleRules({
+            minLoads,
+            minAgeDays,
+            dryRun,
+            force: true,
+        });
+        const verb = dryRun ? 'Would demote' : 'Demoted';
+        console.log(`\n${verb} ${demoted.length} stale rules (load>=${minLoads}, cite=0, age>${minAgeDays}d)\n`);
+        if (demoted.length === 0)
+            return;
+        demoted.forEach(r => {
+            console.log(`  [${r.id}] ${r.type} · loaded ${r.load_count}x, cited 0x — key: ${r.key}`);
+        });
+        if (dryRun) {
+            console.log('\nRun without --dry-run to apply. Restore any row with `claude-recall rules promote <id>`.');
+        }
+        else {
+            console.log('\nRestore any row with `claude-recall rules promote <id>`.');
+        }
+    }
+    /**
+     * Retroactively collapse near-duplicate rules (predate write-time fuzzy dedup or
+     * slipped past its threshold). Keeps the oldest per cluster; sums cite/load into winner.
+     */
+    dedupSimilarRules(options) {
+        var _a;
+        const threshold = options.threshold ?? 0.65;
+        const dryRun = options.dryRun ?? false;
+        const collapses = this.memoryService.dedupSimilarRules({ threshold, dryRun });
+        const verb = dryRun ? 'Would collapse' : 'Collapsed';
+        console.log(`\n${verb} ${collapses.length} near-duplicate pairs (jaccard >= ${threshold})\n`);
+        if (collapses.length === 0)
+            return;
+        const byWinner = {};
+        for (const c of collapses) {
+            byWinner[_a = c.winnerId] ?? (byWinner[_a] = []);
+            byWinner[c.winnerId].push({ loserId: c.loserId, loserKey: c.loserKey, sim: c.similarity });
+        }
+        for (const [winnerId, losers] of Object.entries(byWinner)) {
+            const winnerKey = collapses.find(c => c.winnerId === Number(winnerId))?.winnerKey ?? '?';
+            console.log(`  [${winnerId}] ${winnerKey}`);
+            for (const l of losers) {
+                console.log(`    └─ ${l.loserKey} (sim ${l.sim})`);
+            }
+        }
+        if (dryRun) {
+            console.log('\nRun without --dry-run to apply. Losers are marked is_active=0 (reversible via `rules promote <id>`).');
+        }
+        else {
+            console.log('\nLosers marked is_active=0; restore individually with `rules promote <id>`.');
+        }
+    }
+    /**
+     * Delete legacy test-fixture rows that leaked into the production DB.
+     * Destructive — run with --dry-run first to preview.
+     */
+    cleanupTestPollution(options) {
+        const dryRun = options.dryRun ?? false;
+        const rows = this.memoryService.cleanupTestPollution({ dryRun });
+        const verb = dryRun ? 'Would delete' : 'Deleted';
+        console.log(`\n${verb} ${rows.length} test-pollution rows\n`);
+        if (rows.length === 0)
+            return;
+        const byType = {};
+        for (const r of rows)
+            byType[r.type] = (byType[r.type] || 0) + 1;
+        for (const [type, count] of Object.entries(byType)) {
+            console.log(`  ${type}: ${count}`);
+        }
+        if (dryRun) {
+            console.log('\nRun without --dry-run to apply.');
+        }
+    }
+    /**
+     * Restore a previously auto-demoted rule. Refuses to touch preference-supersession rows.
+     */
+    promoteRule(id) {
+        const ok = this.memoryService.promoteRule(id);
+        if (ok) {
+            console.log(`Rule #${id} restored (is_active=1).`);
+        }
+        else {
+            console.log(`No change. Rule #${id} was not auto-demoted (may not exist, already active, or superseded by another mechanism).`);
+        }
+    }
     /**
      * Show outcome-aware learning status: episodes, outcome events, candidate lessons, memory stats
      */
@@ -1163,7 +1256,7 @@ async function main() {
             lastSearchAt: Date.now(),
             searchQuery: 'test query',
             toolHistory: [
-                { tool: 'mcp__claude-recall__search', at: Date.now() }
+                { tool: 'search_memory', at: Date.now() }
             ]
         };
         fs.writeFileSync(stateFile, JSON.stringify(stateData, null, 2));
@@ -1392,7 +1485,7 @@ async function main() {
             console.log('\nTo use with Claude Code:');
             console.log('1. Ensure Claude Code is not running');
             console.log('2. Start Claude Code');
-            console.log('3. Use MCP tools like mcp__claude-recall__store_memory');
+            console.log('3. Use MCP tools like store_memory (Claude Code adds the mcp__claude-recall__ prefix automatically)');
         }
         catch (error) {
             console.error('❌ Test failed:', error);
@@ -1467,6 +1560,59 @@ async function main() {
         });
         process.exit(0);
     });
+    // Rules group: manage load_rules payload hygiene
+    const rulesCmd = program
+        .command('rules')
+        .description('Manage rule lifecycle: demote stale rules, restore demoted rules');
+    rulesCmd
+        .command('demote')
+        .description('Demote rules loaded >=N times with zero citations (excludes from load_rules)')
+        .option('--dry-run', 'Preview without mutating', false)
+        .option('--min-loads <number>', 'Minimum load count to qualify', '20')
+        .option('--min-age-days <number>', 'Minimum age in days (avoid demoting brand-new rules)', '7')
+        .action((options) => {
+        const cli = new ClaudeRecallCLI(program.opts());
+        cli.demoteRules({
+            dryRun: options.dryRun,
+            minLoads: parseInt(options.minLoads),
+            minAgeDays: parseInt(options.minAgeDays),
+        });
+        process.exit(0);
+    });
+    rulesCmd
+        .command('promote <id>')
+        .description('Restore a previously auto-demoted or auto-deduped rule (safety valve)')
+        .action((id) => {
+        const cli = new ClaudeRecallCLI(program.opts());
+        cli.promoteRule(parseInt(id));
+        process.exit(0);
+    });
+    rulesCmd
+        .command('dedup')
+        .description('Retroactively collapse near-duplicate rules (write-time dedup handles new writes)')
+        .option('--dry-run', 'Preview without mutating', false)
+        .option('--threshold <number>', 'Jaccard similarity threshold (0-1)', '0.65')
+        .action((options) => {
+        const cli = new ClaudeRecallCLI(program.opts());
+        cli.dedupSimilarRules({
+            dryRun: options.dryRun,
+            threshold: parseFloat(options.threshold),
+        });
+        process.exit(0);
+    });
+    // Cleanup group: destructive maintenance — opt-in only, always offers --dry-run
+    const cleanupCmd = program
+        .command('cleanup')
+        .description('Maintenance commands (destructive — always preview with --dry-run first)');
+    cleanupCmd
+        .command('test-pollution')
+        .description('Delete legacy test-fixture rows (Test preference 177…, Memory with complex metadata, etc.)')
+        .option('--dry-run', 'Preview without deleting', false)
+        .action((options) => {
+        const cli = new ClaudeRecallCLI(program.opts());
+        cli.cleanupTestPollution({ dryRun: options.dryRun });
+        process.exit(0);
+    });
     // Export command
     program
         .command('export <output>')

package/dist/mcp/server.js

@@ -330,6 +330,12 @@ class MCPServer {
             // Write PID file after successful startup
             this.processManager.writePidFile(projectId, process.pid);
             this.logger.info('MCPServer', `MCP server started successfully (PID: ${process.pid}, Project: ${projectId})`);
+            // Prune stale rules (loaded often, never cited) from load_rules payload.
+            // Gated on CLAUDE_RECALL_AUTO_DEMOTE=true. Idempotent; safe per-boot.
+            const demoted = this.memoryService.autoDemoteStaleRules();
+            if (demoted.length > 0) {
+                this.logger.info('MCPServer', `Auto-demoted ${demoted.length} stale rules on boot`);
+            }
         }
         catch (error) {
             this.logger.logServiceError('MCPServer', 'start', error);

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

@@ -141,7 +141,7 @@ class MemoryTools {
     registerTools() {
         this.tools = [
             {
-                name: 'mcp__claude-recall__load_rules',
+                name: 'load_rules',
                 description: 'Load all active rules before starting work. Returns preferences, corrections, past failures, and devops rules. Call this once at the start of every task. No query needed.',
                 inputSchema: {
                     type: 'object',
@@ -155,7 +155,7 @@ class MemoryTools {
                 handler: this.handleLoadRules.bind(this)
             },
             {
-                name: 'mcp__claude-recall__store_memory',
+                name: 'store_memory',
                 description: 'Store a rule or learning. Use for: corrections, preferences, devops rules, failures. The stored rule is immediately active in this conversation.',
                 inputSchema: {
                     type: 'object',
@@ -179,7 +179,7 @@ class MemoryTools {
                 handler: this.handleStoreMemory.bind(this)
             },
             {
-                name: 'mcp__claude-recall__search_memory',
+                name: 'search_memory',
                 description: 'Search memories by keyword. Use to find specific memories before making decisions. Returns matched memories ranked by relevance.',
                 inputSchema: {
                     type: 'object',
@@ -206,7 +206,7 @@ class MemoryTools {
                 handler: this.handleSearchMemory.bind(this)
             },
             {
-                name: 'mcp__claude-recall__delete_memory',
+                name: 'delete_memory',
                 description: 'Delete a specific memory by its ID (key). Use search_memory first to find the ID of the memory to delete.',
                 inputSchema: {
                     type: 'object',
@@ -221,7 +221,7 @@ class MemoryTools {
                 handler: this.handleDeleteMemory.bind(this)
             },
             {
-                name: 'mcp__claude-recall__save_checkpoint',
+                name: 'save_checkpoint',
                 description: 'Save a task checkpoint — a structured snapshot of work in progress (completed/remaining/blockers/notes). Replaces any previous checkpoint for this project. Call when ending a work session or pausing on a task.',
                 inputSchema: {
                     type: 'object',
@@ -237,7 +237,7 @@ class MemoryTools {
                 handler: this.handleSaveCheckpoint.bind(this),
             },
             {
-                name: 'mcp__claude-recall__load_checkpoint',
+                name: 'load_checkpoint',
                 description: 'Load the latest task checkpoint for the current project. Returns null if none exists. Call at the start of a session to recall where you left off — load_rules will hint when one exists.',
                 inputSchema: {
                     type: 'object',
@@ -274,6 +274,10 @@ class MemoryTools {
                 ? metadata.type
                 : 'preference';
             const key = `memory_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            const preferenceKey = typeof metadata?.preference_key === 'string' && metadata.preference_key.length > 0
+                ? metadata.preference_key
+                : undefined;
+            const isOverride = metadata?.isOverride === true;
             this.memoryService.store({
                 key,
                 value: {
@@ -288,8 +292,17 @@ class MemoryTools {
                     projectId: scope === 'project' ? context.projectId : undefined,
                     timestamp: context.timestamp,
                     scope: scope || null
-                }
+                },
+                preferenceKey,
+                isOverride
             });
+            // If this store overrides an existing rule, mark previous active rules with
+            // the same preference_key as superseded and surface their keys so the agent
+            // knows to ignore the stale text sitting higher up in its context.
+            let supersededKeys = [];
+            if (isOverride && preferenceKey) {
+                supersededKeys = this.memoryService.supersedeByPreferenceKey(preferenceKey, key, { sessionId: context.sessionId, projectId: context.projectId, timestamp: context.timestamp });
+            }
             this.logger.info('MemoryTools', 'Memory stored successfully', {
                 key,
                 type: detectedType,
@@ -320,6 +333,10 @@ class MemoryTools {
                 activeRule: `Stored as active rule:\n- ${content}`,
                 type: detectedType,
                 _directive: 'Apply this rule immediately. No need to call load_rules again.',
+                ...(supersededKeys.length > 0 && {
+                    supersededKeys,
+                    _supersessionNotice: `Superseded ${supersededKeys.length} prior rule(s) for preference_key="${preferenceKey}". Ignore any earlier text from these rules still in your context: ${supersededKeys.join(', ')}`
+                }),
                 ...(skillResults.length > 0 && {
                     _skillsGenerated: skillResults
                         .filter(r => r.action === 'created' || r.action === 'updated')
@@ -340,29 +357,59 @@ class MemoryTools {
             const { projectId } = input;
             const directive = this.getLoadRulesDirective();
             const rules = this.memoryService.loadActiveRules(projectId || context.projectId);
-            // Format categorized markdown sections
+            // Token budget — cap the load_rules payload so it doesn't dominate the host's
+            // context window (CC precedent: CAPPED_DEFAULT_MAX_TOKENS = 8_000 in utils/context.ts).
+            // Priority order of inclusion: corrections > preferences (by cite) > devops (by cite) > failures.
+            // Within each category, high-cited rules sink to the top so the first-to-drop are uncited.
+            const BUDGET = Number(process.env.CLAUDE_RECALL_LOAD_BUDGET_TOKENS ?? 2000);
+            const byCiteThenFresh = (a, b) => (b.cite_count || 0) - (a.cite_count || 0) ||
+                (b.timestamp || 0) - (a.timestamp || 0);
+            let remaining = BUDGET;
+            let droppedCount = 0;
+            const takeBounded = (items, maxCount) => {
+                const kept = [];
+                const limit = maxCount ?? items.length;
+                for (const item of items) {
+                    if (kept.length >= limit) {
+                        droppedCount += items.length - kept.length;
+                        break;
+                    }
+                    const cost = this.estimateTokens([item]);
+                    if (remaining - cost < 0) {
+                        droppedCount += items.length - kept.length;
+                        break;
+                    }
+                    kept.push(item);
+                    remaining -= cost;
+                }
+                return kept;
+            };
+            // Allocate in priority order (corrections first to protect high-signal items).
+            const keptCorrections = takeBounded(rules.corrections);
+            const keptPreferences = takeBounded([...rules.preferences].sort(byCiteThenFresh));
+            const keptDevops = takeBounded([...rules.devops].sort(byCiteThenFresh));
+            const keptFailures = takeBounded(rules.failures, 3);
+            // Format categorized markdown sections (output order stays user-familiar).
             const sections = [];
-            if (rules.preferences.length > 0) {
-                sections.push('## Preferences\n' + rules.preferences.map(m => {
+            if (keptPreferences.length > 0) {
+                sections.push('## Preferences\n' + keptPreferences.map(m => {
                     const val = formatRuleValue(m.value);
-                    // Only show key prefix if it's a meaningful name (not auto-generated)
                     const key = m.preference_key || m.key || '';
                     const isAutoKey = key.startsWith('memory_') || key.startsWith('auto_') || key.startsWith('pref_');
                     return isAutoKey ? `- ${val}` : `- ${key}: ${val}`;
                 }).join('\n'));
             }
-            if (rules.corrections.length > 0) {
-                sections.push('## Corrections\n' + rules.corrections.map(m => {
+            if (keptCorrections.length > 0) {
+                sections.push('## Corrections\n' + keptCorrections.map(m => {
                     const val = formatRuleValue(m.value);
                     const isPromoted = m.key.startsWith('promoted_') || m.value?.source === 'promotion-engine';
                     const evidence = isPromoted && m.value?.evidence_count ? ` (learned from ${m.value.evidence_count} observations)` : '';
                     return isPromoted ? `- [promoted lesson] ${val}${evidence}` : `- ${val}`;
                 }).join('\n'));
             }
-            if (rules.failures.length > 0) {
-                // Separate promoted lessons from regular failures
-                const promotedLessons = rules.failures.filter(m => m.key.startsWith('promoted_') || m.value?.source === 'promotion-engine');
-                const regularFailures = rules.failures.filter(m => !m.key.startsWith('promoted_') && m.value?.source !== 'promotion-engine');
+            if (keptFailures.length > 0) {
+                const promotedLessons = keptFailures.filter(m => m.key.startsWith('promoted_') || m.value?.source === 'promotion-engine');
+                const regularFailures = keptFailures.filter(m => !m.key.startsWith('promoted_') && m.value?.source !== 'promotion-engine');
                 if (promotedLessons.length > 0) {
                     sections.push('## Promoted Lessons (learned from repeated outcomes)\n' + promotedLessons.map(m => {
                         const val = formatRuleValue(m.value);
@@ -377,56 +424,28 @@ class MemoryTools {
                     }).join('\n'));
                 }
             }
-            if (rules.devops.length > 0) {
-                sections.push('## DevOps Rules\n' + rules.devops.map(m => {
+            if (keptDevops.length > 0) {
+                sections.push('## DevOps Rules\n' + keptDevops.map(m => {
                     const val = formatRuleValue(m.value);
                     return `- ${val}`;
                 }).join('\n'));
             }
-            // Add compliance section for rules loaded frequently but never cited
-            const compliance = this.memoryService.getComplianceReport(projectId || context.projectId);
-            const lowCompliance = compliance.rules.filter(r => r.load_count >= 5 && r.cite_count === 0);
-            if (lowCompliance.length > 0) {
-                sections.push('## Rule Health\nThese rules are loaded frequently but never cited — consider rewording or removing:\n' +
-                    lowCompliance.map(r => {
-                        let val;
-                        if (typeof r.value === 'string') {
-                            try {
-                                const parsed = JSON.parse(r.value);
-                                val = typeof parsed === 'string' ? parsed
-                                    : typeof parsed?.content === 'string' ? parsed.content
-                                        : typeof parsed?.value === 'string' ? parsed.value
-                                            : r.value;
-                            }
-                            catch {
-                                val = r.value;
-                            }
-                        }
-                        else if (typeof r.value === 'object' && r.value !== null) {
-                            const v = r.value;
-                            val = typeof v.content === 'string' ? v.content
-                                : typeof v.value === 'string' ? v.value
-                                    : JSON.stringify(r.value);
-                        }
-                        else {
-                            val = String(r.value ?? '');
-                        }
-                        return `- "${String(val).substring(0, 80)}" (loaded ${r.load_count}x, cited 0x)`;
-                    }).join('\n'));
+            // Truncation marker — turns a capacity failure into a discoverable affordance.
+            // Rule Health diagnostic moved to `npx claude-recall outcomes` to save ~10 lines/payload.
+            if (droppedCount > 0) {
+                sections.push(`*${droppedCount} more rules available via \`search_memory\`. Run \`npx claude-recall outcomes\` for full stats.*`);
             }
-            const totalRules = rules.preferences.length + rules.corrections.length +
-                rules.failures.length + rules.devops.length;
-            const resultTokens = this.estimateTokens([
-                ...rules.preferences, ...rules.corrections,
-                ...rules.failures, ...rules.devops
-            ]);
+            const totalRules = keptPreferences.length + keptCorrections.length +
+                keptFailures.length + keptDevops.length;
+            const keptAll = [...keptPreferences, ...keptCorrections, ...keptFailures, ...keptDevops];
+            const resultTokens = this.estimateTokens(keptAll);
             // Record to SearchMonitor so monitoring/stats still work
             this.searchMonitor.recordSearch('load_rules', totalRules, context.sessionId, 'mcp', { tool: 'load_rules', tokenMetrics: { resultTokens, tokensSaved: totalRules > 0 ? totalRules * 200 : 0 } });
-            // Track retrievals for outcome-aware scoring
+            // Track retrievals for outcome-aware scoring — only emitted rules, so dropped
+            // ones aren't credited as "retrieved" when the caller never saw them.
             try {
                 const outcomeStorage = outcome_storage_1.OutcomeStorage.getInstance();
-                const allMemories = [...rules.preferences, ...rules.corrections, ...rules.failures, ...rules.devops];
-                for (const m of allMemories) {
+                for (const m of keptAll) {
                     outcomeStorage.recordRetrieval(m.key);
                 }
             }
@@ -461,11 +480,12 @@ class MemoryTools {
             return {
                 rules: rulesText,
                 counts: {
-                    preferences: rules.preferences.length,
-                    corrections: rules.corrections.length,
-                    failures: rules.failures.length,
-                    devops: rules.devops.length,
-                    total: totalRules
+                    preferences: keptPreferences.length,
+                    corrections: keptCorrections.length,
+                    failures: keptFailures.length,
+                    devops: keptDevops.length,
+                    total: totalRules,
+                    dropped: droppedCount,
                 },
                 summary: rules.summary,
             };

package/dist/memory/storage.js

@@ -41,6 +41,7 @@ const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const test_pollution_1 = require("../services/test-pollution");
 class MemoryStorage {
     constructor(dbPath) {
         this.db = new better_sqlite3_1.default(dbPath);
@@ -562,6 +563,23 @@ class MemoryStorage {
         const stmt = this.db.prepare(`UPDATE memories SET ${setClause} WHERE key = ?`);
         stmt.run(...values, key);
     }
+    /**
+     * Get active memories (any type) that share the given preference_key.
+     * Used by store_memory's override path — a user can override a rule of any
+     * type (devops, correction, preference) as long as it was stored with a
+     * preference_key.
+     */
+    getActiveByPreferenceKeyAnyType(preferenceKey, projectId) {
+        let query = 'SELECT * FROM memories WHERE preference_key = ? AND is_active = 1';
+        const params = [preferenceKey];
+        if (projectId) {
+            query += ' AND (project_id = ? OR project_id IS NULL)';
+            params.push(projectId);
+        }
+        query += ' ORDER BY timestamp DESC';
+        const rows = this.db.prepare(query).all(...params);
+        return rows.map(row => this.rowToMemory(row));
+    }
     /**
      * Get preferences by preference key
      */
@@ -640,6 +658,174 @@ class MemoryStorage {
     incrementCiteCount(id) {
         this.db.prepare('UPDATE memories SET cite_count = cite_count + 1 WHERE id = ?').run(id);
     }
+    /**
+     * Demote rules that are loaded frequently but never cited.
+     * Matches rules where is_active=1, load_count >= minLoads, cite_count = 0,
+     * and timestamp older than minAgeDays. Flips is_active=0 and marks
+     * superseded_by='auto-demote' so they can be distinguished from preference supersession
+     * and selectively promoted back via promoteRule().
+     *
+     * Returns rows that were (or would be, in dryRun) demoted.
+     */
+    demoteStaleRules(options) {
+        const cutoff = Date.now() - options.minAgeDays * 86400000;
+        const candidates = this.db.prepare(`
+      SELECT id, key, type, load_count, cite_count, timestamp
+      FROM memories
+      WHERE is_active = 1
+        AND load_count >= ?
+        AND cite_count = 0
+        AND timestamp < ?
+        AND type IN ('preference', 'correction', 'failure', 'devops', 'project-knowledge')
+      ORDER BY load_count DESC
+    `).all(options.minLoads, cutoff);
+        if (!options.dryRun && candidates.length > 0) {
+            const ids = candidates.map(c => c.id);
+            const placeholders = ids.map(() => '?').join(',');
+            const now = Date.now();
+            this.db.prepare(`UPDATE memories SET is_active = 0, superseded_at = ?, superseded_by = 'auto-demote'
+         WHERE id IN (${placeholders})`).run(now, ...ids);
+            this.db.pragma('wal_checkpoint(TRUNCATE)');
+        }
+        return candidates;
+    }
+    /**
+     * Delete rows whose stored value matches legacy test-fixture patterns.
+     * Matches against json_extract(value, '$.content') OR the raw value (covers both
+     * structured and legacy string payloads). Returns rows that were (or would be,
+     * in dryRun) deleted. Destructive — CLI-gated, not called from boot.
+     */
+    deleteTestPollution(options) {
+        const dryRun = options?.dryRun ?? false;
+        if (test_pollution_1.TEST_POLLUTION_LIKE.length === 0)
+            return [];
+        const likeClauses = test_pollution_1.TEST_POLLUTION_LIKE
+            .map(() => `(json_extract(value, '$.content') LIKE ? OR value LIKE ?)`)
+            .join(' OR ');
+        const params = [];
+        for (const pat of test_pollution_1.TEST_POLLUTION_LIKE) {
+            params.push(pat, `%${pat.replace(/%$/, '')}%`);
+        }
+        const candidates = this.db
+            .prepare(`SELECT id, key, type, value FROM memories WHERE ${likeClauses}`)
+            .all(...params);
+        if (!dryRun && candidates.length > 0) {
+            const ids = candidates.map(c => c.id);
+            const placeholders = ids.map(() => '?').join(',');
+            this.db
+                .prepare(`DELETE FROM memories WHERE id IN (${placeholders})`)
+                .run(...ids);
+            this.db.pragma('wal_checkpoint(TRUNCATE)');
+        }
+        return candidates;
+    }
+    /**
+     * Retroactive dedup: collapse near-duplicate active rules that predate write-time
+     * fuzzy dedup (or slipped past its threshold).
+     *
+     * For each (type, project_id) group:
+     *   1. Sort by timestamp ASC (oldest first — preserves original authoring order).
+     *   2. Greedy clustering: for each unassigned rule, pull in all later rules with
+     *      Jaccard >= threshold into a cluster.
+     *   3. In each cluster of size > 1, keep the oldest as winner; sum cite/load
+     *      counts into it; mark the rest is_active=0, superseded_by='auto-dedup'.
+     *
+     * Returns one entry per collapse: {winnerId, loserId, similarity}.
+     */
+    dedupSimilar(options) {
+        const threshold = options.threshold ?? 0.65;
+        const dryRun = options.dryRun ?? false;
+        const RULE_TYPES = ['preference', 'correction', 'failure', 'devops', 'project-knowledge'];
+        const collapses = [];
+        for (const type of RULE_TYPES) {
+            const rows = this.db.prepare(`SELECT id, key, value, project_id, timestamp, load_count, cite_count
+         FROM memories
+         WHERE type = ? AND is_active = 1
+         ORDER BY COALESCE(project_id, ''), timestamp ASC`).all(type);
+            // Sub-group by project so cross-project rules never collapse into each other.
+            const byProject = new Map();
+            for (const row of rows) {
+                const pid = row.project_id ?? '';
+                const bucket = byProject.get(pid) ?? [];
+                bucket.push(row);
+                byProject.set(pid, bucket);
+            }
+            for (const bucket of byProject.values()) {
+                // Pre-tokenize once to avoid O(n^2) re-parse.
+                const tokenized = bucket.map(r => {
+                    let text = '';
+                    try {
+                        const parsed = JSON.parse(r.value);
+                        text = this.extractText(parsed);
+                    }
+                    catch {
+                        text = r.value;
+                    }
+                    return { ...r, text: text.toLowerCase() };
+                });
+                const assigned = new Set();
+                for (let i = 0; i < tokenized.length; i++) {
+                    const winner = tokenized[i];
+                    if (assigned.has(winner.id))
+                        continue;
+                    if (winner.text.length < 40)
+                        continue; // too short to fuzzy-match reliably
+                    let mergedCite = winner.cite_count;
+                    let mergedLoad = winner.load_count;
+                    const losers = [];
+                    for (let j = i + 1; j < tokenized.length; j++) {
+                        const candidate = tokenized[j];
+                        if (assigned.has(candidate.id))
+                            continue;
+                        if (candidate.text.length < 40)
+                            continue;
+                        const sim = this.jaccardSimilarity(winner.text, candidate.text);
+                        if (sim >= threshold) {
+                            assigned.add(candidate.id);
+                            losers.push({ id: candidate.id, key: candidate.key, cite: candidate.cite_count, load: candidate.load_count, sim });
+                            mergedCite += candidate.cite_count;
+                            mergedLoad += candidate.load_count;
+                        }
+                    }
+                    if (losers.length === 0)
+                        continue;
+                    for (const loser of losers) {
+                        collapses.push({
+                            winnerId: winner.id, winnerKey: winner.key,
+                            loserId: loser.id, loserKey: loser.key,
+                            similarity: Number(loser.sim.toFixed(3)),
+                        });
+                    }
+                    if (!dryRun) {
+                        const now = Date.now();
+                        this.db.prepare('UPDATE memories SET cite_count = ?, load_count = ? WHERE id = ?').run(mergedCite, mergedLoad, winner.id);
+                        const loserIds = losers.map(l => l.id);
+                        const placeholders = loserIds.map(() => '?').join(',');
+                        this.db.prepare(`UPDATE memories SET is_active = 0, superseded_by = 'auto-dedup', superseded_at = ?
+               WHERE id IN (${placeholders})`).run(now, ...loserIds);
+                    }
+                }
+            }
+        }
+        if (!dryRun && collapses.length > 0) {
+            this.db.pragma('wal_checkpoint(TRUNCATE)');
+        }
+        return collapses;
+    }
+    /**
+     * Restore a previously auto-demoted or auto-deduped rule. Only flips rows where
+     * superseded_by IN ('auto-demote', 'auto-dedup') — refuses to touch rules
+     * superseded by preference override logic (where superseded_by points at another key).
+     * Returns true if a row was restored.
+     */
+    promoteRule(id) {
+        const result = this.db.prepare(`UPDATE memories SET is_active = 1, superseded_at = NULL, superseded_by = NULL
+       WHERE id = ? AND is_active = 0 AND superseded_by IN ('auto-demote', 'auto-dedup')`).run(id);
+        if (result.changes > 0) {
+            this.db.pragma('wal_checkpoint(TRUNCATE)');
+        }
+        return result.changes > 0;
+    }
     /**
      * Get rules with their compliance metrics (load_count, cite_count).
      * Returns rules that have been loaded at least once.

package/dist/pi/extension.js

@@ -365,7 +365,13 @@ function default_1(pi) {
         label: 'Store Memory',
         description: 'Store a rule or learning. Use for: corrections, preferences, devops rules, failures.',
         promptSnippet: 'Store a rule, correction, or preference to memory',
-        parameters: {},
+        parameters: {
+            type: 'object',
+            properties: {
+                content: { type: 'string', description: 'The rule, correction, or preference to store' },
+            },
+            required: ['content'],
+        },
         async execute(_id, params, _signal, _onUpdate, _ctx) {
             try {
                 const content = params.content;
@@ -416,7 +422,13 @@ function default_1(pi) {
         label: 'Search Memory',
         description: 'Search memories by keyword. Returns matched memories ranked by relevance.',
         promptSnippet: 'Search stored memories by keyword',
-        parameters: {},
+        parameters: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Keyword or phrase to search for' },
+            },
+            required: ['query'],
+        },
         async execute(_id, params, _signal, _onUpdate, _ctx) {
             try {
                 const query = params.query;
@@ -466,7 +478,16 @@ function default_1(pi) {
         label: 'Save Task Checkpoint',
         description: 'Save a structured snapshot of work in progress (completed/remaining/blockers/notes). Replaces any previous checkpoint for this project. Call when ending a session or pausing on a task.',
         promptSnippet: 'Save a task checkpoint with what is done, what remains, and any blockers',
-        parameters: {},
+        parameters: {
+            type: 'object',
+            properties: {
+                completed: { type: 'string', description: 'What has been completed so far' },
+                remaining: { type: 'string', description: 'What remains to be done' },
+                blockers: { type: 'string', description: 'Any blockers or issues (use "none" if none)' },
+                notes: { type: 'string', description: 'Optional additional notes' },
+            },
+            required: ['completed', 'remaining', 'blockers'],
+        },
         async execute(_id, params, _signal, _onUpdate, _ctx) {
             try {
                 const { completed, remaining, blockers, notes } = params || {};
@@ -532,7 +553,13 @@ function default_1(pi) {
         name: 'recall_delete_memory',
         label: 'Delete Memory',
         description: 'Delete a specific memory by its ID. Use recall_search_memory first to find the ID.',
-        parameters: {},
+        parameters: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Memory ID to delete (use recall_search_memory to find IDs)' },
+            },
+            required: ['id'],
+        },
         async execute(_id, params, _signal, _onUpdate, _ctx) {
             try {
                 const id = params.id;

package/dist/services/memory.js

@@ -5,6 +5,7 @@ const storage_1 = require("../memory/storage");
 const retrieval_1 = require("../core/retrieval");
 const config_1 = require("./config");
 const logging_1 = require("./logging");
+const test_pollution_1 = require("./test-pollution");
 class MemoryService {
     constructor() {
         this.config = config_1.ConfigService.getInstance();
@@ -25,6 +26,16 @@ class MemoryService {
      */
     store(request) {
         try {
+            // Write-time guard: silently drop values matching known test-fixture patterns
+            // (Test preference 177…, Session test preference …, Memory with complex metadata,
+            // Test memory content). Prevents legacy test harnesses from re-polluting the DB.
+            if ((0, test_pollution_1.isTestPollution)(request.value)) {
+                this.logger.info('MemoryService', 'Dropped test-pollution write', {
+                    key: request.key,
+                    type: request.type,
+                });
+                return;
+            }
             // Check memory limits and notify if approaching
             const stats = this.getStats();
             const config = this.config.getConfig();
@@ -43,7 +54,9 @@ class MemoryService {
                 file_path: request.context?.filePath,
                 timestamp: request.context?.timestamp || Date.now(),
                 relevance_score: request.relevanceScore || 1.0,
-                scope: scope
+                scope: scope,
+                preference_key: request.preferenceKey,
+                is_active: true
             };
             this.storage.save(memory);
             this.logger.logMemoryOperation('STORE', {
@@ -303,6 +316,30 @@ class MemoryService {
             throw error;
         }
     }
+    /**
+     * Mark all currently-active memories with the given preference_key as superseded by newKey.
+     * Returns the list of superseded keys so callers can surface them to the agent — this
+     * closes the "I stored an override but the old rule is still in my context" gap.
+     */
+    supersedeByPreferenceKey(preferenceKey, newKey, context) {
+        if (!preferenceKey || !newKey)
+            return [];
+        const superseded = [];
+        try {
+            const pid = context.projectId || this.config.getProjectId();
+            const existing = this.storage.getActiveByPreferenceKeyAnyType(preferenceKey, pid);
+            for (const prev of existing) {
+                if (prev.key !== newKey) {
+                    this.storage.markSuperseded(prev.key, newKey);
+                    superseded.push(prev.key);
+                }
+            }
+        }
+        catch (error) {
+            this.logger.logServiceError('MemoryService', 'supersedeByPreferenceKey', error, { preferenceKey, newKey });
+        }
+        return superseded;
+    }
     /**
      * Mark existing preferences as superseded
      */
@@ -378,21 +415,25 @@ class MemoryService {
         try {
             const pid = projectId || this.config.getProjectId();
             const searchContext = { project_id: pid };
+            // All categories filter is_active so auto-demoted rules are excluded uniformly.
+            const isActive = (m) => m.is_active !== false;
             // Preferences: active only
             const allPreferences = this.storage.searchByContext({ ...searchContext, type: 'preference' });
-            const preferences = allPreferences.filter(m => m.is_active !== false);
+            const preferences = allPreferences.filter(isActive);
             // Corrections: top 10 by timestamp
             const allCorrections = this.storage.searchByContext({ ...searchContext, type: 'correction' });
             const corrections = allCorrections
+                .filter(isActive)
                 .sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0))
                 .slice(0, 10);
             // Failures: top 5 by timestamp
             const allFailures = this.storage.searchByContext({ ...searchContext, type: 'failure' });
             const failures = allFailures
+                .filter(isActive)
                 .sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0))
                 .slice(0, 5);
-            // DevOps: all rules
-            const devops = this.storage.searchByContext({ ...searchContext, type: 'devops' });
+            // DevOps: all active rules
+            const devops = this.storage.searchByContext({ ...searchContext, type: 'devops' }).filter(isActive);
             const counts = [
                 preferences.length && `${preferences.length} preferences`,
                 corrections.length && `${corrections.length} corrections`,
@@ -427,6 +468,52 @@ class MemoryService {
             this.storage.incrementCiteCount(memory.id);
         }
     }
+    /**
+     * Auto-demote rules that burn context without earning citations.
+     * Reads env vars: CLAUDE_RECALL_AUTO_DEMOTE (gate), CLAUDE_RECALL_DEMOTE_MIN_LOADS (default 20),
+     * CLAUDE_RECALL_DEMOTE_MIN_AGE_DAYS (default 7).
+     * Safe to call on every boot — idempotent, only acts on newly-qualifying rules.
+     */
+    autoDemoteStaleRules(options) {
+        const force = options?.force ?? false;
+        if (!force && process.env.CLAUDE_RECALL_AUTO_DEMOTE !== 'true') {
+            return [];
+        }
+        const minLoads = options?.minLoads ?? Number(process.env.CLAUDE_RECALL_DEMOTE_MIN_LOADS ?? 20);
+        const minAgeDays = options?.minAgeDays ?? Number(process.env.CLAUDE_RECALL_DEMOTE_MIN_AGE_DAYS ?? 7);
+        const dryRun = options?.dryRun ?? false;
+        try {
+            const demoted = this.storage.demoteStaleRules({ minLoads, minAgeDays, dryRun });
+            if (demoted.length > 0) {
+                this.logger.info('MemoryService', `${dryRun ? 'Would demote' : 'Demoted'} ${demoted.length} stale rules (load>=${minLoads}, cite=0, age>${minAgeDays}d)`, { count: demoted.length, dryRun });
+            }
+            return demoted;
+        }
+        catch (error) {
+            this.logger.logServiceError('MemoryService', 'autoDemoteStaleRules', error);
+            return [];
+        }
+    }
+    /**
+     * Restore an auto-demoted rule. Returns true if the row was flipped back.
+     */
+    promoteRule(id) {
+        return this.storage.promoteRule(id);
+    }
+    /**
+     * Delete legacy test-fixture rows that leaked into the production DB.
+     * Destructive — exposed via CLI only, not called from boot.
+     */
+    cleanupTestPollution(options) {
+        return this.storage.deleteTestPollution(options);
+    }
+    /**
+     * Retroactive fuzzy dedup. Write-time dedup (findFuzzyDuplicate) handles new
+     * writes; this method catches duplicates that predate it or crossed its threshold.
+     */
+    dedupSimilarRules(options) {
+        return this.storage.dedupSimilar(options ?? {});
+    }
     /**
      * Get top N rules scored for sync to Claude Code's auto-memory directory.
      * Scores by: (cite_count * 3) + (load_count * 0.5) + recency_bonus.

package/dist/services/test-pollution.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Test-pollution patterns — values produced by legacy unit/integration test fixtures
+ * that leaked into the production memory DB. Centralized here so the write-time guard
+ * (MemoryService.store) and the cleanup command (MemoryStorage.deleteTestPollution)
+ * never drift.
+ *
+ * If you legitimately want to test the store path, use values that don't match these
+ * patterns (e.g. fixture strings that include the test name, not "Test preference 177…").
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEST_POLLUTION_LIKE = exports.TEST_POLLUTION_REGEXES = void 0;
+exports.isTestPollution = isTestPollution;
+exports.TEST_POLLUTION_REGEXES = [
+    /^Test preference \d+/i,
+    /^Session test preference \d+/i,
+    /^Memory with complex metadata$/i,
+    /^Test memory content$/i,
+];
+/**
+ * SQL LIKE patterns (case-insensitive via COLLATE NOCASE) mirroring the regexes above.
+ * better-sqlite3 has no regex built-in; LIKE is enough for these anchored prefixes.
+ */
+exports.TEST_POLLUTION_LIKE = [
+    'Test preference 1%',
+    'Session test preference 1%',
+    'Memory with complex metadata',
+    'Test memory content',
+];
+function extractContentString(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value && typeof value === 'object') {
+        const v = value;
+        if (typeof v.content === 'string')
+            return v.content;
+        if (typeof v.value === 'string')
+            return v.value;
+        if (typeof v.title === 'string')
+            return v.title;
+    }
+    return '';
+}
+/**
+ * Returns true if the provided memory value looks like test-fixture pollution.
+ * Only string-ish payloads are inspected; structured rules with real content pass through.
+ */
+function isTestPollution(value) {
+    const str = extractContentString(value);
+    if (!str)
+        return false;
+    return exports.TEST_POLLUTION_REGEXES.some(rx => rx.test(str));
+}

package/package.json

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