claude-recall 0.35.0 → 0.36.1

package/README.md

@@ -42,6 +42,21 @@ $ claude-recall search "pnpm"
 
 ---
 
+## Why not just steering files or CLAUDE.md?
+
+Use them! They're the right tool for **team standards you already know** — written by hand, reviewed in PRs, shipped with the repo. Claude Recall covers what they structurally can't:
+
+- **Nobody writes it down.** Steering files hold what you remembered to document. Recall captures rules *in the flow of work* — you correct the agent once, mid-session, and it's stored. The stuff that burns you repeatedly is exactly the stuff too small to feel worth documenting.
+- **They can't learn from failure.** There's no steering-file mechanism for *tool failure → lesson → rule*. "Exit code 0 doesn't mean the tests passed" enters Recall because the agent got burned — not because someone wrote a postmortem.
+- **One memory, every agent.** Steering is Kiro-only, CLAUDE.md is Claude-Code-only. Recall is one local DB behind Claude Code, Kiro, and Pi — correct one agent, all of them know.
+- **They rot.** Nobody prunes a rules file. Recall tracks whether rules are actually used, demotes dead ones, and a daily LLM janitor merges duplicates and cleans noise.
+- **Personal ≠ repo.** "GPG signing fails in *my* WSL" doesn't belong in a committed file. Recall is per-developer and never touches your repo.
+- **They bloat context.** An always-included steering file ships its full text into every interaction, relevant or not, and only ever grows. Recall's injection is token-budgeted, surfaces rules relevant to the action at hand, and the corpus self-prunes — the context cost stays bounded as the memory grows.
+
+In short: steering files are documentation — what your team decided. Claude Recall is memory — what your sessions taught.
+
+---
+
 ## Features
 
 - **Automatic capture** — an LLM classifier detects preferences, corrections, and project facts in your normal prompts, running on **the agent's own LLM** (Claude subscription / Kiro credits — never a separate API key), with regex fallback when no LLM is available
@@ -180,6 +195,8 @@ Once installed, Claude Recall works in the background (CC = Claude Code):
 
 Classification runs on each runtime's **own** LLM — Claude Code via headless `claude -p` on your subscription; Kiro via `kiro-cli chat --no-interactive` on Kiro credits — with regex as the fallback. **An exported `ANTHROPIC_API_KEY` is never touched** unless you explicitly opt in with `CLAUDE_RECALL_PREFER_API_KEY=1`. No API key is ever required; no configuration needed.
 
+Captured rules are kept **precise and current**: the classifier phrases each rule as *trigger + concrete pattern* where your message allows ("email files must start with email" → *"When creating an email text file, name it `email_*.txt`"*); a rule too vague to act on is stored but flagged, and the agent is nudged at injection time to ask you for a precise restatement. When you restate an existing rule in new words, the **new phrasing supersedes the old row** (counters carry over) instead of creating a duplicate or being swallowed by the old wording.
+
 ```bash
 # Verify it's working
 claude-recall stats
@@ -194,6 +211,7 @@ claude-recall search "preference"
 claude-recall status                     # Installation health: hooks, MCP, DB path, project ID
 claude-recall stats                      # What's in the DB for this project (--global for all)
 
+claude-recall list                       # List all memories, newest first (-t <type>, --all, --json, --global)
 claude-recall search "query"             # Search this project's memories (--global, --json, --project <id>)
 claude-recall failures                   # What broke and what fixed it
 claude-recall outcomes                   # Outcome-aware learning status
@@ -256,6 +274,7 @@ claude-recall hooks test-enforcement     # Test if search enforcer hook works
 
 # ── Memory ───────────────────────────────────────────────────────────
 claude-recall stats                      # Memory statistics (--global for all projects)
+claude-recall list                       # List memories, newest first (-t <type>, --all, --json, --global)
 claude-recall search "query"             # Search memories (--global, --json, --project <id>)
 claude-recall store "content"            # Store memory directly
 claude-recall store "content" -t <type>  # Type: preference, correction, failure, devops, project-knowledge

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

@@ -733,6 +733,85 @@ class ClaudeRecallCLI {
         });
         this.logger.info('CLI', 'Search completed', { query, resultCount: results.length });
     }
+    /**
+     * List (enumerate) stored memories — no query, no ranking, no relevance cap.
+     *
+     * Fills the gap between `search` (needs a query, returns ranked top-N) and
+     * `stats` (counts only, no content). Backed by getAllByProject/getAllMemories
+     * so it returns EVERYTHING in scope, newest first. Shows the numeric id and
+     * key so rows can be fed to `delete <key>` / `rules promote <id>`.
+     */
+    listMemories(options) {
+        // Scope resolution mirrors search(): current project (+ universal/unscoped)
+        // by default, a named project, or every project with --global.
+        let memories;
+        let scopeLabel;
+        if (options.global) {
+            memories = this.memoryService.getAllMemories();
+            scopeLabel = 'all projects';
+        }
+        else {
+            const projectId = options.project || config_1.ConfigService.getInstance().getProjectId();
+            memories = this.memoryService.getAllByProject(projectId);
+            scopeLabel = `project: ${projectId}`;
+        }
+        if (options.type) {
+            memories = memories.filter(m => m.type === options.type);
+        }
+        // Newest first — most recently learned memory at the top.
+        memories.sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0));
+        const total = memories.length;
+        const limit = options.all ? total : (0, parse_utils_1.parsePositiveInt)(options.limit, 'limit', 20);
+        const shown = memories.slice(0, limit);
+        if (options.json) {
+            console.log(JSON.stringify(shown.map(m => ({
+                id: m.id,
+                key: m.key,
+                type: m.type,
+                value: m.value,
+                project_id: m.project_id,
+                scope: m.scope,
+                is_active: m.is_active,
+                timestamp: m.timestamp,
+            })), null, 2));
+            return;
+        }
+        const typeFilter = options.type ? ` of type "${options.type}"` : '';
+        console.log(`\n🧠 Memories (${scopeLabel})\n`);
+        console.log(`${total} memor${total === 1 ? 'y' : 'ies'}${typeFilter}${total > shown.length ? ` — showing ${shown.length} (use --all or --limit)` : ''}\n`);
+        if (shown.length === 0) {
+            console.log('No memories found.\n');
+            return;
+        }
+        for (const m of shown) {
+            const inactive = m.is_active === false ? ' 💤 inactive' : '';
+            const when = m.timestamp ? new Date(m.timestamp).toLocaleString() : 'unknown time';
+            console.log(`[${m.id ?? '?'}] ${m.type}${inactive} · ${when}`);
+            console.log(`   ${this.truncateContent(this.extractContent(m.value))}`);
+            console.log(`   key: ${m.key}`);
+            console.log('');
+        }
+        this.logger.info('CLI', 'List completed', { scope: scopeLabel, total, shown: shown.length });
+    }
+    /**
+     * Pull the human-readable text out of a memory value, whether it's a raw
+     * string, a JSON string, or a structured object with a content/value field.
+     */
+    extractContent(value) {
+        let v = value;
+        if (typeof v === 'string') {
+            try {
+                v = JSON.parse(v);
+            }
+            catch {
+                return value;
+            }
+        }
+        if (v && typeof v === 'object') {
+            return String(v.content ?? v.value ?? v.text ?? JSON.stringify(v));
+        }
+        return String(v);
+    }
     /**
      * Export memories to a file
      */
@@ -1869,6 +1948,28 @@ async function main() {
         });
         process.exit(0);
     });
+    // List command — enumerate memories (no query, unlike `search`)
+    program
+        .command('list')
+        .description('List stored memories (no query needed; newest first)')
+        .option('-t, --type <type>', 'Filter by memory type (preference, failure, devops, ...)')
+        .option('-l, --limit <number>', 'Maximum memories to show', '20')
+        .option('--all', 'Show every memory in scope (ignores --limit)')
+        .option('--project <id>', 'List a specific project (includes universal memories)')
+        .option('--global', 'List memories across all projects')
+        .option('--json', 'Output as JSON')
+        .action((options) => {
+        const cli = new ClaudeRecallCLI(program.opts());
+        cli.listMemories({
+            type: options.type,
+            limit: (0, parse_utils_1.parsePositiveInt)(options.limit, 'limit', 20),
+            all: options.all,
+            project: options.project,
+            global: options.global,
+            json: options.json,
+        });
+        process.exit(0);
+    });
     // Stats command
     program
         .command('stats')

package/dist/hooks/correction-detector.js

@@ -65,7 +65,15 @@ async function handleCorrectionDetector(input) {
         (0, shared_1.hookLog)('correction-detector', `Skipped duplicate: ${result.extract.substring(0, 80)}`);
         return;
     }
-    (0, shared_1.storeMemory)(result.extract, result.type, undefined, result.confidence);
+    // fuzzyNewestWins: a user restating an existing rule in new words is a
+    // deliberate refinement — the new phrasing supersedes the old row instead
+    // of being absorbed into it. needsPrecision: vague-but-durable rules are
+    // stored (losing what the user said is worse) but flagged so injection
+    // nudges the agent to ask for a precise restatement.
+    (0, shared_1.storeMemory)(result.extract, result.type, undefined, result.confidence, {
+        needsPrecision: result.precision === 'vague',
+        fuzzyNewestWins: true,
+    });
     const summary = result.extract.length > 60
         ? result.extract.substring(0, 60) + '...'
         : result.extract;

package/dist/hooks/kiro-classifier.js

@@ -46,7 +46,7 @@ function buildClassifyPrompt(text) {
     return ('You are a memory classifier for a developer tool. Classify the USER MESSAGE ' +
         'into exactly one type and respond with ONLY minified JSON — no markdown, no ' +
         'prose, no code fence:\n' +
-        '{"type":"correction|preference|failure|devops|project-knowledge|none","confidence":0.0-1.0,"extract":"<concise imperative rule to remember, or empty>"}\n\n' +
+        '{"type":"correction|preference|failure|devops|project-knowledge|none","confidence":0.0-1.0,"extract":"<concise imperative rule to remember, or empty>","precision":"precise|vague"}\n\n' +
         'Types:\n' +
         '- correction: user durably correcting how something should ALWAYS be done ("no, use X not Y"). Correcting a one-off action in the current task is NOT durable.\n' +
         '- preference: a reusable directive about how the user wants things done ("I prefer X", "we use tabs", "my favourite color is green"). Must apply beyond this one message.\n' +
@@ -61,7 +61,14 @@ function buildClassifyPrompt(text) {
         '- Reject meta-conversation about this tool or what to write/do next.\n\n' +
         'Be conservative: when in doubt use "none" with confidence 0. Use confidence >= 0.75 for correction/preference/devops. ' +
         'extract must be a clean standalone rule (e.g. "Favourite colour is green"), or empty when type is none.\n\n' +
-        'Examples: "we use pnpm, not npm" → {"type":"preference","confidence":0.9,"extract":"Use pnpm, not npm"}; ' +
+        'PRECISION — a rule is applied at a future moment of decision, so make the extract as precise as the message allows: ' +
+        'name the TRIGGER (when it applies) and the CONCRETE pattern (what exactly to do), e.g. ' +
+        '"email files must start with email" → "When creating an email text file, name it email_*.txt". ' +
+        'Never invent details the message does not contain. Add "precision":"vague" when the rule is durable but its ' +
+        'trigger or concrete pattern is missing and cannot be inferred (e.g. "name docs so they sort together" — sort by what?); ' +
+        'otherwise "precision":"precise".\n\n' +
+        'Examples: "we use pnpm, not npm" → {"type":"preference","confidence":0.9,"extract":"Use pnpm, not npm","precision":"precise"}; ' +
+        '"name docs so they sort together" → {"type":"preference","confidence":0.8,"extract":"Name documents so they sort together in the file explorer","precision":"vague"}; ' +
         '"first fix the sentence" → {"type":"none","confidence":0,"extract":""}; ' +
         '"then run claude-recall kiro setup" → {"type":"none","confidence":0,"extract":""}.\n\n' +
         'USER MESSAGE: ' + text);
@@ -104,6 +111,9 @@ function extractClassification(raw) {
         type: parsed.type,
         confidence,
         extract: parsed.extract.trim(),
+        ...(parsed.precision === 'vague' || parsed.precision === 'precise'
+            ? { precision: parsed.precision }
+            : {}),
     };
 }
 /**

package/dist/hooks/kiro-hooks.js

@@ -120,7 +120,7 @@ function formatRulesForContext() {
     const section = (title, items) => {
         if (items.length === 0)
             return null;
-        return `## ${title}\n` + items.map(m => `- ${(0, memory_tools_1.formatRuleValue)(m.value)}`).join('\n');
+        return `## ${title}\n` + items.map(m => `- ${(0, memory_tools_1.formatRuleValue)(m.value)}${(0, memory_tools_1.precisionNudge)(m.value)}`).join('\n');
     };
     const sections = [
         section('Preferences', rules.preferences),

package/dist/hooks/llm-classifier.js

@@ -37,7 +37,9 @@ const SYSTEM_PROMPT = `You are a memory classifier for a developer tool. Classif
 - none: Casual conversation, questions, code snippets, one-off task instructions, meta-conversation, sentence fragments, or anything not worth remembering across sessions
 
 Respond with ONLY valid JSON (no markdown fences). Format:
-{"type":"<type>","confidence":<0.0-1.0>,"extract":"<the key fact to remember, concise>"}
+{"type":"<type>","confidence":<0.0-1.0>,"extract":"<the key fact to remember, concise>","precision":"precise|vague"}
+
+PRECISION — a rule is applied at a future moment of decision, so make the extract as precise as the text allows: name the TRIGGER (when it applies) and the CONCRETE pattern (what exactly to do), e.g. "email files must start with email" → "When creating an email text file, name it email_*.txt". Never invent details the text does not contain. Set "precision":"vague" when the rule is durable but its trigger or concrete pattern is missing and cannot be inferred; otherwise "precision":"precise".
 
 THE STANDALONE TEST — apply this BEFORE classifying anything as correction/preference/devops:
 A durable rule must make complete sense on its own, read cold in a future session with NO knowledge of this conversation. If the text needs the surrounding chat to be understood, it is "none".
@@ -219,6 +221,9 @@ async function classifyWithLLM(text) {
             type: result.type,
             confidence: result.confidence,
             extract: result.extract,
+            ...(result.precision === 'vague' || result.precision === 'precise'
+                ? { precision: result.precision }
+                : {}),
         };
     }
     catch {

package/dist/hooks/memory-janitor.js

@@ -61,6 +61,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.claimJanitorRun = claimJanitorRun;
 exports.maybeSpawnJanitor = maybeSpawnJanitor;
+exports.dropCosmeticRewrites = dropCosmeticRewrites;
 exports.buildJanitorPrompt = buildJanitorPrompt;
 exports.parseJanitorActions = parseJanitorActions;
 exports.applyJanitorActions = applyJanitorActions;
@@ -157,15 +158,19 @@ function maybeSpawnJanitor(input, runtime) {
         (0, shared_1.hookLog)(HOOK_NAME, `spawn failed: ${(0, shared_1.safeErrorMessage)(err)}`);
     }
 }
-/** Render one rule for the review prompt — id, type, counters, age, text. */
-function renderRuleForReview(rule, nowMs) {
-    let text;
+/** Threshold above which a rewrite is judged cosmetic and dropped. */
+const REWRITE_MIN_CHANGE_SIMILARITY = 0.8;
+/** Extract a rule's display text from its stored value. */
+function ruleText(rule) {
     try {
-        text = (0, memory_tools_1.formatRuleValue)(JSON.parse(rule.value));
+        return (0, memory_tools_1.formatRuleValue)(JSON.parse(rule.value));
     }
     catch {
-        text = String(rule.value);
+        return String(rule.value);
     }
+}
+/** Render one rule for the review prompt — id, type, counters, age, text. */
+function renderRuleForReview(rule, nowMs) {
     const ageDays = Math.max(0, Math.round((nowMs - rule.timestamp) / 86400000));
     return JSON.stringify({
         id: rule.id,
@@ -173,7 +178,27 @@ function renderRuleForReview(rule, nowMs) {
         loads: rule.load_count,
         cites: rule.cite_count,
         age_days: ageDays,
-        text: text.slice(0, 400),
+        text: ruleText(rule).slice(0, 400),
+    });
+}
+/**
+ * Deterministic backstop against cosmetic rewrites: whatever the LLM claims,
+ * a rewrite whose replacement is near-identical to the original changes
+ * nothing at decision time and just churns the row. Observed live on the
+ * first wild run ("already specific and actionable; minor clarification
+ * only" — and it rewrote anyway).
+ */
+function dropCosmeticRewrites(actions, textById) {
+    return actions.filter((a) => {
+        if (a.action !== 'rewrite')
+            return true;
+        const original = textById.get(a.ids[0]) ?? '';
+        const similarity = (0, shared_1.jaccardSimilarity)(original, a.replacement ?? '');
+        if (similarity >= REWRITE_MIN_CHANGE_SIMILARITY) {
+            (0, shared_1.hookLog)(HOOK_NAME, `dropped cosmetic rewrite [${a.ids[0]}] (similarity=${similarity.toFixed(2)})`);
+            return false;
+        }
+        return true;
     });
 }
 function buildJanitorPrompt(ruleLines) {
@@ -195,6 +220,9 @@ function buildJanitorPrompt(ruleLines) {
         'the naming prefix of similar files — email files are email_*.txt".\n\n' +
         'Be conservative:\n' +
         '- When unsure, DO NOTHING with that rule. An empty actions array is a valid answer.\n' +
+        '- If a rule is ALREADY precise, do not rewrite it. A cosmetic rephrasing or ' +
+        '"minor clarification" is not an action — rewrite ONLY when the current wording ' +
+        'would fail to trigger at the moment of decision.\n' +
         '- Never rewrite meaning — only clarity. Never merge rules that differ in substance.\n' +
         '- Specific, actionable rules are valuable even if rarely used. Low usage counters alone are NOT grounds to demote.\n' +
         '- Do not demote failure lessons that name a specific command, file, or error.\n\n' +
@@ -271,9 +299,16 @@ function applyJanitorActions(actions, rulesById, opts = {}) {
             if (!opts.dryRun) {
                 if (action.action === 'merge' || action.action === 'rewrite') {
                     const type = action.type ?? rulesById.get(action.ids[0])?.type ?? 'preference';
-                    (0, shared_1.storeMemory)(action.replacement, type, undefined, 0.9);
+                    // fuzzyNewestWins: without it, a replacement similar to the rule it
+                    // replaces gets absorbed into that still-active row by fuzzy dedup —
+                    // then the demote below would destroy both versions.
+                    (0, shared_1.storeMemory)(action.replacement, type, undefined, 0.9, { fuzzyNewestWins: true });
                 }
-                applied = storage.demoteRulesByIds(action.ids, 'janitor') > 0;
+                const demoted = storage.demoteRulesByIds(action.ids, 'janitor');
+                // For merge/rewrite the store above already succeeded (no throw), and
+                // newest-wins supersession may have retired the source row before the
+                // demote ran (changes=0) — the action still applied.
+                applied = action.action === 'demote' ? demoted > 0 : true;
             }
             else {
                 applied = true; // would apply
@@ -325,7 +360,8 @@ async function handleMemoryJanitorWorker(_input, opts = {}) {
             return null;
         }
         const validIds = new Set(reviewable.map(r => r.id));
-        const actions = parseJanitorActions(raw, validIds);
+        const textById = new Map(reviewable.map(r => [r.id, ruleText(r)]));
+        const actions = dropCosmeticRewrites(parseJanitorActions(raw, validIds), textById);
         (0, shared_1.hookLog)(HOOK_NAME, `reviewed ${reviewable.length} rules → ${actions.length} action(s)${opts.dryRun ? ' (dry-run)' : ''}`);
         const rulesById = new Map(reviewable.map(r => [r.id, { id: r.id, type: r.type }]));
         const results = applyJanitorActions(actions, rulesById, { dryRun: opts.dryRun });

package/dist/hooks/shared.js

@@ -275,7 +275,7 @@ function isDuplicate(content, existingMemories, threshold = 0.7) {
 /**
  * Store a memory via MemoryService (in-process, no subprocess).
  */
-function storeMemory(content, type, projectId, confidence = 0.8) {
+function storeMemory(content, type, projectId, confidence = 0.8, opts) {
     const memoryService = memory_1.MemoryService.getInstance();
     const key = `hook_${type}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
     memoryService.store({
@@ -285,6 +285,9 @@ function storeMemory(content, type, projectId, confidence = 0.8) {
             confidence,
             source: 'hook-auto-capture',
             timestamp: Date.now(),
+            // Vague-but-durable rule: injection nudges the agent to ask the user
+            // for a precise restatement (trigger + concrete pattern).
+            ...(opts?.needsPrecision ? { needs_precision: true } : {}),
         },
         type,
         context: {
@@ -292,7 +295,7 @@ function storeMemory(content, type, projectId, confidence = 0.8) {
             timestamp: Date.now(),
         },
         relevanceScore: confidence,
-    });
+    }, { fuzzyNewestWins: opts?.fuzzyNewestWins });
 }
 /**
  * Search existing memories for dedup comparison.

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemoryTools = void 0;
+exports.precisionNudge = precisionNudge;
 exports.formatRuleValue = formatRuleValue;
 const config_1 = require("../../services/config");
 const search_monitor_1 = require("../../services/search-monitor");
@@ -25,6 +26,17 @@ const directives_1 = require("../../shared/directives");
  *
  * Exported for direct unit testing in tests/unit/format-rule-value.test.ts.
  */
+/**
+ * Injection-time nudge for rules the capture classifier graded as vague
+ * (needs_precision in the stored value). Hooks have no interactive channel to
+ * the user, but the AGENT does — the marker instructs it to ask for a precise
+ * restatement, whose capture then supersedes this row via fuzzy newest-wins.
+ */
+function precisionNudge(value) {
+    return value && typeof value === 'object' && value.needs_precision === true
+        ? ' ⚠️ [vague — ask the user to restate this rule with its trigger and concrete pattern, e.g. "when X, do Y"]'
+        : '';
+}
 function formatRuleValue(value) {
     if (value == null)
         return '';
@@ -333,7 +345,7 @@ class MemoryTools {
             const sections = [];
             if (keptPreferences.length > 0) {
                 sections.push('## Preferences\n' + keptPreferences.map(m => {
-                    const val = formatRuleValue(m.value);
+                    const val = formatRuleValue(m.value) + precisionNudge(m.value);
                     const key = m.preference_key || m.key || '';
                     const isAutoKey = key.startsWith('memory_') || key.startsWith('auto_') || key.startsWith('pref_');
                     return isAutoKey ? `- ${val}` : `- ${key}: ${val}`;
@@ -341,7 +353,7 @@ class MemoryTools {
             }
             if (keptCorrections.length > 0) {
                 sections.push('## Corrections\n' + keptCorrections.map(m => {
-                    const val = formatRuleValue(m.value);
+                    const val = formatRuleValue(m.value) + precisionNudge(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}`;
@@ -366,7 +378,7 @@ class MemoryTools {
             }
             if (keptDevops.length > 0) {
                 sections.push('## DevOps Rules\n' + keptDevops.map(m => {
-                    const val = formatRuleValue(m.value);
+                    const val = formatRuleValue(m.value) + precisionNudge(m.value);
                     return `- ${val}`;
                 }).join('\n'));
             }

package/dist/memory/storage.js

@@ -346,7 +346,7 @@ class MemoryStorage {
         const union = wordsA.size + wordsB.size - intersection;
         return union === 0 ? 0 : intersection / union;
     }
-    save(memory) {
+    save(memory, opts) {
         const contentHash = this.computeContentHash(memory.value, memory.type);
         // Write-time dedup: identical content already stored under a different key.
         // Scoped to the same project (or universal/unscoped) — without the project
@@ -388,11 +388,24 @@ class MemoryStorage {
         const fuzzyMatch = MemoryStorage.RULE_TYPES.includes(memory.type)
             ? this.findFuzzyDuplicate(memory)
             : null;
-        if (fuzzyMatch) {
+        if (fuzzyMatch && !opts?.fuzzyNewestWins) {
             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;
         }
+        // Newest-wins supersession (opt-in, user-prompt captures and janitor
+        // replacements): a user restating a rule in different words is a
+        // deliberate refinement — the NEW phrasing must win, not be absorbed into
+        // the old row (which is what the bump above does, and which silently
+        // discarded precise re-teaches of vague rules). The new row is inserted
+        // below; the old row is superseded BY KEY (not a hygiene sentinel), so it
+        // is not revivable — it was replaced, not judged noise. Compliance
+        // counters carry over so demotion/ranking history isn't reset by a
+        // rewording.
+        let fuzzySupersede = null;
+        if (fuzzyMatch && opts?.fuzzyNewestWins && fuzzyMatch !== memory.key) {
+            fuzzySupersede = { key: fuzzyMatch };
+        }
         // Upsert instead of INSERT OR REPLACE: OR REPLACE deletes and reinserts,
         // which resets columns absent from the insert list (load_count, cite_count,
         // last_accessed) and churns the rowid. A same-key re-save must not destroy
@@ -420,6 +433,15 @@ class MemoryStorage {
         content_hash = excluded.content_hash
     `);
         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, contentHash);
+        // Newest-wins: retire the fuzzy-matched old row in favor of the row just
+        // written, carrying its compliance counters over.
+        if (fuzzySupersede) {
+            const old = this.db.prepare('SELECT load_count, cite_count FROM memories WHERE key = ?').get(fuzzySupersede.key);
+            this.db.prepare(`UPDATE memories SET is_active = 0, superseded_by = ?, superseded_at = ? WHERE key = ?`).run(memory.key, Date.now(), fuzzySupersede.key);
+            if (old) {
+                this.db.prepare('UPDATE memories SET load_count = ?, cite_count = ? WHERE key = ?').run(old.load_count || 0, old.cite_count || 0, memory.key);
+            }
+        }
         // 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)');

package/dist/services/memory.js

@@ -31,7 +31,7 @@ class MemoryService {
     /**
      * Store a memory with proper context and logging
      */
-    store(request) {
+    store(request, opts) {
         try {
             // Write-time guard: silently drop values matching known test-fixture patterns
             // (Test preference 177…, Session test preference …, Memory with complex metadata,
@@ -66,7 +66,7 @@ class MemoryService {
                 preference_key: request.preferenceKey,
                 is_active: true
             };
-            this.storage.save(memory);
+            this.storage.save(memory, opts);
             this.logger.logMemoryOperation('STORE', {
                 key: request.key,
                 type: request.type,

package/docs/using-claude-code-subscription-instead-of-api-key.md

@@ -0,0 +1,69 @@
+# Wiring a project to the Claude Code subscription (no API key)
+
+The mechanism: don't call the Anthropic API at all — **shell out to the `claude`
+CLI**, which is already authenticated by the user's Claude Code subscription
+login. No key, no billing setup; it borrows the session the user logged into.
+
+> Applies to any project. Replace the placeholder name (`MY_APP_NESTED`) with
+> your own convention.
+
+## The core idea
+
+`claude -p "<prompt>"` runs a one-shot, non-interactive completion using the
+subscription auth. Your project spawns it as a subprocess and reads stdout.
+That's the whole trick.
+
+```bash
+claude -p "Summarize this in one line: ..."      # prints completion to stdout, exits
+```
+
+## Wiring it into any project
+
+Spawn it non-interactively (never through a shell string — pass args to avoid
+injection):
+
+```ts
+import { spawn } from 'node:child_process';
+
+function complete(prompt: string, timeoutMs = 60_000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const p = spawn('claude', ['-p', prompt], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+      env: { ...process.env, MY_APP_NESTED: '1' }, // recursion guard
+    });
+    let out = '', err = '';
+    p.stdout.on('data', d => (out += d));
+    p.stderr.on('data', d => (err += d));
+    p.on('close', code =>
+      code === 0 ? resolve(out.trim()) : reject(new Error(err || `exit ${code}`)));
+    p.on('error', reject);
+  });
+}
+```
+
+## The things that bite people
+
+- **Recursion.** If your code runs *inside* a Claude Code session (a hook, an
+  MCP tool) and then spawns `claude -p`, that child can trigger the same hook
+  and fork-bomb. Set a sentinel env var on the child and bail at the top of your
+  entry point if it's present.
+- **Availability.** Require `claude` to be installed and logged in. If it's not
+  on `PATH` (`ENOENT`), surface a clear error telling the user to install the
+  CLI and run `claude login` — don't crash silently.
+- **Timeouts.** The CLI is a full agent process, slower and heavier than a raw
+  API call. Always set a timeout and handle the null result; never block your
+  main flow on it.
+- **Structured output.** `-p` returns prose. If you need JSON, say so in the
+  prompt and parse defensively (treat malformed output as a no-op). Add
+  `--output-format json` if you want the CLI's own envelope instead.
+
+## Setup, once
+
+```bash
+claude login          # authenticate the subscription — no key involved
+claude -p "ping"      # verify it responds
+```
+
+That's all a fresh clone needs: an installed, logged-in `claude` CLI. No
+secrets, no `ANTHROPIC_API_KEY`, no billing configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-recall",
-  "version": "0.35.0",
+  "version": "0.36.1",
   "description": "Persistent memory for Claude Code and Pi with native Skills integration, automatic capture, failure learning, and project scoping",
   "main": "dist/index.js",
   "bin": {
@@ -102,7 +102,7 @@
     "typescript-eslint": "^8.63.0"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.110.0",
+    "@anthropic-ai/sdk": "^0.111.0",
     "better-sqlite3": "^12.2.0",
     "chalk": "^5.5.0",
     "commander": "^14.0.3"