@esparkman/pensieve 0.1.2 → 0.1.4

package/.claude/commands/recall.md

@@ -0,0 +1,183 @@
+---
+description: Query the Pensieve knowledge base for stored information. Use to retrieve decisions, preferences, entities, discoveries, or session history.
+---
+
+# /recall
+
+Query the Pensieve knowledge base for specific information.
+
+## Usage
+
+```
+/recall authentication         -> Returns all auth-related memories
+/recall entities               -> Returns domain model understanding
+/recall session:last           -> Returns last session summary
+/recall preferences:testing    -> Returns testing preferences
+/recall discoveries            -> Returns all discoveries
+/recall patterns               -> Returns identified patterns
+/recall questions              -> Returns open questions
+```
+
+## Step 1: Parse Query
+
+Identify what the user wants to recall:
+- Topic keyword -> Search all memories for that topic
+- `entities` -> List all entities
+- `session:last` -> Get last session
+- `preferences:[category]` -> Get preferences in category
+- `discoveries` -> List all discoveries
+- `patterns` -> List identified patterns
+- `questions` -> List open questions
+
+## Step 2: Use Pensieve MCP Tool
+
+Use the `pensieve_recall` MCP tool with the appropriate query.
+
+### Topic Search (Default)
+
+```json
+{
+  "query": "[topic_keyword]"
+}
+```
+
+### Entities
+
+```json
+{
+  "query": "entities"
+}
+```
+
+### Last Session
+
+```json
+{
+  "query": "session:last"
+}
+```
+
+### Preferences by Category
+
+```json
+{
+  "query": "preferences:[category]"
+}
+```
+
+### Discoveries
+
+```json
+{
+  "query": "discoveries"
+}
+```
+
+### Patterns
+
+```json
+{
+  "query": "patterns"
+}
+```
+
+### Open Questions
+
+```json
+{
+  "query": "questions"
+}
+```
+
+## Step 3: Format Results
+
+Present the results to the user in a clear format:
+
+```
+## Recall: [query]
+
+Found [N] results:
+
+### Decisions
+- [Topic]: [Decision] (recorded [date])
+
+### Discoveries
+- [Name]: [Description] at [location]
+
+### Preferences
+- [category]/[key]: [value]
+
+### Entities
+- [Name]: [Description] -> [Relationships]
+```
+
+If no results found:
+"No memories found for '[query]'. Try a different search term or use `/remember` to save new knowledge."
+
+## Examples
+
+**Input:** `/recall authentication`
+
+**Action:** Call `pensieve_recall` with:
+```json
+{
+  "query": "authentication"
+}
+```
+
+**Output:**
+```
+## Recall: authentication
+
+Found 3 results:
+
+### Decisions
+- Authentication: We use Devise with magic links (recorded 2024-01-15)
+- Session Management: Use Redis for session storage (recorded 2024-01-14)
+
+### Discoveries
+- DeviseConfig: Custom Devise configuration at config/initializers/devise.rb
+```
+
+**Input:** `/recall preferences:testing`
+
+**Action:** Call `pensieve_recall` with:
+```json
+{
+  "query": "preferences:testing"
+}
+```
+
+**Output:**
+```
+## Recall: preferences:testing
+
+### Preferences
+- testing/approach: system tests for UI flows
+- testing/coverage: 80% minimum
+- testing/framework: RSpec with Capybara
+```
+
+**Input:** `/recall session:last`
+
+**Action:** Call `pensieve_recall` with:
+```json
+{
+  "query": "session:last"
+}
+```
+
+**Output:**
+```
+## Recall: Last Session
+
+**Date:** 2024-01-15 14:30
+**Summary:** Implemented user authentication with Devise
+
+### Work in Progress
+Email templates (partially styled)
+
+### Next Steps
+1. Complete email templates
+2. Add OAuth providers
+```

package/.claude/commands/remember.md

@@ -0,0 +1,145 @@
+---
+description: Save discoveries, decisions, or preferences to Pensieve memory. Use to persist important learnings like architectural decisions, coding preferences, or discovered patterns.
+---
+
+# /remember
+
+Save discoveries, decisions, or preferences to Pensieve memory.
+
+## Usage
+
+```
+/remember decision: We use Devise for authentication with magic links
+/remember preference: Always use system tests over request specs for UI flows
+/remember entity: Customer belongs_to Tenant, has_many Orders
+/remember discovery: Found ButtonComponent at app/components/base/button_component.rb
+```
+
+## Step 1: Parse Input
+
+Identify the type from the user's input:
+- `decision:` -> Save as decision
+- `preference:` -> Save as preference
+- `entity:` -> Save as entity
+- `discovery:` -> Save as discovery
+
+Extract the content after the type indicator.
+
+## Step 2: Use Pensieve MCP Tool
+
+Use the `pensieve_remember` MCP tool with the appropriate parameters.
+
+### For Decisions
+
+```json
+{
+  "type": "decision",
+  "topic": "[extracted_topic]",
+  "content": "[decision_text]",
+  "rationale": "[rationale_if_provided]"
+}
+```
+
+### For Preferences
+
+```json
+{
+  "type": "preference",
+  "category": "[category]",
+  "key": "[key]",
+  "value": "[value]"
+}
+```
+
+### For Entities
+
+```json
+{
+  "type": "entity",
+  "name": "[entity_name]",
+  "description": "[description]",
+  "relationships": "[relationships]",
+  "location": "[file_location_if_known]"
+}
+```
+
+### For Discoveries
+
+```json
+{
+  "type": "discovery",
+  "category": "[component|pattern|token|other]",
+  "name": "[name]",
+  "location": "[file_path]",
+  "description": "[description]"
+}
+```
+
+## Step 3: Confirm
+
+Report what was saved to the user:
+
+"Saved [type]: [summary]"
+
+If the save failed, report the error and suggest a fix.
+
+## Examples
+
+**Input:** `/remember decision: We use TypeScript for all new code because it catches errors at compile time`
+
+**Action:** Call `pensieve_remember` with:
+```json
+{
+  "type": "decision",
+  "topic": "Language Choice",
+  "content": "We use TypeScript for all new code",
+  "rationale": "Catches errors at compile time"
+}
+```
+
+**Output:**
+```
+Saved decision:
+  Topic: Language Choice
+  Decision: We use TypeScript for all new code
+  Rationale: Catches errors at compile time
+```
+
+**Input:** `/remember preference: testing/approach = system tests for UI flows`
+
+**Action:** Call `pensieve_remember` with:
+```json
+{
+  "type": "preference",
+  "category": "testing",
+  "key": "approach",
+  "value": "system tests for UI flows"
+}
+```
+
+**Output:**
+```
+Saved preference:
+  Category: testing
+  Key: approach
+  Value: system tests for UI flows
+```
+
+**Input:** `/remember entity: Order has_many LineItems, belongs_to Customer`
+
+**Action:** Call `pensieve_remember` with:
+```json
+{
+  "type": "entity",
+  "name": "Order",
+  "description": "Represents a customer order",
+  "relationships": "has_many LineItems, belongs_to Customer"
+}
+```
+
+**Output:**
+```
+Saved entity:
+  Name: Order
+  Relationships: has_many LineItems, belongs_to Customer
+```

package/.claude/commands/session-end.md

@@ -0,0 +1,162 @@
+---
+description: Persist learnings and summarize the session before ending. Use this before closing a conversation to save decisions, discoveries, and next steps for continuity.
+---
+
+# /session-end
+
+Persist learnings and summarize the session before context is cleared.
+
+## Purpose
+
+Save everything learned during this session so the next conversation can pick up seamlessly:
+- Summarize accomplishments
+- Note work in progress
+- Record planned next steps
+- Persist any unrecorded decisions or preferences
+
+## Step 1: Gather Session Information
+
+Ask the user (or infer from conversation):
+- What was accomplished this session?
+- What is still in progress?
+- What are the planned next steps?
+
+If the user doesn't provide this, attempt to summarize based on the conversation.
+
+## Step 2: Identify Key Files
+
+List the key files that were worked on during this session:
+
+```bash
+# If git is available, check recent changes
+git diff --name-only HEAD~1 2>/dev/null || echo "Unable to detect changed files"
+```
+
+Or track files mentioned during the conversation.
+
+## Step 3: Save Any Pending Memories
+
+Before ending the session, use `pensieve_remember` to save any decisions, discoveries, or preferences that were made but not yet recorded.
+
+For each unrecorded decision:
+```json
+{
+  "type": "decision",
+  "topic": "[topic]",
+  "content": "[decision]",
+  "rationale": "[rationale]"
+}
+```
+
+For each unrecorded discovery:
+```json
+{
+  "type": "discovery",
+  "category": "[category]",
+  "name": "[name]",
+  "location": "[location]",
+  "description": "[description]"
+}
+```
+
+## Step 4: End Session with Summary
+
+Use the `pensieve_session_end` MCP tool to finalize the session:
+
+```json
+{
+  "summary": "[what was accomplished]",
+  "work_in_progress": "[what's still ongoing]",
+  "next_steps": "[planned actions for next session]",
+  "key_files": ["file1.rb", "file2.ts"]
+}
+```
+
+## Step 5: Confirm Session Saved
+
+Present a summary to the user:
+
+```
+## Session Saved
+
+### Summary
+[what was accomplished]
+
+### Work in Progress
+[what's still ongoing]
+
+### Next Steps
+[planned actions for next session]
+
+### Key Files
+- [file1]
+- [file2]
+
+### Decisions Recorded
+- [decision1]
+- [decision2]
+
+### Open Questions
+- [question1]
+
+---
+
+Your session has been saved. When you start a new conversation,
+Pensieve will automatically load this context.
+```
+
+## Automatic Triggers
+
+Consider running `/session-end` when:
+- User says "goodbye", "done", "that's all", etc.
+- User explicitly requests to save progress
+- A significant milestone is completed
+
+## Example
+
+**User:** "Okay, I think we're done for now. We finished the user authentication flow."
+
+**Action:** Call `pensieve_session_end` with:
+```json
+{
+  "summary": "Completed user authentication flow with Devise, including login, logout, password reset, and magic link support",
+  "work_in_progress": "Email templates (partially styled)",
+  "next_steps": "1. Complete email templates\n2. Add OAuth providers\n3. Add two-factor authentication",
+  "key_files": [
+    "app/models/user.rb",
+    "app/controllers/sessions_controller.rb",
+    "config/initializers/devise.rb"
+  ]
+}
+```
+
+**Output:**
+```
+## Session Saved
+
+### Summary
+Completed user authentication flow with Devise, including:
+- Login/logout functionality
+- Password reset flow
+- Magic link support
+
+### Work in Progress
+Email templates (partially styled)
+
+### Next Steps
+1. Complete email templates
+2. Add OAuth providers
+3. Add two-factor authentication
+
+### Key Files
+- app/models/user.rb
+- app/controllers/sessions_controller.rb
+- config/initializers/devise.rb
+
+### Decisions Recorded
+- Use Devise with magic links for passwordless auth
+
+---
+
+Your session has been saved. See you next time!
+```

package/.claude/commands/session-start.md

@@ -0,0 +1,97 @@
+---
+description: Load and display context from Pensieve at the start of a conversation. Use this at the beginning of every session to ensure continuity from previous work.
+---
+
+# /session-start
+
+Display and confirm the context loaded from Pensieve at the start of a conversation.
+
+## Purpose
+
+Pensieve automatically loads context when the MCP server starts. This command:
+- Displays what was loaded for transparency
+- Starts session tracking for the current conversation
+- Provides continuity from previous sessions
+
+## Step 1: Start Session Tracking
+
+Use the `pensieve_session_start` MCP tool to begin tracking this session:
+
+```json
+{}
+```
+
+This creates a new session record that will be updated when `/session-end` is called.
+
+## Step 2: Get Full Context
+
+Use the `pensieve_get_context` MCP tool to retrieve all loaded context:
+
+```json
+{}
+```
+
+This returns:
+- Last session summary and next steps
+- Key decisions
+- User preferences
+- Open questions
+- Recent discoveries
+
+## Step 3: Present Context
+
+Format and present the loaded context to the user:
+
+```
+## Session Started
+
+### Last Session
+**Date:** [started_at]
+**Summary:** [summary]
+
+### Work in Progress
+[work_in_progress or "None"]
+
+### Planned Next Steps
+[next_steps or "None"]
+
+### Key Decisions
+- [topic]: [decision]
+- [topic]: [decision]
+...
+
+### Your Preferences
+- [category]/[key]: [value]
+...
+
+### Open Questions
+- [question]
+...
+
+---
+
+Ready to continue. What would you like to work on?
+```
+
+## Fresh Installation
+
+If Pensieve returns no prior context, inform the user:
+
+```
+## Session Started (Fresh Installation)
+
+No prior context found. This appears to be a fresh Pensieve installation.
+
+Your memories will be stored as you work. Use:
+- `/remember` to save decisions, preferences, and discoveries
+- `/recall` to query stored knowledge
+- `/session-end` before ending to save your progress
+
+What would you like to work on?
+```
+
+## Notes
+
+- Pensieve auto-loads context when the MCP server starts, so this command primarily displays what's already loaded
+- Session tracking begins with this command and ends with `/session-end`
+- Context persists in `~/.pensieve/memory.sqlite` (user-level) or project-level if configured

package/dist/database.d.ts

@@ -65,7 +65,13 @@ export interface OpenQuestion {
 export declare class MemoryDatabase {
     private db;
     private projectPath;
+    private dbPath;
     constructor(projectPath?: string);
+    private openDatabase;
+    /**
+     * Check if the database is writable and reconnect if needed
+     */
+    ensureWritable(): boolean;
     private getDbPath;
     /**
      * Truncate a string to the maximum field length

package/dist/database.js

@@ -15,32 +15,82 @@ export const LIMITS = {
 export class MemoryDatabase {
     db;
     projectPath;
+    dbPath;
     constructor(projectPath) {
         // Use provided path, or detect from current directory, or use home
         this.projectPath = projectPath || process.cwd();
-        const dbPath = this.getDbPath();
+        this.dbPath = this.getDbPath();
         // Ensure directory exists
-        const dbDir = dirname(dbPath);
+        const dbDir = dirname(this.dbPath);
         if (!existsSync(dbDir)) {
             mkdirSync(dbDir, { recursive: true });
         }
-        this.db = new Database(dbPath);
+        this.db = this.openDatabase();
         this.initSchema();
     }
+    openDatabase() {
+        // Always try to open in read-write mode
+        // If file doesn't exist, it will be created
+        try {
+            return new Database(this.dbPath, { fileMustExist: false });
+        }
+        catch (error) {
+            console.error(`[Pensieve] Failed to open database: ${error}`);
+            throw error;
+        }
+    }
+    /**
+     * Check if the database is writable and reconnect if needed
+     */
+    ensureWritable() {
+        try {
+            // Test write capability
+            this.db.exec('SELECT 1');
+            this.db.prepare('CREATE TABLE IF NOT EXISTS _pensieve_health_check (id INTEGER)').run();
+            return true;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (errorMessage.includes('readonly')) {
+                console.error('[Pensieve] Database is read-only, attempting reconnection...');
+                try {
+                    this.db.close();
+                    this.db = this.openDatabase();
+                    console.error('[Pensieve] Reconnected successfully');
+                    return true;
+                }
+                catch (reconnectError) {
+                    console.error(`[Pensieve] Reconnection failed: ${reconnectError}`);
+                    return false;
+                }
+            }
+            return false;
+        }
+    }
     getDbPath() {
-        // Check for explicit environment variable override first
+        // Check for explicit database path override
         const envPath = process.env.PENSIEVE_DB_PATH;
         if (envPath) {
             console.error(`[Pensieve] Using database from PENSIEVE_DB_PATH: ${envPath}`);
             return envPath;
         }
-        // Try project-local first, then fall back to home directory
+        // Check for explicit project path (recommended for MCP server usage)
+        // This should be set in the MCP server config to ensure deterministic behavior
+        const projectDir = process.env.PENSIEVE_PROJECT_DIR;
+        if (projectDir) {
+            const projectPath = join(projectDir, '.pensieve', 'memory.sqlite');
+            console.error(`[Pensieve] Using project database from PENSIEVE_PROJECT_DIR: ${projectPath}`);
+            return projectPath;
+        }
+        // Fallback: Try project-local first, then fall back to home directory
+        // WARNING: Using process.cwd() is unreliable in MCP server context
         const localPath = join(this.projectPath, '.pensieve', 'memory.sqlite');
         const globalPath = join(homedir(), '.claude-pensieve', 'memory.sqlite');
         // If local .pensieve directory exists or we're in a git repo, use local
         if (existsSync(join(this.projectPath, '.pensieve')) ||
             existsSync(join(this.projectPath, '.git'))) {
-            console.error(`[Pensieve] Using project-local database: ${localPath}`);
+            console.error(`[Pensieve] WARNING: Using cwd-based path (unreliable): ${localPath}`);
+            console.error(`[Pensieve] Set PENSIEVE_PROJECT_DIR for deterministic behavior`);
             return localPath;
         }
         console.error(`[Pensieve] Using global database: ${globalPath}`);
@@ -177,6 +227,7 @@ export class MemoryDatabase {
     }
     // Decision methods
     addDecision(decision) {
+        this.ensureWritable();
         this.pruneIfNeeded();
         const stmt = this.db.prepare(`
       INSERT INTO decisions (topic, decision, rationale, alternatives, source)
@@ -205,6 +256,7 @@ export class MemoryDatabase {
     }
     // Preference methods
     setPreference(pref) {
+        this.ensureWritable();
         const stmt = this.db.prepare(`
       INSERT OR REPLACE INTO preferences (category, key, value, notes, updated_at)
       VALUES (?, ?, ?, ?, datetime('now'))
@@ -231,6 +283,7 @@ export class MemoryDatabase {
     }
     // Discovery methods
     addDiscovery(discovery) {
+        this.ensureWritable();
         this.pruneIfNeeded();
         const stmt = this.db.prepare(`
       INSERT INTO discoveries (category, name, location, description, metadata, confidence)
@@ -257,6 +310,7 @@ export class MemoryDatabase {
     }
     // Entity methods
     upsertEntity(entity) {
+        this.ensureWritable();
         const stmt = this.db.prepare(`
       INSERT OR REPLACE INTO entities (name, description, relationships, attributes, location, updated_at)
       VALUES (?, ?, ?, ?, ?, datetime('now'))
@@ -273,11 +327,13 @@ export class MemoryDatabase {
     }
     // Session methods
     startSession() {
+        this.ensureWritable();
         const stmt = this.db.prepare(`INSERT INTO sessions (started_at) VALUES (datetime('now'))`);
         const result = stmt.run();
         return result.lastInsertRowid;
     }
     endSession(sessionId, summary, workInProgress, nextSteps, keyFiles, tags) {
+        this.ensureWritable();
         this.pruneIfNeeded();
         const stmt = this.db.prepare(`
       UPDATE sessions
@@ -305,6 +361,7 @@ export class MemoryDatabase {
     }
     // Open questions methods
     addQuestion(question, context) {
+        this.ensureWritable();
         const stmt = this.db.prepare(`
       INSERT INTO open_questions (question, context) VALUES (?, ?)
     `);
@@ -312,6 +369,7 @@ export class MemoryDatabase {
         return result.lastInsertRowid;
     }
     resolveQuestion(id, resolution) {
+        this.ensureWritable();
         const stmt = this.db.prepare(`
       UPDATE open_questions
       SET status = 'resolved', resolution = ?, resolved_at = datetime('now')
@@ -336,7 +394,7 @@ export class MemoryDatabase {
     }
     // Get database path for debugging
     getPath() {
-        return this.getDbPath();
+        return this.dbPath;
     }
     close() {
         this.db.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esparkman/pensieve",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Pensieve - persistent memory for Claude Code. Remember decisions, preferences, and context across sessions.",
   "type": "module",
   "main": "dist/index.js",
@@ -40,6 +40,7 @@
     "node": ">=18"
   },
   "files": [
-    "dist"
+    "dist",
+    ".claude"
   ]
 }