thedotmack/claude-mem v5.2.0

v5.2.0 - Major Worker Service Refactor & UI Improvements

on GitHub

v5.2.0 (2025-11-07)

This release delivers a comprehensive architectural refactor of the worker service, extensive UI enhancements, and significant code cleanup. Merges PR #69.

Breaking Changes: None (backward compatible)

🏗️ Architecture Changes (Worker Service v2)

Modular Rewrite

Extracted monolithic worker-service.ts into focused, single-responsibility modules:

• DatabaseManager.ts (111 lines): Centralized database initialization and access
• SessionManager.ts (204 lines): Complete session lifecycle management
• SDKAgent.ts (309 lines): Claude SDK interactions & observation compression
• SSEBroadcaster.ts (86 lines): Server-Sent Events broadcast management
• PaginationHelper.ts (196 lines): Reusable pagination logic for all data types
• SettingsManager.ts (68 lines): Viewer settings persistence
• worker-types.ts (176 lines): Shared TypeScript types

Key Improvements

• ✅ Eliminated duplicated session logic (4 instances → 1 helper)
• ✅ Replaced magic numbers with named constants (HEALTH_CHECK_TIMEOUT_MS, etc.)
• ✅ Removed fragile PM2 string parsing → Direct PM2 restart
• ✅ Fail-fast error handling instead of silent failures
• ✅ Fixed SDK agent bug: Changed from obs.title to obs.narrative

🎨 UI/UX Improvements

New Features

ScrollToTop Component (src/ui/viewer/components/ScrollToTop.tsx)

• GPU-accelerated smooth scrolling
• Appears after scrolling 400px
• Accessible with ARIA labels

Enhancements

ObservationCard Refactoring

• Fixed facts toggle logic
• Improved metadata display (timestamps, tokens, model)
• Enhanced narrative display with proper typography
• Better empty states

Pagination Improvements

• Better loading state management
• Improved error recovery on failed fetches
• Automatic deduplication
• Scroll preservation

Card Consistency

• Unified layout patterns across Observation/Prompt/Summary cards
• Consistent spacing and alignment

📚 Documentation

New Files (7,542 lines total):

• context/agent-sdk-ref.md (1,797 lines): Complete Agent SDK reference
• docs/worker-service-architecture.md (1,174 lines): v2 architecture documentation
• docs/worker-service-rewrite-outline.md (1,069 lines): Refactor planning document
• docs/worker-service-overhead.md (959 lines): Performance analysis
• docs/processing-indicator-audit.md + processing-indicator-code-reference.md (980 lines): Processing status documentation
• docs/typescript-errors.md (180 lines): TypeScript error reference
• PLAN-full-observation-display.md (468 lines): Future UI enhancement roadmap
• src-analysis.md + src-tree.md (418 lines): Source code organization

🧹 Code Cleanup

Deleted Dead Code (~2,000 lines)

Shared Modules:

• src/shared/config.ts (48 lines)
• src/shared/storage.ts (188 lines)
• src/shared/types.ts (29 lines)

Utils:

• src/utils/platform.ts (64 lines)
• src/utils/usage-logger.ts (61 lines)

Index Files:

• src/hooks/index.ts
• src/sdk/index.ts

Documentation:

• docs/VIEWER.md (405 lines)
• docs/worker-server-architecture.md (1,129 lines)

🐛 Bug Fixes

1. SDK Agent Narrative Assignment (commit e22edad)

   • Fixed: Changed from obs.title to obs.narrative
   • Impact: Observations now correctly preserve narrative content

2. PostToolUse Hook Field Name (commit 13643a5)

   • Fixed: Corrected field reference in hook output
   • Impact: Tool usage properly captured

3. Smart Install Flow (commit 6204fe9)

   • Removed: Unnecessary startWorker() function
   • Simplified: Installation flow now relies on context-hook to start worker
   • Rationale: PM2 start is idempotent, no pre-flight checks needed

4. Context Hook Worker Management (commit 6204fe9)

   • Removed: Redundant worker status checks
   • Simplified: Direct health check + restart if unhealthy
   • Performance: Faster session startup

📊 Statistics

Files Changed: 70 total

• 11 new files
• 7 deleted files
• 52 modified files

Net Impact: +7,470 lines

• 11,105 additions
• 3,635 deletions

✅ Testing

All systems verified:

• ✓ Worker service starts successfully
• ✓ All hooks function correctly (context, save, cleanup, summary)
• ✓ Viewer UI renders properly with all improvements
• ✓ Build pipeline compiles without errors
• ✓ SSE broadcasts work for real-time updates
• ✓ Pagination loads correctly

🔄 Migration Guide

No action required - this release is fully backward compatible.

All changes are internal refactoring. Public APIs remain unchanged:

• Hook interfaces unchanged
• MCP search tools unchanged
• Database schema unchanged
• Environment variables unchanged

To activate:

1. Pull latest: git pull
2. Rebuild: npm run build
3. Sync to marketplace: npm run sync-marketplace
4. Restart worker: npm run worker:restart
5. Start new Claude Code session

📖 Related

• PR: #69
• Previous Version: 5.1.4
• Semantic Version: MINOR (backward compatible features & improvements)

🤖 Generated with Claude Code