@hivehub/rulebook 3.0.0 → 3.2.0

package/templates/modules/MEMORY.md

@@ -23,27 +23,90 @@ rulebook_memory_get({ ids: ["abc-123", "def-456"] })
 → Returns: Full memory objects with content (~500-1000 tokens each)
 ```
 
+### Memory Structure
+
+Each memory contains:
+- **id**: Unique identifier
+- **type**: Memory type (see below)
+- **title**: Short title (80 chars)
+- **summary**: Rich contextual summary with key concepts, decisions, patterns, gotchas (auto-extracted)
+- **content**: Full content
+- **tags**: Searchable tags for categorization
+- **createdAt/updatedAt/accessedAt**: Timestamps for LRU tracking
+
 ### Memory Types
 
-- **bugfix**: Bug fixes, error resolutions
-- **feature**: New features, additions
-- **refactor**: Code restructuring
-- **decision**: Architectural decisions (protected from eviction)
-- **discovery**: Insights and learnings
-- **change**: Updates and modifications
-- **observation**: General observations
+- **bugfix**: Bug fixes, error resolutions — save root cause and solution
+- **feature**: New features, additions — save design approach and patterns
+- **refactor**: Code restructuring — save architectural reasoning
+- **decision**: Architectural decisions (protected from eviction) — save why this choice
+- **discovery**: Insights and learnings — save patterns and gotchas
+- **change**: Updates and modifications — save impact and reasoning
+- **observation**: General observations — save insights worth preserving
+
+### What to Capture in Summaries
+
+Effective summaries include:
+1. **Problem/Context**: What was being solved
+2. **Approach**: How it was solved
+3. **Key Decision**: Why this approach
+4. **Pattern**: Reusable solution discovered
+5. **Gotcha**: Edge case or limitation found
+6. **Result**: Outcome or impact
+
+**Example Summary**:
+```
+"Implemented OAuth token refresh with 30-min expiry. Decision: Used interceptor middleware for transparent refresh (avoids scattered retry logic). Gotcha: Tokens expire silently - must check response headers before retrying. Pattern: Double-request pattern for simultaneous requests during refresh."
+```
 
 ### CLI Commands
 
 ```bash
-rulebook memory search "authentication bug"     # Hybrid search
-rulebook memory save "Decided to use sql.js" --type decision --title "DB Choice"
+# Search with hybrid BM25+Vector
+rulebook memory search "authentication bug"     # Returns top results with summaries
+rulebook memory search "oauth" --mode bm25      # BM25 keyword-only search
+rulebook memory search "token" --mode vector    # Vector semantic search
+rulebook memory search "api" --type feature     # Filter by memory type
+
+# Save memories (summary auto-extracted from content)
+rulebook memory save "Fixed OAuth token refresh..." --type feature --title "OAuth Implementation"
+rulebook memory save "Decided to use sql.js for zero-dependency..." --type decision --title "DB Choice" --tags architecture,database
+
+# Timeline and details
+rulebook memory timeline --memoryId abc-123     # See 5 before/after
+rulebook memory get abc-123 def-456             # Full details for specific memories
+
+# Management
 rulebook memory list --limit 10                  # Recent memories
-rulebook memory stats                            # Database statistics
-rulebook memory cleanup --force                  # Force eviction
+rulebook memory stats                            # Database statistics & health
+rulebook memory cleanup --force                  # Force cache eviction
 rulebook memory export --format json             # Export all memories
 ```
 
+### Best Practices for Rich Memories
+
+1. **Save immediately after learning**: Capture insights while fresh
+2. **Use memory types correctly**: Features vs decisions vs discoveries
+3. **Include context in content**: Don't just save code, save reasoning
+4. **Add relevant tags**: Enable discovery for related work
+5. **Reference past memories**: Include memory IDs when related
+
+**Workflow**:
+```bash
+# Before implementing: search for similar work
+rulebook memory search "your feature" --mode hybrid
+
+# During implementation: save discoveries
+rulebook memory save "Pattern discovered: use X instead of Y because Z" --type discovery --title "Pattern Name"
+
+# After implementation: save complete solution
+rulebook memory save "Full implementation details, gotchas, test cases..." --type feature --title "Feature Name" --tags relevant,tags
+
+# Next session: reference past work
+rulebook memory search "feature name" --type feature
+# → Displays summaries automatically, can drill down to full details
+```
+
 ### Configuration (.rulebook)
 
 ```json