claude_memory 0.2.0 → 0.3.0

data/.claude/skills/study-repo/focus-examples.md

@@ -0,0 +1,327 @@
+# Focused Analysis Examples
+
+When using the `--focus` flag, narrow the analysis to specific aspects of the repository. This is especially useful for:
+- Very large repositories (>5000 files)
+- Time-constrained analysis
+- Specific adoption goals
+- Deep study of one component
+
+## How Focus Mode Works
+
+1. **Narrows file exploration** to relevant paths only
+2. **Focuses comparison** on the specific aspect
+3. **Targets recommendations** to the focused area
+4. **Reduces context usage** for faster analysis
+5. **Produces smaller** influence documents
+
+## Example Focus Topics
+
+### Testing Strategy
+
+```bash
+/study-repo /tmp/repo --focus="testing strategy"
+```
+
+**What to analyze**:
+- Test files and directory structure (spec/, test/)
+- Test framework choice (RSpec, Minitest, etc.)
+- CI configuration (.github/workflows/, .circleci/)
+- Test coverage tools and reporting
+- Mocking/stubbing patterns
+- Integration vs unit test balance
+- Test factories and fixtures
+- Performance test practices
+
+**Output focus**:
+- How they organize tests
+- What patterns they use for test data
+- How they achieve high coverage
+- CI/CD testing pipeline design
+
+---
+
+### MCP Integration
+
+```bash
+/study-repo /tmp/repo --focus="MCP server implementation"
+```
+
+**What to analyze**:
+- MCP server files (mcp/, server/)
+- Tool definitions and schemas
+- Request/response handling
+- Error handling approach
+- Tool composition and organization
+- JSON-RPC implementation
+- Streaming support
+- Authentication/security
+
+**Output focus**:
+- How tools are structured
+- Best practices for tool design
+- Error handling patterns
+- Performance optimizations
+
+---
+
+### Database Schema
+
+```bash
+/study-repo /tmp/repo --focus="database design"
+```
+
+**What to analyze**:
+- Schema files (db/schema.rb, migrations/)
+- Index strategies
+- Query optimization patterns
+- Transaction management
+- Connection pooling
+- Database abstraction layer
+- Migration practices
+- Backup/restore approaches
+
+**Output focus**:
+- Schema design decisions
+- Performance optimizations
+- Migration safety patterns
+- Query efficiency techniques
+
+---
+
+### CLI Architecture
+
+```bash
+/study-repo /tmp/repo --focus="CLI design"
+```
+
+**What to analyze**:
+- Entry points (bin/, exe/)
+- Command organization (commands/, lib/commands/)
+- Argument parsing (Thor, OptionParser, etc.)
+- Help text and documentation
+- Error messages and exit codes
+- Subcommand structure
+- Configuration file handling
+- Output formatting
+
+**Output focus**:
+- Command organization patterns
+- User experience considerations
+- Error handling best practices
+- Testing CLI commands
+
+---
+
+### Performance Optimizations
+
+```bash
+/study-repo /tmp/repo --focus="performance"
+```
+
+**What to analyze**:
+- Caching strategies (Redis, in-memory)
+- Batch processing patterns
+- Query optimization
+- Resource management
+- Profiling and metrics
+- Lazy loading techniques
+- Memory efficiency
+- Concurrency patterns
+
+**Output focus**:
+- What they optimize and how
+- Benchmarking approaches
+- Trade-offs made
+- Performance monitoring
+
+---
+
+### Error Handling
+
+```bash
+/study-repo /tmp/repo --focus="error handling"
+```
+
+**What to analyze**:
+- Exception hierarchy
+- Error class organization
+- Recovery strategies
+- User-facing error messages
+- Logging practices
+- Retry logic
+- Graceful degradation
+- Error reporting/telemetry
+
+**Output focus**:
+- Exception design patterns
+- Error communication to users
+- Debugging support
+- Resilience patterns
+
+---
+
+### Configuration Management
+
+```bash
+/study-repo /tmp/repo --focus="configuration"
+```
+
+**What to analyze**:
+- Config file formats (YAML, JSON, TOML)
+- Environment variable handling
+- Default value strategies
+- Configuration validation
+- Secret management
+- Multi-environment support
+- Configuration discovery
+- Override precedence
+
+**Output focus**:
+- Configuration architecture
+- Validation and defaults
+- Security practices
+- User experience
+
+---
+
+### Domain Modeling
+
+```bash
+/study-repo /tmp/repo --focus="domain model"
+```
+
+**What to analyze**:
+- Core domain objects
+- Value objects vs entities
+- Aggregate boundaries
+- Repository pattern usage
+- Domain events
+- Business logic organization
+- Validation rules
+- Domain services
+
+**Output focus**:
+- How domain is modeled
+- Separation of concerns
+- Business rule implementation
+- Pattern usage
+
+---
+
+### Dependency Injection
+
+```bash
+/study-repo /tmp/repo --focus="dependency injection"
+```
+
+**What to analyze**:
+- DI container (if any)
+- Constructor injection patterns
+- Service locator usage
+- Factory patterns
+- Testability approaches
+- Configuration of dependencies
+- Lifecycle management
+- Interface abstractions
+
+**Output focus**:
+- DI strategy and patterns
+- Testing benefits
+- Complexity vs benefits
+- Best practices
+
+---
+
+### API Design
+
+```bash
+/study-repo /tmp/repo --focus="API design"
+```
+
+**What to analyze**:
+- REST/GraphQL/RPC patterns
+- Endpoint organization
+- Request/response formats
+- Versioning strategy
+- Authentication/authorization
+- Rate limiting
+- Documentation (OpenAPI, etc.)
+- Client SDK design
+
+**Output focus**:
+- API structure and conventions
+- Versioning approach
+- Documentation practices
+- Client experience
+
+---
+
+## Custom Focus Topics
+
+You can specify any aspect you want to focus on:
+
+```bash
+/study-repo /tmp/repo --focus="logging and observability"
+/study-repo /tmp/repo --focus="file system abstraction"
+/study-repo /tmp/repo --focus="plugin architecture"
+/study-repo /tmp/repo --focus="webhook handling"
+```
+
+The skill will adapt the analysis to your specified topic.
+
+## When to Use Focus Mode
+
+### Use Focus When:
+- Repository has >1000 files
+- You have a specific adoption goal
+- You want deep analysis of one aspect
+- Time is limited
+- You're comparing specific features
+
+### Use Full Analysis When:
+- Repository is small (<500 files)
+- You want comprehensive overview
+- Architecture understanding is the goal
+- Time allows for thorough exploration
+- Making major adoption decisions
+
+## Output Differences
+
+### Full Analysis Output:
+```
+docs/influence/project-name.md
+- All sections populated
+- Broad recommendations
+- Comprehensive comparison
+- 10-20 pages typical
+```
+
+### Focused Analysis Output:
+```
+docs/influence/project-name-focus.md
+- Focused sections only
+- Targeted recommendations
+- Specific comparison
+- 3-8 pages typical
+```
+
+## Combining Focuses
+
+For very large projects, run multiple focused analyses:
+
+```bash
+# Study different aspects separately
+/study-repo /tmp/big-repo --focus="MCP implementation"
+/study-repo /tmp/big-repo --focus="testing strategy"
+/study-repo /tmp/big-repo --focus="database design"
+```
+
+Each produces a separate influence document focused on that aspect.
+
+## Tips for Effective Focus
+
+1. **Be specific**: "MCP server" is better than "server stuff"
+2. **Match their terminology**: Use terms from their docs/code
+3. **Start broad, then focus**: Run full analysis first to identify interesting areas
+4. **Combine with grep**: Search for keywords related to your focus
+5. **Review examples**: Look at their tests for the focused component

data/CHANGELOG.md

@@ -4,6 +4,139 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+### Changed
+
+### Fixed
+
+### Documentation
+
+### Internal
+
+## [0.3.0] - 2026-01-29
+
+### Added
+
+**Setup & Initialization**
+- Version markers in CLAUDE.md files for upgrade detection
+  - HTML comment format: `<!-- ClaudeMemory vX.Y.Z -->`
+  - Enables version comparison and upgrade workflows
+- `memory.check_setup` MCP tool for initialization detection
+  - Returns status: healthy, needs_upgrade, partially_initialized, not_initialized
+  - Checks databases, CLAUDE.md, version, and hooks configuration
+  - Provides actionable recommendations
+- `/setup-memory` skill for installation guidance
+  - Comprehensive troubleshooting documentation
+  - Step-by-step setup instructions
+  - Links to diagnostic tools
+
+**Database & Infrastructure**
+- Schema version 6 with new tables:
+  - `operation_progress` - Track long-running operation state (index generation, migrations)
+  - `schema_health` - Record schema validation results and migration history
+- WAL (Write-Ahead Logging) mode for better concurrency and crash recovery
+- Incremental sync with `source_mtime` tracking to avoid re-processing unchanged files
+- Atomic migrations with per-migration transactions for safety
+- Configuration class for centralized ENV access and testability
+
+**Search & Recall**
+- `index` command to generate TF-IDF embeddings for semantic search
+- Index command resumability with checkpoints (recover from interruption)
+- Semantic search capabilities using TF-IDF embeddings
+- Improved full-text search with empty query handling
+
+**Session Intelligence**
+- Session metadata extraction:
+  - Git branch tracking (`git_branch`)
+  - Working directory context (`cwd`)
+  - Claude version tracking (`claude_version`)
+  - Tool usage patterns (`tool_calls`)
+- Session-aware fact extraction for better provenance
+
+**Developer Tools**
+- Enhanced `doctor` command with:
+  - Schema validation and integrity checks
+  - Migration history verification
+  - Recovery suggestions for corrupted databases
+- `stats` command for database statistics
+- Recovery command for stuck long-running operations
+- Transaction wrapper for ingestion atomicity
+
+**Quality Improvements**
+- Quality review workflow with Ruby expert perspectives:
+  - `/review-for-quality` skill for comprehensive codebase review
+  - Expert analysis from Sandi Metz, Jeremy Evans, Kent Beck, Avdi Grimm, Gary Bernhardt
+  - Automated quality documentation generation
+- Infrastructure abstractions (FileSystem, InMemoryFileSystem) for testability
+- Domain model enhancements with immutable, self-validating objects
+
+**Repository Analysis**
+- `/study-repo` skill for deep analysis of external repositories
+  - Systematic exploration through 6 phases (context, architecture, patterns, quality, comparison, adoption)
+  - Generates comprehensive influence documents in `docs/influence/`
+  - Updates `docs/improvements.md` with prioritized recommendations
+  - Focus mode support for targeted analysis (testing, MCP, database, CLI, performance)
+  - Integration with `/improve` workflow
+
+**Error Handling**
+- Graceful error messages when databases are missing or not accessible
+- Structured error responses with recommendations
+- Directs users to `memory.check_setup` for diagnosis
+
+### Changed
+- **IMPORTANT**: Switched from sqlite3 to extralite as required dependency
+  - Extralite provides better concurrency and performance
+  - Fixes database lock contention between MCP server and hooks
+  - Extralite (~> 2.14) is now the only SQLite adapter
+- Ingestion now tracks file modification time to skip unchanged content
+- Migration process now uses per-migration transactions for atomicity
+- Doctor command now includes schema validation and recovery guidance
+- Index operations can resume from checkpoints after interruption
+- MCP tool descriptions now emphasize memory-first workflow
+- Tool descriptions are more directive ("Check FIRST", "Use BEFORE")
+- Init command now adds version markers to generated CLAUDE.md files
+
+### Fixed
+- **Critical**: Database lock contention between MCP server and hooks
+  - Switched to extralite adapter for better concurrent access
+  - Improved busy timeout handling
+- Database busy error handling for both SQLite adapters
+- Concurrent access test for extralite adapter
+- Public keyword placement in SQLiteStore (Ruby style conformance)
+- Transaction safety for multi-step database operations
+
+### Documentation
+- Complete getting started guide (GETTING_STARTED.md)
+- Enhanced plugin documentation with setup workflows
+- Comprehensive examples for all features
+- Architecture documentation updates
+- Updated all documentation to reflect current codebase metrics
+  - 20 commands (was documented as 16)
+  - 18 MCP tools (was documented as 7-8)
+  - 985 test examples (was documented as 583/426)
+- Auto-initialization and upgrade design document (docs/auto_init_design.md)
+- Multi-phase upgrade strategy documentation
+
+### Internal
+- Consolidated ENV access via Configuration class
+- Registered new infrastructure modules in main loader
+- Improved test coverage for new features
+- Major code quality improvements with component extraction:
+  - `Core::FactQueryBuilder` - Query construction logic from Recall
+  - `Core::SetupStatusAnalyzer` - Setup status analysis from MCP Tools
+  - `MCP::ToolDefinitions` - Tool definitions separated from server logic
+  - `MCP::ResponseFormatter` - Response formatting with multiple query types
+  - `Core::TextBuilder` - Text building utilities
+  - `Core::ResultSorter` - Result sorting logic
+  - `Core::EmbeddingCandidateBuilder` - Embedding candidate construction
+  - `Core::FactCollector` - Fact collection logic
+  - `Core::ResultBuilder` - Result building logic
+- Init command test suite (19 examples)
+- Setup detection test suite (25 examples)
+- Error handling test suite (4 examples)
+- Comprehensive test coverage (53 new tests)
+
 ## [0.2.0] - 2026-01-22
 
 ### Added

data/CLAUDE.md

@@ -9,7 +9,7 @@ ClaudeMemory is a Ruby gem that provides long-term, self-managed memory for Clau
 **Key dependencies:**
 - Ruby 3.2.0+
 - Sequel (~> 5.0) for database access
-- SQLite3 (~> 2.0) for storage
+- Extralite (~> 2.14) for high-performance SQLite storage
 
 ## Development Commands
 
@@ -85,7 +85,7 @@ Transcripts → Ingest → Index (FTS5)
   - Each command is a separate class (HelpCommand, DoctorCommand, etc.)
   - All commands inherit from BaseCommand
   - Dependency injection for I/O (stdout, stderr, stdin)
-  - 16 commands total, each focused on single responsibility
+  - 20 commands total, each focused on single responsibility
 
 - **`Configuration`**: Centralized ENV access (`configuration.rb`)
   - Single source of truth for paths and environment variables
@@ -236,7 +236,7 @@ Single-value predicates (like "uses_database") supersede old values. Multi-value
 
 - `lib/claude_memory.rb`: Main module, requires, database path helpers
 - `lib/claude_memory/cli.rb`: Thin command router (41 lines)
-- `lib/claude_memory/commands/`: Individual command classes (16 commands)
+- `lib/claude_memory/commands/`: Individual command classes (20 commands)
 - `lib/claude_memory/configuration.rb`: Centralized configuration and ENV access
 - `lib/claude_memory/domain/`: Domain models (Fact, Entity, Provenance, Conflict)
 - `lib/claude_memory/core/`: Value objects and null objects
@@ -251,14 +251,15 @@ Single-value predicates (like "uses_database") supersede old values. Multi-value
 
 The gem includes an MCP server (`claude-memory serve-mcp`) that exposes memory operations as tools. Configuration should be in `.mcp.json` at project root.
 
-Available MCP tools:
-- `memory.recall` - Search for relevant facts (scope filtering supported)
-- `memory.explain` - Get detailed fact provenance
-- `memory.promote` - Promote project fact to global
-- `memory.status` - Health check for both databases
-- `memory.changes` - Recent fact updates
-- `memory.conflicts` - Open contradictions
-- `memory.sweep_now` - Run maintenance
+Available MCP tools (18 total):
+- **Query & Recall**: `memory.recall`, `memory.recall_index`, `memory.recall_details`, `memory.recall_semantic`, `memory.search_concepts`
+- **Provenance**: `memory.explain`
+- **Shortcuts**: `memory.decisions`, `memory.conventions`, `memory.architecture`
+- **Context**: `memory.facts_by_tool`, `memory.facts_by_context`
+- **Management**: `memory.promote`, `memory.store_extraction`
+- **Monitoring**: `memory.status`, `memory.stats`, `memory.changes`, `memory.conflicts`
+- **Maintenance**: `memory.sweep_now`
+- **Setup**: `memory.check_setup`
 
 ## Hook Integration
 
@@ -285,3 +286,121 @@ Key conventions:
 - Prefer explicit returns only when control flow is complex
 - Use Sequel's dataset methods (avoid raw SQL where possible)
 - Keep CLI commands focused; extract complex logic to dedicated classes
+
+## Custom Commands
+
+### `/review-for-quality`
+
+Runs a comprehensive quality review of the entire codebase.
+
+**What it does:**
+1. Launches a Plan agent to thoroughly explore the codebase
+2. Critically reviews code for Ruby best-practices, idiom use, and overall quality
+3. Analyzes through the perspectives of 5 Ruby experts:
+   - **Sandi Metz** - POODR principles, single responsibility, small objects
+   - **Jeremy Evans** - Sequel best practices, performance, simplicity
+   - **Kent Beck** - Test-driven development, simple design, revealing intent
+   - **Avdi Grimm** - Confident Ruby, explicit code, null objects, tell-don't-ask
+   - **Gary Bernhardt** - Boundaries, functional core/imperative shell, fast tests
+4. Updates `docs/quality_review.md` with findings including:
+   - Specific file:line references for every issue
+   - Which expert's principle is violated
+   - Concrete improvement suggestions with code examples
+   - Priority levels (Critical 🔴 / High / Medium 🟡 / Low)
+   - Metrics comparison showing progress since last review
+   - Quick wins that can be done immediately
+
+**Usage:**
+```
+/review-for-quality
+```
+
+**Output:** Updated `docs/quality_review.md` with dated review and actionable refactoring recommendations.
+
+### `/review-commit`
+
+Quick quality review of staged changes for pre-commit validation through expert perspectives.
+
+**What it does:**
+1. Reviews only staged Ruby files (fast, < 30 seconds)
+2. Applies Ruby best practices from 5 experts:
+   - **Sandi Metz**: SRP, small methods (<15 lines), DRY, frozen_string_literal
+   - **Jeremy Evans**: Sequel datasets over raw SQL, transaction safety, no N+1 queries
+   - **Kent Beck**: Simple design, revealing names, Command-Query Separation
+   - **Avdi Grimm**: Null objects, explicit returns, Law of Demeter, tell-don't-ask
+   - **Gary Bernhardt**: Functional core/imperative shell, immutable values, fast tests
+3. Returns clear BLOCK / WARNING / PASS verdict with expert attributions
+4. Designed for headless mode (runs in git pre-commit hook)
+
+**Critical checks (BLOCK):**
+- Missing frozen_string_literal, methods >15 lines, classes >200 lines
+- Raw SQL, DB writes without transactions, N+1 queries
+- Nested conditionals >3 levels, Command-Query violations
+- Implicit nil returns, defensive nil checks, bare rescue
+- I/O mixed with logic, mutable value objects, I/O in tests
+- New public methods without tests
+
+**Warning checks:**
+- Methods 10-15 lines, classes 100-200 lines, >3 parameters
+- Poor naming, methods doing multiple things
+- Law of Demeter violations, ask-don't-tell patterns
+- Missing value objects, business logic in imperative shell
+
+**Usage:**
+```
+/review-commit
+```
+
+**Output:** Console output with file:line references, expert attributions, and concrete fixes.
+
+**Hook Integration:** Automatically runs via lefthook pre-commit hook when Ruby files are staged.
+
+### `/study-repo`
+
+Deep analysis of an external repository's architecture, patterns, and design decisions.
+
+**What it does:**
+1. Requires user to manually clone the target repository first
+2. Performs systematic exploration through 6 phases:
+   - Repository Context (metadata, dependencies, purpose)
+   - Architecture Mapping (structure, modules, components)
+   - Pattern Recognition (design patterns, conventions)
+   - Code Quality Assessment (testing, docs, performance)
+   - Comparative Analysis (vs ClaudeMemory's approach)
+   - Adoption Opportunities (prioritized recommendations)
+3. Creates comprehensive influence document in `docs/influence/<project>.md`
+4. Updates `docs/improvements.md` with high-priority recommendations
+5. Follows QMD analysis format with priority markers
+
+**Usage:**
+```bash
+# Step 1: Clone repository to study
+git clone --depth 1 https://github.com/user/project /tmp/study-repos/project
+
+# Step 2: Run analysis
+/study-repo /tmp/study-repos/project
+
+# Optional: Focus on specific aspect
+/study-repo /tmp/study-repos/project --focus="MCP implementation"
+
+# Step 3: Review generated documents
+# - docs/influence/project.md (detailed analysis)
+# - docs/improvements.md (updated with recommendations)
+
+# Step 4: Implement selected improvements
+/improve
+```
+
+**Output:**
+- `docs/influence/<project_name>.md` - Comprehensive analysis with code examples
+- `docs/improvements.md` - Updated with dated section of recommendations
+- Console summary of key findings and priorities
+
+**Integration with `/improve`:**
+The recommendations added to `docs/improvements.md` can be implemented using the `/improve` skill, creating a complete workflow:
+```
+/study-repo → adds recommendations → /improve → implements features
+```
+
+**Focus Mode:**
+Use `--focus` to narrow analysis to specific aspects (testing, MCP, database, CLI, performance). See `.claude/skills/study-repo/focus-examples.md` for examples.