claude-recall 0.35.0 → 0.36.0

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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-recall",
-  "version": "0.35.0",
+  "version": "0.36.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": {