claude-recall 0.21.0 → 0.21.2

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

@@ -8,14 +8,14 @@ source: claude-recall
 
 # Preferences
 
-Auto-generated from 5 memories. Last updated: 2026-04-10.
+Auto-generated from 5 memories. Last updated: 2026-04-11.
 
 ## Rules
 
-- Session test preference 1775856590823
-- Test preference 1775856590766-2
-- Test preference 1775856590766-1
-- Test preference 1775856590766-0
+- Session test preference 1775900146096
+- Test preference 1775900146036-2
+- Test preference 1775900146036-1
+- Test preference 1775900146036-0
 - Test memory content
 
 ---

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

@@ -1,13 +1,13 @@
 {
   "topicId": "preferences",
-  "sourceHash": "bc008faff7f86df3f887d5949481aad102da2261a2872bb1b030bc4279eee9fd",
+  "sourceHash": "32712ec321c1c8e831bfb1d227b5682434e69ab3a0934115453c984b36866477",
   "memoryCount": 5,
-  "generatedAt": "2026-04-10T21:29:50.846Z",
+  "generatedAt": "2026-04-11T09:35:46.110Z",
   "memoryKeys": [
-    "memory_1775856590824_6gpdsqsh0",
-    "memory_1775856590800_fv6xg43wx",
-    "memory_1775856590782_kwl352n83",
-    "memory_1775856590768_crx4xtq3i",
-    "memory_1775856590726_t9ap1te0i"
+    "memory_1775900146097_ap6ffit4i",
+    "memory_1775900146071_8y0wnmbu6",
+    "memory_1775900146056_0tbld53h7",
+    "memory_1775900146038_czc25c8ra",
+    "memory_1775900145994_1cvxoyda8"
   ]
 }

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

@@ -137,13 +137,14 @@ a SKILL.md file that Claude Code loads automatically.
 
 ## Automatic Capture Hooks
 
-Claude Recall registers hooks on three Claude Code events to capture memories automatically — no MCP tool call needed:
+Claude Recall registers hooks on four Claude Code events to capture memories automatically — no MCP tool call needed:
 
 | Hook | Event | What it captures |
 |------|-------|-----------------|
 | `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 |
 | `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. |
 
 **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
@@ -152,9 +153,10 @@ Claude Recall registers hooks on three Claude Code events to capture memories au
 - Batch classification: Stop and PreCompact hooks send all texts in a single API call
 - Near-duplicate detection via Jaccard similarity (55% threshold) prevents redundant storage
 - Per-event limits: 3 (Stop), 5 (PreCompact) to prevent DB flooding
+- 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`.
+**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).
 
 ## Example Workflows
 

package/README.md

@@ -90,6 +90,7 @@ Once installed, Claude Recall works automatically in the background:
 7. **After context compression** (Claude Code only) — rules are automatically re-injected into context so they're not lost when the window shrinks
 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
 
 Classification uses Claude Haiku (via `ANTHROPIC_API_KEY`) with silent regex fallback. No configuration needed.
 
@@ -198,6 +199,22 @@ claude-recall checkpoint clear             # Delete the checkpoint
 
 Agents can also save/load checkpoints via MCP tools (`mcp__claude-recall__save_checkpoint` / `mcp__claude-recall__load_checkpoint`) or Pi tools (`recall_save_checkpoint` / `recall_load_checkpoint`).
 
+#### Auto-checkpoint on session exit (v0.21.2+)
+
+Manual `checkpoint save` is the explicit path. **Auto-checkpoint** is the safety net: when a session ends, the most recent task is extracted into a checkpoint automatically so the next session can resume.
+
+- **Pi** — fires from the `session_shutdown` event handler. In-process synchronous call, runs as part of the existing session-end pipeline. **Critical for Pi: there is no `pi --resume` equivalent, so without this, restarting Pi loses all session context.**
+- **Claude Code** — fires from the `SessionEnd` hook for voluntary exit reasons (`clear`, `prompt_input_exit`, `logout`). Spawns a detached background worker (fork+unref) so it stays well within Claude Code's tight 1.5s `SessionEnd` timeout. Skips `bypass_permissions_disabled` and `other` reasons (those are system-driven, not user intent). Useful for users who exit and start fresh instead of using `claude --resume`.
+
+Both runtimes share the same Haiku-backed extraction (`extractCheckpointWithLLM`) and the same quality gate:
+
+- **Quality gate**: refuses to save if the LLM returns an empty or trivially-short `remaining` field. The model is prompted to detect completion signals (assistant said "Done.", user said "thanks", no follow-up question) and return empty `remaining` when the task is finished. **An empty checkpoint is far better than a fabricated one** — manual checkpoints are never overwritten with garbage.
+- **Notes tag**: auto-saved checkpoints include `[auto-saved on <pi|cc> session exit at <iso-timestamp>]` in the notes field, so you can tell auto from manual via `checkpoint load`.
+- **Requires `ANTHROPIC_API_KEY`**. Without it, `extractCheckpointWithLLM` returns `null` (graceful fallback) and no auto-checkpoint is saved. Manual `checkpoint save` still works.
+- **Disable**: remove the `SessionEnd` block from `.claude/settings.json` (Claude Code) or, for Pi, no per-project disable flag exists yet — open an issue if you need one.
+
+The auto-checkpoint never clobbers a useful manual checkpoint because of the quality gate. If the LLM doesn't see clear unfinished work, it returns empty and the gate refuses the save. Manual checkpoints stay sticky until you explicitly save over them.
+
 ### Troubleshooting
 
 ```bash

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 = '12.0.0'; // v12 = add SubagentStart/Stop for sub-agent recall integration
+        settings.hooksVersion = '13.0.0'; // v13 = add SessionEnd for auto-checkpoint on session exit
         settings.hooks = {
             SubagentStart: [
                 {
@@ -919,6 +919,20 @@ async function main() {
                         }
                     ]
                 }
+            ],
+            // Auto-checkpoint on voluntary session exits. Worker is fire-and-forget,
+            // so the synchronous handler returns instantly (well within CC's tight
+            // 1.5s SessionEnd timeout). Symmetric with Pi's session_shutdown handler.
+            SessionEnd: [
+                {
+                    hooks: [
+                        {
+                            type: "command",
+                            command: `${hookCmd} session-end-checkpoint`,
+                            timeout: 5
+                        }
+                    ]
+                }
             ]
         };
         if (!fs.existsSync(claudeDir)) {

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

@@ -106,9 +106,19 @@ class HookCommands {
                         await handleBashFailureWatcher(input);
                         break;
                     }
+                    case 'session-end-checkpoint': {
+                        const { handleSessionEndCheckpoint } = await Promise.resolve().then(() => __importStar(require('../../hooks/session-end-checkpoint')));
+                        await handleSessionEndCheckpoint(input);
+                        break;
+                    }
+                    case 'session-end-checkpoint-worker': {
+                        const { handleSessionEndCheckpointWorker } = await Promise.resolve().then(() => __importStar(require('../../hooks/session-end-checkpoint-worker')));
+                        await handleSessionEndCheckpointWorker(input);
+                        break;
+                    }
                     default:
                         console.error(`Unknown hook: ${name}`);
-                        console.error('Available: correction-detector, memory-stop, precompact-preserve, memory-sync, tool-outcome-watcher');
+                        console.error('Available: correction-detector, memory-stop, precompact-preserve, memory-sync, tool-outcome-watcher, session-end-checkpoint');
                 }
             }
             catch {

package/dist/hooks/llm-classifier.js

@@ -9,6 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.classifyWithLLM = classifyWithLLM;
 exports.extractHindsightHint = extractHindsightHint;
 exports.extractSessionLearningsWithLLM = extractSessionLearningsWithLLM;
+exports.extractCheckpointWithLLM = extractCheckpointWithLLM;
 exports.classifyBatchWithLLM = classifyBatchWithLLM;
 // Lazy singleton — avoid import cost when API key is absent
 let clientInstance; // undefined = not yet checked
@@ -217,6 +218,86 @@ async function extractSessionLearningsWithLLM(summary, existingMemories) {
         return null;
     }
 }
+const CHECKPOINT_EXTRACTION_PROMPT = `You are extracting a "where I left off" checkpoint from a coding session that just ended. The next session — possibly minutes from now, possibly days later — needs a brief, accurate hint to resume from. Your output will overwrite any existing checkpoint, so it MUST be either accurate or empty. NEVER fabricate.
+
+You will see the FINAL portion of a session transcript. Your job is to extract THREE fields:
+
+- completed: what the user/agent finished in THIS recent task (concrete, brief, max 200 chars). Empty string if nothing was clearly completed.
+- remaining: what was still in flight when the session ended — the actual hand-off (concrete, brief, max 300 chars). MUST be non-empty if there is real unfinished work. EMPTY STRING if the task is done.
+- blockers: anything that was blocking progress (tools failing, decisions pending, dependencies). "none" if no blockers.
+
+THE MOST IMPORTANT RULE — completion detection:
+If the transcript ends with ANY signal that the task is finished, return remaining="". Completion signals include:
+- assistant says "Done.", "All set.", "All done.", "Finished.", "That's it.", "Complete.", or similar terminal acknowledgement
+- last user message is thanks/acknowledgement ("thanks", "perfect", "great") with no follow-up question
+- tool calls succeeded and there is no explicit next step in the user's most recent prompt
+- the conversation has reached a natural stopping point
+
+When in doubt, prefer remaining="". An empty checkpoint is far better than a fabricated one.
+
+THE SECOND MOST IMPORTANT RULE — no fabrication:
+- ONLY use information present in the transcript. Do NOT extrapolate, do NOT invent follow-up work.
+- If the most recent task is clearly complete, do NOT manufacture next steps from your imagination.
+- If you cannot determine what was happening with high confidence, return all-empty: {"completed":"","remaining":"","blockers":""}
+- "remaining" must be a SPECIFIC unfinished item visible in the transcript. Never generic ("continue work", "more testing", "documentation").
+
+Other rules:
+- Focus ONLY on the most recent coherent task. Ignore earlier work in the session.
+- Return JSON: {"completed":"...","remaining":"...","blockers":"..."}
+- Be terse and specific. Each field should help the future session pick up the thread.
+- Do NOT include markdown fences. Respond with raw JSON only.
+
+Examples of GOOD output:
+
+Scenario A — task finished, agent said "Done.":
+{"completed":"Copied cc-source-code into a dedicated dir under claude-recall/cc-source-code/","remaining":"","blockers":"none"}
+
+Scenario B — task in progress, midway through implementation:
+{"completed":"Added saveCheckpoint() to storage and MemoryService","remaining":"Wire CLI checkpoint command and add MCP/Pi tool wrappers","blockers":"none"}
+
+Scenario C — task in progress, blocked on something:
+{"completed":"Diagnosed [object Object] rendering bug in handleLoadRules","remaining":"Write failing test, extract formatRuleValue helper, replace 5 call sites","blockers":"none"}
+
+Scenario D — uncertain, sparse context, can't tell what's happening:
+{"completed":"","remaining":"","blockers":""}
+
+Scenario E — just a question, no work done:
+{"completed":"","remaining":"","blockers":""}
+
+Examples of BAD output (DO NOT DO THIS):
+{"completed":"various changes","remaining":"more work","blockers":"none"}              # too vague
+{"completed":"explored architecture","remaining":"document findings","blockers":"none"} # FABRICATED — there was no documentation task
+{"completed":"finished everything","remaining":"finish everything","blockers":"none"}   # nonsense filler`;
+async function extractCheckpointWithLLM(conversationSummary) {
+    const client = getClient();
+    if (!client)
+        return null;
+    if (!conversationSummary || conversationSummary.trim().length < 30) {
+        return null;
+    }
+    try {
+        const response = await client.messages.create({
+            model: MODEL,
+            max_tokens: 600,
+            system: CHECKPOINT_EXTRACTION_PROMPT,
+            messages: [{ role: 'user', content: conversationSummary }],
+        });
+        const content = response.content?.[0];
+        if (content?.type !== 'text')
+            return null;
+        const result = parseJSON(content.text);
+        if (typeof result !== 'object' || result === null)
+            return null;
+        return {
+            completed: typeof result.completed === 'string' ? result.completed : '',
+            remaining: typeof result.remaining === 'string' ? result.remaining : '',
+            blockers: typeof result.blockers === 'string' ? result.blockers : '',
+        };
+    }
+    catch {
+        return null;
+    }
+}
 async function classifyBatchWithLLM(texts) {
     if (texts.length === 0)
         return [];

package/dist/hooks/session-end-checkpoint-worker.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * session-end-checkpoint-worker — detached background worker spawned by the
+ * session-end-checkpoint hook handler.
+ *
+ * Runs OUTSIDE Claude Code's 1.5s SessionEnd hook timeout. Reads the transcript,
+ * extracts a most-recent-task checkpoint via Haiku, and saves it via
+ * MemoryService.saveCheckpoint(). The next CC session that calls load_rules
+ * will see the checkpoint hint.
+ *
+ * This worker is the symmetric counterpart to Pi's in-process auto-checkpoint
+ * (src/pi/extension.ts session_shutdown handler). Both call the same shared
+ * extractCheckpoint() function from event-processors.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleSessionEndCheckpointWorker = handleSessionEndCheckpointWorker;
+const shared_1 = require("./shared");
+const event_processors_1 = require("../shared/event-processors");
+const config_1 = require("../services/config");
+const TRANSCRIPT_TAIL_SIZE = 30;
+async function handleSessionEndCheckpointWorker(input) {
+    // Wire event-processor logs through hookLog so extractCheckpoint diagnostics
+    // (LLM null, quality gate filter, save failure) end up in
+    // ~/.claude-recall/hook-logs/session-end-checkpoint-worker.log instead of
+    // being silently dropped by the default no-op logFn.
+    (0, event_processors_1.setLogFunction)((source, msg) => (0, shared_1.hookLog)('session-end-checkpoint-worker', `[${source}] ${msg}`));
+    const transcriptPath = input?.transcript_path ?? '';
+    if (!transcriptPath) {
+        (0, shared_1.hookLog)('session-end-checkpoint-worker', 'No transcript_path provided');
+        return;
+    }
+    const cwd = input?.cwd;
+    if (cwd) {
+        try {
+            config_1.ConfigService.getInstance().updateConfig({ project: { rootDir: cwd } });
+        }
+        catch {
+            // Non-critical — getProjectId will fall back to process.cwd() basename
+        }
+    }
+    const projectId = config_1.ConfigService.getInstance().getProjectId();
+    if (!projectId) {
+        (0, shared_1.hookLog)('session-end-checkpoint-worker', 'No project_id resolved — aborting');
+        return;
+    }
+    const entries = (0, shared_1.readTranscriptTail)(transcriptPath, TRANSCRIPT_TAIL_SIZE);
+    if (entries.length === 0) {
+        (0, shared_1.hookLog)('session-end-checkpoint-worker', 'No transcript entries found');
+        return;
+    }
+    // Convert raw transcript JSONL entries to the ConversationEntry shape that
+    // extractCheckpoint expects. We include user prompts, assistant text blocks,
+    // AND tool interactions — Haiku needs the assistant's reasoning (especially
+    // completion signals like "Done.") to know whether the most recent task is
+    // finished or still in flight. Without assistant text the model hallucinates
+    // follow-up work from sparse tool-call context.
+    const converted = [];
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const role = entry?.message?.role ?? entry?.role;
+        if (role === 'user') {
+            // Skip user entries that are pure tool_result wrappers — those will be
+            // captured via extractToolInteractions below
+            const content = entry?.message?.content ?? entry?.content;
+            const isPureToolResult = Array.isArray(content) && content.every((b) => b?.type === 'tool_result');
+            if (isPureToolResult)
+                continue;
+            const text = (0, shared_1.extractTextFromEntry)(entry);
+            if (text && text.trim().length > 0) {
+                converted.push({
+                    entry: { role: 'user', text: text.trim() },
+                    index: i,
+                });
+            }
+        }
+    }
+    // Add assistant text blocks with their original index — these include
+    // completion signals ("Done.", "All set", etc.) that help Haiku judge
+    // whether the most recent task is actually finished.
+    const assistantTexts = (0, shared_1.extractAssistantTexts)(entries);
+    for (const at of assistantTexts) {
+        if (!at.text || !at.text.trim())
+            continue;
+        converted.push({
+            entry: { role: 'assistant', text: at.text.trim().substring(0, 400) },
+            index: at.entryIndex,
+        });
+    }
+    // Add tool interactions as tool_result entries with their original index
+    const interactions = (0, shared_1.extractToolInteractions)(entries);
+    for (const interaction of interactions) {
+        if (!interaction.result)
+            continue;
+        const text = interaction.result.content.substring(0, 300);
+        if (!text)
+            continue;
+        converted.push({
+            entry: {
+                role: 'tool_result',
+                text,
+                toolName: interaction.call.name,
+                isError: interaction.result.isError,
+            },
+            index: interaction.result.entryIndex,
+        });
+    }
+    // Sort by original transcript index to preserve chronological order
+    converted.sort((a, b) => a.index - b.index);
+    const conversationEntries = converted.map(c => c.entry);
+    if (conversationEntries.length < 3) {
+        (0, shared_1.hookLog)('session-end-checkpoint-worker', `Too few entries (${conversationEntries.length}) — skipping`);
+        return;
+    }
+    (0, shared_1.hookLog)('session-end-checkpoint-worker', `Extracting checkpoint from ${conversationEntries.length} entries (project=${projectId})`);
+    const saved = await (0, event_processors_1.extractCheckpoint)(conversationEntries, projectId, 'cc');
+    if (saved) {
+        (0, shared_1.hookLog)('session-end-checkpoint-worker', `Auto-checkpoint saved for ${projectId}`);
+    }
+    else {
+        (0, shared_1.hookLog)('session-end-checkpoint-worker', `No checkpoint saved (LLM null, quality gate, or save failure)`);
+    }
+}

package/dist/hooks/session-end-checkpoint.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * session-end-checkpoint hook — fires on Claude Code SessionEnd event.
+ *
+ * Goal: auto-save a "where I left off" checkpoint when the session ends, so
+ * the next session can pick up from the most recent task. Less critical for
+ * Claude Code (which has `claude --resume`) than for Pi, but still useful
+ * for users who exit and start fresh instead of resuming.
+ *
+ * Architecture: this handler is the SYNCHRONOUS gate that Claude Code's hook
+ * runner waits on. SessionEnd hooks have a tight default timeout (1.5s — see
+ * cc-source-code/utils/hooks.ts:175 SESSION_END_HOOK_TIMEOUT_MS_DEFAULT) which
+ * is too short for transcript-read + Haiku call + DB write.
+ *
+ * Solution: this handler spawns a DETACHED worker process that does the real
+ * work in the background, then returns instantly. The worker survives the
+ * parent's exit and writes the checkpoint asynchronously. Worst case race:
+ * if the user starts a new session before the worker finishes, the new
+ * session sees no checkpoint — graceful degradation, not data loss.
+ *
+ * Reason filter: only fires for voluntary user exits (clear, prompt_input_exit,
+ * logout, resume). Skips system-driven exits (bypass_permissions_disabled, other)
+ * because those don't represent user intent to pause.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleSessionEndCheckpoint = handleSessionEndCheckpoint;
+const child_process_1 = require("child_process");
+const shared_1 = require("./shared");
+const SKIP_REASONS = new Set(['bypass_permissions_disabled', 'other']);
+async function handleSessionEndCheckpoint(input) {
+    const reason = input?.reason ?? 'unknown';
+    if (SKIP_REASONS.has(reason)) {
+        (0, shared_1.hookLog)('session-end-checkpoint', `Skipping (reason=${reason})`);
+        return;
+    }
+    if (!input?.transcript_path) {
+        (0, shared_1.hookLog)('session-end-checkpoint', 'No transcript_path in input — nothing to extract');
+        return;
+    }
+    try {
+        // process.argv[1] is the absolute path to claude-recall-cli.js (whichever
+        // entry the parent hook ran from). Reuse the same binary so the worker
+        // picks up the same dist version, MemoryService singleton path, env, etc.
+        const cliPath = process.argv[1];
+        const child = (0, child_process_1.spawn)(process.execPath, // node binary path
+        [cliPath, 'hook', 'run', 'session-end-checkpoint-worker'], {
+            detached: true,
+            stdio: ['pipe', 'ignore', 'ignore'],
+            // Inherit cwd so getProjectId() resolves correctly in the worker
+        });
+        if (child.stdin) {
+            child.stdin.write(JSON.stringify(input));
+            child.stdin.end();
+        }
+        // Detach so the worker outlives the parent. The hook handler returns
+        // immediately, well within Claude Code's 1.5s SessionEnd timeout.
+        child.unref();
+        (0, shared_1.hookLog)('session-end-checkpoint', `Spawned detached worker (pid=${child.pid}, reason=${reason})`);
+    }
+    catch (err) {
+        (0, shared_1.hookLog)('session-end-checkpoint', `Failed to spawn worker: ${err?.message ?? err}`);
+        // Best-effort — never block the hook
+    }
+}

package/dist/mcp/tools/memory-tools.js

@@ -1,10 +1,67 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemoryTools = void 0;
+exports.formatRuleValue = formatRuleValue;
 const config_1 = require("../../services/config");
 const search_monitor_1 = require("../../services/search-monitor");
 const skill_generator_1 = require("../../services/skill-generator");
 const outcome_storage_1 = require("../../services/outcome-storage");
+/**
+ * Render any memory.value shape as a readable string for load_rules output.
+ *
+ * Memory values land in the DB in several historical shapes. The previous
+ * rendering used `m.value.content || m.value.value || JSON.stringify(m.value)`
+ * which short-circuited on truthy non-string objects, producing "[object Object]"
+ * when string interpolation eventually called toString() on the returned object.
+ *
+ * Rules:
+ *   1. strings/numbers pass through (or coerce)
+ *   2. null/undefined → empty string
+ *   3. objects: prefer the first STRING field in order: content, value, title, description
+ *      (only string — non-string `content` falls through to title)
+ *   4. nested failure shapes: extract `what_failed` (top-level or under `content`)
+ *   5. last resort: truncated JSON.stringify (never raw object)
+ *
+ * Exported for direct unit testing in tests/unit/format-rule-value.test.ts.
+ */
+function formatRuleValue(value) {
+    if (value == null)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value !== 'object')
+        return String(value);
+    const v = value;
+    // Prefer the first non-empty string field. Order matters:
+    // - `content` covers legacy hook failures and promoted lessons (lesson text)
+    // - `value` covers preference shape
+    // - `title` covers tool-outcome-watcher failures whose `content` is a nested object
+    // - `description` is a last-ditch human label
+    for (const field of ['content', 'value', 'title', 'description']) {
+        const candidate = v[field];
+        if (typeof candidate === 'string' && candidate.trim()) {
+            return candidate;
+        }
+    }
+    // Nested failure object — extract what_failed if present
+    if (typeof v.what_failed === 'string' && v.what_failed.trim()) {
+        return v.what_failed;
+    }
+    if (v.content && typeof v.content === 'object') {
+        const inner = v.content;
+        if (typeof inner.what_failed === 'string' && inner.what_failed.trim()) {
+            return inner.what_failed;
+        }
+    }
+    // Last resort: truncated JSON. Never return a raw object.
+    try {
+        const json = JSON.stringify(value);
+        return json.length > 200 ? json.substring(0, 200) + '…' : json;
+    }
+    catch {
+        return String(value);
+    }
+}
 class MemoryTools {
     constructor(memoryService, logger, onMemoryChanged) {
         this.memoryService = memoryService;
@@ -287,7 +344,7 @@ class MemoryTools {
             const sections = [];
             if (rules.preferences.length > 0) {
                 sections.push('## Preferences\n' + rules.preferences.map(m => {
-                    const val = typeof m.value === 'object' ? (m.value.content || m.value.value || JSON.stringify(m.value)) : m.value;
+                    const val = formatRuleValue(m.value);
                     // Only show key prefix if it's a meaningful name (not auto-generated)
                     const key = m.preference_key || m.key || '';
                     const isAutoKey = key.startsWith('memory_') || key.startsWith('auto_') || key.startsWith('pref_');
@@ -296,7 +353,7 @@ class MemoryTools {
             }
             if (rules.corrections.length > 0) {
                 sections.push('## Corrections\n' + rules.corrections.map(m => {
-                    const val = typeof m.value === 'object' ? (m.value.content || m.value.value || JSON.stringify(m.value)) : m.value;
+                    const val = formatRuleValue(m.value);
                     const isPromoted = m.key.startsWith('promoted_') || m.value?.source === 'promotion-engine';
                     const evidence = isPromoted && m.value?.evidence_count ? ` (learned from ${m.value.evidence_count} observations)` : '';
                     return isPromoted ? `- [promoted lesson] ${val}${evidence}` : `- ${val}`;
@@ -308,21 +365,21 @@ class MemoryTools {
                 const regularFailures = rules.failures.filter(m => !m.key.startsWith('promoted_') && m.value?.source !== 'promotion-engine');
                 if (promotedLessons.length > 0) {
                     sections.push('## Promoted Lessons (learned from repeated outcomes)\n' + promotedLessons.map(m => {
-                        const val = typeof m.value === 'object' ? (m.value.content || m.value.value || JSON.stringify(m.value)) : m.value;
+                        const val = formatRuleValue(m.value);
                         const evidence = m.value?.evidence_count ? ` (seen ${m.value.evidence_count}x)` : '';
                         return `- ${val}${evidence}`;
                     }).join('\n'));
                 }
                 if (regularFailures.length > 0) {
                     sections.push('## Failures\n' + regularFailures.map(m => {
-                        const val = typeof m.value === 'object' ? (m.value.content || m.value.value || JSON.stringify(m.value)) : m.value;
+                        const val = formatRuleValue(m.value);
                         return `- ${val}`;
                     }).join('\n'));
                 }
             }
             if (rules.devops.length > 0) {
                 sections.push('## DevOps Rules\n' + rules.devops.map(m => {
-                    const val = typeof m.value === 'object' ? (m.value.content || m.value.value || JSON.stringify(m.value)) : m.value;
+                    const val = formatRuleValue(m.value);
                     return `- ${val}`;
                 }).join('\n'));
             }

package/dist/pi/extension.js

@@ -67,6 +67,12 @@ function default_1(pi) {
     const collectedToolResults = [];
     let rulesLoaded = false;
     const collectedUserTexts = [];
+    // Chronologically interleaved entries (user input + tool results in order)
+    // for auto-checkpoint extraction at session end. Distinct from the two
+    // arrays above which are kept for backward compat with processSessionEnd
+    // and extractSessionLearnings.
+    const collectedEntries = [];
+    const MAX_COLLECTED_ENTRIES = 100;
     // Route logs through Pi's UI when available
     (0, event_processors_1.setLogFunction)((source, msg) => {
         try {
@@ -80,6 +86,7 @@ function default_1(pi) {
         rulesLoaded = false;
         collectedUserTexts.length = 0;
         collectedToolResults.length = 0;
+        collectedEntries.length = 0;
         (0, event_processors_1.resetPendingFailures)();
         try {
             config_1.ConfigService.getInstance().updateConfig({
@@ -121,6 +128,16 @@ function default_1(pi) {
             toolName: event.toolName,
             isError: event.isError,
         });
+        // Append to chronologically interleaved log for auto-checkpoint
+        collectedEntries.push({
+            role: 'tool_result',
+            text: output.substring(0, 300),
+            toolName: event.toolName,
+            isError: event.isError,
+        });
+        if (collectedEntries.length > MAX_COLLECTED_ENTRIES) {
+            collectedEntries.splice(0, collectedEntries.length - MAX_COLLECTED_ENTRIES);
+        }
         if (ctx.hasUI) {
             const label = event.input?.command
                 ? truncateStr(event.input.command, 40)
@@ -139,6 +156,10 @@ function default_1(pi) {
     // --- Event: detect corrections from user input ---
     pi.on('input', (event, ctx) => {
         collectedUserTexts.push(event.text);
+        collectedEntries.push({ role: 'user', text: event.text });
+        if (collectedEntries.length > MAX_COLLECTED_ENTRIES) {
+            collectedEntries.splice(0, collectedEntries.length - MAX_COLLECTED_ENTRIES);
+        }
         (0, event_processors_1.processUserInput)(event.text, sessionId).then(msg => {
             if (msg && ctx.hasUI) {
                 try {
@@ -179,6 +200,21 @@ function default_1(pi) {
                 }
             }).catch(() => { });
         }
+        // Auto-checkpoint: extract "where I left off" hint for next Pi session.
+        // Critical for Pi which has no `--resume` flag — without this, the next
+        // Pi session has no memory of what came before. Uses chronologically
+        // interleaved entries (collectedEntries) so the LLM sees the actual
+        // most-recent task, not user texts followed by all tool results.
+        if (collectedEntries.length >= 3 && projectId) {
+            (0, event_processors_1.extractCheckpoint)(collectedEntries, projectId, 'pi').then(saved => {
+                if (saved && ctx.hasUI) {
+                    try {
+                        ctx.ui.notify('📌 Recall: saved task checkpoint for next session', 'info');
+                    }
+                    catch { /* non-critical */ }
+                }
+            }).catch(() => { });
+        }
     });
     // --- Event: pre-compaction — aggressive capture ---
     pi.on('session_before_compact', (event, _ctx) => {

package/dist/shared/event-processors.js

@@ -48,6 +48,8 @@ exports.processSessionEnd = processSessionEnd;
 exports.processPreCompact = processPreCompact;
 exports.buildSummary = buildSummary;
 exports.extractSessionLearnings = extractSessionLearnings;
+exports.buildRecentTaskSummary = buildRecentTaskSummary;
+exports.extractCheckpoint = extractCheckpoint;
 const shared_1 = require("../hooks/shared");
 const llm_classifier_1 = require("../hooks/llm-classifier");
 const memory_1 = require("../services/memory");
@@ -493,3 +495,100 @@ async function extractSessionLearnings(entries, sessionId, projectId, maxStore =
         return 0;
     }
 }
+// --- Auto-Checkpoint Extraction ---
+const CHECKPOINT_SUMMARY_MAX_CHARS = 4000;
+const CHECKPOINT_MIN_ENTRIES = 3;
+const CHECKPOINT_MIN_REMAINING_LEN = 10;
+/**
+ * Build a summary of the MOST RECENT entries (not the start) for checkpoint extraction.
+ * Walks backward from the end, accumulates lines until char budget is exhausted,
+ * then returns them in chronological order.
+ *
+ * Distinct from buildSummary() which prefers the START of the session.
+ */
+function buildRecentTaskSummary(entries) {
+    const lines = [];
+    let totalChars = 0;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        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 > CHECKPOINT_SUMMARY_MAX_CHARS)
+            break;
+        lines.unshift(line);
+        totalChars += line.length + 1;
+    }
+    return lines.join('\n');
+}
+/**
+ * Auto-extract a "where I left off" checkpoint from a session that is ending.
+ *
+ * Built for two callers with different runtime constraints:
+ *   - Pi: in-process synchronous call from session_shutdown handler
+ *   - Claude Code: detached worker process spawned from a SessionEnd hook
+ *
+ * Both runtimes pass the same ConversationEntry[] shape and get the same
+ * quality-gated behavior. Pi is the primary use case because Pi has no
+ * `--resume` equivalent — without this, restarted Pi sessions have no
+ * memory of what came before.
+ *
+ * Quality gate: skips the save if the LLM extraction has an empty/short
+ * `remaining` field. The whole point of a checkpoint is "what to resume
+ * from"; saving empty resumes would clobber any manual checkpoint with
+ * useless garbage.
+ *
+ * @param entries Recent conversation entries (last ~30 from session)
+ * @param projectId Current project ID
+ * @param runtime Tag for the notes field — distinguishes Pi vs CC auto-saves
+ * @returns true if a checkpoint was saved, false otherwise (no API key,
+ *          insufficient entries, empty extraction, save failure)
+ */
+async function extractCheckpoint(entries, projectId, runtime) {
+    if (!entries || entries.length < CHECKPOINT_MIN_ENTRIES) {
+        return false;
+    }
+    try {
+        const summary = buildRecentTaskSummary(entries);
+        if (!summary || summary.trim().length === 0)
+            return false;
+        const extraction = await (0, llm_classifier_1.extractCheckpointWithLLM)(summary);
+        if (extraction === null) {
+            logFn('event-processor', 'extractCheckpoint: LLM returned null (no API key, parse error, or empty extraction)');
+            return false;
+        }
+        // Quality gate: must have meaningful `remaining` content to be worth saving
+        const remaining = (extraction.remaining || '').trim();
+        if (remaining.length < CHECKPOINT_MIN_REMAINING_LEN) {
+            logFn('event-processor', `extractCheckpoint: skipping save — remaining field empty or too short (${remaining.length} chars)`);
+            return false;
+        }
+        const completed = (extraction.completed || '').trim();
+        const blockers = (extraction.blockers || '').trim();
+        const timestamp = new Date().toISOString();
+        const notes = `[auto-saved on ${runtime} session exit at ${timestamp}]`;
+        try {
+            const ms = memory_1.MemoryService.getInstance();
+            ms.saveCheckpoint(projectId, { completed, remaining, blockers, notes });
+            logFn('event-processor', `extractCheckpoint: saved auto-checkpoint for ${projectId} (runtime=${runtime})`);
+            return true;
+        }
+        catch (saveErr) {
+            logFn('event-processor', `extractCheckpoint: saveCheckpoint failed: ${(0, shared_1.safeErrorMessage)(saveErr)}`);
+            return false;
+        }
+    }
+    catch (err) {
+        logFn('event-processor', `extractCheckpoint error: ${(0, shared_1.safeErrorMessage)(err)}`);
+        return false;
+    }
+}

package/package.json

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