claude-recall 0.34.3 → 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
@@ -176,9 +191,12 @@ Once installed, Claude Recall works in the background (CC = Claude Code):
 | **Sub-agent spawned** | Rules are injected into the sub-agent; its outcome is captured | ✓ |  |  |
 | **Session exit** | An auto-checkpoint (`{completed, remaining, blockers}`) is saved for next time | ✓ | ✓ |  |
 | **End of session** | Failure patterns become candidate lessons; validated ones are promoted to rules | ✓ | ✓ |  |
+| **Once a day** | The memory janitor reviews stored rules with the runtime's LLM: demotes noise, merges duplicates, rewrites vague rules ([details](#memory-janitor)) | ✓ |  | ✓ |
 
 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
@@ -333,6 +351,24 @@ action → outcome event → episode → candidate lesson → promotion → acti
 
 Failures become candidate lessons (deduplicated by similarity); lessons seen 2+ times (or once, if severe) are promoted to active rules; every just-in-time injection (Claude Code, Pi) is recorded and resolved against the tool's outcome, building per-rule effectiveness data over time.
 
+### Memory janitor
+
+Automatic capture inevitably stores some noise — a conversational fragment misfiled as a preference, the same lesson in five wordings, a rule too vague to act on. Counters can flag *unused* rules (`CLAUDE_RECALL_AUTO_DEMOTE`), but they can't tell a rarely-cited gem from junk. Once a day, the **memory janitor** has the runtime's own LLM (same backend policy as capture — your Claude subscription or Kiro credits, never an API key unless you opted in) review the stored rules and:
+
+- **demote** noise — misfiled conversation, malformed junk, zero-content platitudes
+- **merge** duplicates into the single best phrasing
+- **rewrite** vague rules into precise trigger-plus-pattern form
+
+Guardrails: nothing is ever deleted (demotions are reversible via `rules promote <id>`, and re-teaching a demoted rule revives it); memories younger than 24h are never reviewed; at most 10 actions per run; malformed LLM output does nothing.
+
+```bash
+claude-recall janitor --dry-run   # preview what it would do
+claude-recall janitor             # run it now
+claude-recall janitor --status    # see the last automatic run
+```
+
+Disable with `CLAUDE_RECALL_JANITOR=off`.
+
 ---
 
 ## Upgrading
@@ -404,6 +440,9 @@ Defaults work out of the box; tune via environment variables as needed.
 | `CLAUDE_RECALL_REFRESH_INTERVAL`         | `15`    | **Kiro only.** Re-inject the active rules into context every N prompts, so marathon sessions can't silently lose them to context rollover (Kiro has no post-compaction event). `0` disables. |
 | `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_JANITOR`                  | `on`    | Set to `off` to disable the daily memory-janitor pass (LLM review of stored rules — see [Memory janitor](#memory-janitor)). |
+| `CLAUDE_RECALL_JANITOR_INTERVAL_HOURS`   | `24`    | Minimum hours between automatic janitor runs.                                                            |
+| `CLAUDE_RECALL_JANITOR_GRACE_HOURS`      | `24`    | Memories younger than this are excluded from janitor review — a fresh learning can't be judged noise the day it was taught. |
 | `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).                                    |

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

@@ -1932,12 +1932,58 @@ async function main() {
     });
     rulesCmd
         .command('promote <id>')
-        .description('Restore a previously auto-demoted or auto-deduped rule (safety valve)')
+        .description('Restore a previously auto-demoted, auto-deduped, or janitor-demoted rule (safety valve)')
         .action((id) => {
         const cli = new ClaudeRecallCLI(program.opts());
         cli.promoteRule(parseInt(id));
         process.exit(0);
     });
+    // Janitor: LLM-driven hygiene pass (the judgment layer above rules demote/dedup)
+    program
+        .command('janitor')
+        .description('Review stored rules with the runtime LLM: demote noise, merge duplicates, rewrite vague rules')
+        .option('--dry-run', 'Preview actions without mutating', false)
+        .option('--runtime <cc|kiro>', 'Which LLM backend to use (claude -p or kiro-cli)', 'cc')
+        .option('--status', 'Show the last janitor report instead of running', false)
+        .action(async (options) => {
+        const { handleMemoryJanitorWorker, readLastJanitorReport } = await Promise.resolve().then(() => __importStar(require('../hooks/memory-janitor')));
+        if (options.status) {
+            const last = readLastJanitorReport();
+            if (!last) {
+                console.log('No janitor run recorded yet.');
+            }
+            else {
+                console.log(`Last run: ${new Date(last.timestamp).toLocaleString()} (runtime=${last.runtime}${last.dryRun ? ', dry-run' : ''})`);
+                console.log(`Reviewed ${last.reviewed} rules, ${last.actions.length} action(s):`);
+                for (const a of last.actions) {
+                    console.log(`  ${a.applied ? '✓' : '✗'} ${a.action} [${a.ids.join(',')}]${a.replacement ? ` → "${a.replacement}"` : ''} — ${a.reason}`);
+                }
+            }
+            process.exit(0);
+        }
+        if (options.runtime !== 'cc' && options.runtime !== 'kiro') {
+            console.error(`Invalid --runtime "${options.runtime}" (expected cc or kiro)`);
+            process.exit(1);
+        }
+        console.log(`Running janitor review (runtime=${options.runtime}${options.dryRun ? ', dry-run' : ''})...`);
+        const report = await handleMemoryJanitorWorker({}, { dryRun: options.dryRun, runtime: options.runtime });
+        if (!report) {
+            console.log('Nothing to review (fewer than 2 rules past the grace period), or no LLM backend available.');
+            console.log('Check ~/.claude-recall/hook-logs/memory-janitor.log for details.');
+            process.exit(0);
+        }
+        console.log(`Reviewed ${report.reviewed} rules, ${report.actions.length} action(s)${report.dryRun ? ' (dry-run — nothing mutated)' : ''}:`);
+        for (const a of report.actions) {
+            console.log(`  ${a.applied ? '✓' : '✗'} ${a.action} [${a.ids.join(',')}]${a.replacement ? ` → "${a.replacement}"` : ''} — ${a.reason}`);
+        }
+        if (report.actions.length === 0) {
+            console.log('  (the LLM judged the corpus clean)');
+        }
+        else if (!report.dryRun) {
+            console.log('\nDemotions are reversible: `claude-recall rules promote <id>`.');
+        }
+        process.exit(0);
+    });
     rulesCmd
         .command('dedup')
         .description('Retroactively collapse near-duplicate rules (write-time dedup handles new writes)')

package/dist/cli/commands/hook-commands.js

@@ -56,6 +56,7 @@ const AVAILABLE_HOOKS = [
     'kiro-tool-outcome',
     'kiro-capture',
     'kiro-capture-worker',
+    'memory-janitor-worker',
 ];
 /**
  * Hook CLI Commands
@@ -177,6 +178,11 @@ class HookCommands {
                 await handleKiroCaptureWorker(input);
                 break;
             }
+            case 'memory-janitor-worker': {
+                const { handleMemoryJanitorWorker } = await Promise.resolve().then(() => __importStar(require('../../hooks/memory-janitor')));
+                await handleMemoryJanitorWorker(input);
+                break;
+            }
             default:
                 console.error(`Unknown hook: ${name}`);
                 console.error(`Available: ${AVAILABLE_HOOKS.join(', ')}`);

package/dist/hooks/cc-capture.js

@@ -14,6 +14,39 @@
  * capture is silent and lands ~4s later. Verify via
  * ~/.claude-recall/hook-logs/cc-classifier.log or `claude-recall search`.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleCcCapture = handleCcCapture;
 exports.handleCcCaptureWorker = handleCcCaptureWorker;
@@ -35,6 +68,16 @@ async function handleCcCapture(input) {
         || process.env.CLAUDE_RECALL_KIRO_CLASSIFIER) {
         return;
     }
+    // Janitor trigger rides on the first eligible prompt of the day — BEFORE
+    // the length pre-checks, since hygiene doesn't care whether this particular
+    // prompt is storable. Rate-limited internally (one run per 24h), detached.
+    try {
+        const { maybeSpawnJanitor } = await Promise.resolve().then(() => __importStar(require('./memory-janitor')));
+        maybeSpawnJanitor(input, 'cc');
+    }
+    catch (err) {
+        (0, shared_1.hookLog)(HOOK_NAME, `janitor spawn skipped: ${(0, shared_1.safeErrorMessage)(err)}`);
+    }
     const prompt = input?.prompt ?? '';
     if (prompt.length < 20 || prompt.length > 2000)
         return;

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

@@ -18,6 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLASSIFIER_AGENT = void 0;
 exports.buildClassifyPrompt = buildClassifyPrompt;
 exports.extractClassification = extractClassification;
+exports.completeWithKiroCli = completeWithKiroCli;
 exports.classifyWithKiro = classifyWithKiro;
 const child_process_1 = require("child_process");
 const shared_1 = require("./shared");
@@ -45,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' +
@@ -60,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);
@@ -103,17 +111,23 @@ function extractClassification(raw) {
         type: parsed.type,
         confidence,
         extract: parsed.extract.trim(),
+        ...(parsed.precision === 'vague' || parsed.precision === 'precise'
+            ? { precision: parsed.precision }
+            : {}),
     };
 }
 /**
- * Classify a prompt by invoking Kiro's headless LLM. Returns null on any
- * failure (kiro-cli absent, timeout, non-zero exit, unparseable output) so the
- * caller falls back to regex. Never throws.
+ * Run one headless kiro-cli completion and return raw stdout, or null on any
+ * failure (kiro-cli absent, timeout, non-zero exit). Never throws. This is
+ * the generic primitive: capture classification wraps it below, and the
+ * memory janitor routes its review pass through it — the same role
+ * completeWithClaudeCli plays for the Claude Code runtime.
  */
-function classifyWithKiro(text) {
+function completeWithKiroCli(prompt, opts = {}) {
     const model = process.env.CLAUDE_RECALL_KIRO_MODEL || DEFAULT_MODEL;
-    const timeoutMs = parseInt(process.env.CLAUDE_RECALL_KIRO_LLM_TIMEOUT_MS || '', 10);
-    const timeout = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS;
+    const envTimeout = parseInt(process.env.CLAUDE_RECALL_KIRO_LLM_TIMEOUT_MS || '', 10);
+    const timeout = opts.timeoutMs
+        ?? (Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : DEFAULT_TIMEOUT_MS);
     return new Promise((resolve) => {
         let settled = false;
         const done = (result) => {
@@ -124,14 +138,14 @@ function classifyWithKiro(text) {
         };
         let child;
         try {
-            // args array (no shell) — the user's text is passed as a single argv
+            // args array (no shell) — the prompt is passed as a single argv
             // entry, so no shell escaping or injection is possible.
             child = (0, child_process_1.spawn)('kiro-cli', [
                 'chat',
                 '--no-interactive',
                 '--agent', exports.CLASSIFIER_AGENT,
                 '--model', model,
-                buildClassifyPrompt(text),
+                prompt,
             ], { stdio: ['ignore', 'pipe', 'ignore'] });
         }
         catch (err) {
@@ -162,25 +176,37 @@ function classifyWithKiro(text) {
                 (0, shared_1.hookLog)('kiro-classifier', `kiro-cli exited ${code}`);
                 return done(null);
             }
-            const result = extractClassification(stdout);
-            if (!result) {
-                // Distinguish a deliberate "none" verdict from unparseable output —
-                // "the model said not a rule" and "the call broke" are different
-                // diagnoses when reading the log.
-                (0, shared_1.hookLog)('kiro-classifier', /"type"\s*:\s*"none"/.test(stdout)
-                    ? 'classified as none (not a durable rule)'
-                    : 'no parseable classification in kiro-cli output');
-            }
-            else {
-                // Log success too, not just failures — otherwise a successful Kiro
-                // classification is silent and indistinguishable from "never ran",
-                // which makes "did the Kiro LLM handle this?" impossible to answer
-                // from the log. Spell out that this ran on Kiro credits (not the
-                // ANTHROPIC_API_KEY) using a dedicated classifier model — the `model`
-                // is CLAUDE_RECALL_KIRO_MODEL, independent of the interactive chat model.
-                (0, shared_1.hookLog)('kiro-classifier', `classified via kiro-cli (model=${model}, Kiro credits, no API key): ${result.type} — ${result.extract.slice(0, 60)}`);
-            }
-            done(result);
+            done(stdout);
         });
     });
 }
+/**
+ * Classify a prompt by invoking Kiro's headless LLM. Returns null on any
+ * failure (kiro-cli absent, timeout, non-zero exit, unparseable output) so the
+ * caller falls back to regex. Never throws.
+ */
+async function classifyWithKiro(text) {
+    const model = process.env.CLAUDE_RECALL_KIRO_MODEL || DEFAULT_MODEL;
+    const stdout = await completeWithKiroCli(buildClassifyPrompt(text));
+    if (stdout === null)
+        return null;
+    const result = extractClassification(stdout);
+    if (!result) {
+        // Distinguish a deliberate "none" verdict from unparseable output —
+        // "the model said not a rule" and "the call broke" are different
+        // diagnoses when reading the log.
+        (0, shared_1.hookLog)('kiro-classifier', /"type"\s*:\s*"none"/.test(stdout)
+            ? 'classified as none (not a durable rule)'
+            : 'no parseable classification in kiro-cli output');
+    }
+    else {
+        // Log success too, not just failures — otherwise a successful Kiro
+        // classification is silent and indistinguishable from "never ran",
+        // which makes "did the Kiro LLM handle this?" impossible to answer
+        // from the log. Spell out that this ran on Kiro credits (not the
+        // ANTHROPIC_API_KEY) using a dedicated classifier model — the `model`
+        // is CLAUDE_RECALL_KIRO_MODEL, independent of the interactive chat model.
+        (0, shared_1.hookLog)('kiro-classifier', `classified via kiro-cli (model=${model}, Kiro credits, no API key): ${result.type} — ${result.extract.slice(0, 60)}`);
+    }
+    return result;
+}

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),
@@ -186,6 +186,15 @@ async function handleKiroAgentSpawn(_input) {
         catch { /* checkpoint hint is best-effort */ }
         process.stdout.write(parts.join('\n\n') + '\n');
         (0, shared_1.hookLog)(HOOK_NAME, `agentSpawn: injected memory directive + ${total} rule(s) into Kiro context`);
+        // Session start is also the janitor's trigger: at most one detached
+        // hygiene pass per 24h, never blocking startup (returns in ms).
+        try {
+            const { maybeSpawnJanitor } = await Promise.resolve().then(() => __importStar(require('./memory-janitor')));
+            maybeSpawnJanitor(_input, 'kiro');
+        }
+        catch (err) {
+            (0, shared_1.hookLog)(HOOK_NAME, `janitor spawn skipped: ${(0, shared_1.safeErrorMessage)(err)}`);
+        }
     }
     catch (err) {
         // Never block agent startup

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

@@ -0,0 +1,397 @@
+"use strict";
+/**
+ * Memory janitor — LLM-driven hygiene pass over the stored rule corpus.
+ *
+ * The deterministic hygiene passes judge rules by counters (auto-demote:
+ * loaded often + never cited; auto-dedup: textual similarity). Counters can
+ * say "unused" but not "this is noise", "these five platitudes are one rule",
+ * or "this preference is actually a conversational fragment the classifier
+ * misfiled". This pass gives that judgment to the runtime's own LLM — the
+ * same backend policy as capture classification (claude -p on the user's
+ * subscription under Claude Code, kiro-cli on Kiro credits under Kiro, and
+ * NEVER a personally-exported ANTHROPIC_API_KEY unless the user opted in).
+ *
+ * Design guardrails:
+ *  - Never deletes. Demotes with superseded_by='janitor' — reversible via
+ *    `rules promote <id>`, and re-teaching identical content revives the row.
+ *  - Grace period: memories younger than 24h are not even shown to the LLM,
+ *    so one session's janitor can't erase what the previous session just
+ *    learned.
+ *  - Capped at 10 actions per run; malformed LLM output is a no-op.
+ *  - Rate-limited to one run per 24h (state file), spawned as a DETACHED
+ *    worker from existing session hooks — never blocks a turn, and users get
+ *    it on upgrade with no config change.
+ *
+ * Disable with CLAUDE_RECALL_JANITOR=off. Tune with
+ * CLAUDE_RECALL_JANITOR_INTERVAL_HOURS / CLAUDE_RECALL_JANITOR_GRACE_HOURS.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claimJanitorRun = claimJanitorRun;
+exports.maybeSpawnJanitor = maybeSpawnJanitor;
+exports.dropCosmeticRewrites = dropCosmeticRewrites;
+exports.buildJanitorPrompt = buildJanitorPrompt;
+exports.parseJanitorActions = parseJanitorActions;
+exports.applyJanitorActions = applyJanitorActions;
+exports.handleMemoryJanitorWorker = handleMemoryJanitorWorker;
+exports.readLastJanitorReport = readLastJanitorReport;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const shared_1 = require("./shared");
+const memory_1 = require("../services/memory");
+const config_1 = require("../services/config");
+const memory_tools_1 = require("../mcp/tools/memory-tools");
+const HOOK_NAME = 'memory-janitor';
+const STATE_FILE = 'janitor-state.json';
+const REPORT_FILE = 'janitor-last-report.json';
+const DEFAULT_INTERVAL_HOURS = 24;
+const DEFAULT_GRACE_HOURS = 24;
+const MAX_ACTIONS_PER_RUN = 10;
+/** Review pass is one bigger completion than classification — allow more time. */
+const JANITOR_TIMEOUT_MS = 60000;
+const RULE_TYPES = new Set(['preference', 'correction', 'failure', 'devops', 'project-knowledge']);
+function janitorDisabled() {
+    const v = (process.env.CLAUDE_RECALL_JANITOR || '').trim().toLowerCase();
+    return v === 'off' || v === 'false' || v === '0';
+}
+function envHours(name, fallback) {
+    const n = parseFloat(process.env[name] || '');
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/**
+ * Rate limiter with claim-on-check semantics: the caller that sees the
+ * interval elapsed WRITES the new timestamp before spawning, so several
+ * sessions starting in the same minute produce one janitor run, not one each.
+ */
+function claimJanitorRun(nowMs = Date.now()) {
+    const intervalMs = envHours('CLAUDE_RECALL_JANITOR_INTERVAL_HOURS', DEFAULT_INTERVAL_HOURS) * 3600000;
+    const statePath = path.join((0, shared_1.hookStateDir)(), STATE_FILE);
+    try {
+        const raw = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+        if (typeof raw?.lastRun === 'number' && nowMs - raw.lastRun < intervalMs) {
+            return false;
+        }
+    }
+    catch { /* missing/corrupt state = never ran */ }
+    try {
+        fs.writeFileSync(statePath, JSON.stringify({ lastRun: nowMs }));
+    }
+    catch (err) {
+        // If the claim can't be persisted, don't run — an unwritable state file
+        // would otherwise mean a janitor pass on EVERY session start.
+        (0, shared_1.hookLog)(HOOK_NAME, `state write failed, skipping run: ${(0, shared_1.safeErrorMessage)(err)}`);
+        return false;
+    }
+    return true;
+}
+/**
+ * The inline half — called from existing session hooks (kiro-agent-spawn,
+ * cc-capture). Decides eligibility and spawns the detached worker. Returns in
+ * milliseconds; never throws.
+ */
+function maybeSpawnJanitor(input, runtime) {
+    try {
+        if (janitorDisabled())
+            return;
+        // Recursion guard — a nested headless session must never run hygiene.
+        if (process.env.CLAUDE_RECALL_NESTED
+            || process.env.CLAUDE_RECALL_CC_CLASSIFIER
+            || process.env.CLAUDE_RECALL_KIRO_CLASSIFIER
+            || process.env.CLAUDE_RECALL_JANITOR_WORKER) {
+            return;
+        }
+        if (!claimJanitorRun())
+            return;
+        const cliPath = process.argv[1];
+        const child = (0, child_process_1.spawn)(process.execPath, [cliPath, 'hook', 'run', 'memory-janitor-worker'], {
+            detached: true,
+            stdio: ['pipe', 'ignore', 'ignore'],
+            env: { ...process.env, CLAUDE_RECALL_JANITOR_RUNTIME: runtime },
+        });
+        child.on('error', (err) => {
+            (0, shared_1.hookLog)(HOOK_NAME, `worker spawn error: ${err?.message ?? err}`);
+        });
+        if (child.stdin) {
+            child.stdin.on('error', (err) => {
+                (0, shared_1.hookLog)(HOOK_NAME, `worker stdin error: ${err?.message ?? err}`);
+            });
+            child.stdin.write(JSON.stringify(input ?? {}));
+            child.stdin.end();
+        }
+        child.unref();
+        (0, shared_1.hookLog)(HOOK_NAME, `spawned detached janitor worker (pid=${child.pid}, runtime=${runtime})`);
+    }
+    catch (err) {
+        (0, shared_1.hookLog)(HOOK_NAME, `spawn failed: ${(0, shared_1.safeErrorMessage)(err)}`);
+    }
+}
+/** 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 {
+        return (0, memory_tools_1.formatRuleValue)(JSON.parse(rule.value));
+    }
+    catch {
+        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,
+        type: rule.type,
+        loads: rule.load_count,
+        cites: rule.cite_count,
+        age_days: ageDays,
+        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) {
+    return ('You are a memory hygiene reviewer for a developer tool. Below are rules a ' +
+        'coding agent stored automatically from past sessions. Some are valuable; ' +
+        'some are noise that pollutes every future session. Review them and respond ' +
+        'with ONLY minified JSON — no markdown, no prose, no code fence:\n' +
+        '{"actions":[{"action":"demote|merge|rewrite","ids":[<id>,...],"replacement":"<text or empty>","reason":"<short>"}]}\n\n' +
+        'Actions:\n' +
+        '- demote: the rule is NOISE. Conversational fragments or meta-discussion ' +
+        'misfiled as rules, statements about this tool or this chat, truncated/' +
+        'malformed junk, or generic platitudes with zero actionable content (e.g. ' +
+        '"check inputs before retrying" — advice so obvious no agent needs it stored).\n' +
+        '- merge: two or more rules say the SAME thing in different words. ids = all ' +
+        'of them; replacement = the single best phrasing (may combine details).\n' +
+        '- rewrite: the rule is real but too vague to act on at the moment of ' +
+        'decision. ids = [the one id]; replacement = a precise version naming the ' +
+        'TRIGGER and the CONCRETE pattern, e.g. "When creating a new file, match ' +
+        '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' +
+        'Rules to review (JSON per line):\n' +
+        ruleLines.join('\n'));
+}
+/**
+ * Parse and validate the LLM's response. Anything malformed is dropped;
+ * unknown ids are dropped; the total is capped. A parse failure returns [] —
+ * the janitor never guesses.
+ */
+function parseJanitorActions(raw, validIds) {
+    let parsed;
+    try {
+        const cleaned = raw.trim().replace(/^```(?:json)?\s*/, '').replace(/\s*```$/, '');
+        const start = cleaned.indexOf('{');
+        const end = cleaned.lastIndexOf('}');
+        if (start === -1 || end <= start)
+            return [];
+        parsed = JSON.parse(cleaned.slice(start, end + 1));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed?.actions))
+        return [];
+    const out = [];
+    for (const a of parsed.actions) {
+        if (out.length >= MAX_ACTIONS_PER_RUN)
+            break;
+        if (!a || typeof a !== 'object')
+            continue;
+        if (a.action !== 'demote' && a.action !== 'merge' && a.action !== 'rewrite')
+            continue;
+        const ids = Array.isArray(a.ids)
+            ? a.ids.filter((id) => Number.isInteger(id) && validIds.has(id))
+            : [];
+        if (ids.length === 0)
+            continue;
+        const replacement = typeof a.replacement === 'string' ? a.replacement.trim() : '';
+        if (a.action === 'merge') {
+            if (ids.length < 2)
+                continue;
+            if (replacement.length < 10 || replacement.length > 300)
+                continue;
+        }
+        if (a.action === 'rewrite') {
+            if (ids.length !== 1)
+                continue;
+            if (replacement.length < 10 || replacement.length > 300)
+                continue;
+            // A rewrite that doesn't change the text is a no-op dressed as work.
+        }
+        out.push({
+            action: a.action,
+            ids,
+            replacement: replacement || undefined,
+            type: typeof a.type === 'string' && RULE_TYPES.has(a.type) ? a.type : undefined,
+            reason: typeof a.reason === 'string' ? a.reason.slice(0, 200) : '',
+        });
+    }
+    return out;
+}
+/**
+ * Apply validated actions. merge/rewrite store the replacement FIRST, then
+ * demote the sources — if the store throws, the originals survive untouched.
+ */
+function applyJanitorActions(actions, rulesById, opts = {}) {
+    const storage = memory_1.MemoryService.getInstance().getStorage();
+    const results = [];
+    for (const action of actions) {
+        let applied = false;
+        try {
+            if (!opts.dryRun) {
+                if (action.action === 'merge' || action.action === 'rewrite') {
+                    const type = action.type ?? rulesById.get(action.ids[0])?.type ?? 'preference';
+                    // 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 });
+                }
+                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
+            }
+        }
+        catch (err) {
+            (0, shared_1.hookLog)(HOOK_NAME, `apply ${action.action} [${action.ids.join(',')}] failed: ${(0, shared_1.safeErrorMessage)(err)}`);
+        }
+        results.push({ ...action, applied });
+    }
+    return results;
+}
+/** Route one completion through the runtime's own LLM. Null = no backend. */
+async function completeForJanitor(prompt, runtime) {
+    if (runtime === 'kiro') {
+        const { completeWithKiroCli } = await Promise.resolve().then(() => __importStar(require('./kiro-classifier')));
+        return completeWithKiroCli(prompt, { timeoutMs: JANITOR_TIMEOUT_MS });
+    }
+    if (runtime === 'cc') {
+        const { completeWithClaudeCli } = await Promise.resolve().then(() => __importStar(require('./cc-classifier')));
+        return completeWithClaudeCli(prompt, { timeoutMs: JANITOR_TIMEOUT_MS });
+    }
+    return null;
+}
+/**
+ * The worker half — runs detached (or inline via `claude-recall janitor`).
+ * Loads the corpus, asks the runtime's LLM for hygiene actions, applies them,
+ * and writes a report file the CLI can display.
+ */
+async function handleMemoryJanitorWorker(_input, opts = {}) {
+    // Mark this process so any hooks fired by the nested LLM call stay inert.
+    process.env.CLAUDE_RECALL_JANITOR_WORKER = '1';
+    const runtime = opts.runtime || process.env.CLAUDE_RECALL_JANITOR_RUNTIME || 'cc';
+    try {
+        const storage = memory_1.MemoryService.getInstance().getStorage();
+        const projectId = config_1.ConfigService.getInstance().getProjectId();
+        const now = Date.now();
+        const graceMs = envHours('CLAUDE_RECALL_JANITOR_GRACE_HOURS', DEFAULT_GRACE_HOURS) * 3600000;
+        const all = storage.getActiveRules(projectId);
+        const reviewable = all.filter(r => now - r.timestamp > graceMs);
+        if (reviewable.length < 2) {
+            (0, shared_1.hookLog)(HOOK_NAME, `nothing to review (${all.length} active, ${reviewable.length} past grace period)`);
+            return null;
+        }
+        const prompt = buildJanitorPrompt(reviewable.map(r => renderRuleForReview(r, now)));
+        const raw = await completeForJanitor(prompt, runtime);
+        if (raw === null) {
+            (0, shared_1.hookLog)(HOOK_NAME, `no LLM backend available (runtime=${runtime}) — skipping`);
+            return null;
+        }
+        const validIds = new Set(reviewable.map(r => r.id));
+        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 });
+        const report = {
+            timestamp: now,
+            runtime,
+            reviewed: reviewable.length,
+            actions: results,
+            dryRun: opts.dryRun ?? false,
+        };
+        try {
+            fs.writeFileSync(path.join((0, shared_1.hookStateDir)(), REPORT_FILE), JSON.stringify(report, null, 2));
+        }
+        catch { /* report is best-effort */ }
+        for (const r of results) {
+            (0, shared_1.hookLog)(HOOK_NAME, `${r.applied ? 'applied' : 'FAILED'} ${r.action} [${r.ids.join(',')}]: ${r.reason}`);
+        }
+        return report;
+    }
+    catch (err) {
+        (0, shared_1.hookLog)(HOOK_NAME, `worker error: ${(0, shared_1.safeErrorMessage)(err)}`);
+        return null;
+    }
+}
+/** Read the last report for CLI display. Null if none exists. */
+function readLastJanitorReport() {
+    try {
+        return JSON.parse(fs.readFileSync(path.join((0, shared_1.hookStateDir)(), REPORT_FILE), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}

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
@@ -367,11 +367,13 @@ class MemoryStorage {
             this.db.pragma('wal_checkpoint(TRUNCATE)');
             return;
         }
-        // Re-teaching an auto-demoted/auto-deduped rule revives it — otherwise the
-        // dedup hit would bump a dead row that loadActiveRules never returns and
-        // the rule would be unrecoverable through normal use. Rows superseded by a
-        // USER override are deliberately not revived (mirrors promoteRule).
-        const autoDemotedMatch = hashMatches.find(m => m.is_active !== 1 && (m.superseded_by === 'auto-demote' || m.superseded_by === 'auto-dedup'));
+        // Re-teaching an auto-demoted/auto-deduped/janitor-demoted rule revives it
+        // — otherwise the dedup hit would bump a dead row that loadActiveRules
+        // never returns and the rule would be unrecoverable through normal use.
+        // Deliberate re-teaching outranks the janitor's noise verdict. Rows
+        // superseded by a USER override are deliberately not revived (mirrors
+        // promoteRule).
+        const autoDemotedMatch = hashMatches.find(m => m.is_active !== 1 && MemoryStorage.REVIVABLE_SENTINELS.includes(m.superseded_by ?? ''));
         if (autoDemotedMatch) {
             this.db.prepare(`UPDATE memories SET timestamp = ?, access_count = access_count + 1,
          is_active = 1, superseded_by = NULL, superseded_at = NULL
@@ -386,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
@@ -418,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)');
@@ -812,6 +836,41 @@ class MemoryStorage {
         }
         return candidates;
     }
+    /**
+     * All active rule-type rows, for the memory janitor's review pass.
+     * Scoped like loadActiveRules: the given project, universal, or unscoped.
+     */
+    getActiveRules(projectId) {
+        const typePlaceholders = MemoryStorage.RULE_TYPES.map(() => '?').join(',');
+        const params = [...MemoryStorage.RULE_TYPES];
+        let scopeClause = `AND (project_id IS NULL OR project_id = '' OR scope = 'universal')`;
+        if (projectId) {
+            scopeClause = `AND (project_id = ? OR project_id IS NULL OR project_id = '' OR scope = 'universal')`;
+            params.push(projectId);
+        }
+        return this.db.prepare(`
+      SELECT id, key, type, value, load_count, cite_count, timestamp
+      FROM memories
+      WHERE is_active = 1 AND type IN (${typePlaceholders}) ${scopeClause}
+      ORDER BY timestamp ASC
+    `).all(...params);
+    }
+    /**
+     * Demote specific rows by id with a hygiene sentinel (default 'janitor').
+     * Reversible via promoteRule(); re-teaching identical content revives too.
+     * Returns the number of rows flipped.
+     */
+    demoteRulesByIds(ids, sentinel = 'janitor') {
+        if (ids.length === 0)
+            return 0;
+        const placeholders = ids.map(() => '?').join(',');
+        const result = this.db.prepare(`UPDATE memories SET is_active = 0, superseded_at = ?, superseded_by = ?
+       WHERE id IN (${placeholders}) AND is_active = 1`).run(Date.now(), sentinel, ...ids);
+        if (result.changes > 0) {
+            this.db.pragma('wal_checkpoint(TRUNCATE)');
+        }
+        return result.changes;
+    }
     /**
      * Delete rows whose stored value matches legacy test-fixture patterns.
      * Matches against json_extract(value, '$.content') OR the raw value (covers both
@@ -935,14 +994,15 @@ class MemoryStorage {
         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.
+     * Restore a previously auto-demoted, auto-deduped, or janitor-demoted rule.
+     * Only flips rows whose superseded_by is a hygiene sentinel — 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 placeholders = MemoryStorage.REVIVABLE_SENTINELS.map(() => '?').join(',');
         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);
+       WHERE id = ? AND is_active = 0 AND superseded_by IN (${placeholders})`).run(id, ...MemoryStorage.REVIVABLE_SENTINELS);
         if (result.changes > 0) {
             this.db.pragma('wal_checkpoint(TRUNCATE)');
         }
@@ -1001,6 +1061,13 @@ class MemoryStorage {
 exports.MemoryStorage = MemoryStorage;
 /** Rule-type memories: the only types subject to fuzzy dedup and retro-dedup. */
 MemoryStorage.RULE_TYPES = ['preference', 'correction', 'failure', 'devops', 'project-knowledge'];
+/**
+ * Supersession sentinels written by automatic hygiene passes (as opposed to
+ * a USER preference override, where superseded_by names the winning key).
+ * Rows carrying one of these are revivable: by content-hash re-teach in
+ * save() and individually via promoteRule().
+ */
+MemoryStorage.REVIVABLE_SENTINELS = ['auto-demote', 'auto-dedup', 'janitor'];
 // Bookkeeping fields the MCP store handler injects into every memory value.
 // They carry no semantic meaning, but now that sessionId is stable per
 // process (v0.26.0) a constant sessionId token would appear in every memory

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/2026-07-positioning-vs-steering-files.md

@@ -0,0 +1,92 @@
+# Positioning: claude-recall vs. steering files (and CLAUDE.md)
+
+*Reference note, 2026-07-15. Prompted by the question: "why would I use claude-recall
+if I can just use steering files?" The same argument covers CLAUDE.md and any
+hand-written per-tool rules file.*
+
+## What steering files are
+
+Kiro's persistent-context mechanism: markdown files the agent loads into context.
+
+- **Workspace scope**: `.kiro/steering/` (per project, checked into the repo)
+- **Global scope**: `~/.kiro/steering/` (all workspaces; MDM-distributable for teams)
+- **Inclusion modes**: always (default) · conditional (file-pattern match) ·
+  manual (`#steering-file-name`) · auto (description match)
+- Explicitly documented as "part of your codebase" — no secrets, team-visible.
+
+Claude Code's CLAUDE.md is the same idea with fewer inclusion modes; Pi has no
+equivalent.
+
+## The one-sentence positioning
+
+> **Steering files are documentation; claude-recall is learning.**
+> Use steering files for what your *team* has decided; use claude-recall for
+> what your *sessions* have taught.
+
+## Where steering files win (concede cleanly)
+
+1. **Deliberate, curated, team-shared standards.** Tech stack, architecture
+   conventions, "we use pnpm." Reviewed in PRs, versioned with the code,
+   distributed to every teammate. Recall's DB is local and personal — it
+   cannot do this and shouldn't try.
+2. **Reliable inclusion under Kiro.** Always-mode steering is loaded into every
+   interaction by the platform itself — sturdier than any hook channel.
+
+## Why steering files don't replace claude-recall
+
+1. **Somebody has to write them.** Steering captures what you already knew and
+   remembered to document. Recall captures what surfaces *in the flow of work*:
+   correct the agent once mid-session and it's stored. Nobody stops coding to
+   open `.kiro/steering/conventions.md` and write "email files are
+   `email_*.txt`" — the stuff that burns you repeatedly is precisely the stuff
+   too small to feel worth documenting.
+
+2. **Steering files can't learn from failure.** There is no steering-file
+   equivalent of the outcome pipeline: tool failure → episode → candidate
+   lesson → promoted rule. "Exit code 0 doesn't mean the tests passed" entered
+   the DB because the agent got burned, not because someone wrote a postmortem.
+   The self-improvement rationale (agent gets better at coding/building/
+   reasoning from its own experience) has no steering-file mechanism at all.
+
+3. **One memory, every agent.** Steering is Kiro-only; CLAUDE.md is
+   Claude-Code-only; Pi has neither. One SQLite DB sits behind all three
+   runtimes: correct the agent once in Claude Code and Kiro knows it tomorrow.
+   With steering files you hand-maintain N parallel rule files per project per
+   tool.
+
+4. **Steering files rot; the recall corpus self-maintains.** No one prunes a
+   steering file — stale rules burn context forever, and the platform never
+   reports that a rule was ignored 44 times. Recall tracks loads/citations,
+   auto-demotes dead rules (`CLAUDE_RECALL_AUTO_DEMOTE`), and runs the daily
+   memory janitor (v0.35.0): LLM review that demotes noise, merges duplicates,
+   and rewrites vague rules into trigger+pattern form.
+
+5. **Personal ≠ repo.** Steering files are code — committed, team-visible,
+   unsuitable for anything user-specific ("GPG signing fails in *my* WSL",
+   "*I* prefer X"). Recall is per-developer and never touches the repo.
+
+## Roadmap idea: compose, don't compete
+
+Recall already crystallizes memories into skill files (`.claude/skills/auto-*`).
+The same mechanism could emit a **steering-file draft**:
+
+> "Your sessions taught this project 6 durable rules — commit them to
+> `.kiro/steering/` for the team?"
+
+That turns the personal-learning layer into a feeder for the team-documentation
+layer: recall discovers the rules from experience, steering distributes the
+vetted ones to humans and agents alike. It converts "why not just steering
+files?" from an objection into the integration story — the strongest possible
+answer, because it stops being either/or.
+
+## Cheat sheet
+
+| | Steering files / CLAUDE.md | claude-recall |
+|---|---|---|
+| Authored by | Humans, deliberately | Hooks + LLM, automatically |
+| Captures | What you already know | What sessions teach (incl. failures) |
+| Scope | Per tool, per repo (team-shared) | One DB across CC/Kiro/Pi (personal) |
+| Learns from outcomes | No | Yes (episodes → lessons → rules) |
+| Hygiene | Manual, rots | Citation tracking, auto-demote, daily janitor |
+| Sensitive/personal rules | No (committed code) | Yes (local DB) |
+| Team distribution | Yes (repo/MDM) | No (by design) |

package/package.json

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