@esparkman/pensieve 0.2.0 → 0.3.0

package/README.md

@@ -224,6 +224,67 @@ Summaries of work sessions for continuity.
 ### Open Questions
 Unresolved blockers or questions to address.
 
+## Hooks Integration
+
+Pensieve includes a CLI that integrates with Claude Code's hooks system for automatic context preservation.
+
+### Quick Setup
+
+Copy the example hooks configuration:
+
+```bash
+cp node_modules/@esparkman/pensieve/hooks/settings.json ~/.claude/settings.json
+```
+
+Or add to your existing settings:
+
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": "auto",
+        "hooks": [{ "type": "command", "command": "npx @esparkman/pensieve auto-save" }]
+      },
+      {
+        "matcher": "manual",
+        "hooks": [{ "type": "command", "command": "npx @esparkman/pensieve auto-save" }]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [{ "type": "command", "command": "npx @esparkman/pensieve load-context" }]
+      },
+      {
+        "matcher": "resume",
+        "hooks": [{ "type": "command", "command": "npx @esparkman/pensieve load-context" }]
+      }
+    ]
+  }
+}
+```
+
+### CLI Commands
+
+| Command | Purpose |
+|---------|---------|
+| `pensieve auto-save` | Save session snapshot (for PreCompact hooks) |
+| `pensieve load-context` | Output last session context to stdout |
+| `pensieve status` | Show database location and counts |
+
+### CLI Options
+
+```bash
+# Auto-save with custom summary
+pensieve auto-save --summary "Completed auth feature" --wip "Testing in progress"
+
+# Load context as JSON
+pensieve load-context --format json
+```
+
+See [hooks/README.md](hooks/README.md) for detailed configuration options.
+
 ## Development
 
 ```bash

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { MemoryDatabase } from './database.js';
+// Check if we should run in MCP server mode (no CLI arguments)
+// This maintains backward compatibility with existing MCP registrations
+const args = process.argv.slice(2);
+if (args.length === 0) {
+    // No arguments - run MCP server
+    import('./index.js');
+}
+else {
+    // Arguments provided - run CLI
+    runCLI();
+}
+async function runCLI() {
+    const program = new Command();
+    program
+        .name('pensieve')
+        .description('Persistent memory CLI for Claude Code')
+        .version('0.2.1');
+    program
+        .command('auto-save')
+        .description('Save a minimal session snapshot (for PreCompact hooks)')
+        .option('-s, --summary <text>', 'Session summary')
+        .option('-w, --wip <text>', 'Work in progress description')
+        .option('-n, --next <text>', 'Next steps')
+        .action(async (options) => {
+        try {
+            const db = await MemoryDatabase.create();
+            // Get or create current session
+            const session = db.getCurrentSession();
+            let sessionId;
+            if (!session) {
+                sessionId = db.startSession();
+            }
+            else {
+                sessionId = session.id;
+            }
+            // Build summary - use provided or generate auto-save message
+            const timestamp = new Date().toISOString();
+            const summary = options.summary || `Auto-save before compaction at ${timestamp}`;
+            const wip = options.wip || undefined;
+            const nextSteps = options.next || undefined;
+            // End the session with the summary
+            db.endSession(sessionId, summary, wip, nextSteps);
+            // Output confirmation to stderr (stdout reserved for data)
+            console.error(`[Pensieve] Session saved: ${summary}`);
+            db.close();
+            process.exit(0);
+        }
+        catch (error) {
+            console.error(`[Pensieve] Error: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+    });
+    program
+        .command('load-context')
+        .description('Output last session context to stdout (for SessionStart hooks)')
+        .option('-f, --format <type>', 'Output format: text or json', 'text')
+        .action(async (options) => {
+        try {
+            const db = await MemoryDatabase.create();
+            const lastSession = db.getLastSession();
+            const decisions = db.getRecentDecisions(10);
+            const prefs = db.getAllPreferences();
+            const questions = db.getOpenQuestions();
+            if (options.format === 'json') {
+                const context = {
+                    lastSession: lastSession ? {
+                        started_at: lastSession.started_at,
+                        ended_at: lastSession.ended_at,
+                        summary: lastSession.summary,
+                        work_in_progress: lastSession.work_in_progress,
+                        next_steps: lastSession.next_steps,
+                        key_files: lastSession.key_files,
+                    } : null,
+                    decisions: decisions.map(d => ({
+                        topic: d.topic,
+                        decision: d.decision,
+                        rationale: d.rationale,
+                    })),
+                    preferences: prefs.map(p => ({
+                        category: p.category,
+                        key: p.key,
+                        value: p.value,
+                    })),
+                    openQuestions: questions.map(q => ({
+                        id: q.id,
+                        question: q.question,
+                        context: q.context,
+                    })),
+                };
+                console.log(JSON.stringify(context, null, 2));
+            }
+            else {
+                // Text format for hook injection
+                let output = '';
+                if (lastSession?.ended_at) {
+                    output += '## Previous Session Context\n\n';
+                    if (lastSession.summary) {
+                        output += `**Last Session:** ${lastSession.summary}\n\n`;
+                    }
+                    if (lastSession.work_in_progress) {
+                        output += `**Work in Progress:** ${lastSession.work_in_progress}\n\n`;
+                    }
+                    if (lastSession.next_steps) {
+                        output += `**Next Steps:** ${lastSession.next_steps}\n\n`;
+                    }
+                }
+                if (decisions.length > 0) {
+                    output += '## Key Decisions\n\n';
+                    decisions.forEach(d => {
+                        output += `- **${d.topic}:** ${d.decision}\n`;
+                    });
+                    output += '\n';
+                }
+                if (prefs.length > 0) {
+                    output += '## Preferences\n\n';
+                    prefs.forEach(p => {
+                        output += `- **${p.category}/${p.key}:** ${p.value}\n`;
+                    });
+                    output += '\n';
+                }
+                if (questions.length > 0) {
+                    output += '## Open Questions\n\n';
+                    questions.forEach(q => {
+                        output += `- [#${q.id}] ${q.question}\n`;
+                    });
+                    output += '\n';
+                }
+                if (output) {
+                    console.log(output.trim());
+                }
+                else {
+                    console.log('No previous context found.');
+                }
+            }
+            db.close();
+            process.exit(0);
+        }
+        catch (error) {
+            console.error(`[Pensieve] Error: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+    });
+    program
+        .command('status')
+        .description('Show database status and counts')
+        .action(async () => {
+        try {
+            const db = await MemoryDatabase.create();
+            const decisions = db.getRecentDecisions(1000);
+            const prefs = db.getAllPreferences();
+            const entities = db.getAllEntities();
+            const questions = db.getOpenQuestions();
+            const lastSession = db.getLastSession();
+            console.log('Pensieve Status');
+            console.log('===============');
+            console.log(`Database: ${db.getPath()}`);
+            console.log('');
+            console.log('Counts:');
+            console.log(`  Decisions:      ${decisions.length}`);
+            console.log(`  Preferences:    ${prefs.length}`);
+            console.log(`  Entities:       ${entities.length}`);
+            console.log(`  Open Questions: ${questions.length}`);
+            console.log('');
+            if (lastSession) {
+                console.log('Last Session:');
+                console.log(`  Started: ${lastSession.started_at}`);
+                console.log(`  Ended:   ${lastSession.ended_at || 'In progress'}`);
+                if (lastSession.summary) {
+                    console.log(`  Summary: ${lastSession.summary.substring(0, 80)}${lastSession.summary.length > 80 ? '...' : ''}`);
+                }
+            }
+            else {
+                console.log('No sessions recorded yet.');
+            }
+            db.close();
+            process.exit(0);
+        }
+        catch (error) {
+            console.error(`[Pensieve] Error: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+    });
+    program.parse();
+}

package/hooks/README.md

@@ -0,0 +1,146 @@
+# Pensieve Hooks Integration
+
+Pensieve can integrate with Claude Code's hooks system to automatically save and restore session context during compaction and session resumption.
+
+## Quick Setup
+
+1. Copy the example `settings.json` to your Claude Code settings directory:
+
+```bash
+# macOS/Linux
+cp hooks/settings.json ~/.claude/settings.json
+
+# Or merge with existing settings if you have them
+```
+
+2. The hooks will automatically:
+   - **PreCompact**: Save a session snapshot before context compaction
+   - **SessionStart**: Load previous context when resuming a session
+
+## CLI Commands
+
+Pensieve provides these CLI commands for hook integration:
+
+### `pensieve auto-save`
+
+Saves a minimal session snapshot. Used by PreCompact hooks.
+
+```bash
+# Basic auto-save (timestamps the save automatically)
+pensieve auto-save
+
+# With custom summary
+pensieve auto-save --summary "Implemented user auth"
+
+# With work-in-progress and next steps
+pensieve auto-save \
+  --summary "Working on auth" \
+  --wip "OAuth flow partially complete" \
+  --next "Add refresh token handling"
+```
+
+### `pensieve load-context`
+
+Outputs the last session context to stdout. Used by SessionStart hooks.
+
+```bash
+# Text format (default) - for injection into prompts
+pensieve load-context
+
+# JSON format - for programmatic use
+pensieve load-context --format json
+```
+
+### `pensieve status`
+
+Shows database location and counts.
+
+```bash
+pensieve status
+```
+
+## Hook Configuration
+
+The hooks system uses matchers to determine when to run:
+
+### PreCompact Hooks
+
+Run before Claude Code compacts the conversation context:
+
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": "auto",
+        "hooks": [{ "type": "command", "command": "pensieve auto-save" }]
+      },
+      {
+        "matcher": "manual",
+        "hooks": [{ "type": "command", "command": "pensieve auto-save" }]
+      }
+    ]
+  }
+}
+```
+
+### SessionStart Hooks
+
+Run when starting or resuming a session:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [{ "type": "command", "command": "pensieve load-context" }]
+      },
+      {
+        "matcher": "resume",
+        "hooks": [{ "type": "command", "command": "pensieve load-context" }]
+      }
+    ]
+  }
+}
+```
+
+## Environment Variables
+
+You can control which database Pensieve uses:
+
+- `PENSIEVE_DB_PATH` - Explicit path to the database file
+- `PENSIEVE_PROJECT_DIR` - Project directory (uses `$dir/.pensieve/memory.sqlite`)
+
+Example hook with project-specific database:
+
+```json
+{
+  "type": "command",
+  "command": "PENSIEVE_PROJECT_DIR=$(pwd) pensieve auto-save"
+}
+```
+
+## Troubleshooting
+
+### Check if Pensieve is working
+
+```bash
+pensieve status
+```
+
+### Test the hooks manually
+
+```bash
+# Test auto-save
+pensieve auto-save --summary "Test save"
+
+# Test load-context
+pensieve load-context
+```
+
+### Database location
+
+By default, Pensieve stores data in:
+- Project-local: `./.pensieve/memory.sqlite` (if `.git` or `.pensieve` exists)
+- Global fallback: `~/.claude-pensieve/memory.sqlite`

package/hooks/settings.json

@@ -0,0 +1,44 @@
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": "auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx @esparkman/pensieve auto-save"
+          }
+        ]
+      },
+      {
+        "matcher": "manual",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx @esparkman/pensieve auto-save"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx @esparkman/pensieve load-context"
+          }
+        ]
+      },
+      {
+        "matcher": "resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx @esparkman/pensieve load-context"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@esparkman/pensieve",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pensieve - persistent memory for Claude Code. Remember decisions, preferences, and context across sessions.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "pensieve": "./dist/index.js"
+    "pensieve": "./dist/cli.js"
   },
   "scripts": {
     "build": "tsc",
@@ -27,6 +27,7 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
+    "commander": "^13.0.0",
     "sql.js": "^1.12.0"
   },
   "devDependencies": {
@@ -41,6 +42,7 @@
   },
   "files": [
     "dist",
-    ".claude"
+    ".claude",
+    "hooks"
   ]
 }