claude-baton 2.1.5 → 2.2.0

package/commands/memo-checkpoint.md

@@ -21,6 +21,11 @@ Save session state before context loss.
    - **decisions**: key choices made and WHY
    - **blockers**: anything blocking progress
    - **plan_reference**: file path and section of the active plan document (e.g. "docs/v2-plan.md Phase 2 Step 3"), or omit if no plan is active
+   - **learnings**: review the conversation for corrections, failures, and wrong assumptions. For each, write a short actionable statement. Examples:
+     - "User corrected: always run tests before committing"
+     - "Assumed API returns array but it returns object"
+     - "Build failed because forgot to update imports after rename"
+     If nothing went wrong this session, use an empty array.
 
 5. Call the `save_checkpoint` MCP tool with all fields:
    - what_was_built
@@ -32,6 +37,7 @@ Save session state before context loss.
    - branch (from step 2)
    - uncommitted_files (array of lines from git status --short)
    - git_snapshot (from git log --oneline -10)
+   - learnings (array of strings from step 4)
 
 6. Print structured confirmation:
 

package/commands/memo-retro.md

@@ -0,0 +1,84 @@
+Analyze recent checkpoints to surface learnings and suggest memory updates.
+
+Run periodically (weekly or after major milestones) to close the learning loop.
+
+## Steps
+
+1. Detect the project from the current working directory. Construct the project slug by replacing all `/` with `-` in the full path.
+
+2. Call the `list_checkpoints` MCP tool with `limit: 10` (no date) to fetch the 10 most recent checkpoints.
+
+3. Load current memory state:
+   - Read all files in `~/.claude/projects/[PROJECT_SLUG]/memory/`
+   - Read `MEMORY.md` in the memory directory
+   - Read the project's `CLAUDE.md` (in the working directory root)
+
+4. Check git history for correction patterns:
+   ```bash
+   git log --oneline -30
+   ```
+   Look for reverts, quick-follow fix commits (e.g., "fix: ..." immediately after a feature commit), and patterns indicating repeated mistakes.
+
+5. Analyze the checkpoint data:
+
+   **Extract learnings:**
+   - Pull the `learnings` array from each checkpoint (may be empty or absent on older checkpoints)
+   - Also extract signals from `decisions_made`, `blockers`, and `what_was_built`
+
+   **Frequency analysis:**
+   - Count how many times each learning (or semantically similar learning) appears
+   - Single occurrence = note only
+   - 2+ occurrences = high confidence, propose as rule
+
+   **Cross-reference:**
+   - Is this learning already captured in a memory file? → skip
+   - Is this learning already a CLAUDE.md rule? → skip
+   - Is this a correction/preference? → propose as feedback memory
+   - Is this about the project? → propose as project memory
+
+6. Present the report:
+
+```
+## 🔄 Retro — [PROJECT_NAME] — [DATE]
+
+### 🧠 Memory Health
+
+- 📁 Total memories: [count of files in memory dir]
+- 📏 MEMORY.md line count: [N]/200 (⚠️ warn if >150)
+- 🪦 Stale memories: [any referencing completed/outdated work]
+- 🔀 Duplicate/overlapping memories: [any found]
+
+### 📚 Learnings Summary
+
+**🔁 Recurring (2+ times) — propose as rules:**
+
+- [learning] — appeared in [N] checkpoints
+- ...
+
+**📌 Single occurrence — note only:**
+
+- [learning]
+- ...
+
+### 🔍 Git Correction Patterns
+
+[Reverts, quick-follow fixes that indicate recurring mistakes, or "✅ None detected"]
+
+### 🛠️ Proposed Changes
+
+**📝 Memory file actions:**
+
+- ➕ **Create:** [new memory file if a pattern warrants it, with suggested filename and content]
+- ✏️ **Update:** [existing memory with outdated info]
+- 🔗 **Merge:** [overlapping memories to consolidate]
+- 🗑️ **Prune:** [stale memories to delete]
+
+**📐 CLAUDE.md rules** (only for recurring learnings not already captured):
+
+1. Add to section [X]: "[exact rule wording]"
+   _Reason: appeared in [N] checkpoints, e.g., [quote from learning]_
+```
+
+7. Ask: **"Which changes should I apply? (all / list numbers / none)"**
+
+   Do NOT modify CLAUDE.md, memory files, or any project files without explicit approval.

package/dist/index.js

@@ -1,7 +1,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { initDatabase, getDefaultDbPath, insertCheckpoint, getLatestCheckpoint, getCheckpoint, getCheckpointsByDate, insertDailySummary, countAll, } from "./store.js";
+import { initDatabase, getDefaultDbPath, insertCheckpoint, getLatestCheckpoint, getCheckpoint, getCheckpointsByDate, getRecentCheckpoints, insertDailySummary, countAll, } from "./store.js";
 import { callClaudeJson } from "./llm.js";
 import { formatSize, normalizeProjectPath } from "./utils.js";
 import { readFileSync, statSync } from "fs";
@@ -76,6 +76,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                         type: "string",
                         description: "Reference to active plan document and section, e.g. 'docs/plan.md Phase 2 Step 3'",
                     },
+                    learnings: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Actionable learnings from the session — corrections, wrong assumptions, failed approaches",
+                    },
                     source: {
                         type: "string",
                         enum: ["manual", "auto"],
@@ -108,13 +113,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "list_checkpoints",
-            description: "List all checkpoints for a date",
+            description: "List checkpoints by date or most recent",
             inputSchema: {
                 type: "object",
                 properties: {
                     date: {
                         type: "string",
-                        description: "YYYY-MM-DD (defaults to today)",
+                        description: "YYYY-MM-DD — returns checkpoints for this date. If omitted, returns most recent across all dates.",
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Max checkpoints to return (default 10). Used when date is omitted.",
                     },
                     project: {
                         type: "string",
@@ -161,6 +170,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     uncommittedFiles: a?.uncommitted_files,
                     gitSnapshot: a?.git_snapshot,
                     planReference: a?.plan_reference,
+                    learnings: a?.learnings,
                     source: a?.source ?? "manual",
                 }, dbPath);
                 return { content: [{ type: "text", text: `Checkpoint saved: ${id}` }] };
@@ -177,14 +187,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case "list_checkpoints": {
-                const cpDate = args?.date ?? new Date().toISOString().slice(0, 10);
-                const cps = getCheckpointsByDate(db, projectPath, cpDate);
+                const cpDate = args?.date;
+                const limit = args?.limit ?? 10;
+                const cps = cpDate
+                    ? getCheckpointsByDate(db, projectPath, cpDate)
+                    : getRecentCheckpoints(db, projectPath, limit);
                 const summary = cps.map((cp) => ({
                     id: cp.id,
                     created_at: cp.created_at,
                     what_was_built: cp.what_was_built,
                     branch: cp.branch,
                     current_state: cp.current_state,
+                    decisions_made: cp.decisions_made,
+                    learnings: cp.learnings,
                 }));
                 return {
                     content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],

package/dist/store.d.ts

@@ -12,10 +12,12 @@ export declare function insertCheckpoint(db: Database, projectPath: string, sess
     gitSnapshot?: string;
     planReference?: string;
     source?: "manual" | "auto";
+    learnings?: string[];
 }, dbPath?: string): string;
 export declare function getCheckpoint(db: Database, id: string): Checkpoint | null;
 export declare function getLatestCheckpoint(db: Database, projectPath: string): Checkpoint | null;
 export declare function getCheckpointsByDate(db: Database, projectPath: string, date: string): Checkpoint[];
+export declare function getRecentCheckpoints(db: Database, projectPath: string, limit?: number): Checkpoint[];
 export declare function getAllCheckpoints(db: Database, projectPath?: string): Checkpoint[];
 export declare function insertDailySummary(db: Database, projectPath: string, date: string, summary: Record<string, unknown>, dbPath?: string): string;
 export declare function getDailySummary(db: Database, projectPath: string, date: string): DailySummary | null;

package/dist/store.js

@@ -88,12 +88,21 @@ export function initSchema(db) {
         if (!msg.includes("duplicate column"))
             throw e;
     }
+    // Migration: add learnings column for existing databases
+    try {
+        db.exec("ALTER TABLE checkpoints ADD COLUMN learnings TEXT DEFAULT '[]'");
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : "";
+        if (!msg.includes("duplicate column"))
+            throw e;
+    }
 }
 // --- Checkpoints CRUD ---
 export function insertCheckpoint(db, projectPath, sessionId, currentState, whatWasBuilt, nextSteps, opts, dbPath) {
     const id = crypto.randomUUID();
-    db.run(`INSERT INTO checkpoints (id, project_path, session_id, branch, current_state, what_was_built, next_steps, decisions_made, blockers, uncommitted_files, git_snapshot, plan_reference, source, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+    db.run(`INSERT INTO checkpoints (id, project_path, session_id, branch, current_state, what_was_built, next_steps, decisions_made, blockers, uncommitted_files, git_snapshot, plan_reference, source, learnings, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
         id,
         projectPath,
         sessionId,
@@ -107,6 +116,7 @@ export function insertCheckpoint(db, projectPath, sessionId, currentState, whatW
         opts?.gitSnapshot ?? null,
         opts?.planReference ?? null,
         opts?.source ?? "manual",
+        JSON.stringify(opts?.learnings ?? []),
         new Date().toISOString(),
     ]);
     if (dbPath)
@@ -137,6 +147,7 @@ function parseCheckpointRow(row) {
         uncommitted_files: JSON.parse(row.uncommitted_files),
         git_snapshot: row.git_snapshot ?? null,
         plan_reference: row.plan_reference ?? null,
+        learnings: JSON.parse(row.learnings ?? "[]"),
         source: row.source ?? "manual",
     };
 }
@@ -154,6 +165,16 @@ export function getCheckpointsByDate(db, projectPath, date) {
     stmt.free();
     return results;
 }
+export function getRecentCheckpoints(db, projectPath, limit = 10) {
+    const stmt = db.prepare("SELECT * FROM checkpoints WHERE project_path = ? ORDER BY created_at DESC, rowid DESC LIMIT ?");
+    stmt.bind([projectPath, limit]);
+    const results = [];
+    while (stmt.step()) {
+        results.push(parseCheckpointRow(stmt.getAsObject()));
+    }
+    stmt.free();
+    return results;
+}
 export function getAllCheckpoints(db, projectPath) {
     let sql = "SELECT * FROM checkpoints";
     const params = [];

package/dist/types.d.ts

@@ -12,6 +12,7 @@ export interface Checkpoint {
     uncommitted_files: string[];
     git_snapshot: string | null;
     plan_reference: string | null;
+    learnings: string[];
     source: "manual" | "auto";
     created_at: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-baton",
-  "version": "2.1.5",
+  "version": "2.2.0",
   "description": "Session lifecycle management for Claude Code",
   "type": "module",
   "main": "dist/index.js",

package/prompts/auto_checkpoint.txt

@@ -19,6 +19,7 @@ Analyze these inputs and produce a JSON object with these fields:
 - decisions_made: Key decisions made since the previous checkpoint, if any (1-2 sentences, or "None")
 - blockers: Anything blocking progress, if any (1 sentence, or "None")
 - plan_reference: If the session references an active plan document (e.g. PLAN.md, docs/plan.md, a spec file), include the file path and the specific section being worked on (e.g. "docs/v2-plan.md Phase 2 Step 3"). Null if no plan document is referenced.
+- learnings: Review the transcript for corrections made by the user, failed approaches, wrong assumptions, or mistakes by Claude. For each, write a short actionable learning statement. Examples: "User corrected: always run tests before committing", "Assumed API returns array but it returns object", "Build failed because forgot to update imports after rename". If nothing went wrong, output an empty array.
 
 Rules:
 - Be concise — each field should be 1-3 sentences max
@@ -40,5 +41,6 @@ Example output:
   "next_steps": "Wire up login form to POST /auth/login endpoint. Add token refresh middleware.",
   "decisions_made": "Using bcrypt over argon2 for password hashing due to simpler deployment. Storing refresh tokens in httpOnly cookies.",
   "blockers": "None",
-  "plan_reference": "docs/auth-plan.md Phase 2 Step 1"
+  "plan_reference": "docs/auth-plan.md Phase 2 Step 1",
+  "learnings": ["Assumed bcrypt was already installed but had to add it to dependencies"]
 }