claude-recall 0.20.16 → 0.21.0

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

@@ -12,10 +12,10 @@ Auto-generated from 5 memories. Last updated: 2026-04-10.
 
 ## Rules
 
-- Session test preference 1775841028541
-- Test preference 1775841028479-2
-- Test preference 1775841028479-1
-- Test preference 1775841028479-0
+- Session test preference 1775856590823
+- Test preference 1775856590766-2
+- Test preference 1775856590766-1
+- Test preference 1775856590766-0
 - Test memory content
 
 ---

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

@@ -1,13 +1,13 @@
 {
   "topicId": "preferences",
-  "sourceHash": "ffe036415b05cb18e9c3e65a38a2e7dedbf02dfd5463c14a03184a9c93c75799",
+  "sourceHash": "bc008faff7f86df3f887d5949481aad102da2261a2872bb1b030bc4279eee9fd",
   "memoryCount": 5,
-  "generatedAt": "2026-04-10T17:10:28.567Z",
+  "generatedAt": "2026-04-10T21:29:50.846Z",
   "memoryKeys": [
-    "memory_1775841028543_yc9163qfd",
-    "memory_1775841028515_8bjn9exsc",
-    "memory_1775841028500_gch5kvqxl",
-    "memory_1775841028480_n2evtiegj",
-    "memory_1775841028436_w06waet05"
+    "memory_1775856590824_6gpdsqsh0",
+    "memory_1775856590800_fv6xg43wx",
+    "memory_1775856590782_kwl352n83",
+    "memory_1775856590768_crx4xtq3i",
+    "memory_1775856590726_t9ap1te0i"
   ]
 }

package/README.md

@@ -180,6 +180,24 @@ claude-recall import backup.json             # Import memories from JSON
 claude-recall clear --force                  # Delete all memories (irreversible)
 ```
 
+### Task Checkpoints
+
+Persistent "where I left off" snapshots — one per project, replaces previous on save. Not loaded as a rule; `load_rules` only hints that one exists.
+
+```bash
+claude-recall checkpoint save \
+  --completed "inference layer, domain layer" \
+  --remaining "wire server.js, strip 3GPP URNs" \
+  --blockers "none" \
+  --notes "see inference/README.md"
+
+claude-recall checkpoint load              # Show the latest checkpoint
+claude-recall checkpoint load --json       # Machine-readable
+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`).
+
 ### Troubleshooting
 
 ```bash
@@ -246,6 +264,11 @@ claude-recall outcomes --section stats   # Retrieval/helpfulness stats
 claude-recall outcomes --limit 20        # More items per section
 claude-recall monitor                    # Memory search monitoring stats
 
+# ── Task Checkpoints ────────────────────────────────────────────────
+claude-recall checkpoint save --completed <text> --remaining <text> [--blockers <text>] [--notes <text>] [--project <id>]
+claude-recall checkpoint load [--project <id>] [--json]
+claude-recall checkpoint clear [--project <id>]
+
 # ── Skills ───────────────────────────────────────────────────────────
 claude-recall skills generate            # Generate skills from memories
 claude-recall skills generate --dry-run  # Preview without writing

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

@@ -500,6 +500,80 @@ class ClaudeRecallCLI {
             process.exit(1);
         }
     }
+    /**
+     * Save a task checkpoint for the current (or specified) project.
+     */
+    checkpointSave(opts) {
+        try {
+            const projectId = opts.project || config_1.ConfigService.getInstance().getProjectId();
+            this.memoryService.saveCheckpoint(projectId, {
+                completed: opts.completed,
+                remaining: opts.remaining,
+                blockers: opts.blockers || 'none',
+                notes: opts.notes,
+            });
+            console.log(`\n✅ Checkpoint saved for project: ${projectId}\n`);
+            console.log(`  Completed: ${opts.completed}`);
+            console.log(`  Remaining: ${opts.remaining}`);
+            console.log(`  Blockers:  ${opts.blockers || 'none'}`);
+            if (opts.notes)
+                console.log(`  Notes:     ${opts.notes}`);
+            console.log('');
+        }
+        catch (error) {
+            console.error('❌ Checkpoint save failed:', error);
+            process.exit(1);
+        }
+    }
+    /**
+     * Load the latest task checkpoint for the current (or specified) project.
+     */
+    checkpointLoad(opts) {
+        try {
+            const projectId = opts.project || config_1.ConfigService.getInstance().getProjectId();
+            const checkpoint = this.memoryService.loadCheckpoint(projectId);
+            if (!checkpoint) {
+                console.log(`\nNo checkpoint found for project: ${projectId}\n`);
+                return;
+            }
+            if (opts.json) {
+                console.log(JSON.stringify({ projectId, ...checkpoint }, null, 2));
+                return;
+            }
+            const updatedDate = new Date(checkpoint.updated_at).toLocaleString();
+            console.log(`\n📌 Checkpoint for project: ${projectId}`);
+            console.log(`   Updated: ${updatedDate}\n`);
+            console.log(`  Completed: ${checkpoint.completed}`);
+            console.log(`  Remaining: ${checkpoint.remaining}`);
+            console.log(`  Blockers:  ${checkpoint.blockers}`);
+            if (checkpoint.notes)
+                console.log(`  Notes:     ${checkpoint.notes}`);
+            console.log('');
+        }
+        catch (error) {
+            console.error('❌ Checkpoint load failed:', error);
+            process.exit(1);
+        }
+    }
+    /**
+     * Delete the task checkpoint for the current (or specified) project.
+     */
+    checkpointClear(opts) {
+        try {
+            const projectId = opts.project || config_1.ConfigService.getInstance().getProjectId();
+            const deleted = this.memoryService.deleteCheckpoint(projectId);
+            if (deleted) {
+                console.log(`\n✅ Checkpoint cleared for project: ${projectId}\n`);
+            }
+            else {
+                console.log(`\nNo checkpoint to clear for project: ${projectId}\n`);
+            }
+        }
+        catch (error) {
+            console.error('❌ Checkpoint clear failed:', error);
+            process.exit(1);
+        }
+    }
     /**
      * Show system status
      */
@@ -1394,6 +1468,48 @@ async function main() {
         await cli.clear(options);
         process.exit(0);
     });
+    // Checkpoint command group
+    const checkpoint = program
+        .command('checkpoint')
+        .description('Save and load task checkpoints (work-in-progress snapshots)');
+    checkpoint
+        .command('save')
+        .description('Save a task checkpoint for the current project (replaces previous)')
+        .requiredOption('--completed <text>', 'What is done')
+        .requiredOption('--remaining <text>', 'What is left to do')
+        .option('--blockers <text>', 'Current blockers (default: "none")')
+        .option('--notes <text>', 'Free-form notes, file refs, etc.')
+        .option('--project <id>', 'Project ID (default: current)')
+        .action((options) => {
+        const cli = new ClaudeRecallCLI(program.opts());
+        cli.checkpointSave({
+            project: options.project,
+            completed: options.completed,
+            remaining: options.remaining,
+            blockers: options.blockers,
+            notes: options.notes,
+        });
+        process.exit(0);
+    });
+    checkpoint
+        .command('load')
+        .description('Load the latest task checkpoint for the current project')
+        .option('--project <id>', 'Project ID (default: current)')
+        .option('--json', 'Output as JSON')
+        .action((options) => {
+        const cli = new ClaudeRecallCLI(program.opts());
+        cli.checkpointLoad({ project: options.project, json: options.json });
+        process.exit(0);
+    });
+    checkpoint
+        .command('clear')
+        .description('Delete the task checkpoint for the current project')
+        .option('--project <id>', 'Project ID (default: current)')
+        .action((options) => {
+        const cli = new ClaudeRecallCLI(program.opts());
+        cli.checkpointClear({ project: options.project });
+        process.exit(0);
+    });
     // Status command
     program
         .command('status')

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

@@ -162,7 +162,34 @@ class MemoryTools {
                     required: ['id']
                 },
                 handler: this.handleDeleteMemory.bind(this)
-            }
+            },
+            {
+                name: 'mcp__claude-recall__save_checkpoint',
+                description: 'Save a task checkpoint — a structured snapshot of work in progress (completed/remaining/blockers/notes). Replaces any previous checkpoint for this project. Call when ending a work session or pausing on a task.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        completed: { type: 'string', description: 'What has been finished in this work stream' },
+                        remaining: { type: 'string', description: 'What is left to do' },
+                        blockers: { type: 'string', description: 'Current blockers (use "none" if none)' },
+                        notes: { type: 'string', description: 'Optional free-form notes, file references, etc.' },
+                        projectId: { type: 'string', description: 'Optional project ID override. Defaults to current project.' },
+                    },
+                    required: ['completed', 'remaining', 'blockers'],
+                },
+                handler: this.handleSaveCheckpoint.bind(this),
+            },
+            {
+                name: 'mcp__claude-recall__load_checkpoint',
+                description: 'Load the latest task checkpoint for the current project. Returns null if none exists. Call at the start of a session to recall where you left off — load_rules will hint when one exists.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        projectId: { type: 'string', description: 'Optional project ID override. Defaults to current project.' },
+                    },
+                },
+                handler: this.handleLoadCheckpoint.bind(this),
+            },
         ];
     }
     /**
@@ -349,15 +376,30 @@ class MemoryTools {
             catch {
                 // Non-critical
             }
+            // Checkpoint hint — surface existence without dumping content
+            let checkpointHint = '';
+            try {
+                const project = projectId || context.projectId || config_1.ConfigService.getInstance().getProjectId();
+                if (this.memoryService.hasCheckpoint(project)) {
+                    const cp = this.memoryService.loadCheckpoint(project);
+                    if (cp) {
+                        const updatedDate = new Date(cp.updated_at).toLocaleString();
+                        checkpointHint = `📌 You have an unfinished task checkpoint from ${updatedDate} — call \`load_checkpoint\` to see completed/remaining/blockers before starting work.\n\n`;
+                    }
+                }
+            }
+            catch {
+                // Non-critical
+            }
             let rulesText;
             if (sections.length > 0) {
                 const body = sections.join('\n\n');
                 rulesText = directive
-                    ? `${directive}\n\n---\n\n${body}`
-                    : body;
+                    ? `${directive}\n\n${checkpointHint}---\n\n${body}`
+                    : `${checkpointHint}${body}`;
             }
             else {
-                rulesText = 'No active rules found. This may be a new project.';
+                rulesText = checkpointHint || 'No active rules found. This may be a new project.';
             }
             return {
                 rules: rulesText,
@@ -462,6 +504,45 @@ class MemoryTools {
             throw error;
         }
     }
+    async handleSaveCheckpoint(input, context) {
+        try {
+            const { completed, remaining, blockers, notes, projectId } = input;
+            if (typeof completed !== 'string' || typeof remaining !== 'string' || typeof blockers !== 'string') {
+                throw new Error('completed, remaining, and blockers are required string fields');
+            }
+            const project = projectId || config_1.ConfigService.getInstance().getProjectId();
+            this.memoryService.saveCheckpoint(project, { completed, remaining, blockers, notes });
+            return {
+                success: true,
+                projectId: project,
+                message: `Checkpoint saved for project: ${project}`,
+            };
+        }
+        catch (error) {
+            this.logger.error('MemoryTools', 'Failed to save checkpoint', error);
+            throw error;
+        }
+    }
+    async handleLoadCheckpoint(input, context) {
+        try {
+            const { projectId } = input || {};
+            const project = projectId || config_1.ConfigService.getInstance().getProjectId();
+            const checkpoint = this.memoryService.loadCheckpoint(project);
+            if (!checkpoint) {
+                return { found: false, projectId: project };
+            }
+            return {
+                found: true,
+                projectId: project,
+                ...checkpoint,
+                updated_at_iso: new Date(checkpoint.updated_at).toISOString(),
+            };
+        }
+        catch (error) {
+            this.logger.error('MemoryTools', 'Failed to load checkpoint', error);
+            throw error;
+        }
+    }
     getTools() {
         return this.tools;
     }

package/dist/memory/storage.js

@@ -329,6 +329,51 @@ class MemoryStorage {
         // This ensures that other processes (like CLI) can see the changes immediately
         this.db.pragma('wal_checkpoint(TRUNCATE)');
     }
+    // --- Task checkpoint methods ---
+    checkpointKey(projectId) {
+        return `task-checkpoint:${projectId}`;
+    }
+    saveCheckpoint(projectId, input) {
+        const checkpoint = {
+            completed: input.completed,
+            remaining: input.remaining,
+            blockers: input.blockers,
+            notes: input.notes,
+            updated_at: Date.now(),
+        };
+        // Use a deterministic key per project so INSERT OR REPLACE replaces the previous one.
+        // Direct INSERT OR REPLACE bypasses fuzzy/hash dedup since they check `key != ?`.
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO memories
+      (key, value, type, project_id, file_path, timestamp, relevance_score, access_count,
+       preference_key, is_active, superseded_by, superseded_at, confidence_score, sophistication_level, scope, content_hash)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const value = JSON.stringify(checkpoint);
+        const contentHash = this.computeContentHash(checkpoint, 'task-checkpoint');
+        stmt.run(this.checkpointKey(projectId), value, 'task-checkpoint', projectId, null, checkpoint.updated_at, 1.0, 0, null, 1, null, null, null, 1, null, contentHash);
+        this.db.pragma('wal_checkpoint(TRUNCATE)');
+    }
+    loadCheckpoint(projectId) {
+        const row = this.db.prepare('SELECT value FROM memories WHERE key = ? AND type = ?').get(this.checkpointKey(projectId), 'task-checkpoint');
+        if (!row)
+            return null;
+        try {
+            return JSON.parse(row.value);
+        }
+        catch {
+            return null;
+        }
+    }
+    hasCheckpoint(projectId) {
+        const row = this.db.prepare('SELECT 1 FROM memories WHERE key = ? AND type = ?').get(this.checkpointKey(projectId), 'task-checkpoint');
+        return !!row;
+    }
+    deleteCheckpoint(projectId) {
+        const result = this.db.prepare('DELETE FROM memories WHERE key = ? AND type = ?').run(this.checkpointKey(projectId), 'task-checkpoint');
+        this.db.pragma('wal_checkpoint(TRUNCATE)');
+        return result.changes > 0;
+    }
     retrieve(key) {
         const stmt = this.db.prepare('SELECT * FROM memories WHERE key = ?');
         const row = stmt.get(key);

package/dist/pi/extension.js

@@ -217,9 +217,21 @@ function default_1(pi) {
                         os.recordRetrieval(m.key);
                 }
                 catch { /* non-critical */ }
+                // Checkpoint hint — surface existence without dumping content
+                let checkpointHint = '';
+                try {
+                    if (ms.hasCheckpoint(projectId)) {
+                        const cp = ms.loadCheckpoint(projectId);
+                        if (cp) {
+                            const updatedDate = new Date(cp.updated_at).toLocaleString();
+                            checkpointHint = `📌 You have an unfinished task checkpoint from ${updatedDate} — call \`recall_load_checkpoint\` to see completed/remaining/blockers before starting work.\n\n`;
+                        }
+                    }
+                }
+                catch { /* non-critical */ }
                 const text = body
-                    ? `${LOAD_RULES_DIRECTIVE}\n\n---\n\n${body}`
-                    : 'No active rules found. This may be a new project.';
+                    ? `${LOAD_RULES_DIRECTIVE}\n\n${checkpointHint}---\n\n${body}`
+                    : (checkpointHint || 'No active rules found. This may be a new project.');
                 return {
                     content: [{ type: 'text', text }],
                 };
@@ -333,6 +345,73 @@ function default_1(pi) {
             }
         },
     });
+    // --- Tool: recall_save_checkpoint ---
+    pi.registerTool({
+        name: 'recall_save_checkpoint',
+        label: 'Save Task Checkpoint',
+        description: 'Save a structured snapshot of work in progress (completed/remaining/blockers/notes). Replaces any previous checkpoint for this project. Call when ending a session or pausing on a task.',
+        promptSnippet: 'Save a task checkpoint with what is done, what remains, and any blockers',
+        parameters: {},
+        async execute(_id, params, _signal, _onUpdate, _ctx) {
+            try {
+                const { completed, remaining, blockers, notes } = params || {};
+                if (typeof completed !== 'string' || typeof remaining !== 'string' || typeof blockers !== 'string') {
+                    return {
+                        content: [{ type: 'text', text: 'Error: completed, remaining, and blockers are required string fields' }],
+                        isError: true,
+                    };
+                }
+                const ms = memory_1.MemoryService.getInstance();
+                ms.saveCheckpoint(projectId, { completed, remaining, blockers, notes });
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({
+                                success: true,
+                                projectId,
+                                message: `Checkpoint saved for project: ${projectId}`,
+                            }) }],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: 'text', text: `Failed to save checkpoint: ${err.message}` }],
+                    isError: true,
+                };
+            }
+        },
+    });
+    // --- Tool: recall_load_checkpoint ---
+    pi.registerTool({
+        name: 'recall_load_checkpoint',
+        label: 'Load Task Checkpoint',
+        description: 'Load the latest task checkpoint for the current project. Returns null if none exists. Call at session start to recall where you left off.',
+        promptSnippet: 'Load the saved task checkpoint to see what was in progress',
+        parameters: {},
+        async execute(_id, _params, _signal, _onUpdate, _ctx) {
+            try {
+                const ms = memory_1.MemoryService.getInstance();
+                const checkpoint = ms.loadCheckpoint(projectId);
+                if (!checkpoint) {
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({ found: false, projectId }) }],
+                    };
+                }
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({
+                                found: true,
+                                projectId,
+                                ...checkpoint,
+                                updated_at_iso: new Date(checkpoint.updated_at).toISOString(),
+                            }) }],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: 'text', text: `Failed to load checkpoint: ${err.message}` }],
+                    isError: true,
+                };
+            }
+        },
+    });
     // --- Tool: recall_delete_memory ---
     pi.registerTool({
         name: 'recall_delete_memory',

package/dist/services/memory.js

@@ -527,6 +527,24 @@ class MemoryService {
     getDatabase() {
         return this.storage.getDatabase();
     }
+    // --- Task checkpoint methods ---
+    saveCheckpoint(projectId, input) {
+        this.storage.saveCheckpoint(projectId, input);
+        this.logger.info('MemoryService', `Checkpoint saved for project: ${projectId}`);
+    }
+    loadCheckpoint(projectId) {
+        return this.storage.loadCheckpoint(projectId);
+    }
+    hasCheckpoint(projectId) {
+        return this.storage.hasCheckpoint(projectId);
+    }
+    deleteCheckpoint(projectId) {
+        const deleted = this.storage.deleteCheckpoint(projectId);
+        if (deleted) {
+            this.logger.info('MemoryService', `Checkpoint deleted for project: ${projectId}`);
+        }
+        return deleted;
+    }
     /**
      * Check if database is connected
      */

package/package.json

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