claude-recall 0.34.2 → 0.35.0

package/README.md

@@ -176,6 +176,7 @@ 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.
 
@@ -333,6 +334,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 +423,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

@@ -57,9 +57,11 @@ const HOOKS_VERSION = '14.0.0';
 const parse_utils_1 = require("./parse-utils");
 const program = new commander_1.Command();
 class ClaudeRecallCLI {
+    get memoryService() {
+        return (this._memoryService ?? (this._memoryService = memory_1.MemoryService.getInstance()));
+    }
     constructor(options) {
         this.options = options;
-        this.memoryService = memory_1.MemoryService.getInstance();
         this.config = config_1.ConfigService.getInstance();
         this.logger = logging_1.LoggingService.getInstance();
         this.patternService = pattern_service_1.PatternService.getInstance();
@@ -1930,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/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");
@@ -106,14 +107,17 @@ function extractClassification(raw) {
     };
 }
 /**
- * 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 +128,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 +166,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

@@ -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/memory-janitor.js

@@ -0,0 +1,361 @@
+"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.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)}`);
+    }
+}
+/** Render one rule for the review prompt — id, type, counters, age, text. */
+function renderRuleForReview(rule, nowMs) {
+    let text;
+    try {
+        text = (0, memory_tools_1.formatRuleValue)(JSON.parse(rule.value));
+    }
+    catch {
+        text = String(rule.value);
+    }
+    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: text.slice(0, 400),
+    });
+}
+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' +
+        '- 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';
+                    (0, shared_1.storeMemory)(action.replacement, type, undefined, 0.9);
+                }
+                applied = storage.demoteRulesByIds(action.ids, 'janitor') > 0;
+            }
+            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 actions = parseJanitorActions(raw, validIds);
+        (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/memory/storage.js

@@ -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
@@ -812,6 +814,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 +972,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 +1039,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/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.2",
+  "version": "0.35.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": {