claude-recall 0.3.3 → 0.5.0

package/.claude/settings.local.json

@@ -1,7 +1,8 @@
 {
   "permissions": {
     "allow": [
-      "Bash(npm view:*)"
+      "Bash(npm view:*)",
+      "mcp__perplexity-mcp__search"
     ],
     "deny": [],
     "ask": []

package/.claude/skills/memory-management/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: "claude-recall-memory-management"
+description: "Automatic memory capture and retrieval for Claude Recall MCP - ensures you never repeat yourself"
+allowed-tools: "mcp__claude-recall__*"
+version: "0.5.0"
+priority: "highest"
+license: "MIT"
+---
+
+# Claude Recall Memory Management
+
+This Skill teaches Claude Code how to use Claude Recall's persistent memory system effectively. It ensures automatic capture of project context, devops workflows, and user preferences.
+
+## Core Principle: Never Repeat Yourself
+
+**The user should NEVER have to repeat preferences or explain what worked/didn't work.**
+
+## Memory Types (Priority Order)
+
+1. **DevOps** (Priority 0 - HIGHEST) - Project-specific workflows
+   - Git conventions, testing approaches, build processes
+   - Development environment setup
+   - Architecture decisions, tech stack choices
+
+2. **Corrections** (Priority 1) - User explicitly fixed mistakes
+   - "No, do this instead" statements
+   - Overrides previous approaches
+
+3. **Preferences** (Priority 2) - User coding style, tool choices
+   - Code style, framework preferences
+   - File organization, naming conventions
+
+4. **Success/Failure** (Priority 3) - What worked and what didn't
+   - Successful implementations to repeat
+   - Failed approaches to avoid
+
+## When to Search Memories (BEFORE ANY TASK)
+
+**CRITICAL**: Before file operations, decisions, or implementations, ALWAYS search memories:
+
+```
+mcp__claude-recall__search("[task keywords] devops preferences success failure correction")
+```
+
+### Search Examples:
+
+**Before creating authentication:**
+```
+mcp__claude-recall__search("authentication devops testing git")
+```
+
+**Before writing tests:**
+```
+mcp__claude-recall__search("testing tdd location framework")
+```
+
+**Before deployment tasks:**
+```
+mcp__claude-recall__search("deploy build docker git workflow")
+```
+
+### What Search Finds Automatically:
+
+- **DevOps workflows**: Git branching, testing rules, deployment steps
+- **Preferences**: User's stated coding style, tool choices
+- **Successes**: Past approaches that worked well
+- **Failures**: Past approaches that failed (avoid these!)
+- **Corrections**: User fixes (HIGHEST PRIORITY - user explicitly said "no, do this")
+
+## When to Store Memories
+
+### Automatic Capture (v0.5.0+)
+
+Claude Recall now **automatically captures** these patterns:
+
+**DevOps Patterns** (Priority 0 - captured automatically):
+- ✅ "This is a [project type]" → Project purpose
+- ✅ "Built with [tech stack]" → Tech stack
+- ✅ "We develop on [environment]" → Dev environment
+- ✅ "Always [X] before [Y]" → Workflow rules
+- ✅ "Use [X] for [Y]" → Tool choices
+- ✅ "Tests go in [location]" → Testing conventions
+- ✅ "Follow TDD" → Development approach
+
+**Project Info** (captured automatically):
+- ✅ "Tenant ID is X" → Configuration
+- ✅ "API endpoint: X" → Endpoints
+- ✅ "Our database is X" → Infrastructure
+
+**Preferences** (captured automatically):
+- ✅ "I prefer TypeScript" → Language preference
+- ✅ "Always use Jest" → Tool preference
+- ✅ "Never use semicolons" → Code style
+
+### Manual Storage Required For:
+
+Use `mcp__claude-recall__store_memory` for:
+
+**Complex multi-step workflows:**
+```
+mcp__claude-recall__store_memory({
+  content: "Deployment process: 1) Run tests 2) Build Docker 3) Push to ECR 4) Update k8s",
+  metadata: { type: "devops", category: "deployment" }
+})
+```
+
+**Lessons learned from failures:**
+```
+mcp__claude-recall__store_memory({
+  content: "Session-based auth failed in production due to distributed sessions - use JWT instead",
+  metadata: { type: "failure", lesson: "use_stateless_auth" }
+})
+```
+
+**User corrections to your work:**
+```
+mcp__claude-recall__store_memory({
+  content: "CORRECTION: Tests go in __tests__/ not tests/",
+  metadata: { type: "correction", priority: "highest" }
+})
+```
+
+## Check What's Captured
+
+To see what memories have been automatically captured:
+
+```
+mcp__claude-recall__get_recent_captures({ limit: 10 })
+```
+
+This helps you verify that important project context was stored.
+
+## Example Workflow
+
+### First Time (User States Preference)
+
+```
+User: "I prefer Python for scripts"
+[Auto-captured as preference]
+
+User: "We use TDD for all new features"
+[Auto-captured as devops workflow_rule, priority 0]
+
+User: "This is a teleprompter tool for interviews"
+[Auto-captured as devops project_purpose, priority 0]
+```
+
+### Second Time (First Use)
+
+```
+User: "Create a test script"
+
+Step 1: Search memories
+mcp__claude-recall__search("script test python")
+Finds: "I prefer Python for scripts" + "We use TDD"
+
+Step 2: Create test_script.py with TDD approach
+
+Step 3: User approves → Store success
+mcp__claude-recall__store_memory({
+  content: "Created test script with Python + TDD - SUCCESS",
+  metadata: { type: "success", task: "test_script" }
+})
+```
+
+### Third Time (Automatic Application)
+
+```
+User: "Create a build script"
+
+Step 1: Search memories
+mcp__claude-recall__search("script build python tdd")
+Finds:
+- "I prefer Python for scripts" (preference)
+- "We use TDD" (devops)
+- "Created test script with Python + TDD - SUCCESS" (validates approach)
+
+Step 2: Create build.py with tests automatically
+User doesn't have to repeat preferences! ✓
+```
+
+## Best Practices
+
+1. **Search broadly** - Include task type + language + workflow keywords
+2. **Trust the learning loop** - Automatic capture handles most cases
+3. **Store manually** for complex multi-step processes
+4. **Check captures** periodically with `get_recent_captures`
+5. **Correct immediately** - If output is wrong, tell me and it gets highest priority
+
+## Troubleshooting
+
+**If memories aren't being found:**
+1. Check search query keywords - be broad
+2. Verify memory exists: `mcp__claude-recall__get_recent_captures`
+3. Search without type filters to see all results
+
+**If automatic capture missed something:**
+1. Use manual storage for that specific item
+2. The pattern may not have matched - broader trigger words help
+
+**For more examples:**
+- Load `references/devops-patterns.md` for DevOps memory examples
+- Load `references/capture-examples.md` for manual storage templates
+- Load `references/troubleshooting.md` for common issues
+
+---
+
+**Remember**: This Skill ensures the learning loop works automatically. Your job is to search memories BEFORE tasks and trust the automatic capture for most cases.

package/.claude/skills/memory-management/references/capture-examples.md

@@ -0,0 +1,305 @@
+# Manual Memory Capture Examples
+
+This document provides templates for manually storing memories when automatic capture isn't sufficient.
+
+## When to Use Manual Storage
+
+Use `mcp__claude-recall__store_memory` when:
+- Complex multi-step workflows need to be documented
+- Lessons learned from failures
+- User corrects your work
+- Nuanced context that patterns might miss
+
+## Success Examples
+
+### Basic Success
+```javascript
+mcp__claude-recall__store_memory({
+  content: "Created authentication with JWT tokens - SUCCESS",
+  metadata: { type: "success", task: "authentication" }
+})
+```
+
+### Success with Context
+```javascript
+mcp__claude-recall__store_memory({
+  content: "Implemented push-to-talk with pyaudio instead of continuous VAD - SUCCESS. Much better performance and user control.",
+  metadata: {
+    type: "success",
+    task: "audio_capture",
+    improvement: "performance + ux"
+  }
+})
+```
+
+### Success with Technical Details
+```javascript
+mcp__claude-recall__store_memory({
+  content: "Fixed memory leak by moving PyAudio initialization outside the loop - SUCCESS. Memory usage dropped from 500MB to 50MB.",
+  metadata: {
+    type: "success",
+    task: "performance",
+    metric: "10x memory reduction"
+  }
+})
+```
+
+## Failure Examples
+
+### Basic Failure
+```javascript
+mcp__claude-recall__store_memory({
+  content: "Session-based authentication failed in distributed environment - use stateless JWT instead",
+  metadata: { type: "failure", avoid: "session_auth_distributed" }
+})
+```
+
+### Failure with Root Cause
+```javascript
+mcp__claude-recall__store_memory({
+  content: "Continuous VAD approach failed - too CPU intensive, poor UX. Root cause: processing audio every frame. Solution: Use push-to-talk instead.",
+  metadata: {
+    type: "failure",
+    root_cause: "continuous_processing",
+    solution: "push_to_talk"
+  }
+})
+```
+
+### Failure with Lesson Learned
+```javascript
+mcp__claude-recall__store_memory({
+  content: "Tried mock audio files for testing but they don't match real mic behavior. Lesson: Need actual microphone for audio tests, can't fully mock.",
+  metadata: {
+    type: "failure",
+    lesson: "use_real_hardware_for_audio_tests"
+  }
+})
+```
+
+## Correction Examples
+
+### Basic Correction
+```javascript
+mcp__claude-recall__store_memory({
+  content: "CORRECTION: Tests go in __tests__/ directory, not tests/",
+  metadata: { type: "correction", priority: "highest" }
+})
+```
+
+### Correction with Rationale
+```javascript
+mcp__claude-recall__store_memory({
+  content: "CORRECTION: Use 4 spaces for indentation, not tabs. Reason: Project convention for Python files.",
+  metadata: {
+    type: "correction",
+    priority: "highest",
+    language: "python"
+  }
+})
+```
+
+### Correction Overriding Previous Approach
+```javascript
+mcp__claude-recall__store_memory({
+  content: "CORRECTION: Don't use Docker for local development, use virtual environment instead. Docker adds unnecessary complexity for this project.",
+  metadata: {
+    type: "correction",
+    priority: "highest",
+    overrides: "docker_local_dev"
+  }
+})
+```
+
+## DevOps Workflow Examples
+
+### Deployment Process
+```javascript
+mcp__claude-recall__store_memory({
+  content: `Deployment workflow:
+1. Create feature branch from main
+2. Run tests locally: npm test
+3. Create PR with conventional commit message
+4. Wait for CI (lint + test + build)
+5. Get 2 code review approvals
+6. Squash merge to main
+7. GitHub Actions auto-deploys to staging
+8. QA approval required for production
+9. Promote to prod: kubectl apply -f k8s/prod/`,
+  metadata: {
+    type: "devops",
+    category: "deployment",
+    steps: 9,
+    tools: ["github-actions", "kubernetes"]
+  }
+})
+```
+
+### Testing Strategy
+```javascript
+mcp__claude-recall__store_memory({
+  content: `Testing strategy:
+- Unit tests: Jest, 80% coverage minimum
+- Integration tests: Supertest for API
+- E2E tests: Playwright for UI
+- Run order: unit → integration → e2e
+- CI runs all, but devs can run unit tests locally`,
+  metadata: {
+    type: "devops",
+    category: "testing_strategy",
+    tools: ["jest", "supertest", "playwright"]
+  }
+})
+```
+
+### Git Branching Strategy
+```javascript
+mcp__claude-recall__store_memory({
+  content: `Git workflow (GitFlow variant):
+- main: production-ready code
+- develop: integration branch
+- feature/*: new features (from develop)
+- bugfix/*: bug fixes (from develop)
+- hotfix/*: emergency production fixes (from main)
+- Merge: feature → develop → main
+- Release: tag main with semver`,
+  metadata: {
+    type: "devops",
+    category: "git_workflow",
+    strategy: "gitflow"
+  }
+})
+```
+
+## Project Knowledge Examples
+
+### API Configuration
+```javascript
+mcp__claude-recall__store_memory({
+  content: "API configuration: Base URL https://api.example.com/v1, Auth header: Bearer token, Rate limit: 100 req/min",
+  metadata: {
+    type: "project-knowledge",
+    category: "api_config"
+  }
+})
+```
+
+### Database Setup
+```javascript
+mcp__claude-recall__store_memory({
+  content: "Database: PostgreSQL 15 on RDS. Connection pooling: 20 connections. Migrations: Alembic. Backup: Daily at 2 AM UTC.",
+  metadata: {
+    type: "project-knowledge",
+    category: "database"
+  }
+})
+```
+
+### Environment Variables
+```javascript
+mcp__claude-recall__store_memory({
+  content: `Required environment variables:
+- DATABASE_URL: postgres connection string
+- REDIS_URL: redis://localhost:6379
+- JWT_SECRET: from 1Password
+- AWS_REGION: us-east-1
+- LOG_LEVEL: info (prod) or debug (dev)`,
+  metadata: {
+    type: "project-knowledge",
+    category: "env_vars"
+  }
+})
+```
+
+## Complex Decision Examples
+
+### Architecture Decision
+```javascript
+mcp__claude-recall__store_memory({
+  content: `Decided on microservices architecture:
+- User Service: authentication, profiles
+- Product Service: catalog, inventory
+- Order Service: cart, checkout, payments
+- Communication: Event bus (RabbitMQ)
+- API Gateway: Kong
+- Reason: Team scaling, independent deployment`,
+  metadata: {
+    type: "devops",
+    category: "architecture",
+    pattern: "microservices",
+    decision_date: "2025-01-15"
+  }
+})
+```
+
+### Technology Choice
+```javascript
+mcp__claude-recall__store_memory({
+  content: `Chose TypeScript over JavaScript:
+- Type safety reduces runtime errors
+- Better IDE support
+- Easier refactoring
+- Team already familiar
+- Strict mode enabled for all files`,
+  metadata: {
+    type: "devops",
+    category: "tech_choice",
+    language: "typescript"
+  }
+})
+```
+
+## Preference Override Examples
+
+### Updating Previous Preference
+```javascript
+mcp__claude-recall__store_memory({
+  content: "FROM NOW ON: Use Vitest instead of Jest for new projects. Vitest is faster and has better ESM support.",
+  metadata: {
+    type: "preference",
+    category: "testing_framework",
+    overrides: "jest",
+    reason: "performance"
+  }
+})
+```
+
+### Changing Workflow
+```javascript
+mcp__claude-recall__store_memory({
+  content: "UPDATED WORKFLOW: Now we're using trunk-based development instead of GitFlow. Feature flags for incomplete features. Direct commits to main allowed with CI passing.",
+  metadata: {
+    type: "devops",
+    category: "git_workflow",
+    overrides: "gitflow",
+    change_date: "2025-01-15"
+  }
+})
+```
+
+## Template for Any Memory
+
+```javascript
+mcp__claude-recall__store_memory({
+  content: "[Clear, concise description of what you learned/decided]",
+  metadata: {
+    type: "[devops|preference|success|failure|correction|project-knowledge]",
+    category: "[specific category]",
+    // Optional fields:
+    priority: "[highest|high|medium|low]",
+    overrides: "[what this replaces]",
+    tools: ["tool1", "tool2"],
+    confidence: 0.85,
+    // Any other relevant context
+  }
+})
+```
+
+## Best Practices
+
+1. **Be specific** - "Created auth with JWT" is better than "Made login work"
+2. **Include context** - Why did it work? What was the problem?
+3. **Add metadata** - Helps future searches find relevant memories
+4. **Use consistent types** - Stick to the standard types (devops, preference, etc.)
+5. **Override explicitly** - If changing previous decision, note what it overrides
+6. **Include tools/versions** - Helps when debugging version-specific issues