claude-recall 0.20.5 → 0.20.7

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

@@ -8,7 +8,7 @@ source: claude-recall
 
 # Corrections
 
-Auto-generated from 12 memories. Last updated: 2026-04-02.
+Auto-generated from 15 memories. Last updated: 2026-04-06.
 
 ## Rules
 
@@ -22,6 +22,9 @@ Auto-generated from 12 memories. Last updated: 2026-04-02.
 - CORRECTION: Memory with complex metadata
 - CORRECTION: Memory with complex metadata
 - CORRECTION: Memory with complex metadata
+- CORRECTION: Memory with complex metadata
+- CORRECTION: Memory with complex metadata
+- CORRECTION: Memory with complex metadata
 - CORRECTION: License copyright should include user's name instead of 'Claude Recall Contributors'
 - CORRECTION: License copyright should list your name instead of 'Claude Recall Contributors'
 

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

@@ -1,9 +1,12 @@
 {
   "topicId": "corrections",
-  "sourceHash": "10b0ac995ebe0c54ad0a5972f28ba4a63e3429879bfb5aa92add0e616711aa33",
-  "memoryCount": 12,
-  "generatedAt": "2026-04-02T22:43:06.559Z",
+  "sourceHash": "6bede026828253771f48ae5c05e80878ab69beb584dfc06f416814840016ad6c",
+  "memoryCount": 15,
+  "generatedAt": "2026-04-06T16:51:19.054Z",
   "memoryKeys": [
+    "memory_1775494279035_j6uj5lzxo",
+    "memory_1775492069326_vksvzmt3f",
+    "memory_1775491767369_sepsjmg8y",
     "memory_1775169786543_43p8to1hu",
     "memory_1775169704632_wzwczltzu",
     "memory_1775169639101_rmxkftqtk",

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

@@ -8,10 +8,30 @@ source: claude-recall
 
 # Preferences
 
-Auto-generated from 54 memories. Last updated: 2026-04-02.
+Auto-generated from 74 memories. Last updated: 2026-04-06.
 
 ## Rules
 
+- Session test preference 1775494279149
+- Test preference 1775494279061-2
+- Test preference 1775494279061-1
+- Test preference 1775494279061-0
+- Test memory content
+- Session test preference 1775492069465
+- Test preference 1775492069353-2
+- Test preference 1775492069353-1
+- Test preference 1775492069353-0
+- Test memory content
+- Session test preference 1775491767519
+- Test preference 1775491767395-2
+- Test preference 1775491767395-1
+- Test preference 1775491767395-0
+- Test memory content
+- When planning implementation work, always divide into phases/stages. Each phase must have its own verification tests with concrete commands and expected outputs. Only proceed to the next phase when the current phase's tests pass. Never combine untested changes into a single deployment. This prevents hours of debugging cascading failures.
+- Solving issues and testing that they are solved takes priority over committing and pushing. Don't suggest committing until the fix is verified end-to-end.
+- When the user says "jam" it means "just answer me" — give a direct, concise answer without extra exploration, tool calls, or elaboration. Skip the research and just respond.
+- After each refactoring, document the changes made. Don't batch documentation to the end — write it as you go.
+- Any major refactoring requires exhaustive search to make sure nothing is missed. Always grep/search comprehensively before and after changes to verify no stale references, broken imports, or missed files remain.
 - Session test preference 1775169786712
 - Test preference 1775169786565-2
 - Test preference 1775169786565-1

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

@@ -1,9 +1,29 @@
 {
   "topicId": "preferences",
-  "sourceHash": "d953115f40d7e590f2e4b1b034582b78ba1f1faa0d1521a6e107538ad328327d",
-  "memoryCount": 54,
-  "generatedAt": "2026-04-02T22:43:06.764Z",
+  "sourceHash": "77d6964d46ea058e3de341d9d43c79901bc596a18b5a03fa8e402368ba20b412",
+  "memoryCount": 74,
+  "generatedAt": "2026-04-06T16:51:19.174Z",
   "memoryKeys": [
+    "memory_1775494279150_n4pq7zy11",
+    "memory_1775494279108_6hbe8qoit",
+    "memory_1775494279088_nv8hjdm7s",
+    "memory_1775494279062_jx4wrwn6s",
+    "memory_1775494278982_fsc491z41",
+    "memory_1775492069467_5cturlg0a",
+    "memory_1775492069400_icg4tjivf",
+    "memory_1775492069377_goix7nu9v",
+    "memory_1775492069354_wma3zh5i7",
+    "memory_1775492069258_q9d2k28wt",
+    "memory_1775491767523_p2xtn4uak",
+    "memory_1775491767447_q1dwsdfk3",
+    "memory_1775491767421_vgntf4jt8",
+    "memory_1775491767397_f181w5lqd",
+    "memory_1775491767290_s7ntmkwpg",
+    "memory_1775491073130_p8b493ay9",
+    "memory_1775236195716_i3pb5nls7",
+    "memory_1775210227089_j433ldlva",
+    "memory_1775208934902_2kovciriy",
+    "memory_1775208477621_fqa3w21j1",
     "memory_1775169786717_1zmwoe6ai",
     "memory_1775169786630_rdudb8hbc",
     "memory_1775169786589_zurej1v51",

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

@@ -34,10 +34,11 @@ Persistent memory system that ensures Claude never repeats mistakes and always a
 
 1. **ALWAYS load rules before acting** — Call `load_rules` as your very first action in a session, before even reading files. Rules inform how you explore, not just how you edit.
 2. **ACT on loaded rules** — After loading, state which rules apply to your current task before proceeding. If a rule conflicts with your plan, follow the rule. If none apply, say so. Loading without applying is the same as not loading.
-3. **Cite applied rules inline** — When a rule influences your work: (applied from memory: <rule>)
-4. **Ask before storing** — Before calling `store_memory`, tell the user what you plan to store and ask for confirmation
-5. **Capture corrections immediately** — User fixes are highest priority (still ask first)
-6. **Never store secrets** — No API keys, passwords, tokens, or PII
+3. **Cite applied rules inline** — When a rule influences your work: (applied from memory: <rule>). Place the citation next to the action it influenced, not at the end of unrelated text.
+4. **User says "recall" / "remember" / "store this" → use Claude Recall** — When the user says any of these keywords, ALWAYS use `mcp__claude-recall__store_memory`. Do NOT write to the native memory directory (`~/.claude/projects/*/memory/`) for these requests. Claude Recall is the user's preferred memory system.
+5. **Ask before storing** — Before calling `store_memory`, tell the user what you plan to store and ask for confirmation
+6. **Capture corrections immediately** — User fixes are highest priority (still ask first)
+7. **Never store secrets** — No API keys, passwords, tokens, or PII
 
 ## Quick Reference
 

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

@@ -693,8 +693,20 @@ 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 = '10.0.0'; // v10 = add PostToolUseFailure for explicit error capture
+        settings.hooksVersion = '11.0.0'; // v11 = add SessionStart(compact) for post-compaction rule reload
         settings.hooks = {
+            SessionStart: [
+                {
+                    matcher: "compact",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: `${hookCmd} post-compact-reload`,
+                            timeout: 10
+                        }
+                    ]
+                }
+            ],
             PostToolUse: [
                 {
                     hooks: [

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

@@ -85,6 +85,11 @@ class HookCommands {
                         await handleToolFailure(input);
                         break;
                     }
+                    case 'post-compact-reload': {
+                        const { handlePostCompactReload } = await Promise.resolve().then(() => __importStar(require('../../hooks/post-compact-reload')));
+                        await handlePostCompactReload(input);
+                        break;
+                    }
                     case 'bash-failure-watcher': {
                         // Backward compat alias — routes to tool-outcome-watcher
                         const { handleBashFailureWatcher } = await Promise.resolve().then(() => __importStar(require('../../hooks/tool-outcome-watcher')));

package/dist/hooks/llm-classifier.js

@@ -8,6 +8,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.classifyWithLLM = classifyWithLLM;
 exports.extractHindsightHint = extractHindsightHint;
+exports.extractSessionLearningsWithLLM = extractSessionLearningsWithLLM;
 exports.classifyBatchWithLLM = classifyBatchWithLLM;
 // Lazy singleton — avoid import cost when API key is absent
 let clientInstance; // undefined = not yet checked
@@ -148,6 +149,64 @@ async function extractHindsightHint(failureDescription, context) {
         return null;
     }
 }
+const SESSION_EXTRACTION_PROMPT = `You are analyzing a coding session transcript to extract durable project knowledge.
+
+The transcript shows tool calls (Bash, Edit, Read, Grep, etc.) and their results, plus user and assistant messages.
+
+Extract ONLY facts useful in FUTURE sessions:
+- Project conventions discovered (file structure, naming patterns, build tools, test frameworks)
+- Workflow patterns that worked or failed (e.g. "tests must be run from project root")
+- Technical constraints or gotchas encountered (e.g. "this project uses ESM, not CJS")
+- Environment requirements discovered (e.g. "needs Node 20+", "uses pnpm not npm")
+
+Do NOT extract:
+- Task-specific details (what was built, which files changed this session)
+- Debugging steps unlikely to recur
+- Code patterns visible by reading the codebase
+- Anything in the EXISTING MEMORIES list below
+
+Respond with ONLY valid JSON (no markdown fences):
+[{"type":"project-knowledge|preference|devops|failure","content":"<imperative statement>","confidence":0.0-1.0}]
+
+Return [] if nothing durable was learned. Max 10 items. Each content should be a concise imperative statement (e.g. "Run tests with pnpm test, not npm test").`;
+/**
+ * Extract durable session learnings from a conversation summary using Haiku.
+ * Returns null if no API key or on any failure.
+ */
+async function extractSessionLearningsWithLLM(summary, existingMemories) {
+    const client = getClient();
+    if (!client)
+        return null;
+    try {
+        const memList = existingMemories.length > 0
+            ? existingMemories.map(m => `- ${m}`).join('\n')
+            : '(none)';
+        const systemPrompt = SESSION_EXTRACTION_PROMPT + `\n\nEXISTING MEMORIES (do not duplicate):\n${memList}`;
+        const response = await client.messages.create({
+            model: MODEL,
+            max_tokens: 1000,
+            system: systemPrompt,
+            messages: [{ role: 'user', content: summary }],
+        });
+        const content = response.content?.[0];
+        if (content?.type !== 'text')
+            return null;
+        const results = parseJSON(content.text);
+        if (!Array.isArray(results))
+            return null;
+        const validTypes = ['project-knowledge', 'preference', 'devops', 'failure'];
+        return results
+            .filter((r) => r && validTypes.includes(r.type) && typeof r.content === 'string' && r.content.length > 5)
+            .map((r) => ({
+            type: r.type,
+            content: r.content,
+            confidence: typeof r.confidence === 'number' ? r.confidence : 0.7,
+        }));
+    }
+    catch {
+        return null;
+    }
+}
 async function classifyBatchWithLLM(texts) {
     if (texts.length === 0)
         return [];

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

@@ -46,6 +46,7 @@ const memory_1 = require("../services/memory");
 const config_1 = require("../services/config");
 const failure_detectors_1 = require("./failure-detectors");
 const outcome_storage_1 = require("../services/outcome-storage");
+const event_processors_1 = require("../shared/event-processors");
 const MAX_STORE = 3;
 async function handleMemoryStop(input) {
     const transcriptPath = input?.transcript_path ?? '';
@@ -107,6 +108,37 @@ async function handleMemoryStop(input) {
         (0, shared_1.hookLog)('memory-stop', `Captured ${result.type}: ${result.extract.substring(0, 80)}`);
     }
     (0, shared_1.hookLog)('memory-stop', `Session end: stored ${stored} memories from ${entries.length} entries`);
+    // Session extraction: learn from long coding sessions (reads wider window)
+    try {
+        (0, event_processors_1.setLogFunction)(shared_1.hookLog);
+        const sessionEntries = (0, shared_1.readTranscriptTail)(transcriptPath, 50);
+        if (sessionEntries.length >= 10) {
+            const conversationEntries = buildConversationEntries(sessionEntries);
+            // Record failed subagent outcomes
+            for (const entry of conversationEntries) {
+                if (entry.toolName === 'Agent' && entry.isError) {
+                    try {
+                        outcomeStorage.createOutcomeEvent({
+                            event_type: 'agent_failure',
+                            actor: 'tool',
+                            action_summary: entry.text,
+                            next_state_summary: entry.text,
+                            tags: ['agent', 'subagent'],
+                        });
+                    }
+                    catch { /* non-critical */ }
+                }
+            }
+            const extracted = await (0, event_processors_1.extractSessionLearnings)(conversationEntries, input?.session_id ?? '', projectId, 5);
+            if (extracted > 0) {
+                (0, shared_1.hookLog)('memory-stop', `Session extraction: stored ${extracted} learnings`);
+                stored += extracted;
+            }
+        }
+    }
+    catch (err) {
+        (0, shared_1.hookLog)('memory-stop', `Session extraction error: ${(0, shared_1.safeErrorMessage)(err)}`);
+    }
     // Scan for citations in assistant messages to track compliance
     scanForCitations(transcriptPath);
     // Scan transcript for failure signals (non-zero exits, test cycles, backtracking, etc.)
@@ -385,3 +417,62 @@ function extractTagsFromContext(context) {
     }
     return tags;
 }
+/**
+ * Convert raw JSONL transcript entries to ConversationEntry[] for session extraction.
+ */
+function buildConversationEntries(entries) {
+    const result = [];
+    for (const entry of entries) {
+        if ((0, shared_1.isUserEntry)(entry)) {
+            const text = (0, shared_1.extractTextFromEntry)(entry);
+            if (text && text.length > 5) {
+                result.push({ role: 'user', text: text.substring(0, 300) });
+            }
+        }
+        else {
+            const text = (0, shared_1.extractTextFromEntry)(entry);
+            if (text && text.length > 5) {
+                // Detect subagent task notifications
+                const notifMatch = text.match(/<task-notification>[\s\S]*?<\/task-notification>/);
+                if (notifMatch) {
+                    const status = notifMatch[0].match(/<status>(.*?)<\/status>/)?.[1] ?? 'unknown';
+                    const summary = notifMatch[0].match(/<summary>(.*?)<\/summary>/)?.[1] ?? '';
+                    result.push({
+                        role: 'tool_result',
+                        text: `Agent ${status}: ${summary}`.substring(0, 300),
+                        toolName: 'Agent',
+                        isError: status === 'failed' || status === 'killed',
+                    });
+                }
+                else {
+                    result.push({ role: 'assistant', text: text.substring(0, 300) });
+                }
+            }
+        }
+    }
+    // Extract paired tool interactions across all entries
+    try {
+        const interactions = (0, shared_1.extractToolInteractions)(entries);
+        for (const ti of interactions) {
+            if (ti.call) {
+                result.push({
+                    role: 'assistant',
+                    text: JSON.stringify(ti.call.input || {}).substring(0, 150),
+                    toolName: ti.call.name,
+                });
+            }
+            if (ti.result) {
+                result.push({
+                    role: 'tool_result',
+                    text: ti.result.content.substring(0, 200),
+                    toolName: ti.call.name,
+                    isError: ti.result.isError,
+                });
+            }
+        }
+    }
+    catch {
+        // Skip if parsing fails
+    }
+    return result;
+}

package/dist/hooks/post-compact-reload.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * post-compact-reload hook — fires on SessionStart with source "compact".
+ *
+ * After context compaction, recall rules loaded earlier in the session are
+ * gone from the model's context. This hook re-injects them by outputting
+ * the active rules to stdout, which CC injects as a system message.
+ *
+ * Input: { session_id, hook_event_name: "SessionStart", source: "compact" }
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handlePostCompactReload = handlePostCompactReload;
+const shared_1 = require("./shared");
+const memory_1 = require("../services/memory");
+const config_1 = require("../services/config");
+const DIRECTIVE = 'These rules were re-loaded after context compaction.\n' +
+    'Continue applying them. Cite at the point of application: (applied from memory: <rule>)';
+function extractVal(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'object' && value !== null) {
+        return value.content || value.value || JSON.stringify(value);
+    }
+    return String(value ?? '');
+}
+function formatRules(rules) {
+    const sections = [];
+    if (rules.preferences.length > 0) {
+        sections.push('## Preferences\n' + rules.preferences.map(m => `- ${extractVal(m.value)}`).join('\n'));
+    }
+    if (rules.corrections.length > 0) {
+        sections.push('## Corrections\n' + rules.corrections.map(m => `- ${extractVal(m.value)}`).join('\n'));
+    }
+    if (rules.failures.length > 0) {
+        sections.push('## Failures\n' + rules.failures.map(m => `- ${extractVal(m.value)}`).join('\n'));
+    }
+    if (rules.devops.length > 0) {
+        sections.push('## DevOps Rules\n' + rules.devops.map(m => `- ${extractVal(m.value)}`).join('\n'));
+    }
+    return sections.join('\n\n');
+}
+async function handlePostCompactReload(input) {
+    try {
+        const projectId = config_1.ConfigService.getInstance().getProjectId();
+        const rules = memory_1.MemoryService.getInstance().loadActiveRules(projectId);
+        const totalRules = rules.preferences.length + rules.corrections.length +
+            rules.failures.length + rules.devops.length;
+        if (totalRules === 0)
+            return;
+        const body = formatRules(rules);
+        console.log(`${DIRECTIVE}\n\n---\n\n${body}`);
+        (0, shared_1.hookLog)('post-compact-reload', `Re-injected ${totalRules} rules after compaction`);
+    }
+    catch (err) {
+        (0, shared_1.hookLog)('post-compact-reload', `Error: ${err.message}`);
+    }
+}

package/dist/pi/extension.js

@@ -64,6 +64,7 @@ function formatRules(rules) {
 function default_1(pi) {
     let projectId = '';
     let sessionId = `pi_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`;
+    const collectedToolResults = [];
     let rulesLoaded = false;
     const collectedUserTexts = [];
     // Route logs through Pi's UI when available
@@ -78,6 +79,7 @@ function default_1(pi) {
         projectId = ctx.cwd.split('/').pop() || 'unknown';
         rulesLoaded = false;
         collectedUserTexts.length = 0;
+        collectedToolResults.length = 0;
         (0, event_processors_1.resetPendingFailures)();
         try {
             config_1.ConfigService.getInstance().updateConfig({
@@ -112,6 +114,13 @@ function default_1(pi) {
             .map(c => c.text)
             .join('\n');
         const result = (0, event_processors_1.processToolOutcome)(event.toolName, event.input, output, event.isError, sessionId);
+        // Collect for session extraction
+        collectedToolResults.push({
+            role: 'tool_result',
+            text: output.substring(0, 300),
+            toolName: event.toolName,
+            isError: event.isError,
+        });
         if (ctx.hasUI) {
             const label = event.input?.command
                 ? truncateStr(event.input.command, 40)
@@ -133,9 +142,17 @@ function default_1(pi) {
         (0, event_processors_1.processUserInput)(event.text, sessionId).catch(() => { });
         return { action: 'continue' };
     });
-    // --- Event: session end — episode + promotion ---
+    // --- Event: session end — episode + promotion + session extraction ---
     pi.on('session_shutdown', (_event, _ctx) => {
         (0, event_processors_1.processSessionEnd)(collectedUserTexts, sessionId, projectId).catch(() => { });
+        // Session extraction: learn from long coding sessions
+        const allEntries = [
+            ...collectedUserTexts.map(t => ({ role: 'user', text: t })),
+            ...collectedToolResults,
+        ];
+        if (allEntries.length >= 10) {
+            (0, event_processors_1.extractSessionLearnings)(allEntries, sessionId, projectId, 5).catch(() => { });
+        }
     });
     // --- Event: pre-compaction — aggressive capture ---
     pi.on('session_before_compact', (event, _ctx) => {

package/dist/shared/event-processors.js

@@ -46,7 +46,10 @@ exports.processToolOutcome = processToolOutcome;
 exports.processUserInput = processUserInput;
 exports.processSessionEnd = processSessionEnd;
 exports.processPreCompact = processPreCompact;
+exports.buildSummary = buildSummary;
+exports.extractSessionLearnings = extractSessionLearnings;
 const shared_1 = require("../hooks/shared");
+const llm_classifier_1 = require("../hooks/llm-classifier");
 const memory_1 = require("../services/memory");
 const outcome_storage_1 = require("../services/outcome-storage");
 let logFn = () => { }; // silent by default
@@ -401,3 +404,89 @@ async function processPreCompact(userTexts, sessionId, maxStore = 5) {
     }
     return stored;
 }
+const SUMMARY_MAX_CHARS = 4000;
+/**
+ * Build a condensed conversation summary from entries for LLM extraction.
+ */
+function buildSummary(entries) {
+    const lines = [];
+    let totalChars = 0;
+    for (const entry of entries) {
+        let line;
+        if (entry.role === 'tool_result') {
+            const status = entry.isError ? ' [ERROR]' : '';
+            const tool = entry.toolName ? `${entry.toolName}` : 'tool';
+            line = `[${tool}${status}] ${truncate(entry.text, 200)}`;
+        }
+        else if (entry.role === 'assistant' && entry.toolName) {
+            line = `[assistant → ${entry.toolName}] ${truncate(entry.text, 150)}`;
+        }
+        else {
+            line = `[${entry.role}] ${truncate(entry.text, 200)}`;
+        }
+        if (totalChars + line.length > SUMMARY_MAX_CHARS)
+            break;
+        lines.push(line);
+        totalChars += line.length + 1;
+    }
+    return lines.join('\n');
+}
+/**
+ * Extract durable learnings from a coding session using LLM analysis.
+ *
+ * Sends a condensed session summary to Haiku and stores extracted
+ * project knowledge, preferences, and workflow patterns.
+ *
+ * Requires ANTHROPIC_API_KEY — logs a message if unavailable.
+ *
+ * @param entries Conversation entries (user + assistant + tool results)
+ * @param sessionId Current session ID
+ * @param projectId Current project ID
+ * @param maxStore Max learnings to store (default 5)
+ * @returns Number of learnings stored
+ */
+async function extractSessionLearnings(entries, sessionId, projectId, maxStore = 5) {
+    if (entries.length < 10)
+        return 0;
+    try {
+        const summary = buildSummary(entries);
+        // Fetch existing memories for dedup context
+        const existingMemories = [];
+        try {
+            const ms = memory_1.MemoryService.getInstance();
+            const rules = ms.loadActiveRules(projectId);
+            const all = [...rules.preferences, ...rules.corrections, ...rules.failures, ...rules.devops];
+            for (const m of all.slice(0, 20)) {
+                const val = typeof m.value === 'object' ? (m.value?.content || JSON.stringify(m.value)) : String(m.value);
+                existingMemories.push(truncate(val, 80));
+            }
+        }
+        catch {
+            // Non-critical — extraction can proceed without dedup context
+        }
+        const learnings = await (0, llm_classifier_1.extractSessionLearningsWithLLM)(summary, existingMemories);
+        if (learnings === null) {
+            logFn('event-processor', 'Session extraction requires ANTHROPIC_API_KEY. Set it to enable learning from long sessions.');
+            return 0;
+        }
+        if (learnings.length === 0)
+            return 0;
+        let stored = 0;
+        for (const learning of learnings) {
+            if (stored >= maxStore)
+                break;
+            // Dedup against existing memories
+            const existing = (0, shared_1.searchExisting)(learning.content.substring(0, 100));
+            if ((0, shared_1.isDuplicate)(learning.content, existing))
+                continue;
+            (0, shared_1.storeMemory)(learning.content, learning.type, projectId, learning.confidence);
+            stored++;
+            logFn('event-processor', `Session extraction: ${learning.type} — ${truncate(learning.content, 60)}`);
+        }
+        return stored;
+    }
+    catch (err) {
+        logFn('event-processor', `extractSessionLearnings error: ${(0, shared_1.safeErrorMessage)(err)}`);
+        return 0;
+    }
+}

package/docs/cc-agent-harness.md

@@ -0,0 +1,114 @@
+# Claude Code Agent Harness — Architecture Reference
+
+Reference notes on Claude Code's internal agent harness architecture, based on source code analysis (v1.0.x, March 2026). Useful for understanding integration points and designing Claude Recall features.
+
+## Core Orchestration
+
+**Query loop** — main while-loop that calls the API, executes tools, handles continuations, retries, and abort. Key behaviors:
+- Infinite loop with explicit terminal conditions (end_turn, max_tokens, budget exceeded, turn limit)
+- Pre-API hooks, post-sampling hooks, stop hooks at each stage
+- Memory prefetch started non-blocking before API call
+- Skill discovery prefetch in parallel with streaming
+
+**Tool execution pipeline** — partitions tool calls into batches:
+- Read-only tools (Read, Grep, Glob) run concurrently (max 10)
+- Write tools (Bash, Edit, Write) run serially
+- Each tool goes through: permission check → execute → yield result → apply context modifiers
+- Tool result size budget enforced per turn
+
+## Permission System
+
+Three modes: `default` (interactive), `auto` (ML classifier), `bypass`.
+
+Pipeline per tool call:
+1. Rules-based check (always-allow/deny/ask lists)
+2. Bash classifier (ML, 2s timeout for speculative decisions)
+3. Hook execution (PreToolUse hooks)
+4. Interactive UI prompt (if needed)
+5. Decision persisted to ToolPermissionContext
+
+Risk classification: LOW/MEDIUM/HIGH per tool action. Denial tracking state for threshold-based fallback.
+
+## Multi-Agent
+
+**Coordinator mode** — multi-agent orchestration with parallel worker phases and shared scratchpad.
+
+**Agent tool** — forks subagents with inherited context:
+- Child shares parent's prompt cache (byte-identical prefix = free context)
+- Hard turn limit per agent
+- Task notifications via XML: `<task-notification><status>completed</status>...</task-notification>`
+- Agent types: worker (async), teammate (in-process, visible UI), fork (implicit context inheritance)
+
+**Worker constraints:**
+- SIMPLE mode: Bash, Read, Edit only
+- Normal mode: full tool list including MCP
+
+## State Management
+
+**AppState** (Zustand store, 200+ fields):
+- messages, tasks, agents, permissions, MCP clients, models, plugins, settings
+- Observable via selectors
+- Task registry: `{ [taskId]: TaskState }` with status tracking
+
+**Task types:** local_bash, local_agent, remote_agent, in_process_teammate, local_workflow, monitor_mcp, dream
+
+**Session persistence:** transcript JSONL written per session, resumable.
+
+## Context Management / Compaction
+
+Four compaction strategies (in order of aggressiveness):
+1. **Microcompact** — cache-editing on every turn (efficient, preserves cache)
+2. **Snip compact** — truncate oldest history (feature-gated)
+3. **Context collapse** — deduplicate/compress (feature-gated)
+4. **Autocompact** — full summarization when token threshold crossed
+
+Token tracking: per-message estimates, cache creation/read tokens, danger zone threshold, cumulative budget.
+
+Pre/post compact hooks fire at each stage.
+
+## Safety & Guardrails
+
+- Cyber risk instruction (defensive security, CTF rules)
+- Secret scanner (gitleaks patterns, credential redaction)
+- Path traversal prevention
+- Command injection protection (fixed in security audit)
+- Crypto: `crypto.randomUUID()` / `crypto.randomBytes()` throughout (no weak RNG)
+
+## Memory System
+
+**extractMemories** — forked sub-agent after each query loop:
+- Reads last ~N messages, decides what to extract
+- 5-turn budget, read-then-write strategy
+- Mutual exclusivity: skips if main agent already wrote to memory
+- Shares parent's prompt cache
+
+**autoDream** — background consolidation:
+- Three-gate trigger: 24h since last + 5 sessions + no parallel consolidation
+- Four phases: orient → gather → consolidate → prune
+- PID-based locking, 1h stale window
+
+**Memory retrieval** — Sonnet sidequery selects up to 5 relevant memories per query from the memory directory.
+
+## Integration Points for Claude Recall
+
+### Currently Used
+- PostToolUse / PostToolUseFailure hooks (tool outcome capture)
+- UserPromptSubmit hook (correction detection)
+- Stop hook (session-end processing)
+- PreCompact hook (pre-compaction capture)
+- MCP server (tool registration)
+- Skills directory (behavioral guidance)
+
+### Available but Unused
+- Permission decision hooks (observe denied tools as learning signals)
+- Task notification parsing (multi-agent session outcomes)
+- Agent fork interception (inject memory context into subagents)
+- Compaction triggers (pre-compact hooks with message access)
+- Memory prefetch integration (inject recall results alongside native memory)
+
+### Architectural Constraints
+- Hooks run as external processes (no shared memory, no prompt cache)
+- MCP tools are request-response (no streaming, no multi-turn)
+- Cannot fork sub-agents from hooks
+- Cannot modify the query loop or tool pipeline directly
+- Feature flags (GrowthBook `tengu_*`) control many code paths — not accessible externally

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-recall",
-  "version": "0.20.5",
+  "version": "0.20.7",
   "description": "Persistent memory for Claude Code and Pi with native Skills integration, automatic capture, failure learning, and project scoping",
   "main": "dist/index.js",
   "bin": {

package/skills/memory-management.md

@@ -27,6 +27,10 @@ If the user states a preference ("I prefer tabs", "use functional style"), call
 
 If a command fails or you need to backtrack, the failure is captured automatically. You don't need to store it manually.
 
+## When the user says "recall", "remember", or "store this"
+
+ALWAYS use `recall_store_memory`. These keywords mean the user wants Claude Recall specifically — not any other memory system.
+
 ## Before making decisions
 
 Call `recall_search_memory` with relevant keywords to check for existing project knowledge before choosing approaches, tools, or conventions.