claude-recall 0.21.2 → 0.22.0

package/.claude/settings.json

@@ -108,7 +108,18 @@
           }
         ]
       }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /home/ebiarao/.nvm/versions/node/v20.19.3/lib/node_modules/claude-recall/dist/cli/claude-recall-cli.js hook run session-end-checkpoint",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   },
-  "hooksVersion": "12.0.0"
+  "hooksVersion": "13.0.0"
 }

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

@@ -12,10 +12,10 @@ Auto-generated from 5 memories. Last updated: 2026-04-11.
 
 ## Rules
 
-- Session test preference 1775900146096
-- Test preference 1775900146036-2
-- Test preference 1775900146036-1
-- Test preference 1775900146036-0
+- Session test preference 1775902182248
+- Test preference 1775902182184-2
+- Test preference 1775902182184-1
+- Test preference 1775902182184-0
 - Test memory content
 
 ---

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

@@ -1,13 +1,13 @@
 {
   "topicId": "preferences",
-  "sourceHash": "32712ec321c1c8e831bfb1d227b5682434e69ab3a0934115453c984b36866477",
+  "sourceHash": "a383c0d6502023d06954eb49fcab8886dc5181d5e59666f6c74a381221e44f87",
   "memoryCount": 5,
-  "generatedAt": "2026-04-11T09:35:46.110Z",
+  "generatedAt": "2026-04-11T10:09:42.271Z",
   "memoryKeys": [
-    "memory_1775900146097_ap6ffit4i",
-    "memory_1775900146071_8y0wnmbu6",
-    "memory_1775900146056_0tbld53h7",
-    "memory_1775900146038_czc25c8ra",
-    "memory_1775900145994_1cvxoyda8"
+    "memory_1775902182249_x5rzzep7s",
+    "memory_1775902182226_9uo2kaw57",
+    "memory_1775902182211_pl5fzrb85",
+    "memory_1775902182185_q6f9widp3",
+    "memory_1775902182147_olowsptz3"
   ]
 }

package/.claude/skills/memory-management/SKILL.md

@@ -137,14 +137,16 @@ a SKILL.md file that Claude Code loads automatically.
 
 ## Automatic Capture Hooks
 
-Claude Recall registers hooks on four Claude Code events to capture memories automatically — no MCP tool call needed:
+Claude Recall registers hooks on six Claude Code events for automatic capture, just-in-time rule injection, and outcome tracking — no MCP tool call needed:
 
-| Hook | Event | What it captures |
+| Hook | Event | What it does |
 |------|-------|-----------------|
-| `correction-detector` | UserPromptSubmit | User corrections, preferences, and project knowledge from natural language |
-| `memory-stop` | Stop | Corrections, preferences, failures, and devops patterns from the last 6 transcript entries |
+| `correction-detector` | UserPromptSubmit | Captures user corrections, preferences, and project knowledge from natural language |
+| `memory-stop` | Stop | Captures corrections, preferences, failures, and devops patterns from the last 6 transcript entries |
 | `precompact-preserve` | PreCompact | Broader sweep of up to 50 transcript entries before context compression |
 | `session-end-checkpoint` | SessionEnd | Auto-saves a `{completed, remaining, blockers}` task checkpoint when the session ends voluntarily (`clear`, `prompt_input_exit`, `logout`). Spawns a detached worker so it stays within Claude Code's 1.5s SessionEnd timeout. Pi has the equivalent via the `session_shutdown` event handler. |
+| `rule-injector` | PreToolUse | **Just-in-time rule injection.** Before each tool call, searches active rules for matches against `tool_name + tool_input` and injects the top 3 (excluding raw failures) as a `<system-reminder>` block adjacent to the action. Closes the rule-loading gap: rules are surfaced at the moment of decision, not 50,000 tokens upstream from where attention has moved on. Each injection is logged to `rule_injection_events` for outcome correlation. Pi has the equivalent via per-turn injection in the `before_agent_start` handler. |
+| `rule-injection-resolver` | PostToolUse / PostToolUseFailure | Resolves recorded `rule_injection_events` with the tool outcome (success/failure). Together with the injector, this becomes the new "is this rule actually helpful" signal — replacing the broken `(applied from memory: ...)` citation regex. |
 
 **Key behaviors:**
 - **LLM-first classification** via Claude Haiku — detects natural statements like "we use tabs here" or "tests go in \_\_tests\_\_/" that regex would miss
@@ -156,7 +158,7 @@ Claude Recall registers hooks on four Claude Code events to capture memories aut
 - Auto-checkpoint quality gate: refuses to save when the LLM detects the task was already complete — manual checkpoints stay sticky
 - Always exits 0 — hooks never block Claude
 
-**Setup:** Run `npx claude-recall setup --install` to register hooks in `.claude/settings.json`. After upgrading to v0.21.2, re-run `setup --install` in each project to pick up the new SessionEnd hook (the `hooksVersion` bump to `13.0.0` signals that registration changed).
+**Setup:** Run `npx claude-recall setup --install` to register hooks in `.claude/settings.json`. After any upgrade, re-run `setup --install` in each project so newly-added hook events get registered (claude-recall uses a `hooksVersion` field to signal when registration has changed).
 
 ## Example Workflows
 

package/README.md

@@ -69,8 +69,8 @@ Both agents use the same database (`~/.claude-recall/claude-recall.db`). Memorie
 npm install -g claude-recall
 claude-recall setup --install    # run from each project directory
 
-# Pi
-pi update claude-recall
+# Pi — must include the npm: prefix (matches the install command)
+pi update npm:claude-recall
 ```
 
 The MCP server picks up the new version automatically. `setup --install` is needed to update hooks in `.claude/settings.json` (new hook events may have been added).
@@ -91,6 +91,7 @@ Once installed, Claude Recall works automatically in the background:
 8. **Sub-agent recall** (Claude Code only) — when sub-agents are spawned, active rules are injected into their context automatically. Sub-agent outcomes (completed/failed/killed) are captured as events
 9. **Rules sync** (Claude Code only) — top 30 rules are exported as typed `.md` files to Claude Code's native memory directory
 10. **Auto-checkpoint on session exit** — when a session ends (Pi shutdown or Claude Code's `SessionEnd` for `clear`/`prompt_input_exit`/`logout`), the most recent task is extracted via Haiku into a structured `{completed, remaining, blockers}` checkpoint and saved for the next session. Critical for Pi (which has no `--resume` flag); a useful safety net for Claude Code users who exit without resuming. Conservative quality gate refuses to save when the LLM detects the task was already complete — manual checkpoints are never clobbered with garbage
+11. **Just-in-time rule injection (JITRI)** — before each tool call (Claude Code) or each agent turn (Pi), the most relevant active rules are searched against `tool_name + tool_input + recent prompt` and injected as a `<system-reminder>` block immediately adjacent to the action. This closes the rule-loading gap: rules are no longer just loaded once at session start (where attention decays as context grows) — they're surfaced at the moment of decision. Each injection is recorded in `rule_injection_events` and resolved with the tool outcome via PostToolUse, replacing the broken citation-detection regex with direct measurement of "was the relevant rule present when the action happened?"
 
 Classification uses Claude Haiku (via `ANTHROPIC_API_KEY`) with silent regex fallback. No configuration needed.
 

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

@@ -809,7 +809,7 @@ async function main() {
         // This avoids registry lookups on every hook invocation.
         const cliScript = path.join(packageDir, 'dist', 'cli', 'claude-recall-cli.js');
         const hookCmd = `node ${cliScript} hook run`;
-        settings.hooksVersion = '13.0.0'; // v13 = add SessionEnd for auto-checkpoint on session exit
+        settings.hooksVersion = '14.0.0'; // v14 = add PreToolUse rule-injector + Post resolver for JITRI
         settings.hooks = {
             SubagentStart: [
                 {
@@ -852,6 +852,11 @@ async function main() {
                             type: "command",
                             command: `${hookCmd} tool-outcome-watcher`,
                             timeout: 3
+                        },
+                        {
+                            type: "command",
+                            command: `${hookCmd} rule-injection-resolver`,
+                            timeout: 3
                         }
                     ]
                 }
@@ -863,6 +868,11 @@ async function main() {
                             type: "command",
                             command: `${hookCmd} tool-failure`,
                             timeout: 3
+                        },
+                        {
+                            type: "command",
+                            command: `${hookCmd} rule-injection-resolver`,
+                            timeout: 3
                         }
                     ]
                 }
@@ -874,6 +884,11 @@ async function main() {
                         {
                             type: "command",
                             command: `python3 ${hookDest}`
+                        },
+                        {
+                            type: "command",
+                            command: `${hookCmd} rule-injector`,
+                            timeout: 5
                         }
                     ]
                 }

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

@@ -116,6 +116,16 @@ class HookCommands {
                         await handleSessionEndCheckpointWorker(input);
                         break;
                     }
+                    case 'rule-injector': {
+                        const { handleRuleInjector } = await Promise.resolve().then(() => __importStar(require('../../hooks/rule-injector')));
+                        await handleRuleInjector(input);
+                        break;
+                    }
+                    case 'rule-injection-resolver': {
+                        const { handleRuleInjectionResolver } = await Promise.resolve().then(() => __importStar(require('../../hooks/rule-injection-resolver')));
+                        await handleRuleInjectionResolver(input);
+                        break;
+                    }
                     default:
                         console.error(`Unknown hook: ${name}`);
                         console.error('Available: correction-detector, memory-stop, precompact-preserve, memory-sync, tool-outcome-watcher, session-end-checkpoint');

package/dist/hooks/memory-stop-hook.js

@@ -174,9 +174,9 @@ async function handleMemoryStop(input) {
     // Prune old outcome data to prevent unbounded table growth
     try {
         const pruned = outcomeStorage.pruneOldData();
-        const total = pruned.episodes + pruned.events + pruned.lessons + pruned.stats;
+        const total = pruned.episodes + pruned.events + pruned.lessons + pruned.stats + pruned.injections;
         if (total > 0) {
-            (0, shared_1.hookLog)('memory-stop', `Pruned: ${pruned.episodes} episodes, ${pruned.events} events, ${pruned.lessons} lessons, ${pruned.stats} orphaned stats`);
+            (0, shared_1.hookLog)('memory-stop', `Pruned: ${pruned.episodes} episodes, ${pruned.events} events, ${pruned.lessons} lessons, ${pruned.stats} orphaned stats, ${pruned.injections} injections`);
         }
     }
     catch (err) {

package/dist/hooks/rule-injection-resolver.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * rule-injection-resolver hook — fires on PostToolUse and PostToolUseFailure.
+ *
+ * Counterpart to rule-injector.ts. After a tool call completes (successfully
+ * or with failure), this hook resolves any rule_injection_events that were
+ * recorded for that tool_use_id with the actual outcome.
+ *
+ * The pair gives us a direct measurement of rule effectiveness:
+ *   - Rule X was injected before Bash call Y
+ *   - Bash call Y succeeded → rule X co-occurs with success
+ *   - Bash call Y failed → rule X was either ignored, wrong, or unrelated
+ *
+ * Aggregated over time, this becomes the new "is this rule helpful" signal,
+ * replacing the broken citation-detection regex (.research/rule-loading-gap.md).
+ *
+ * Always exits cleanly with no stdout — this hook only writes to the DB,
+ * it doesn't influence tool execution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleRuleInjectionResolver = handleRuleInjectionResolver;
+const shared_1 = require("./shared");
+const outcome_storage_1 = require("../services/outcome-storage");
+async function handleRuleInjectionResolver(input) {
+    const toolUseId = input?.tool_use_id ?? '';
+    const eventName = input?.hook_event_name ?? '';
+    if (!toolUseId) {
+        return;
+    }
+    // Outcome inference: PostToolUseFailure means failure, anything else means success.
+    // (PostToolUse fires on success; PostToolUseFailure on tool errors.)
+    const outcome = eventName === 'PostToolUseFailure' ? 'failure' : 'success';
+    try {
+        const outcomeStorage = outcome_storage_1.OutcomeStorage.getInstance();
+        const resolved = outcomeStorage.resolveRuleInjections(toolUseId, outcome);
+        if (resolved > 0) {
+            (0, shared_1.hookLog)('rule-injection-resolver', `Resolved ${resolved} rule injection(s) for ${toolUseId} as ${outcome}`);
+        }
+    }
+    catch (err) {
+        (0, shared_1.hookLog)('rule-injection-resolver', `Error: ${err.message}`);
+    }
+}

package/dist/hooks/rule-injector.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * rule-injector hook — fires on Claude Code's PreToolUse event.
+ *
+ * Just-in-time rule injection (JITRI). The core fix for the rule-loading gap
+ * documented in .research/rule-loading-gap.md: rules are loaded once at session
+ * start, then ignored when the agent acts because they're 50,000 tokens upstream
+ * by the time of the action. This hook closes that gap by searching active rules
+ * for matches against THIS specific tool call and injecting the top matches as
+ * a system-reminder block immediately adjacent to the tool action.
+ *
+ * Output mechanism (verified against cc-source-code/utils/hooks.ts:621 and
+ * services/tools/toolHooks.ts:565):
+ *   - Hook prints JSON to stdout
+ *   - JSON includes hookSpecificOutput.additionalContext
+ *   - CC wraps that string in a <system-reminder> block via wrapInSystemReminder()
+ *     and creates a meta user message at the moment of the tool call
+ *   - The agent sees the rules adjacent to the action it's about to take
+ *
+ * No LLM call in the hot path — pure keyword-based ranking, ~10-30ms typical.
+ *
+ * Each injection is recorded as a rule_injection_event so we can later
+ * resolve it with the tool outcome (success/failure) and measure rule
+ * effectiveness directly. This is the meter that replaces the broken
+ * citation-detection regex.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleRuleInjector = handleRuleInjector;
+const shared_1 = require("./shared");
+const memory_1 = require("../services/memory");
+const config_1 = require("../services/config");
+const outcome_storage_1 = require("../services/outcome-storage");
+const rule_retrieval_1 = require("../services/rule-retrieval");
+const memory_tools_1 = require("../mcp/tools/memory-tools");
+const TYPE_LABELS = {
+    correction: 'correction',
+    devops: 'devops',
+    preference: 'preference',
+    failure: 'avoid',
+    'project-knowledge': 'project',
+};
+/**
+ * Render a rule's value for injection. Reuses the same formatRuleValue helper
+ * that handleLoadRules uses (memory-tools.ts), so the rule-injector and
+ * load_rules output stay consistent. handles all the historical value shapes
+ * including nested-content failures and stringified-JSON content.
+ */
+function extractRuleSnippet(value) {
+    let snippet = (0, memory_tools_1.formatRuleValue)(value);
+    // formatRuleValue may return a stringified JSON for legacy shapes where
+    // value.content is a JSON string. Try one parse-and-extract pass to pull
+    // out a more readable summary.
+    if (snippet.startsWith('{') && snippet.includes('what_failed')) {
+        try {
+            const parsed = JSON.parse(snippet);
+            if (typeof parsed?.what_failed === 'string') {
+                snippet = parsed.what_failed;
+            }
+        }
+        catch { /* fall through with the stringified JSON */ }
+    }
+    return snippet;
+}
+function formatInjection(matches, toolName) {
+    if (matches.length === 0)
+        return '';
+    const lines = matches.map(m => {
+        const label = TYPE_LABELS[m.rule.type] ?? m.rule.type;
+        const snippet = extractRuleSnippet(m.rule.value).substring(0, 200).replace(/\s+/g, ' ').trim();
+        return `• [${label}] ${snippet}`;
+    });
+    return (`Recall: ${matches.length} rule${matches.length === 1 ? '' : 's'} relevant to this ${toolName} call. ` +
+        `Apply them or explicitly note why they don't fit:\n${lines.join('\n')}`);
+}
+async function handleRuleInjector(input) {
+    const toolName = input?.tool_name ?? '';
+    const toolInput = input?.tool_input ?? {};
+    const toolUseId = input?.tool_use_id ?? '';
+    if (!toolName) {
+        // Nothing to do — print empty JSON so CC parses it cleanly
+        process.stdout.write('{}\n');
+        return;
+    }
+    // Skip the hook for our own tools so we don't recursively inject rules
+    // about claude-recall into claude-recall calls. The agent already has
+    // claude-recall context when calling its own tools.
+    if (toolName.startsWith('mcp__claude-recall__') || toolName.startsWith('mcp__claude_recall')) {
+        process.stdout.write('{}\n');
+        return;
+    }
+    try {
+        const projectId = config_1.ConfigService.getInstance().getProjectId();
+        const memoryService = memory_1.MemoryService.getInstance();
+        // Fetch all active rules for this project. We pass them all to the ranker
+        // because the ranking function is fast and we want sticky rules to surface
+        // even when token overlap is low.
+        const activeRules = memoryService.loadActiveRules(projectId);
+        const allRules = [
+            ...activeRules.preferences,
+            ...activeRules.corrections,
+            ...activeRules.failures,
+            ...activeRules.devops,
+        ].map(m => ({
+            key: m.key,
+            type: m.type,
+            value: m.value,
+            is_active: m.is_active !== false,
+            timestamp: m.timestamp,
+            project_id: m.project_id,
+        }));
+        if (allRules.length === 0) {
+            (0, shared_1.hookLog)('rule-injector', `No active rules for project ${projectId} (tool=${toolName})`);
+            process.stdout.write('{}\n');
+            return;
+        }
+        const matches = (0, rule_retrieval_1.rankRulesForToolCall)(toolName, toolInput, allRules);
+        if (matches.length === 0) {
+            (0, shared_1.hookLog)('rule-injector', `No relevant rules for ${toolName} (scanned ${allRules.length})`);
+            process.stdout.write('{}\n');
+            return;
+        }
+        // Record each injection so PostToolUse can resolve it with the outcome
+        try {
+            const outcomeStorage = outcome_storage_1.OutcomeStorage.getInstance();
+            for (const m of matches) {
+                outcomeStorage.recordRuleInjection({
+                    rule_key: m.rule.key,
+                    tool_name: toolName,
+                    tool_use_id: toolUseId,
+                    project_id: projectId,
+                    match_score: m.score,
+                    matched_tokens: m.matchedTokens,
+                });
+            }
+        }
+        catch (err) {
+            // Non-critical — failure to record shouldn't block the injection itself
+            (0, shared_1.hookLog)('rule-injector', `Failed to record injections: ${err.message}`);
+        }
+        const additionalContext = formatInjection(matches, toolName);
+        const output = {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                additionalContext,
+            },
+        };
+        process.stdout.write(JSON.stringify(output) + '\n');
+        (0, shared_1.hookLog)('rule-injector', `Injected ${matches.length} rule(s) for ${toolName} (top score=${matches[0].score.toFixed(3)})`);
+    }
+    catch (err) {
+        (0, shared_1.hookLog)('rule-injector', `Error: ${err.message}`);
+        // Best-effort — never block the tool call
+        process.stdout.write('{}\n');
+    }
+}

package/dist/memory/storage.js

@@ -206,6 +206,29 @@ class MemoryStorage {
           last_retrieved_at TEXT
         )`);
             }
+            // v0.21.x: Just-in-time rule injection tracking. Replaces the broken
+            // citation-detection regex with direct measurement of "was the rule
+            // present at the moment of action." See .research/rule-loading-gap.md
+            // for the design motivation.
+            const injectionTable = this.db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name = 'rule_injection_events'").get();
+            if (!injectionTable) {
+                this.db.exec(`CREATE TABLE rule_injection_events (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          rule_key TEXT NOT NULL,
+          tool_name TEXT NOT NULL,
+          tool_use_id TEXT,
+          project_id TEXT,
+          match_score REAL,
+          matched_tokens TEXT,
+          injected_at INTEGER NOT NULL,
+          tool_outcome TEXT,
+          resolved_at INTEGER
+        )`);
+                this.db.exec('CREATE INDEX idx_injection_rule ON rule_injection_events(rule_key)');
+                this.db.exec('CREATE INDEX idx_injection_project ON rule_injection_events(project_id)');
+                this.db.exec('CREATE INDEX idx_injection_tool_use ON rule_injection_events(tool_use_id)');
+                this.db.exec('CREATE INDEX idx_injection_unresolved ON rule_injection_events(resolved_at) WHERE resolved_at IS NULL');
+            }
         }
         catch (error) {
             console.error('⚠️  Schema migration error:', error);

package/dist/pi/extension.js

@@ -14,6 +14,7 @@ const config_1 = require("../services/config");
 const outcome_storage_1 = require("../services/outcome-storage");
 const logging_1 = require("../services/logging");
 const event_processors_1 = require("../shared/event-processors");
+const rule_retrieval_1 = require("../services/rule-retrieval");
 const LOAD_RULES_DIRECTIVE = 'Before your FIRST action, briefly state which rules below you will apply to this task.\n' +
     'As you work, cite each rule at the point where it influences your action:\n' +
     '(applied from memory: <short rule name>)\n' +
@@ -44,6 +45,38 @@ function extractVal(value) {
     }
     return String(value ?? '');
 }
+/**
+ * Format the just-in-time relevant rules for injection into the per-turn
+ * system prompt addendum. Mirrors the CC rule-injector hook output but as
+ * plain text (no system-reminder wrapper since Pi handles that itself).
+ */
+function formatJitReminder(matches) {
+    if (matches.length === 0)
+        return '';
+    const TYPE_LABELS = {
+        correction: 'correction',
+        devops: 'devops',
+        preference: 'preference',
+        failure: 'avoid',
+        'project-knowledge': 'project',
+    };
+    const lines = matches.map(m => {
+        const label = TYPE_LABELS[m.rule.type] ?? m.rule.type;
+        const v = m.rule.value;
+        let snippet = '';
+        if (typeof v === 'string')
+            snippet = v;
+        else if (v && typeof v === 'object') {
+            snippet = (typeof v.content === 'string' ? v.content
+                : typeof v.value === 'string' ? v.value
+                    : typeof v.title === 'string' ? v.title
+                        : JSON.stringify(v).substring(0, 200));
+        }
+        return `• [${label}] ${snippet.substring(0, 200).replace(/\s+/g, ' ').trim()}`;
+    });
+    return (`Recall: ${matches.length} rule${matches.length === 1 ? '' : 's'} relevant to this turn. ` +
+        `Apply them or explicitly note why they don't fit:\n${lines.join('\n')}`);
+}
 /** Format active rules as markdown sections. */
 function formatRules(rules) {
     const sections = [];
@@ -97,17 +130,63 @@ function default_1(pi) {
             // Non-critical
         }
     });
-    // --- Event: inject rules before first agent turn ---
+    // --- Event: inject rules before each agent turn (full load on first turn,
+    //     just-in-time relevant rules on subsequent turns based on the user's
+    //     current prompt — Pi's analog of CC's PreToolUse rule injector) ---
     pi.on('before_agent_start', (_event, _ctx) => {
-        if (rulesLoaded)
-            return;
-        rulesLoaded = true;
         try {
             const ms = memory_1.MemoryService.getInstance();
             const rules = ms.loadActiveRules(projectId || undefined);
-            const body = formatRules(rules);
-            if (body) {
-                return { systemPrompt: _event.systemPrompt + '\n\n' + LOAD_RULES_DIRECTIVE + '\n\n---\n\n' + body };
+            const allRulesFlat = [
+                ...rules.preferences,
+                ...rules.corrections,
+                ...rules.failures,
+                ...rules.devops,
+            ].map(m => ({
+                key: m.key,
+                type: m.type,
+                value: m.value,
+                is_active: m.is_active !== false,
+                timestamp: m.timestamp,
+                project_id: m.project_id,
+            }));
+            // First turn: full ruleset to seed context, plus JIT injection for the
+            // very first prompt. Subsequent turns: JIT only — context already has
+            // the full set from turn 1.
+            let systemPromptOut;
+            if (!rulesLoaded) {
+                rulesLoaded = true;
+                const body = formatRules(rules);
+                if (body) {
+                    systemPromptOut = _event.systemPrompt + '\n\n' + LOAD_RULES_DIRECTIVE + '\n\n---\n\n' + body;
+                }
+            }
+            // JIT injection on every turn — match rules against the current user prompt
+            const userPrompt = _event?.prompt ?? '';
+            if (userPrompt && allRulesFlat.length > 0) {
+                const matches = (0, rule_retrieval_1.rankRulesForToolCall)('agent_turn', { command: userPrompt }, allRulesFlat);
+                if (matches.length > 0) {
+                    const reminder = formatJitReminder(matches);
+                    systemPromptOut = (systemPromptOut ?? _event.systemPrompt) + '\n\n' + reminder;
+                    // Record each injection so we can correlate with success/failure later
+                    try {
+                        const outcomeStorage = outcome_storage_1.OutcomeStorage.getInstance();
+                        for (const m of matches) {
+                            outcomeStorage.recordRuleInjection({
+                                rule_key: m.rule.key,
+                                tool_name: 'pi:agent_turn',
+                                tool_use_id: `pi_turn_${Date.now()}`,
+                                project_id: projectId,
+                                match_score: m.score,
+                                matched_tokens: m.matchedTokens,
+                            });
+                        }
+                    }
+                    catch { /* non-critical */ }
+                }
+            }
+            if (systemPromptOut) {
+                return { systemPrompt: systemPromptOut };
             }
         }
         catch {

package/dist/services/outcome-storage.js

@@ -201,21 +201,81 @@ class OutcomeStorage {
         times_unhelpful = times_unhelpful + 1
     `).run(key);
     }
+    // --- Rule injection events (just-in-time rule injection meter) ---
+    //
+    // Replaces the broken citation-detection regex. Every time the JITRI hook
+    // injects a rule into a tool call's context, we record an event here.
+    // PostToolUse later resolves the event with the tool outcome (success or
+    // failure), giving us direct evidence of whether rules-at-the-moment-of-action
+    // are correlated with successful tool calls — without depending on the model
+    // remembering to write "(applied from memory: ...)" markers.
+    recordRuleInjection(input) {
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO rule_injection_events
+        (rule_key, tool_name, tool_use_id, project_id, match_score, matched_tokens, injected_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(input.rule_key, input.tool_name, input.tool_use_id ?? null, input.project_id ?? null, input.match_score, JSON.stringify(input.matched_tokens), now);
+    }
+    /**
+     * Resolve all unresolved injection events for a given tool_use_id with
+     * the tool's outcome. Called from PostToolUse / PostToolUseFailure.
+     */
+    resolveRuleInjections(toolUseId, outcome) {
+        const now = Date.now();
+        const result = this.db.prepare(`
+      UPDATE rule_injection_events
+      SET tool_outcome = ?, resolved_at = ?
+      WHERE tool_use_id = ? AND resolved_at IS NULL
+    `).run(outcome, now, toolUseId);
+        return result.changes;
+    }
+    /**
+     * Per-rule injection summary for the outcomes CLI.
+     * Returns: rule_key, total injections, success/failure counts, helpfulness rate.
+     */
+    getInjectionStats(opts) {
+        const limit = opts?.limit ?? 50;
+        const where = opts?.project_id ? 'WHERE project_id = ?' : '';
+        const params = opts?.project_id ? [opts.project_id, limit] : [limit];
+        const rows = this.db.prepare(`
+      SELECT
+        rule_key,
+        COUNT(*) as total_injections,
+        SUM(CASE WHEN tool_outcome = 'success' THEN 1 ELSE 0 END) as successes,
+        SUM(CASE WHEN tool_outcome = 'failure' THEN 1 ELSE 0 END) as failures,
+        SUM(CASE WHEN resolved_at IS NULL THEN 1 ELSE 0 END) as unresolved
+      FROM rule_injection_events
+      ${where}
+      GROUP BY rule_key
+      ORDER BY total_injections DESC
+      LIMIT ?
+    `).all(...params);
+        return rows.map(r => ({
+            ...r,
+            success_rate: (r.successes + r.failures) > 0
+                ? r.successes / (r.successes + r.failures)
+                : 0,
+        }));
+    }
     /**
      * Prune old data from outcome tables to prevent unbounded growth.
      * - Episodes older than 90 days
      * - Outcome events older than 90 days
      * - Rejected/archived candidate lessons older than 14 days
      * - Orphaned memory_stats entries (key no longer in memories table)
+     * - Rule injection events older than 90 days
      */
     pruneOldData() {
         const cutoff90 = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000).toISOString();
         const cutoff14 = new Date(Date.now() - 14 * 24 * 60 * 60 * 1000).toISOString();
+        const cutoff90Ms = Date.now() - 90 * 24 * 60 * 60 * 1000;
         const episodes = this.db.prepare('DELETE FROM episodes WHERE created_at < ?').run(cutoff90).changes;
         const events = this.db.prepare('DELETE FROM outcome_events WHERE created_at < ?').run(cutoff90).changes;
         const lessons = this.db.prepare("DELETE FROM candidate_lessons WHERE status IN ('rejected', 'archived') AND updated_at < ?").run(cutoff14).changes;
         const stats = this.db.prepare('DELETE FROM memory_stats WHERE memory_key NOT IN (SELECT key FROM memories)').run().changes;
-        return { episodes, events, lessons, stats };
+        const injections = this.db.prepare('DELETE FROM rule_injection_events WHERE injected_at < ?').run(cutoff90Ms).changes;
+        return { episodes, events, lessons, stats, injections };
     }
 }
 exports.OutcomeStorage = OutcomeStorage;

package/dist/services/rule-retrieval.js

@@ -0,0 +1,221 @@
+"use strict";
+/**
+ * Rule retrieval & ranking — the core of just-in-time rule injection (JITRI).
+ *
+ * This module is the meter that replaces the broken citation-detection regex.
+ * Instead of trying to detect "(applied from memory: ...)" markers in agent
+ * output (which empirically doesn't work — see .research/rule-loading-gap.md),
+ * we measure "was the relevant rule present at the moment of action" by
+ * injecting matched rules into the agent's context immediately adjacent to
+ * each tool call via a PreToolUse hook.
+ *
+ * This file is intentionally pure — it takes pre-fetched rules as input and
+ * has no DB access. The DB-fetching wrapper lives in RuleRetrievalService.
+ * Keeping the ranking pure makes it dead-simple to test and lets the same
+ * function serve both the CC PreToolUse hook path and the Pi
+ * `before_agent_start` path.
+ *
+ * Ranking ingredients:
+ *   1. Token overlap (Jaccard between query tokens and rule tokens) — main signal
+ *   2. Sticky boost (+0.5) — sticky rules always bubble to the top
+ *   3. Type priority — corrections > devops > preferences > failures
+ *   4. Recency boost — rules updated within 7 days get a small lift
+ *
+ * Filter: only rules with combined score >= MIN_SCORE are returned. Caps at
+ * TOP_N (3) so the additionalContext payload stays small enough to fit
+ * comfortably in the agent's attention budget.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildToolCallQuery = buildToolCallQuery;
+exports.rankRulesForToolCall = rankRulesForToolCall;
+const STOP_WORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'but', 'is', 'are', 'was', 'were', 'be', 'been',
+    'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'should',
+    'could', 'may', 'might', 'must', 'shall', 'can', 'this', 'that', 'these', 'those',
+    'i', 'you', 'he', 'she', 'it', 'we', 'they', 'them', 'their', 'what', 'which',
+    'who', 'when', 'where', 'why', 'how', 'all', 'each', 'every', 'both', 'few',
+    'more', 'most', 'other', 'some', 'such', 'no', 'nor', 'not', 'only', 'own',
+    'same', 'so', 'than', 'too', 'very', 'just', 'as', 'in', 'on', 'at', 'to',
+    'for', 'of', 'with', 'by', 'from', 'up', 'down', 'into', 'over', 'under',
+]);
+const MIN_TOKEN_LENGTH = 3;
+const MIN_SCORE = 0.15;
+const TOP_N = 3;
+const RECENT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const STICKY_BOOST = 0.5;
+const RECENCY_BOOST = 0.1;
+// Type boosts: corrections and devops are ACTIONABLE rules — boost them.
+// Failures are auto-captured post-hoc records that tend to accumulate as
+// noise (every "test failed" attempt becomes a memory). Deboost so generic
+// failure entries need substantial token overlap to surface; real anti-patterns
+// with high overlap still come through. See .research/rule-loading-gap.md.
+const TYPE_BOOSTS = {
+    correction: 0.25,
+    devops: 0.20,
+    preference: 0.10,
+    'project-knowledge': 0.05,
+    failure: -0.10,
+};
+/**
+ * Tokenize a string: lowercase, keep alphanumeric only, drop short tokens
+ * and stop words.
+ */
+function tokenize(text) {
+    if (!text || typeof text !== 'string')
+        return [];
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter(t => t.length >= MIN_TOKEN_LENGTH && !STOP_WORDS.has(t));
+}
+/**
+ * Build the query tokens from a tool call. Includes the tool name plus
+ * relevant fields from tool_input depending on the tool type.
+ *
+ * For Bash:  command
+ * For Edit:  file_path + old_string (truncated)
+ * For Write: file_path + content (truncated)
+ * For Read/Glob: file_path + pattern
+ * For Grep:  pattern + path
+ * For Task:  description + prompt
+ * For others: best-effort stringification of all string-valued fields
+ */
+function buildToolCallQuery(toolName, toolInput) {
+    const parts = [toolName];
+    if (toolInput && typeof toolInput === 'object') {
+        const stringFields = ['command', 'file_path', 'pattern', 'path', 'description', 'prompt', 'query', 'url'];
+        for (const field of stringFields) {
+            const v = toolInput[field];
+            if (typeof v === 'string')
+                parts.push(v);
+        }
+        // Truncated diff fields — keep them but cap length
+        if (typeof toolInput.old_string === 'string') {
+            parts.push(toolInput.old_string.substring(0, 200));
+        }
+        if (typeof toolInput.new_string === 'string') {
+            parts.push(toolInput.new_string.substring(0, 200));
+        }
+        if (typeof toolInput.content === 'string') {
+            parts.push(toolInput.content.substring(0, 200));
+        }
+    }
+    return tokenize(parts.join(' '));
+}
+/**
+ * Recursively extract leaf string values from a value object — used to build
+ * the rule's token vocabulary. Skips JSON structure tokens (keys, brackets).
+ */
+function extractRuleText(value) {
+    if (value == null)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value)) {
+        return value.map(extractRuleText).join(' ');
+    }
+    if (typeof value === 'object') {
+        // Prefer common content fields first
+        if (typeof value.content === 'string')
+            return value.content;
+        if (typeof value.value === 'string')
+            return value.value;
+        // Recurse into all string-leaf fields, including nested
+        const parts = [];
+        for (const v of Object.values(value)) {
+            const text = extractRuleText(v);
+            if (text)
+                parts.push(text);
+        }
+        return parts.join(' ');
+    }
+    return '';
+}
+/**
+ * Check if a rule has the sticky flag set (in value.sticky or top-level).
+ */
+function isSticky(rule) {
+    if (rule.value && typeof rule.value === 'object' && rule.value.sticky === true)
+        return true;
+    return false;
+}
+/**
+ * Compute Jaccard-like overlap: |intersection| / |query|.
+ * Asymmetric: we care what fraction of the QUERY tokens appear in the rule,
+ * not the other way around. A long rule that contains all query tokens scores
+ * higher than a short rule that contains some query tokens — which matches
+ * intuition (specific rules win).
+ */
+function tokenOverlap(queryTokens, ruleTokens) {
+    if (queryTokens.length === 0)
+        return { score: 0, matched: [] };
+    const matched = [];
+    for (const t of queryTokens) {
+        if (ruleTokens.has(t))
+            matched.push(t);
+    }
+    return { score: matched.length / queryTokens.length, matched };
+}
+/**
+ * A "promoted lesson" is a failure-type memory that the promotion engine has
+ * graduated into an actionable rule. Detected by key prefix or value.source.
+ * These ARE worth surfacing in JIT injection (unlike raw failure logs which
+ * are just noise from the auto-capture pipeline).
+ */
+function isPromotedLesson(rule) {
+    if (rule.key && rule.key.startsWith('promoted_'))
+        return true;
+    if (rule.value && typeof rule.value === 'object' && rule.value.source === 'promotion-engine')
+        return true;
+    return false;
+}
+/**
+ * Rank a list of rules against a tool call. Returns the top N (default 3)
+ * with score >= MIN_SCORE, sorted by descending score.
+ *
+ * Sticky rules always pass the threshold (their boost guarantees it).
+ *
+ * Raw failures are EXCLUDED from JIT injection — they're reference material,
+ * not actionable rules at the moment of decision. The auto-capture pipeline
+ * generates many low-value failure entries ("Avoid: Test command reported
+ * failures: npm test ...") that share tokens with common dev commands but
+ * aren't useful as decision-time guidance. The actionable equivalents are
+ * (a) promoted lessons (failures graduated by the promotion engine — these
+ * ARE included), (b) corrections, and (c) devops rules. See
+ * .research/rule-loading-gap.md for the full reasoning.
+ */
+function rankRulesForToolCall(toolName, toolInput, rules) {
+    const queryTokens = buildToolCallQuery(toolName, toolInput);
+    if (queryTokens.length === 0)
+        return [];
+    const ranked = [];
+    for (const rule of rules) {
+        if (rule.is_active === false)
+            continue;
+        // Exclude raw failures from JIT injection. Promoted lessons survive
+        // because they've been graduated into actionable rules.
+        if (rule.type === 'failure' && !isPromotedLesson(rule))
+            continue;
+        const ruleText = extractRuleText(rule.value);
+        if (!ruleText)
+            continue;
+        const ruleTokens = new Set(tokenize(ruleText));
+        const { score: overlapScore, matched } = tokenOverlap(queryTokens, ruleTokens);
+        let totalScore = overlapScore;
+        if (isSticky(rule))
+            totalScore += STICKY_BOOST;
+        const typeBoost = TYPE_BOOSTS[rule.type] ?? 0;
+        totalScore += typeBoost * (overlapScore > 0 ? 1 : 0); // Only apply type boost if there's some overlap
+        if (rule.timestamp && Date.now() - rule.timestamp < RECENT_WINDOW_MS) {
+            totalScore += RECENCY_BOOST * (overlapScore > 0 ? 1 : 0);
+        }
+        if (totalScore >= MIN_SCORE) {
+            ranked.push({ rule, score: totalScore, matchedTokens: matched });
+        }
+    }
+    ranked.sort((a, b) => b.score - a.score);
+    return ranked.slice(0, TOP_N);
+}

package/package.json

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