claude_memory 0.2.0 → 0.3.0

data/.claude/skills/review-commit/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: review-commit
+description: Quick quality review of staged changes for pre-commit validation. Checks Ruby best practices and flags critical issues.
+agent: general-purpose
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# Pre-Commit Quality Review
+
+Review the staged changes in this commit for code quality issues before committing.
+
+## Objectives
+
+- **Fast**: Complete review in < 30 seconds
+- **Focused**: Only review staged Ruby files
+- **Actionable**: Clear pass/fail with specific fixes
+- **Non-interactive**: Works in headless mode
+- **Expert-driven**: Apply Ruby best practices from industry experts
+
+## Expert Panel
+
+Apply principles from these Ruby/software design experts:
+
+1. **Sandi Metz** - POODR principles, small methods/classes, SRP, DRY
+2. **Jeremy Evans** - Sequel best practices, transaction safety, performance
+3. **Kent Beck** - Simple design, revealing names, Command-Query Separation
+4. **Avdi Grimm** - Confident Ruby, null objects, tell-don't-ask, meaningful returns
+5. **Gary Bernhardt** - Functional core/imperative shell, fast tests, immutability
+
+## Review Process
+
+1. **Get staged files:**
+   ```bash
+   git diff --cached --name-only --diff-filter=ACM | grep '\.rb$'
+   ```
+
+2. **For each staged Ruby file, check:**
+   - Get the full diff: `git diff --cached <file>`
+   - Review only the added/modified lines (lines starting with `+`)
+
+3. **Look for critical issues (❌ BLOCK):**
+
+   **Sandi Metz violations:**
+   - ❌ Missing `frozen_string_literal: true` in new files
+   - ❌ Methods > 15 lines (SRP violation, too complex)
+   - ❌ Classes > 200 lines (god object)
+   - ❌ Obvious code duplication (DRY violation)
+
+   **Jeremy Evans (Sequel) violations:**
+   - ❌ Raw SQL strings instead of Sequel dataset methods
+   - ❌ Database writes without transaction wrapper
+   - ❌ N+1 queries (multiple queries in loops)
+
+   **Kent Beck violations:**
+   - ❌ Overly complex solutions (nested conditionals > 3 levels)
+   - ❌ Command-Query Separation violation (methods that both mutate and return calculated values)
+
+   **Avdi Grimm violations:**
+   - ❌ Defensive nil checks everywhere (should use null objects)
+   - ❌ Implicit nil returns in public methods
+   - ❌ Bare `raise` or `rescue` without exception class
+
+   **Gary Bernhardt violations:**
+   - ❌ I/O operations mixed with business logic (should separate)
+   - ❌ Mutable state in value objects
+   - ❌ Database/file I/O in unit tests (makes tests slow)
+
+   **Testing:**
+   - ❌ New public methods without corresponding tests
+
+4. **Look for medium issues (⚠️ WARNING):**
+
+   **Sandi Metz:**
+   - ⚠️ Methods 10-15 lines (consider extracting)
+   - ⚠️ Classes 100-200 lines (approaching god object)
+   - ⚠️ Method parameters > 3 (use parameter object)
+
+   **Jeremy Evans:**
+   - ⚠️ Missing indexes on foreign keys
+   - ⚠️ Connection not properly managed
+
+   **Kent Beck:**
+   - ⚠️ Poor naming (unclear variable/method names, abbreviations)
+   - ⚠️ Methods doing multiple things (and/or in method name)
+
+   **Avdi Grimm:**
+   - ⚠️ Law of Demeter violations (chained method calls like `foo.bar.baz.qux`)
+   - ⚠️ Asking instead of telling (lots of getters instead of sending commands)
+
+   **Gary Bernhardt:**
+   - ⚠️ Business logic scattered in imperative shell
+   - ⚠️ Missing value objects (primitives passed around)
+
+   **General:**
+   - ⚠️ Missing documentation for public APIs
+   - ⚠️ Tight coupling between modules
+
+## Output Format
+
+Provide a clear summary with expert attributions:
+
+```
+# Pre-Commit Quality Review
+
+## Files Reviewed
+- file1.rb (23 lines changed)
+- file2.rb (8 lines changed)
+
+## Status: ❌ BLOCK / ✅ PASS / ⚠️ WARNING
+
+### Critical Issues ❌ (must fix before commit)
+
+**Sandi Metz violations:**
+- file1.rb:1 - Missing frozen_string_literal: true
+- file2.rb:15-38 - Method too long (24 lines, max 15)
+
+**Jeremy Evans violations:**
+- file1.rb:42 - Raw SQL string instead of Sequel dataset method
+- file1.rb:50 - Database write without transaction wrapper
+
+**Avdi Grimm violations:**
+- file2.rb:10 - Implicit nil return in public method
+
+### Medium Issues ⚠️ (consider fixing)
+
+**Sandi Metz:**
+- file3.rb:20-32 - Method is 13 lines (consider extracting)
+
+**Kent Beck:**
+- file2.rb:5 - Variable name `x` is unclear (revealing intent)
+
+**Avdi Grimm:**
+- file3.rb:45 - Law of Demeter violation: user.account.settings.theme
+
+### Recommendations
+
+1. Add `frozen_string_literal: true` to file1.rb (Sandi Metz)
+2. Convert raw SQL at file1.rb:42 to Sequel dataset (Jeremy Evans)
+3. Wrap database write at file1.rb:50 in transaction (Jeremy Evans)
+4. Extract file2.rb:15-38 into smaller methods (Sandi Metz)
+5. Return explicit value instead of nil at file2.rb:10 (Avdi Grimm)
+6. Rename `x` to describe what it contains (Kent Beck)
+7. Extract file3.rb:20-32 for better readability (Sandi Metz)
+8. Use tell-don't-ask at file3.rb:45 (Avdi Grimm)
+
+## Suggested Actions
+
+[If BLOCK] Run: git reset HEAD <files> && fix issues && git add <files>
+[If WARNING] Consider fixing before commit or create a follow-up task
+[If PASS] Commit looks good! 🚀
+```
+
+## Exit Behavior
+
+- **Return clear judgment**: BLOCK, WARNING, or PASS
+- **Be specific**: Include file:line references for all issues
+- **Be helpful**: Suggest concrete fixes
+- **Be fast**: Don't over-analyze, focus on obvious problems
+
+## Quick Reference Checklist
+
+For each added/modified line in the diff, scan for:
+
+**Sandi Metz:**
+- [ ] frozen_string_literal at top?
+- [ ] Methods < 15 lines? (warn at 10+)
+- [ ] Classes < 200 lines? (warn at 100+)
+- [ ] No duplicate code?
+- [ ] Parameters <= 3? (warn if more)
+
+**Jeremy Evans:**
+- [ ] Sequel datasets not raw SQL?
+- [ ] DB writes in transactions?
+- [ ] No N+1 queries in loops?
+
+**Kent Beck:**
+- [ ] Nested conditionals <= 3?
+- [ ] Clear, revealing names?
+- [ ] Methods do one thing?
+- [ ] Command-Query Separation?
+
+**Avdi Grimm:**
+- [ ] Null objects instead of nil checks?
+- [ ] Explicit returns (not implicit nil)?
+- [ ] Specific exception classes?
+- [ ] Law of Demeter (max 2 dots)?
+
+**Gary Bernhardt:**
+- [ ] Business logic separate from I/O?
+- [ ] Value objects immutable?
+- [ ] Tests avoid I/O?
+
+## Success Criteria
+
+The review is complete when:
+- All staged Ruby files have been checked
+- Clear BLOCK/WARNING/PASS verdict is given
+- All critical issues have file:line references with expert attribution
+- Concrete fix suggestions are provided with expert rationale

data/.claude/skills/review-for-quality/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: review-for-quality
+description: Comprehensive code quality review through expert perspectives (Sandi Metz, Jeremy Evans, Kent Beck, Avdi Grimm, Gary Bernhardt). Updates docs/quality_review.md with findings.
+agent: Plan
+allowed-tools: Read, Grep, Glob
+---
+
+# Code Quality Review
+
+Critically review this Ruby codebase for best-practices, idiom use, and overall quality through the eyes of Ruby experts.
+
+## Expert Perspectives
+
+Analyze the codebase through these 5 perspectives:
+
+1. **Sandi Metz** (POODR principles)
+   - Single Responsibility Principle
+   - Small, focused methods (< 5 lines ideal)
+   - Classes with single purpose
+   - DRY principle
+   - Clear dependencies
+   - High test coverage
+
+2. **Jeremy Evans** (Sequel maintainer)
+   - Proper Sequel usage patterns (datasets over raw SQL)
+   - Database performance optimization
+   - Schema design best practices
+   - Connection management
+   - Transaction safety
+   - Sequel plugins and extensions
+
+3. **Kent Beck** (TDD, Simple Design)
+   - Test-first design
+   - Simple solutions over complex ones
+   - Revealing intent through naming
+   - Clear boundaries between components
+   - Testability without mocks
+   - Command-Query Separation
+
+4. **Avdi Grimm** (Confident Ruby)
+   - Confident code (no defensive nil checks everywhere)
+   - Tell, don't ask principle
+   - Null object pattern
+   - Meaningful return values (not nil)
+   - Duck typing
+   - Result objects over exceptions
+
+5. **Gary Bernhardt** (Boundaries, Fast Tests)
+   - Functional core, imperative shell
+   - Fast unit tests (no I/O in logic)
+   - Clear boundaries between layers
+   - Separation of I/O and pure logic
+   - Value objects
+   - Immutable data structures
+
+## Review Process
+
+1. **Explore the codebase systematically:**
+   - `lib/claude_memory/` (all subdirectories)
+   - Identify the largest files (> 500 lines)
+   - Find code duplication patterns
+   - Check architecture and design patterns
+
+2. **Document EVERY issue found** with:
+   - Priority: 🔴 Critical / High / 🟡 Medium / Low
+   - Specific file:line references
+   - Which expert's principle is violated
+   - Concrete improvement suggestions with code examples
+   - Estimated effort to fix
+
+3. **Track progress:**
+   - Compare with previous review date
+   - Show metrics (lines of code, god objects, etc.)
+   - Identify what's been fixed since last review
+   - Highlight new issues that have emerged
+
+4. **Provide actionable recommendations:**
+   - High priority items (this week)
+   - Medium priority items (next week)
+   - Low priority items (later)
+   - Quick wins (can do today)
+
+## Output Format
+
+Update `docs/quality_review.md` with:
+
+### Structure:
+```
+# Code Quality Review - Ruby Best Practices
+
+**Review Date:** [YYYY-MM-DD]
+**Previous Review:** [YYYY-MM-DD]
+
+## Executive Summary
+[Progress since last review + new critical issues]
+
+## 1. Sandi Metz Perspective
+### What's Been Fixed ✅
+### Critical Issues 🔴
+### Medium Issues 🟡
+
+## 2. Jeremy Evans Perspective
+[Same structure]
+
+## 3. Kent Beck Perspective
+[Same structure]
+
+## 4. Avdi Grimm Perspective
+[Same structure]
+
+## 5. Gary Bernhardt Perspective
+[Same structure]
+
+## 6. General Ruby Idioms
+[Style and convention issues]
+
+## 7. Positive Observations
+[What's working well]
+
+## 8. Priority Refactoring Recommendations
+### High Priority (This Week)
+### Medium Priority (Next Week)
+### Low Priority (Later)
+
+## 9. Conclusion
+[Summary + risk assessment + next steps]
+
+## Appendix A: Metrics Comparison
+[Table showing progress]
+
+## Appendix B: Quick Wins
+[Things that can be done immediately]
+
+## Appendix C: File Size Report
+[Largest files identified]
+```
+
+## Important Notes
+
+- Be thorough and critical - find real issues to improve
+- Every issue needs a specific file:line reference
+- Provide code examples for suggested fixes
+- Don't just praise - identify concrete problems
+- Compare metrics with previous review date
+- Estimate effort for each recommendation (days)
+
+## Success Criteria
+
+The review is complete when:
+- `docs/quality_review.md` is updated with dated findings
+- Every issue has file:line references
+- Concrete code examples are provided
+- Metrics comparison table is included
+- Actionable priorities are listed with time estimates

data/.claude/skills/review-for-quality/expert-checklists.md

@@ -0,0 +1,79 @@
+# Expert Review Checklists
+
+## Sandi Metz (POODR) Checklist
+
+- [ ] Classes under 100 lines
+- [ ] Methods under 5 lines
+- [ ] Method parameters limited (< 4)
+- [ ] Single Responsibility Principle followed
+- [ ] No god objects (classes > 500 lines)
+- [ ] DRY violations eliminated
+- [ ] Dependencies injected, not created
+- [ ] Public interface is minimal
+- [ ] Private methods grouped at bottom
+- [ ] attr_reader used appropriately
+
+## Jeremy Evans (Sequel) Checklist
+
+- [ ] Using Sequel datasets, not raw SQL
+- [ ] Transactions wrap multi-step operations
+- [ ] DateTime columns instead of String timestamps
+- [ ] Sequel migrations used (not manual)
+- [ ] Connection pooling configured
+- [ ] Sequel plugins utilized (timestamps, validation_helpers)
+- [ ] No N+1 query patterns
+- [ ] Batch queries used for multiple records
+- [ ] Foreign keys defined properly
+- [ ] Indexes created for common queries
+
+## Kent Beck (TDD, Simple Design) Checklist
+
+- [ ] Dependencies can be injected for testing
+- [ ] No side effects in constructors
+- [ ] Methods reveal intent through naming
+- [ ] Complex boolean logic is extracted and named
+- [ ] No large case statements (use polymorphism)
+- [ ] Tests exist for failure modes
+- [ ] Command-Query Separation followed
+- [ ] Simple solutions chosen over complex ones
+- [ ] Test coverage for edge cases
+- [ ] Clear boundaries between components
+
+## Avdi Grimm (Confident Ruby) Checklist
+
+- [ ] Null Object pattern used instead of nil checks
+- [ ] Consistent return values (not mixed types)
+- [ ] Result objects for success/failure
+- [ ] Tell, don't ask (no ask-then-do patterns)
+- [ ] Early returns minimized (use guard clauses)
+- [ ] Primitive obsession eliminated (use value objects)
+- [ ] Domain objects instead of hashes
+- [ ] Duck typing enables polymorphism
+- [ ] Meaningful default values
+- [ ] Confident code (no defensive programming everywhere)
+
+## Gary Bernhardt (Boundaries) Checklist
+
+- [ ] I/O separated from business logic
+- [ ] Core logic is pure (no side effects)
+- [ ] Fast unit tests (no database/filesystem)
+- [ ] Value objects used for domain concepts
+- [ ] State passed as parameters, not stored in instance variables
+- [ ] Clear layer boundaries (presentation → application → domain → infrastructure)
+- [ ] File I/O abstracted (dependency injection)
+- [ ] Database access abstracted (repository pattern)
+- [ ] Functional core, imperative shell pattern
+- [ ] Immutable data structures preferred
+
+## General Ruby Idioms Checklist
+
+- [ ] frozen_string_literal: true in all files
+- [ ] Consistent method parentheses style
+- [ ] Keyword arguments for methods with > 2 params
+- [ ] Parameter objects for long parameter lists
+- [ ] Consistent hash access (symbols vs strings)
+- [ ] Specific exception rescues (not bare rescue)
+- [ ] ENV access centralized
+- [ ] Boolean traps eliminated (use explicit values)
+- [ ] Ruby 3 features used where appropriate
+- [ ] Standard Ruby linter passing

data/.claude/skills/setup-memory/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: setup-memory
+description: Automatically install, configure, or upgrade ClaudeMemory
+---
+
+# ClaudeMemory Setup & Upgrade
+
+This skill automatically sets up or upgrades ClaudeMemory based on your current state.
+
+## What This Skill Does
+
+When invoked, it will:
+
+1. **Check current installation status**
+   - Detect installed gem version
+   - Check database existence and health
+   - Verify configuration files
+
+2. **Determine required action**
+   - Fresh install (no databases)
+   - Upgrade (version mismatch)
+   - Verification (already up to date)
+
+3. **Execute setup/upgrade automatically**
+   - Run `claude-memory doctor` for health check
+   - Add version markers to `.claude/CLAUDE.md`
+   - Run smoke tests
+   - Report results
+
+4. **Provide next steps**
+   - Restart recommendations if needed
+   - Usage guidance
+
+## Instructions
+
+**IMPORTANT**: This skill should take action, not just provide instructions.
+
+### Step 1: Check Installation Status
+
+```bash
+claude-memory --version
+claude-memory doctor
+```
+
+Analyze the output to determine current state.
+
+### Step 2: Determine Action Required
+
+- **Not installed**: Databases don't exist
+  - Action: Run `claude-memory init` (ask user for --global flag preference)
+- **Installed but outdated**: Version marker missing or old
+  - Action: Run upgrade steps (doctor, add version marker, verify)
+- **Up to date**: All healthy
+  - Action: Report status only
+
+### Step 3: Execute Required Actions
+
+**For Fresh Install:**
+1. Ask user: "Install globally only or with project memory? [project/global]"
+2. Run `claude-memory init` (with --global if selected)
+3. Run `claude-memory doctor` to verify
+4. Add version marker to `.claude/CLAUDE.md`
+5. Report success
+
+**For Upgrade:**
+1. Run `claude-memory doctor` (auto-runs migrations)
+2. Add/update version marker in `.claude/CLAUDE.md`
+3. Run `claude-memory stats` for smoke test
+4. Report upgrade complete
+
+**For Verification:**
+1. Run `claude-memory doctor`
+2. Confirm version in `.claude/CLAUDE.md`
+3. Report all healthy
+
+### Step 4: Report Results
+
+Provide a clear summary:
+- ✅ What was done
+- 📊 Current status (facts, schema version, etc.)
+- 🔄 Next steps (if any)
+
+## After Setup/Upgrade
+
+Always remind the user:
+
+1. **Restart Claude Code** if configuration files were modified
+2. **Test memory tools**: Try `memory.status` or `memory.recall "<topic>"`
+3. **Use memory-first workflow**: Check memory before reading files
+
+## What Gets Created
+
+### Databases
+- `~/.claude/memory.sqlite3` - Global knowledge (preferences, conventions)
+- `.claude/memory.sqlite3` - Project-specific facts and decisions
+
+### Configuration Files
+- `.claude/CLAUDE.md` - Workflow instructions for memory-first usage
+- `.claude/settings.json` - Hooks for automatic ingestion
+- `.claude.json` - MCP server configuration
+- `.claude/rules/claude_memory.generated.md` - Published snapshot
+
+### Hooks
+ClaudeMemory automatically ingests transcripts on these events:
+- SessionStart - Catch up on previous session
+- Stop - After each response
+- SessionEnd - Final ingestion before closing
+- PreCompact - Before context summarization
+
+## Common Scenarios
+
+### Fresh Install
+User has never installed ClaudeMemory:
+1. Ask installation preference (project vs global)
+2. Run `claude-memory init` with appropriate flags
+3. Verify with `doctor`
+4. Add version marker
+5. Report success and next steps
+
+### Upgrade After Gem Update
+User updated gem but not configuration:
+1. Run `claude-memory doctor` (auto-migrates schema)
+2. Update version marker in `.claude/CLAUDE.md`
+3. Verify with smoke tests
+4. Report upgrade complete
+
+### Verification
+User wants to check current status:
+1. Run `claude-memory doctor`
+2. Run `claude-memory stats`
+3. Check version marker in `.claude/CLAUDE.md`
+4. Report all findings
+
+## Troubleshooting Guide
+
+If automatic setup fails, provide these solutions:
+
+**Permission Denied**
+```bash
+chmod +x $(which claude-memory)
+```
+
+**Database Locked**
+- Close other Claude sessions
+- Run `claude-memory recover`
+
+**Missing Ruby**
+ClaudeMemory requires Ruby 3.2.0+. Check with:
+```bash
+ruby --version
+```
+
+**Hooks Not Working**
+Re-run setup:
+```bash
+claude-memory init
+```
+
+## Memory-First Workflow
+
+After successful setup, always remind users:
+
+1. **Query memory first**: `memory.recall "<topic>"`
+2. **Use semantic shortcuts**: `memory.decisions`, `memory.conventions`, `memory.architecture`
+3. **Check before exploring**: Memory saves time vs reading files
+4. **Combine knowledge**: Merge recalled facts with code exploration
+
+This workflow leverages distilled knowledge from previous sessions.