v5.1.1

v5.1.1 (2025-11-06)

Breaking Changes: None (patch version)

Bugfix:

• Fixed PM2 ENOENT error on Windows by using full path to PM2 binary
• Improved cross-platform compatibility for PM2 process management

Technical Details:

• Modified files:
  • scripts/smart-install.js (improved PM2 binary path resolution)
  • package-lock.json (dependency updates)
• The fix ensures PM2 commands work correctly on Windows systems by using the full path to the PM2 binary instead of relying on PATH resolution
• This resolves the "ENOENT: no such file or directory" error that Windows users encountered when the plugin tried to start the worker service

Installation:
Users on Windows will now have a smoother installation experience with automatic PM2 worker startup working correctly.

v5.1.0 - Web-Based Viewer UI

v5.1.0 (2025-11-05)

🎉 Major Feature: Web-Based Viewer UI

This release introduces a production-ready web interface for visualizing your memory stream in real-time!

Access the viewer: http://localhost:37777 (auto-starts with the worker)

✨ Key Features

Real-Time Visualization

• Server-Sent Events (SSE) for instant updates as observations are captured
• See user prompts, observations, and session summaries as they happen
• No polling - efficient push-based updates

Infinite Scroll & Pagination

• Load more content seamlessly as you scroll
• Automatic deduplication prevents duplicates
• Smooth loading states with skeleton components

Project Filtering

• Filter memory stream by project/codebase
• Quick project switcher in sidebar
• View stats for all projects or focus on one

Persistent Settings

• Sidebar state (open/closed) saved to localStorage
• Selected project filter persists across sessions
• Smooth GPU-accelerated animations

Auto-Reconnection

• Exponential backoff retry logic
• Graceful handling of worker restarts
• Connection status indicator

🔧 Technical Improvements

New Worker Endpoints (+500 lines)

• /api/prompts - Paginated user prompts with project filtering
• /api/observations - Paginated observations with project filtering
• /api/summaries - Paginated session summaries with project filtering
• /api/stats - Database statistics (total counts by project)
• /api/projects - List of unique project names
• /stream - Server-Sent Events for real-time updates
• / - Serves viewer HTML
• /health - Health check endpoint

Database Enhancements (+98 lines in SessionStore)

• getRecentPrompts() - Paginated prompts with OFFSET/LIMIT
• getRecentObservations() - Paginated observations with OFFSET/LIMIT
• getRecentSummaries() - Paginated summaries with OFFSET/LIMIT
• getStats() - Aggregated statistics by project
• getUniqueProjects() - Distinct project names

Complete React UI (17 new files, 1,500+ lines)

• Components: Header, Sidebar, Feed, Cards (Observation, Prompt, Summary, Skeleton)
• Hooks: useSSE, usePagination, useSettings, useStats
• Utils: Data merging, formatters, constants
• Assets: Monaspace Radon font, logos (dark mode + logomark)
• Build: esbuild pipeline for self-contained HTML bundle

📚 Documentation

Updated CLAUDE.md with:

• Viewer UI architecture and components
• Build process for viewer changes
• Configuration and usage instructions
• Design rationale for SSE and self-contained bundle approach

🎨 Design Highlights

• Monaspace Radon variable font for beautiful monospace rendering
• Claude branding with official logos and dark mode support
• Responsive layout with collapsible sidebar
• Smooth animations using GPU acceleration (transform/opacity)
• Error boundaries for graceful failure handling

🚀 Getting Started

1. Update claude-mem to v5.1.0
2. Start a Claude Code session (worker auto-starts)
3. Open http://localhost:37777 in your browser
4. Watch your memory stream in real-time!

📦 Files Changed

New Files:

• src/ui/viewer/ - Complete React application (17 files)
• src/ui/viewer-template.html - HTML template for bundle
• scripts/build-viewer.js - esbuild configuration
• plugin/ui/viewer.html - Built self-contained bundle
• plugin/ui/viewer-bundle.js - Compiled React code
• plugin/ui/assets/fonts/ - Monaspace Radon font files
• src/ui/*.webp - Claude logos and branding

Modified Files:

• src/services/worker-service.ts - Added 8 new HTTP/SSE endpoints
• src/services/sqlite/SessionStore.ts - Added pagination methods
• scripts/build-hooks.js - Integrated viewer build process
• CLAUDE.md - Comprehensive documentation update

🙏 Acknowledgments

Built with:

• React 19 + TypeScript
• esbuild for ultra-fast bundling
• Monaspace Radon font by GitHub Next
• Server-Sent Events for real-time updates

---

Breaking Changes: None (backward compatible MINOR version)

Full Changelog: v5.0.3...v5.1.0

v5.0.3

v5.0.3 (2025-11-05)

Breaking Changes: None (patch version)

Fixes:

• Fixed Windows installation with smart caching installer (PR #54: scripts/smart-install.js)
• Eliminated redundant npm install executions on every SessionStart (improved from 2-5s to ~10ms)
• Added comprehensive Windows troubleshooting with VS Build Tools guidance
• Fixed dynamic Python version detection in Windows error messages (scripts/smart-install.js:106-115)

Improvements:

• Smart install now caches version state in .install-version file
• Only runs npm install when needed: first time, version change, or missing dependencies
• Enhanced rsync to respect gitignore rules in sync-marketplace (package.json:38)
• Better PM2 worker startup verification and management
• Cross-platform compatible installer (pure Node.js, no shell dependencies)

Technical Details:

• New: scripts/smart-install.js (smart caching installer with PM2 worker management)
• Modified: plugin/hooks/hooks.json:25 (use smart-install.js instead of raw npm install)
• Modified: .gitignore (added .install-version cache file)
• Modified: CLAUDE.md (added Windows requirements and troubleshooting section)
• Modified: package.json:38 (enhanced sync-marketplace with --filter=':- .gitignore' --exclude=.git)
• Root cause: npm install was running on every SessionStart regardless of whether dependencies changed
• Impact: 200x faster SessionStart for cached installations (10ms vs 2-5s)

For Windows Users:
This release should completely resolve installation issues. The smart installer will:

1. Show you clear error messages if better-sqlite3 fails to install
2. Guide you to install VS Build Tools if needed (though you probably won't need them)
3. Only run once on first launch, then be instant on subsequent launches

v5.0.2

v5.0.2 (2025-11-04)

Breaking Changes: None (patch version)

Fixes:

• Fixed worker startup reliability with async health checks (PR #51: src/shared/worker-utils.ts)
• Added proper error handling to PM2 process spawning (src/shared/worker-utils.ts)
• Worker now verifies health before proceeding with hook operations
• Improved handling of PM2 failures when not yet installed

Technical Details:

• Modified: src/shared/worker-utils.ts (added isWorkerHealthy, waitForWorkerHealth functions)
• Modified: src/hooks/*.ts (all hooks now await ensureWorkerRunning)
• Modified: plugin/scripts/*.js (rebuilt hook executables)
• Root cause: ensureWorkerRunning was synchronous and didn't verify worker was actually responsive before proceeding
• Impact: More reliable worker startup with proper health verification

Installation

Install via Claude Code marketplace:

/plugin marketplace add https://raw.githubusercontent.com/thedotmack/claude-mem/main/.claude-plugin/marketplace.json
/plugin install claude-mem

Full Changelog

View all changes

v5.0.1

v5.0.1 (2025-11-04)

Breaking Changes: None (patch version)

Fixes:

• Fixed worker service stability issues (PR #47: src/services/worker-service.ts, src/shared/worker-utils.ts)
• Improved worker process management and restart reliability (src/hooks/*-hook.ts)
• Enhanced session management and logging across all hooks
• Removed error/output file redirection from PM2 ecosystem config for better debugging (ecosystem.config.cjs)

Improvements:

• Added GitHub Actions workflows for automated code review (PR #48)
  • Claude Code Review workflow (.github/workflows/claude-code-review.yml)
  • Claude PR Assistant workflow (.github/workflows/claude.yml)
• Better worker health checks and startup sequence
• Improved error handling and logging throughout hook lifecycle
• Cleaned up documentation files and consolidated project context

Technical Details:

• Modified: src/services/worker-service.ts (stability improvements)
• Modified: src/shared/worker-utils.ts (consistent formatting and readability)
• Modified: ecosystem.config.cjs (removed error/output redirection)
• Modified: src/hooks/*-hook.ts (ensure worker running before processing)
• New: .github/workflows/claude-code-review.yml
• New: .github/workflows/claude.yml
• Rebuilt: plugin/scripts/*.js (all hook executables)
• Impact: More reliable worker service with better error visibility and automated PR assistance

---

Installation: See README for installation instructions.

v5.0.0 - Hybrid Search Architecture

v5.0.0 (2025-11-03)

BREAKING CHANGES

• Python dependency for optimal performance: While the plugin works without Python, installing Python 3.8+ and the Chroma MCP server unlocks semantic search capabilities. Without Python, the system falls back to SQLite FTS5 keyword search.
• Search behavior changes: Search queries now prioritize semantic relevance when Chroma is available, then apply temporal ordering. Keyword-only queries may return different results than v4.x.
• Worker service changes: Worker now initializes ChromaSync on startup. If Chroma MCP is unavailable, worker continues with FTS5-only mode but logs a warning.

Added

• Hybrid Search Architecture: Combines ChromaDB semantic search with SQLite temporal/metadata filtering
  • Chroma vector database for semantic similarity (top 100 matches)
  • 90-day temporal recency window for relevant results
  • SQLite hydration in chronological order
  • Graceful fallback to FTS5 when Chroma unavailable
• ChromaSync Service: Automatic vector database synchronization
  • Syncs observations, session summaries, and user prompts to Chroma
  • Splits large text fields into multiple vectors for better granularity
  • Maintains metadata for filtering (project, type, concepts, files)
  • Background sync process via worker service
• get_timeline_by_query Tool: Natural language timeline search with dual modes
  • Auto mode: Automatically uses top search result as timeline anchor
  • Interactive mode: Shows top N results for manual anchor selection
  • Combines semantic search discovery with timeline context retrieval
• User Prompt Semantic Search: Raw user prompts now indexed in Chroma for semantic discovery
• Enhanced MCP Tools: All 8 existing search tools now support hybrid search
  • search_observations - Now uses semantic + temporal hybrid algorithm
  • search_sessions - Semantic search across session summaries
  • search_user_prompts - Semantic search across raw prompts
  • find_by_concept, find_by_file, find_by_type - Enhanced with semantic capabilities
  • get_recent_context - Unchanged (temporal only)
  • get_context_timeline - Unchanged (anchor-based temporal)

Changed

• Search Server: Expanded from ~500 to ~1,500 lines with hybrid search implementation
• Worker Service: Now initializes ChromaSync and handles Chroma MCP lifecycle
• Search Pipeline: Now follows semantic-first strategy with temporal ordering

  Query → Chroma Semantic Search (top 100) → 90-day Filter → SQLite Hydration (temporal order) → Results
  

• Worker Resilience: Worker no longer crashes when Chroma MCP unavailable; gracefully falls back to FTS5

Fixed

• Critical temporal filtering bug: Fixed deduplication and date range filtering in search results
• User prompt formatting bug: Corrected field reference in search result formatting
• Worker crash prevention: Worker now handles missing Chroma MCP gracefully instead of crashing

Technical Details

• New files:
  • src/services/sync/ChromaSync.ts (738 lines) - Vector database sync service
  • experiment/chroma-search-test.ts - Comprehensive hybrid search testing
  • experiment/chroma-sync-experiment.ts - Vector sync validation
  • docs/chroma-search-completion-plan.md - Implementation planning
  • FEATURE_PLAN_HYBRID_SEARCH.md - Feature specification
  • IMPLEMENTATION_STATUS.md - Testing and validation results
• Modified files:
  • src/servers/search-server.ts (+995 lines) - Hybrid search algorithm implementation
  • src/services/worker-service.ts (+136 lines) - ChromaSync integration
  • src/services/sqlite/SessionStore.ts (+276 lines) - Enhanced timeline queries
  • src/hooks/context-hook.ts - Type legend improvements
• Validation: 1,390 observations synced to 8,279 vector documents
• Performance: Semantic search with 90-day window returns results in <200ms

v4.3.4

v4.3.4 (2025-11-01)

Breaking Changes: None (patch version)

Fixes:

• Fixed SessionStart hooks running on session resume (plugin/hooks/hooks.json:4)
• Added matcher configuration to only run SessionStart hooks on startup, clear, or compact events
• Prevents unnecessary hook execution and improves performance on session resume

Technical Details:

• Modified: plugin/hooks/hooks.json:4 (added "matcher": "startup|clear|compact")
• Impact: Hooks now skip execution when resuming existing sessions

v4.3.3

v4.3.3 (2025-10-27)

Breaking Changes: None (patch version)

Improvements:

• Made session display count configurable via constant (DISPLAY_SESSION_COUNT = 8) in src/hooks/context-hook.ts:11
• Added first-time setup detection with helpful user messaging in src/hooks/user-message-hook.ts:12-39
• Improved user experience: First install message clarifies why it appears under "Plugin Hook Error"

Fixes:

• Cleaned up profanity in code comments (src/hooks/context-hook.ts:3)
• Fixed first-time setup UX by detecting missing node_modules and showing informative message

Technical Details:

• Modified: src/hooks/context-hook.ts:11 (configurable DISPLAY_SESSION_COUNT constant)
• Modified: src/hooks/user-message-hook.ts:12-39 (first-time setup detection and messaging)
• Modified: plugin/scripts/context-hook.js (rebuilt)
• Modified: plugin/scripts/user-message-hook.js (rebuilt)

v4.3.2

v4.3.2 (2025-10-27)

Breaking Changes: None (patch version)

Improvements:

• Added user-message-hook for displaying context to users via stderr mechanism
• Enhanced context visibility: Hook fires simultaneously with context injection, sending duplicate message as "error" so Claude Code displays it to users
• Added comprehensive documentation (4 new MDX files covering architecture evolution, context engineering, hooks architecture, and progressive disclosure)
• Improved cross-platform path handling in context-hook

Technical Details:

• New files:
  • src/hooks/user-message-hook.ts (stderr-based user-facing context display)
  • plugin/scripts/user-message-hook.js (built hook executable)
  • docs/architecture-evolution.mdx (801 lines)
  • docs/context-engineering.mdx (222 lines)
  • docs/hooks-architecture.mdx (784 lines)
  • docs/progressive-disclosure.mdx (655 lines)
• Modified:
  • plugin/hooks/hooks.json (added user-message-hook configuration)
  • src/hooks/context-hook.ts (improved path handling)
  • scripts/build-hooks.js (build support for new hook)
• Design rationale: Error messages don't get added to context, so we intentionally duplicate context output via stderr for user visibility. This is a temporary workaround until Claude Code potentially adds ability to share messages with both user and context simultaneously.

v4.3.1 - SessionStart Hook Context Injection Fix

Fixes

• Fixed SessionStart hook context injection by silencing npm install output (plugin/hooks/hooks.json:25)
• Changed npm loglevel from --loglevel=error to --loglevel=silent to ensure clean JSON output
• Consolidated hooks architecture by removing bin/hooks wrapper layer (src/hooks/*-hook.ts)
• Fixed double shebang issues in hook executables (esbuild now adds shebang during build)

Technical Details

• Modified: plugin/hooks/hooks.json (npm install verbosity)
• Removed: src/bin/hooks/* (wrapper layer no longer needed)
• Consolidated: Hook logic moved directly into src/hooks/*-hook.ts files
• Root cause: npm install stderr/stdout was polluting hook JSON output, preventing context injection

Breaking Changes

None (patch version)

---

Full Changelog: v4.3.0...v4.3.1