@esparkman/pensieve 0.1.3 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esparkman/pensieve",
-  "version": "0.1.3",
+  "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"
   ]
 }