claude-mem 3.3.7 → 3.3.9

package/docs/todos/implementation-todos.md

@@ -0,0 +1,280 @@
+# Claude-Mem Cloud Service Implementation TODOs
+
+## Phase 1: Infrastructure Setup (Week 1-2)
+
+### Database Setup
+- [ ] Create PostgreSQL instance on Coolify
+- [ ] Run database migration scripts
+- [ ] Create organizations table
+- [ ] Create subscriptions table
+- [ ] Create users table
+- [ ] Create api_keys table
+- [ ] Create api_usage table
+- [ ] Create api_usage_daily table
+- [ ] Create audit_logs table
+- [ ] Set up database backups to S3
+
+### ChromaDB Deployment
+- [ ] Create docker-compose.yml for ChromaDB
+- [ ] Configure persistent volume storage
+- [ ] Set up ChromaDB authentication
+- [ ] Test collection creation/deletion
+- [ ] Configure backup strategy
+- [ ] Set up monitoring endpoints
+
+### Redis Setup
+- [ ] Deploy Redis container on Coolify
+- [ ] Configure Redis persistence
+- [ ] Set up Redis password
+- [ ] Test connection from Node.js
+- [ ] Configure key expiration policies
+
+### Core API Server
+- [ ] Initialize Node.js/TypeScript project
+- [ ] Set up Express.js framework
+- [ ] Configure environment variables
+- [ ] Set up logging with Winston
+- [ ] Create health check endpoints
+- [ ] Configure CORS settings
+- [ ] Set up error handling middleware
+
+## Phase 2: Authentication System (Week 3)
+
+### API Key Service
+- [ ] Implement ApiKeyService class
+- [ ] Create key generation function (sk_live_ prefix)
+- [ ] Implement bcrypt hashing for keys
+- [ ] Create key validation method
+- [ ] Add key rotation functionality
+
+### Database Operations
+- [ ] Create ApiKeyRepository class
+- [ ] Implement createApiKey method
+- [ ] Implement validateAndGetContext method
+- [ ] Implement revokeApiKey method
+- [ ] Add getKeysByOrganization method
+- [ ] Create usage tracking queries
+
+### Authentication Middleware
+- [ ] Create AuthMiddleware class
+- [ ] Implement Bearer token extraction
+- [ ] Add Redis caching layer (5min TTL)
+- [ ] Implement rate limiting checks
+- [ ] Add request context injection
+- [ ] Create auth error responses
+
+### Usage Tracking
+- [ ] Create UsageTracker class
+- [ ] Implement async request logging
+- [ ] Add Redis counter updates
+- [ ] Create daily aggregation job
+- [ ] Implement getUsageStats method
+- [ ] Build usage analytics queries
+
+## Phase 3: Billing Integration (Week 4)
+
+### Stripe Setup
+- [ ] Create Stripe account
+- [ ] Get API keys (test & live)
+- [ ] Create subscription products ($9.95)
+- [ ] Set up webhook endpoint
+- [ ] Configure customer portal
+
+### Subscription Management
+- [ ] Create SubscriptionService class
+- [ ] Implement createSubscription method
+- [ ] Add updateSubscription method
+- [ ] Create cancelSubscription method
+- [ ] Implement reactivation flow
+- [ ] Add proration calculations
+
+### Webhook Handlers
+- [ ] Set up webhook verification
+- [ ] Handle customer.subscription.created
+- [ ] Handle customer.subscription.updated
+- [ ] Handle customer.subscription.deleted
+- [ ] Handle invoice.payment_succeeded
+- [ ] Handle invoice.payment_failed
+- [ ] Implement idempotency checks
+- [ ] Add webhook event logging
+
+### Payment Recovery
+- [ ] Configure smart retry rules
+- [ ] Set up dunning emails
+- [ ] Create grace period logic
+- [ ] Implement reactivation flow
+- [ ] Add payment method update flow
+
+## Phase 4: Synchronization Engine (Week 5-6)
+
+### WebSocket Server
+- [ ] Set up Socket.IO server
+- [ ] Implement connection authentication
+- [ ] Create room management (by org)
+- [ ] Add connection pooling
+- [ ] Implement heartbeat/reconnection
+- [ ] Add connection analytics
+
+### Sync Protocol
+- [ ] Define message types
+- [ ] Implement vector clock logic
+- [ ] Create document change events
+- [ ] Add batch sync operations
+- [ ] Implement incremental sync
+- [ ] Create sync status tracking
+
+### Conflict Resolution
+- [ ] Implement vector clock comparison
+- [ ] Add semantic similarity calculation
+- [ ] Create auto-merge logic (>90%)
+- [ ] Build manual resolution queue
+- [ ] Implement CRDT for metadata
+- [ ] Add conflict notification system
+
+### Offline Support
+- [ ] Create Write-Ahead Log schema
+- [ ] Implement WAL operations
+- [ ] Add offline detection
+- [ ] Create replay mechanism
+- [ ] Implement sync queue
+- [ ] Add retry with backoff
+
+### ChromaDB Integration
+- [ ] Create IsolatedChromaClient class
+- [ ] Implement collection prefixing
+- [ ] Add query methods
+- [ ] Create upsert operations
+- [ ] Implement delete operations
+- [ ] Add collection management
+
+## Phase 5: Web Dashboard (Week 7)
+
+### Frontend Setup
+- [ ] Create Next.js application
+- [ ] Set up Tailwind CSS
+- [ ] Configure authentication
+- [ ] Create routing structure
+- [ ] Add state management (Zustand)
+
+### Authentication Pages
+- [ ] Create signup page
+- [ ] Build login page
+- [ ] Add password reset flow
+- [ ] Implement email verification
+- [ ] Create OAuth integration (GitHub)
+
+### Dashboard Pages
+- [ ] Build main dashboard
+- [ ] Create API keys page
+- [ ] Add usage analytics view
+- [ ] Build billing management
+- [ ] Create team management (future)
+- [ ] Add documentation section
+
+### API Key Management
+- [ ] Display active keys (masked)
+- [ ] Add key creation modal
+- [ ] Implement key revocation
+- [ ] Show key usage stats
+- [ ] Add key naming/description
+- [ ] Create copy-to-clipboard
+
+### Billing Interface
+- [ ] Show current plan
+- [ ] Display usage metrics
+- [ ] Add upgrade/downgrade flow
+- [ ] Create payment method update
+- [ ] Show invoice history
+- [ ] Add download receipts
+
+## Phase 6: Testing & Launch (Week 8)
+
+### Testing Infrastructure
+- [ ] Set up Jest for unit tests
+- [ ] Configure integration tests
+- [ ] Create E2E test suite
+- [ ] Add load testing (K6)
+- [ ] Set up CI/CD pipeline
+
+### Security Audit
+- [ ] Review authentication flow
+- [ ] Audit API permissions
+- [ ] Check SQL injection prevention
+- [ ] Verify XSS protection
+- [ ] Test rate limiting
+- [ ] Review encryption implementation
+
+### Documentation
+- [ ] Write API documentation
+- [ ] Create integration guide
+- [ ] Build troubleshooting guide
+- [ ] Add code examples
+- [ ] Create video tutorials
+- [ ] Write migration guide
+
+### Monitoring Setup
+- [ ] Deploy Prometheus
+- [ ] Configure Grafana dashboards
+- [ ] Set up alerting rules
+- [ ] Create PagerDuty integration
+- [ ] Add application metrics
+- [ ] Configure log aggregation
+
+### Beta Launch
+- [ ] Create landing page
+- [ ] Set up waitlist system
+- [ ] Prepare onboarding emails
+- [ ] Create feedback collection
+- [ ] Launch to 50 beta users
+- [ ] Monitor system stability
+
+### Production Launch
+- [ ] Finalize pricing page
+- [ ] Complete legal documents
+- [ ] Set up customer support
+- [ ] Prepare launch announcement
+- [ ] Create Product Hunt submission
+- [ ] Launch marketing campaign
+
+## Ongoing Operations
+
+### Daily Tasks
+- [ ] Monitor system health
+- [ ] Review error logs
+- [ ] Check payment failures
+- [ ] Respond to support tickets
+
+### Weekly Tasks
+- [ ] Review usage analytics
+- [ ] Analyze churn metrics
+- [ ] Update documentation
+- [ ] Deploy bug fixes
+
+### Monthly Tasks
+- [ ] Review infrastructure costs
+- [ ] Analyze customer feedback
+- [ ] Plan feature updates
+- [ ] Update security patches
+
+## Future Enhancements
+
+### Team Plan Features
+- [ ] Multi-user management
+- [ ] Role-based access control
+- [ ] Shared collections
+- [ ] Team usage analytics
+- [ ] Centralized billing
+
+### Advanced Features
+- [ ] Custom embeddings
+- [ ] Data export API
+- [ ] Webhook integrations
+- [ ] Advanced analytics
+- [ ] White-label options
+
+### Scale Optimizations
+- [ ] Implement sharding
+- [ ] Add read replicas
+- [ ] Create CDN integration
+- [ ] Optimize vector search
+- [ ] Add caching layers

package/docs/todos/restructure-hook-output-tasks.md

@@ -0,0 +1,103 @@
+# Todo: Restructure Session Hook Output Implementation
+
+## Priority 1: Core Data Loading
+
+- [ ] Update `loadContext()` in `/src/commands/load-context.ts`
+  - Increase default count to fetch more entries
+  - Separate overview extraction from memory extraction
+  - Return structured object with both overviews and memories
+
+- [ ] Modify `extractOverview()` to `extractOverviews()` 
+  - Accept count parameter (default 3)
+  - Return array of overview objects with timestamps
+  - Preserve content and metadata fields
+
+## Priority 2: Time Utilities
+
+- [ ] Create `/src/lib/time-utils.ts`
+  - Implement `formatRelativeTime(timestamp: string): string`
+  - Handle various time ranges (minutes, hours, days, weeks)
+  - Return human-readable strings ("2 hours ago", "Yesterday", etc.)
+
+- [ ] Add timestamp parsing to overview objects
+  - Extract timestamp from JSONL entry
+  - Convert to Date object for calculations
+  - Handle missing/invalid timestamps gracefully
+
+## Priority 3: Template Updates
+
+- [ ] Create new Handlebars template `SESSION_START_LAYERED_TEMPLATE`
+  - User-visible section with 3 overviews and time-ago
+  - Clean formatting without granular details
+  - Professional header and separators
+
+- [ ] Add HTML comment wrapper template
+  - Wrap granular memories in `<!-- CONTEXT-DATA ... -->`
+  - Preserve all memory details and keywords
+  - Ensure proper escaping of content
+
+## Priority 4: Rendering Logic
+
+- [ ] Update `renderSessionStartTemplate()` function
+  - Process overviews array with time formatting
+  - Generate HTML comment block for memories
+  - Combine both layers into single output
+
+- [ ] Test output formatting
+  - Verify HTML comments are properly hidden
+  - Confirm Claude can access both layers
+  - Check time-ago displays correctly
+
+## Priority 5: Integration & Testing
+
+- [ ] Update `sessionStartHook()` orchestration
+  - Pass new parameters to loadContext
+  - Handle dual-layer output properly
+  - Maintain error handling
+
+- [ ] Test with various scenarios
+  - Fresh project (no memories)
+  - Project with 1-2 overviews only
+  - Project with 3+ overviews
+  - Mixed timestamps (recent and old)
+
+## Priority 6: Edge Cases
+
+- [ ] Handle missing timestamps
+  - Default to "Recent" or similar label
+  - Don't break on invalid dates
+  - Log warnings for debugging
+
+- [ ] Handle special characters in content
+  - Escape HTML comment delimiters
+  - Prevent comment injection
+  - Preserve original formatting
+
+## Priority 7: Documentation
+
+- [ ] Update code comments
+  - Document dual-layer approach
+  - Explain HTML comment purpose
+  - Add examples of output format
+
+- [ ] Update README if needed
+  - Note new output format
+  - Explain visibility layers
+  - Add configuration options if any
+
+## Implementation Order
+1. Start with time-utils.ts creation
+2. Modify data extraction functions  
+3. Update templates
+4. Integrate rendering logic
+5. Test end-to-end
+6. Handle edge cases
+7. Document changes
+
+## Testing Checklist
+- [ ] User sees only 3 overviews
+- [ ] Time-ago formatting works correctly
+- [ ] Granular memories in HTML comments
+- [ ] Claude can access full context
+- [ ] No console errors or warnings
+- [ ] Backward compatibility maintained

package/docs/todos/session-start-hook-fix.md

@@ -0,0 +1,26 @@
+# Session Start Hook Fix - Todo List
+
+## Investigation Phase
+
+- [ ] Examine session-start.js implementation
+- [ ] Check Weaviate entity naming patterns
+- [ ] Verify compression process project name extraction
+- [ ] Query Weaviate for claude-mem-source entities
+
+## Diagnosis Phase
+
+- [ ] Identify why entities aren't being retrieved
+- [ ] Confirm correct project name usage
+- [ ] Validate search query construction
+
+## Implementation Phase
+
+- [ ] Fix entity naming or search logic as needed
+- [ ] Update session-start hook if required
+- [ ] Test context retrieval with new session
+
+## Validation Phase
+
+- [ ] Verify latest updates appear in session context
+- [ ] Confirm consistent behavior across restarts
+- [ ] Document any changes to entity naming convention

package/docs/todos/terminal-effects-tasks.md

@@ -0,0 +1,42 @@
+# Terminal Effects Implementation Tasks
+
+## Prerequisites Enhancement
+- [ ] Enhance `validatePrerequisites()` spinner messages with specific checks being performed
+- [ ] Add visual separators between prerequisite check results  
+- [ ] Improve error message formatting for failed prerequisites
+
+## Installation Flow Progress
+- [ ] Add step indicators to the main `p.group()` operation (Step 1/6, Step 2/6, etc.)
+- [ ] Enhance individual spinner messages with more context:
+  - [ ] "Creating directory structure" → "Creating ~/.claude-mem directories..."
+  - [ ] "Installing Chroma MCP server" → "Setting up persistent memory backend..."
+  - [ ] "Installing hooks" → "Configuring Claude Code integration..."
+  - [ ] "Configuring settings" → "Updating Claude configuration..."
+
+## Error Display Improvements  
+- [ ] Create consistent error message formatting throughout
+- [ ] Add visual hierarchy for error vs warning vs info messages
+- [ ] Improve error context in `installChromaMcp()` function
+- [ ] Enhance cancellation messages with better formatting
+
+## Verification & Results
+- [ ] Improve `verifyInstallation()` feedback with detailed results list
+- [ ] Add visual checkmarks/indicators for successful installation steps  
+- [ ] Format final success message with better visual hierarchy
+- [ ] Enhance backup notification messages
+
+## Status Message Polish
+- [ ] Review all spinner messages for consistency and clarity
+- [ ] Add contextual information to longer-running operations
+- [ ] Improve Claude path detection feedback messages
+- [ ] Polish Smart Trash and save-on-clear configuration messages
+
+## Code Quality
+- [ ] Ensure consistent use of @clack/prompts patterns throughout
+- [ ] Verify all existing functionality remains unchanged
+- [ ] Test installation flow with enhanced messages
+- [ ] Document any new message patterns for consistency
+
+---
+
+*Target: Enhanced visual feedback without functional changes*