Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

[7.0.11] - 2025-12-12

Patch release adding feature/bun-executable to experimental branch selector for testing Bun runtime integration.

[7.0.9] - 2025-12-10

Bug Fixes

Fixed MCP response format in search route handlers - all 14 search endpoints now return complete response objects with error status instead of just content arrays, restoring MCP protocol compatibility

Changes

SearchRoutes.ts: Updated all route handlers to return full result object instead of extracted content property

[7.0.8] - 2025-12-10

Bug Fixes

Critical: Filter out meta-observations for session-memory files to prevent recursive timeline pollution
- Memory agent was creating observations about editing Agent SDK's session-memory/summary.md files
- This created a recursive loop where investigating timeline pollution caused more pollution
- Filter now skips Edit/Write/Read/NotebookEdit operations on any file path containing 'session-memory'
- Eliminates 91+ meta-observations that were polluting the timeline

Technical Details

Added filtering logic in SessionRoutes.ts to detect and skip file operations on session-memory files before observations are queued to the SDK agent. This prevents the memory agent from observing its own observation metadata files.

[7.0.7] - 2025-12-10

What's Changed

Code Quality Improvements

Refactored hooks codebase to reduce complexity and improve maintainability (#204)
Net reduction of 78 lines while adding new functionality
Improved type safety across all hook input interfaces

New Features

Added CLAUDE_MEM_SKIP_TOOLS configuration setting for controlling which tools are excluded from observations
Default skip tools: ListMcpResourcesTool, SlashCommand, Skill, TodoWrite, AskUserQuestion

Technical Improvements

Created shared utilities: transcript-parser.ts, hook-constants.ts, hook-error-handler.ts
Migrated business logic from hooks to worker service for better separation of concerns
Enhanced error handling and spinner management
Removed dead code and unnecessary abstractions

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.0.6...v7.0.7

[7.0.6] - 2025-12-10

Bug Fixes

Fixed Windows terminal spawning to hide terminal windows when spawning child processes (#203, thanks @CrystallDEV)
Improved worker service process management on Windows

Contributors

Thanks to @CrystallDEV for this contribution!

[7.0.5] - 2025-12-09

What's Changed

Bug Fixes

Fixed settings schema inconsistency between write and read operations
Fixed PowerShell command injection vulnerability in worker-utils.ts
Enhanced PM2 existence check with clear error messages
Added error logging to silent tool serialization handlers

Improvements

Settings centralization: Migrated to SettingsDefaultsManager across codebase
Auto-creation of settings.json file with defaults on first run
Settings schema migration from nested to flat format
Refactored HTTP-only new-hook implementation
Cross-platform worker service improvements

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.0.4...v7.0.5

[7.0.4] - 2025-12-09

What's Changed

Bug Fixes

Windows: Comprehensive fixes for Windows plugin installation
Cache: Add package.json to plugin directory for cache dependency resolution

Thanks to @kat-bell for the excellent contributions!

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.0.3...v7.0.4

[7.0.3] - 2025-12-09

What's Changed

Refactoring:

Completed rename of search-server to mcp-server throughout codebase
Updated all documentation references from search-server to mcp-server
Updated debug log messages to use [mcp-server] prefix
Removed legacy search-server.cjs file

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.0.2...v7.0.3

[7.0.2] - 2025-12-09

What's Changed

Bug Fixes:

Improved auto-start worker functionality for better reliability

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.0.1...v7.0.2

[7.0.1] - 2025-12-09

Bug Fixes

Hook Execution: Ensure worker is running at the beginning of all hook files
Context Hook: Replace waitForPort with ensureWorkerRunning for better error handling
Reliability: Move ensureWorkerRunning to start of all hook functions to ensure worker is started before any logic executes

Technical Changes

context-hook.ts: Replace waitForPort logic with ensureWorkerRunning
summary-hook.ts: Move ensureWorkerRunning before input validation
new-hook.ts: Move ensureWorkerRunning before debug logging
save-hook.ts: Move ensureWorkerRunning before SKIP_TOOLS check
cleanup-hook.ts: Move ensureWorkerRunning before silentDebug calls

This ensures more reliable worker startup and clearer error messages when the worker fails to start.

[7.0.0] - 2025-12-08

Major Architectural Refactor

This major release represents a complete architectural transformation of claude-mem from a monolithic design to a clean, modular HTTP-based architecture.

Breaking Changes

None - Despite being a major version bump due to the scope of changes, this release maintains full backward compatibility. All existing functionality works exactly as before.

What Changed

Hooks → HTTP Clients

All 5 lifecycle hooks converted from direct database access to lightweight HTTP clients
Each hook reduced from 400-800 lines to ~75 lines
Hooks now make simple HTTP calls to the worker service
Eliminates SQL duplication across hooks - single source of truth in worker

Worker Service Modularization

worker-service.ts reduced from 1600+ lines to clean orchestration layer
New route-based HTTP architecture:
- SessionRoutes - Session lifecycle management
- DataRoutes - Database queries (observations, sessions, timeline)
- SearchRoutes - Full-text and semantic search
- SettingsRoutes - Configuration management
- ViewerRoutes - UI endpoints

New Service Layer

BaseRouteHandler - Centralized error handling, response formatting (used 46x)
SessionEventBroadcaster - Semantic SSE event broadcasting
SessionCompletionHandler - Consolidated session completion logic
SettingsDefaultsManager - Single source of truth for configuration defaults
PrivacyCheckValidator - Centralized privacy tag validation
FormattingService - Dual-format result rendering
TimelineService - Complex markdown timeline formatting
SearchManager - Extracted search logic from context generation

Database Improvements

Migrated from `bun:sqlite` to `better-sqlite3` for broader compatibility
SQL queries moved from route handlers to `SessionStore` for separation of concerns
`PaginationHelper` centralizes paginated queries with LIMIT+1 optimization

Testing Infrastructure

New comprehensive happy path tests for full session lifecycle
Integration tests covering session init, observation capture, search, summaries, cleanup
Test helpers and mocks for consistent testing patterns

Type Safety

Removed 'as any' casts throughout codebase
New `src/types/database.ts` with proper type definitions
Enhanced null safety in SearchManager

Stats

60 files changed
8,671 insertions, 5,585 deletions
Net: ~3,000 lines of new code (mostly tests and new modular services)

Migration Notes

No migration required! Update and continue using claude-mem as before.

[6.5.3] - 2025-12-05

Bug Fixes

Windows: Hide console window when spawning child processes (#166)
- Adds windowsHide: true to spawnSync and execSync calls
- Prevents empty terminal windows from appearing on Windows when hooks execute

Reference: https://nodejs.org/api/child_process.html (windowsHide option)

[6.5.2] - 2025-12-04

What's Changed

Upgraded better-sqlite3 from ^11.0.0 to ^12.5.0 for Node.js 25 compatibility

Fixes

Resolves compilation errors when installing on Node.js 25.x (#164)

[6.5.1] - 2025-12-04

What's New

Decorative Product Hunt announcement in terminal with rocket borders
Product Hunt badge in viewer header with theme-aware switching (light/dark)
Badge uses separate tracking URL for analytics

Changes

This is a temporary launch day update. The announcement will auto-expire at midnight EST.

[6.5.0] - 2025-12-04

Documentation Overhaul

This release brings comprehensive documentation updates to reflect all features added in v6.4.x and standardize version references across the codebase.

Changes

Updated "What's New" Sections:

Highlights v6.4.9 Context Configuration Settings (11 new settings)
Highlights v6.4.0 Dual-Tag Privacy System (<private> tags)
Highlights v6.3.0 Version Channel (beta toggle in UI)

Key Features Updated:

Added 🔒 Privacy Control (<private> tags)
Added ⚙️ Context Configuration settings

Clarifications:

Fixed lifecycle hook count: 5 lifecycle events with 6 hook scripts
Fixed default model: claude-haiku-4-5 (not sonnet)
Removed outdated MCP search server references (replaced by skills in v5.4.0)

Files Updated:

README.md - version badge, features, What's New, default model
docs/public/introduction.mdx - features, hook count, What's New
docs/public/installation.mdx - removed MCP reference
docs/public/configuration.mdx - default model corrections
plugin/skills/mem-search/operations/help.md - version references

📚 Full documentation available at docs.claude-mem.ai

[6.4.9] - 2025-12-02

New Features

This release adds comprehensive context configuration settings, giving users fine-grained control over how memory context is injected at session start.

Context Configuration (11 new settings)

Token Economics Display:

Control visibility of read tokens, work tokens, savings amount, and savings percentage

Observation Filtering:

Filter by observation types (bugfix, feature, refactor, discovery, decision, change)
Filter by observation concepts (how-it-works, why-it-exists, what-changed, problem-solution, gotcha, pattern, trade-off)

Display Configuration:

Configure number of full observations to include
Choose which field to show in full (narrative/facts)
Set number of recent sessions to include

Feature Toggles:

Control inclusion of last session summary
Control inclusion of final messages from prior session

All settings have sensible defaults and are fully backwards compatible.

What's Next

Settings UI enhancements coming very shortly in the next release! We're working on improving the settings interface for even better user experience.

Technical Details

10 files changed (+825, -212)
New centralized observation metadata constants
Enhanced context hook with SQL-based filtering
Worker service settings validation
Viewer UI controls for all settings

[6.4.1] - 2025-12-01

Hey there, claude-mem community! 👋

We're doing something new and exciting: our first-ever Live AMA!

🔴 When You'll See Us Live

December 1st-5th, 2025
Daily from 5-7pm EST

During these times, you'll see a live indicator (🔴) when you start a new session, letting you know we're available right now to answer questions, discuss ideas, or just chat about what you're building with claude-mem.

What Changed in This Release

We've added a smart announcement system that:

Shows upcoming AMA schedule before/after live hours
Displays a live indicator (🔴) when we're actively available
Automatically cleans up after the event ends

Why We're Doing This

We want to hear from you! Whether you're:

Just getting started with claude-mem
A power user with feature ideas
Curious about how memory compression works
Running into any issues
Or just want to say hi 👋

This is your chance to connect directly with the developer (@thedotmack) and fellow community members.

Join the Community

Can't make the live times? No worries! Join our Discord to stay connected:
https://discord.gg/J4wttp9vDu

We're excited to meet you and hear what you're building!

Technical Details

Changed Files:

src/hooks/user-message-hook.ts - Added time-aware announcement logic
Version bumped across all manifests (6.4.0 → 6.4.1)

Built Artifacts:

plugin/scripts/user-message-hook.js - Updated compiled hook

Looking forward to seeing you at the AMA! 🎉

[6.4.0] - 2025-12-01

🎯 Highlights

This release introduces a powerful dual-tag privacy system that gives you fine-grained control over what gets stored in your observation history, along with significant search API improvements.

✨ New Features

Dual-Tag Privacy System

<private> tags: User-level privacy control - wrap any sensitive content to prevent storage in observation history
<claude-mem-context> tags: System-level tags for auto-injected observations to prevent recursive storage
Tag stripping happens at the hook layer (edge processing) before data reaches worker/database
Comprehensive documentation in docs/public/usage/private-tags.mdx

User Experience

New inline help message in context hook highlighting the <private> tag feature
Improved Community link formatting in startup messages

🔧 Improvements

Search API

Simplified search endpoint parameters to eliminate bracket encoding issues (#154)
Cleaner API interface for mem-search skill

Performance

Added composite index for user prompts lookup optimization
Shared tag-stripping utilities in src/utils/tag-stripping.ts

📚 Documentation

Updated CLAUDE.md with Privacy Tags section
Enhanced private-tags.mdx with implementation details
Added comprehensive test coverage for tag stripping

🔗 Related PRs

#153: Dual-tag system for meta-observation control
#154: Eliminate bracket encoding in search API parameters

💡 Try it now: Wrap sensitive data with <private>your-secret-data</private> in any message to Claude Code!

[6.3.7] - 2025-12-01

Bug Fixes

fix: Remove orphaned closing brace in smart-install.js - Fixes SyntaxError "Missing catch or finally after try" that was preventing the plugin from loading correctly

What Changed

Fixed a syntax error in scripts/smart-install.js where an extra closing brace on line 392 caused the SessionStart hook to fail. The PM2 worker startup try/catch block was properly formed but had an orphaned closing brace that didn't match any opening brace.

This bug was introduced in a recent release and prevented the plugin from loading correctly for users.

[6.3.6] - 2025-11-30

Auto-detect and rebuild native modules on Node.js version changes

Bug Fixes

Native Module Compatibility: Auto-detects Node.js version changes and rebuilds better-sqlite3 when needed
Self-healing Recovery: Gracefully handles ERR_DLOPEN_FAILED errors with automatic reinstall on next session
Version Tracking: Enhanced .install-version marker now tracks both package and Node.js versions (JSON format)
Runtime Verification: Added verifyNativeModules() to catch ABI mismatches and corrupted builds

Technical Details

This release fixes a critical issue where upgrading Node.js (e.g., v22 → v25) would cause native module failures that the plugin couldn't auto-recover from. The smart-install script now:

Tracks Node.js version in addition to package version
Verifies native modules actually load (not just file existence)
Triggers rebuild when either version changes
Handles runtime failures gracefully with helpful user messaging

Contributors

@dreamiurg - Thank you for the comprehensive fix and thorough testing!

Merged PRs

#149 - feat: Auto-detect and rebuild native modules on Node.js version changes

[6.3.5] - 2025-11-30

Changes

✨ Restored Discord community button in viewer header
📱 Added responsive mobile navigation menu
🔄 Reorganized Sidebar component for better mobile UX
🐛 Fixed missing props being passed to Sidebar component

Technical Details

Community button visible in header on desktop (> 600px width)
Mobile menu icon appears on small screens (≤ 600px width)
Sidebar toggles via hamburger menu on mobile
Both buttons positioned in header for consistent UX

Full changelog: https://github.com/thedotmack/claude-mem/compare/v6.3.4...v6.3.5

[6.3.4] - 2025-11-30

Bug Fixes

Worker Startup Improvements

Fixed critical issues with worker service startup on fresh installations:

Auto-start worker after installation - The PM2 worker now starts automatically during plugin installation
Local PM2 resolution - Plugin now uses local PM2 from node_modules/.bin instead of requiring global installation
Improved error messages - Clear, actionable instructions with full paths when worker fails to start
Cross-platform support - Proper handling of Windows platform differences (pm2.cmd)
Security enhancement - Switched from execSync to spawnSync with array arguments to prevent command injection

These changes significantly improve the first-time installation experience, eliminating the need for manual PM2 setup.

Special thanks to @dreamiurg for identifying and fixing this critical UX issue! 🙏

[6.3.3] - 2025-11-30

Bug fixes and improvements to timeline context feature:

Added session ID validation to filterTimelineByDepth
Added timestamp fallback warning
Exported filterTimelineByDepth function for unit testing
Fixed type breakdown display in timeline item count

Full changes: https://github.com/thedotmack/claude-mem/compare/v6.3.2...v6.3.3

[6.3.2] - 2025-11-25

What's Changed

Improvements

Add search query support to /api/decisions endpoint - now supports semantic search within decisions using Chroma with { type: 'decision' } metadata filter

Usage

# Search within decisions (new)
curl "http://localhost:37777/api/decisions?query=architecture&format=full&limit=5"

# All decisions (existing behavior preserved)
curl "http://localhost:37777/api/decisions?format=index&limit=10"

[6.3.1] - 2025-11-25

What's New

Add script to help estimate token savings from on-the-fly replacements

[6.3.0] - 2025-11-25

What's New

Branch-Based Beta Toggle

Added Version Channel section to Settings sidebar allowing users to switch between stable and beta versions directly from the UI.

Features:

See current branch (main or beta/7.0) and stability status
Switch to beta branch to access Endless Mode features
Switch back to stable for production use
Pull updates for current branch

Implementation:

BranchManager.ts: Git operations for branch detection/switching
worker-service.ts: /api/branch/* endpoints (status, switch, update)
Sidebar.tsx: Version Channel UI with branch state and handlers

Installation

To update, restart Claude Code or run the plugin installer.

[6.2.1] - 2025-11-23

🐛 Bug Fixes

Critical: Empty Project Names Breaking Context Injection

Problem:

Observations and summaries created with empty project names
Context-hook couldn't find recent context (queries WHERE project = 'claude-mem')
Users saw no observations or summaries in SessionStart since Nov 22

Root Causes:

Sessions: createSDKSession() used INSERT OR IGNORE for idempotency, but never updated project field when session already existed
In-Memory Cache: SessionManager cached sessions with stale empty project values, even after database was updated

Fixes:

5d23c60 - fix: Update project name when session already exists in createSDKSession
54ef149 - fix: Refresh in-memory session project when updated in database

Impact:

✅ 364 observations backfilled with correct project names
✅ 13 summaries backfilled with correct project names
✅ Context injection now works (shows recent observations and summaries)
✅ Future sessions will always have correct project names

📦 Full Changelog

Commits since v6.2.0:

634033b - chore: Bump version to 6.2.1
54ef149 - fix: Refresh in-memory session project when updated in database
5d23c60 - fix: Update project name when session already exists in createSDKSession

[6.2.0] - 2025-11-22

Major Features

Unified Search API (#145, #133)

Vector-first search architecture: All text queries now use ChromaDB semantic search
Unified /api/search endpoint: Single endpoint with filter parameters (type, concepts, files)
ID-based fetch endpoints: New GET /api/observation/:id, /api/session/:id, /api/prompt/:id
90-day recency filter: Automatic relevance filtering for search results
Backward compatibility: Legacy endpoints still functional, routing through unified infrastructure

Search Architecture Cleanup

Removed FTS5 fallback code: Eliminated ~300 lines of deprecated full-text search code
Removed experimental contextualize endpoint: Will be reimplemented as LLM-powered skill (see #132)
Simplified mem-search skill: Streamlined to prescriptive 3-step workflow (Search → Review IDs → Fetch by ID)
Better error messages: Clear guidance when ChromaDB/UVX unavailable

Bug Fixes

Search Improvements

Fixed parameter handling in searchUserPrompts method
Improved dual-path logic for filter-only vs text queries
Corrected missing debug output in search API

Documentation

Updated CLAUDE.md to reflect vector-first architecture
Clarified FTS5 tables maintained for backward compatibility only (removal planned for v7.0.0)
Enhanced mem-search skill documentation with clearer usage patterns
Added comprehensive test results for search functionality

Breaking Changes

None - all changes maintain backward compatibility.

Installation

Users with auto-update enabled will receive this update automatically. To manually update:

```bash

Restart Claude Code or run:

npm run sync-marketplace ```

[6.1.1] - 2025-11-21

Bug Fixes

Dynamic Project Name Detection (#142)

Fixed hardcoded "claude-mem" project name in ChromaSync and search-server
Now uses getCurrentProjectName() to dynamically detect the project based on working directory
Resolves #140 where all observations were incorrectly tagged with "claude-mem"

Viewer UI Scrolling

Simplified overflow CSS to enable proper scrolling in viewer UI
Removed overcomplicated nested overflow containers
Fixed issue where feed content wouldn't scroll

Installation

Users with auto-update enabled will receive this patch automatically. To manually update:

```bash

Restart Claude Code or run:

npm run sync-marketplace ```

[6.1.0] - 2025-11-19

Viewer UI: Responsive Layout Improvements

The viewer UI now handles narrow screens better with responsive breakpoints:

Community button relocates to sidebar below 600px width
Projects dropdown relocates to sidebar below 480px width
Sidebar constrained to 400px max width

Makes the viewer usable on phones and narrow browser windows.

[6.0.9] - 2025-11-17

Queue Depth Indicator Feature

Added a real-time queue depth indicator to the viewer UI that displays the count of active work items (queued + currently processing).

Features

Visual badge next to claude-mem logo
Shows count of pending messages + active SDK generators
Only displays when queueDepth > 0
Subtle pulse animation for visual feedback
Theme-aware styling
Real-time updates via SSE

Implementation

Backend: Added getTotalActiveWork() method to SessionManager
Backend: Updated worker-service to broadcast queueDepth via SSE
Frontend: Enhanced Header component to display queue bubble
Frontend: Updated useSSE hook to track queueDepth state
Frontend: Added CSS styling with pulse animation

Closes

#122 - Implement queue depth indicator feature
#96 - Add real-time queue depth indicator to viewer UI
#97 - Fix inconsistent queue depth calculation

Credit

Original implementation by @thedotmack in PR #96 Bug fix by @copilot-swe-agent in PR #97

[6.0.8] - 2025-11-17

Critical Fix

This patch release fixes a critical bug where the PM2 worker process would start from the wrong directory (development folder instead of marketplace folder), causing the plugin to malfunction when installed via the marketplace.

What's Fixed

Worker Startup Path Resolution (src/shared/worker-utils.ts:61)
Added cwd: pluginRoot option to execSync when starting PM2

This ensures the worker always starts from the correct marketplace directory (~/.claude/plugins/marketplaces/thedotmack/), regardless of where the hook is invoked from.

Impact

Users will no longer experience issues with the worker starting from the wrong location. The plugin now works correctly when installed via marketplace without manual intervention.

Verification

Run pm2 info claude-mem-worker to verify:

exec cwd should be: /Users/[username]/.claude/plugins/marketplaces/thedotmack
script path should be: /Users/[username]/.claude/plugins/marketplaces/thedotmack/plugin/scripts/worker-service.cjs

[6.0.7] - 2025-11-17

Critical Hotfix: Database Migration Issue (#121)

This is an emergency hotfix addressing a critical database migration bug that prevented claude-mem from loading for some users.

What was fixed

Issue: Users were seeing SqliteError: no such column: discovery_tokens when starting Claude Code.

Root Cause: The ensureDiscoveryTokensColumn migration was using version number 7, which was already taken by another migration (removeSessionSummariesUniqueConstraint). This duplicate version number caused migration tracking issues in databases that were upgraded through multiple versions.

Fix:

Changed migration version from 7 to 11 (next available)
Added explicit schema_versions check to prevent unnecessary re-runs
Improved error propagation and documentation

Upgrade Instructions

If you're experiencing the error:

Option 1 - Manual fix (preserves history):

sqlite3 ~/.claude-mem/claude-mem.db "ALTER TABLE observations ADD COLUMN discovery_tokens INTEGER DEFAULT 0; ALTER TABLE session_summaries ADD COLUMN discovery_tokens INTEGER DEFAULT 0;"

Option 2 - Delete and recreate (loses history):

rm ~/.claude-mem/claude-mem.db
# Restart Claude Code - database will recreate with correct schema

Option 3 - Fresh install: Just upgrade to v6.0.7 and the migration will work correctly.

Changes

Fixed: Database migration version conflict (migration 7 → 11) (#121)
Improved: Migration error handling and schema_versions tracking

Full Changelog

See CHANGELOG.md for complete version history.

Affected Users: @liadtigloo @notmyself - this release fixes your reported issue. Please try one of the upgrade options above and let me know if the issue persists.

Thanks to everyone who reported this issue with detailed error logs! 🙏

[6.0.6] - 2025-11-17

Critical Bugfix Release

Fixed

Database Migration: Fixed critical bug where discovery_tokens migration logic trusted schema_versions table without verifying actual column existence (#121)
Migration now always checks if columns exist before queries, preventing "no such column" errors
Safe for all users - auto-migrates on next Claude Code session without data loss

Technical Details

Removed early return based on schema_versions check that could skip actual column verification
Migration now uses PRAGMA table_info() to verify column existence before every query
Ensures idempotent, safe schema migrations for SQLite databases

Impact

Users experiencing "SqliteError: no such column: discovery_tokens" will be automatically fixed
No manual intervention or database backup required
Update to v6.0.6 via marketplace or git pull and restart Claude Code

Affected Users: All users who upgraded to v6.0.5 and experienced the migration error

[6.0.5] - 2025-11-17

Changes

Automatic MCP Server Cleanup

Automatic cleanup of orphaned MCP server processes on worker startup
Self-healing maintenance runs on every worker restart
Prevents orphaned process accumulation and resource leaks

Improvements

Removed manual cleanup notice from session context
Streamlined worker initialization process

What's Fixed

Memory leaks from orphaned uvx/python processes are now prevented automatically
Workers self-heal on every restart without manual intervention

Release Date: November 16, 2025 Plugin Version: 6.0.5

[6.0.4] - 2025-11-17

Patch Release

Fixes memory leaks from orphaned uvx/python processes that could accumulate during ChromaDB operations.

Changes:

Fixed process cleanup in ChromaDB sync operations to prevent orphaned processes
Improved resource management for external process spawning

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v6.0.3...v6.0.4

[6.0.3] - 2025-11-16

What's Changed

Documentation alignment release - merged PR #116 fixing hybrid search architecture documentation.

Documentation Updates

Added comprehensive guide
Updated technical architecture documentation to reflect hybrid ChromaDB + SQLite + timeline context flow
Fixed skill operation guides to accurately describe semantic search capabilities

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v6.0.2...v6.0.3

[6.0.2] - 2025-11-14

Changes

Updated user message hook with Claude-Mem community discussion link for better user engagement and support

What's Changed

Enhanced startup context messaging with community connection information

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v6.0.1...v6.0.2

[6.0.1] - 2025-11-14

UI Enhancements

Changes

Refined color theme with warmer tones for better visual hierarchy
New observation card blue/teal theme with distinct light/dark mode values
Added 8 SVG icon assets for summary card sections (thick and thin variants)
Enhanced summary card component with icon support for completed, investigated, learned, and next-steps sections
Updated build system to handle icon asset copying

Visual Improvements

Unified color palette refinements across all UI components
Improved card type differentiation: gold/amber for summaries, purple for prompts, blue/teal for observations
Better visual consistency in viewer UI

Full changelog: https://github.com/thedotmack/claude-mem/compare/v6.0.0...v6.0.1

[6.0.0] - 2025-11-13

What's New

Major Enhancements

Session Management

Enhanced session initialization to accept userPrompt and promptNumber
Live userPrompt updates for multi-turn conversations
Improved SessionManager with better context handling

Transcript Processing

Added comprehensive transcript processing scripts for analysis
New transcript data structures and parsing utilities
Rich context extraction capabilities

Architecture Improvements

Refactored hooks and SDKAgent for improved observation handling
Added silent debug logging utilities
Better error handling and debugging capabilities

Documentation

Added implementation plan for ROI metrics feature
Added rich context examples and documentation
Multiple transcript processing examples

Files Changed

39 files changed, 4584 insertions(+), 2809 deletions(-)

Breaking Changes

This is a major version bump due to significant architectural changes in session management and observation handling. Existing sessions will continue to work, but the internal APIs have evolved.

📦 Install via Claude Code: ~/.claude/plugins/marketplaces/thedotmack/ 📖 Documentation: CLAUDE.md

[5.5.1] - 2025-11-11

Breaking Changes: None (patch version)

Improvements:

Enhanced summary hook to capture last user message from Claude Code session transcripts
Improved activity indicator that tracks both active sessions and queue depth
Better user feedback during prompt processing
More accurate processing status broadcasting

Technical Details:

Modified files:
- src/hooks/summary-hook.ts (added transcript parser for extracting last user message)
- src/services/worker-service.ts (enhanced processing status broadcasting)
- src/services/worker/SessionManager.ts (queue depth tracking for activity indicators)
- src/services/worker-types.ts (added last_user_message field to SDKSession)
- src/sdk/prompts.ts (updated summary prompt to include last user message context)
- src/services/worker/SDKAgent.ts (pass through last user message to SDK)
Built outputs updated:
- plugin/scripts/summary-hook.js
- plugin/scripts/worker-service.cjs

What Changed: The summary hook now reads Claude Code transcript files to extract the last user message before generating session summaries. This provides better context for AI-powered session summarization. The activity indicator now accurately reflects both active sessions and queued work, giving users better feedback about what's happening behind the scenes.

[5.5.0] - 2025-11-11

Breaking Changes: None (minor version)

Improvements:

Merged PR #91: Replace generic "search" skill with enhanced "mem-search" skill
Improved skill effectiveness from 67% to 100% (Anthropic standards)
Enhanced scope differentiation to prevent confusion with native conversation memory
Increased concrete triggers from 44% to 85%
Added 5+ unique identifiers and explicit exclusion patterns
Comprehensive documentation reorganization (17 total files)

Technical Changes:

New mem-search skill with system-specific naming
Explicit temporal keywords ("previous sessions", "weeks/months ago")
Technical anchors referencing FTS5 full-text index and typed observations
Documentation moved from /context/ to /docs/context/
Detailed technical architecture documentation added
12 operation guides + 2 principle directories

Credits:

Skill design and enhancement by @basher83

[5.4.5] - 2025-11-11

Patch Release: Bugfixes and minor improvements

[5.4.4] - 2025-11-10

Breaking Changes: None (patch version)

Bugfix:

Fixed duplicate observations and summaries appearing in viewer with different IDs and timestamps
Root cause: handleSessionInit spawned an SDK agent but didn't save the promise to session.generatorPromise, causing handleObservations to spawn a second agent for the same session

Technical Details:

Modified: src/services/worker-service.ts:265
Change: Now assigns session.generatorPromise = this.sdkAgent.startSession(...) to track the promise
Impact: Single SDK agent per session (previously two), eliminates duplicate database entries and SSE broadcasts
Pattern: Matches existing implementation in handleSummarize (line 332)
Guard: Leverages existing condition in handleObservations (line 301) that checks for existing promise

User Impact:

No more duplicate entries in the viewer UI
Cleaner, more accurate memory stream visualization
Reduced redundant processing and database writes

Merged via PR #86

[5.4.3] - 2025-11-10

Breaking Changes: None (patch version)

Bug Fixes:

Fixed PM2 race condition between watch mode and PostToolUse hook
Eliminated TypeError: Cannot read properties of undefined (reading 'pm2_env') errors
Reduced unnecessary worker restarts (39+ restarts → minimal)

Technical Details:

Removed PM2 restart logic from ensureWorkerRunning() in src/shared/worker-utils.ts
PM2 watch mode now exclusively handles worker restarts on file changes
Function now only checks worker health via HTTP endpoint and provides clear error messaging
Removed unused imports and helper functions (execSync, getPackageRoot, waitForWorkerHealth)

Files Modified:

src/shared/worker-utils.ts (40 deletions, 14 additions)
All built hooks and worker service (rebuilt from source)

Impact: This fix eliminates error spam in hook output while maintaining full functionality. Users will see cleaner output and fewer unnecessary restarts.

Upgrade Notes: No action required. PM2 watch mode will automatically restart the worker on plugin updates.

[5.4.2] - 2025-11-10

Bugfix Release: CWD spatial awareness for SDK agent

What's Fixed

CWD Context Propagation: SDK agent now receives current working directory (CWD) context from tool executions
Spatial Awareness: Prevents false "file not found" reports when working across multiple repositories
Observer Guidance: Agent prompts now include tool_cwd XML elements with spatial awareness instructions

Technical Details

Data Flow:

Hook extracts CWD from PostToolUseInput (hookInput.result.tool_cwd)
Worker service receives CWD in PendingMessage and ObservationData interfaces
SessionManager passes CWD to SDKAgent's addObservation method
SDK agent includes CWD in tool observation objects sent to Claude API
Prompts conditionally render tool_cwd XML with spatial awareness guidance

Implementation:

Optional CWD fields throughout for backward compatibility
Defaults to empty string when CWD is missing
CWD treated as read-only display context, not for file operations
Complete propagation chain from hook → worker → SDK → prompts

Test Coverage:

8 comprehensive tests validating CWD propagation
Tests cover hook extraction, worker forwarding, SDK inclusion, and prompt rendering
All tests pass with tsx TypeScript loader

Security:

Zero vulnerabilities introduced
CodeQL analysis: No alerts
Read-only context display (no file operation changes)
Input validation and sanitization maintained

Files Changed

Source Files:

src/hooks/save-hook.ts - Extract CWD from PostToolUseInput
src/services/worker-types.ts - Add optional CWD fields to interfaces
src/services/worker-service.ts - Forward CWD in message handling
src/services/worker/SessionManager.ts - Pass CWD to SDK agent
src/services/worker/SDKAgent.ts - Include CWD in tool observations
src/sdk/prompts.ts - Render tool_cwd XML with spatial guidance

Built Artifacts:

plugin/scripts/save-hook.js - Compiled hook with CWD extraction
plugin/scripts/worker-service.cjs - Compiled worker with CWD handling

Tests & Documentation:

tests/cwd-propagation.test.ts - Comprehensive test suite (8 tests)
context/CWD_CONTEXT_FIX.md - Technical implementation documentation
PR_SUMMARY.md - Pull request summary and rationale
SECURITY_SUMMARY.md - Security analysis and review
CHANGELOG.md - Version history entry

Installation

# Update to latest version
/plugin update claude-mem

Or restart Claude Code to auto-update.

Upgrade Notes

Backward Compatible: No breaking changes
No Action Required: CWD propagation works automatically
Existing Sessions: Will benefit from improved spatial awareness

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v5.4.1...v5.4.2

[5.4.1] - 2025-11-10

Breaking Changes: None (patch version)

New Features:

Added REST API endpoints for MCP server status and toggle control
Implemented UI toggle in viewer sidebar for enabling/disabling MCP search server
File-based persistence mechanism (.mcp.json ↔ .mcp.json.disabled)
Independent state management for MCP toggle

Technical Details:

New endpoints:
- GET /api/mcp/status (returns mcpEnabled boolean)
- POST /api/mcp/toggle (toggles MCP server state)
Modified files:
- src/services/worker-service.ts (added MCP control logic)
- src/ui/viewer/components/Sidebar.tsx (added MCP toggle UI)
- plugin/.mcp.json (MCP server configuration)
Design rationale: Provides runtime control of the MCP search server to allow users to disable it when not needed, reducing resource usage. The file-based toggle mechanism ensures persistence across worker restarts.

Known Issues: None

Upgrade Notes: No breaking changes. Upgrade by running standard update process.

[5.4.0] - 2025-11-10

⚠️ BREAKING CHANGE: MCP Search Tools Removed

Migration: None required. Claude automatically uses the search skill when needed.

🔍 Major Feature: Skill-Based Search Architecture

Token Savings: ~2,250 tokens per session start (90% reduction)

What Changed:

Before: 9 MCP tools (~2,500 tokens in tool definitions per session start)
After: 1 search skill (~250 tokens in frontmatter, full instructions loaded on-demand)
User Experience: Identical - just ask naturally about past work

✨ Improvements

Progressive Disclosure Pattern:

Skill frontmatter (~250 tokens) loads at session start
Full instructions (~2,500 tokens) load only when skill is invoked
HTTP API endpoints replace MCP protocol
No user action required - migration is transparent

Natural Language Queries:

"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"

🆕 Added

10 New HTTP Search API Endpoints in worker service:

GET /api/search/observations - Full-text search observations
GET /api/search/sessions - Full-text search session summaries
GET /api/search/prompts - Full-text search user prompts
GET /api/search/by-concept - Find observations by concept tag
GET /api/search/by-file - Find work related to specific files
GET /api/search/by-type - Find observations by type (bugfix, feature, etc.)
GET /api/context/recent - Get recent session context
GET /api/context/timeline - Get timeline around specific point in time
GET /api/timeline/by-query - Search + timeline in one call
GET /api/search/help - API documentation

Search Skill (plugin/skills/search/SKILL.md):

Auto-invoked when users ask about past work, decisions, or history
Comprehensive documentation with usage examples and workflows
Format guidelines for presenting search results
12 operation files with detailed instructions

🗑️ Removed

MCP Search Server (deprecated):

Removed claude-mem-search from plugin/.mcp.json
Build script no longer compiles search-server.mjs
Source file kept for reference: src/servers/search-server.ts
All 9 MCP tools replaced by equivalent HTTP API endpoints

📚 Documentation

Comprehensive Updates:

README.md: Updated version badge, What's New, and search section
docs/usage/search-tools.mdx: Complete rewrite for skill-based approach
docs/architecture/mcp-search.mdx → search-architecture.mdx: New architecture doc
docs/architecture/overview.mdx: Updated components and search pipeline
docs/usage/getting-started.mdx: Added skill-based search section
docs/configuration.mdx: Updated search configuration
docs/introduction.mdx: Updated key features

🔧 Technical Details

How It Works:

User asks: "What did we do last session?"
Claude recognizes intent → invokes search skill
Skill loads full instructions from SKILL.md
Skill uses curl to call HTTP API endpoint
Results formatted and returned to Claude
Claude presents results to user

Benefits:

Token Efficient: Only loads what you need, when you need it
Natural: No syntax to learn, just ask questions
Progressive: Start with overview, drill down as needed
Flexible: HTTP API can be called from skills, MCP tools, or other clients

🐛 Migration Notes

For Users:

✅ No action required - migration is transparent
✅ Same questions work - natural language queries identical
✅ Invisible change - only notice better performance

For Developers:

⚠️ MCP search server deprecated (source kept for reference)
✅ New implementation: Skill files + HTTP endpoints
✅ Build/sync workflow unchanged

📦 Installation

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Restart Claude Code to start using v5.4.0.

🔗 Resources

Documentation: https://github.com/thedotmack/claude-mem/tree/main/docs
Issues: https://github.com/thedotmack/claude-mem/issues
CHANGELOG: https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v5.3.0...v5.4.0

[5.3.0] - 2025-11-09

Breaking Changes: None (minor version)

Session Lifecycle Improvements:

Prompt Counter Restoration: SessionManager now loads prompt counter from database on worker restart, preventing state loss
Continuation Prompts: Lightweight prompts for request #2+ avoid re-initializing SDK agent's mental model
Summary Framing: Changed from "final report" to "progress checkpoint" to clarify mid-session summaries

Bug Fixes:

#76: Fixed PM2 "Process 0 not found" error by using idempotent pm2 start instead of pm2 restart
#74, #75: Fixed troubleshooting skill distribution by moving to plugin/skills/ directory
#73 (Partial): Improved context-loading task reporting in summaries

Technical Details:

Modified files:
- src/services/worker/SessionManager.ts (loads prompt_counter from DB)
- src/services/worker/SDKAgent.ts (uses continuation prompts)
- src/sdk/prompts.ts (added buildContinuationPrompt function)
- src/shared/worker-utils.ts (pm2 start instead of restart)
- src/hooks/context-hook.ts (improved context loading)
- Moved .claude/skills/troubleshoot → plugin/skills/troubleshoot

Why These Changes Matter:

Worker restarts no longer lose session state
Subsequent prompts are more efficient (no re-initialization overhead)
Summaries better reflect ongoing work vs completed sessions
PM2 errors eliminated for new users
Troubleshooting skill now properly distributed to plugin users

Upgrade Notes: No breaking changes. Worker will automatically pick up improvements on restart.

[5.2.3] - 2025-11-09

Breaking Changes: None (patch version)

Improvements:

Added troubleshooting slash command skill for diagnosing claude-mem installation issues
Comprehensive diagnostic workflow covering PM2, worker health, database, dependencies, logs, and viewer UI
Automated fix sequences and common issue resolutions
Full system diagnostic report generation

Technical Details:

New file: .claude/skills/troubleshoot/SKILL.md (363 lines)
Added troubleshooting skill documentation to README.md and docs/troubleshooting.mdx
Version bumped to 5.2.3 across all metadata files

Usage: Run /skill troubleshoot or invoke the troubleshoot skill to diagnose claude-mem issues.

The skill provides systematic checks for:

PM2 worker status
Worker service health
Database state and integrity
Dependencies installation
Worker logs
Viewer UI endpoints
Full system diagnostic report

[5.2.2] - 2025-11-08

Breaking Changes: None (patch version)

Improvements:

Context hook now displays 'investigated' and 'learned' fields from session summaries
Enhanced startup context visibility with color-coded formatting (blue for investigated, yellow for learned)
Improved session summary detail display at startup

Technical Details:

Modified files:
- src/hooks/context-hook.ts (enhanced SQL query and display logic)
- plugin/scripts/context-hook.js (built hook with new functionality)
Updated SQL query to SELECT investigated and learned columns
Added TypeScript type definitions for nullable investigated and learned fields
Added conditional display blocks with appropriate color formatting

Impact: Users will now see more comprehensive session summary information at startup, providing better context about what was investigated and learned in previous sessions.

[5.2.1] - 2025-11-08

Breaking Changes: None (patch version)

Bug Fixes

This patch release fixes critical race conditions and state synchronization issues in the viewer UI's project filtering system.

Fixed Issues:

Race condition with offset reset: When filter changed, offset wasn't reset synchronously, causing incorrect pagination ranges (e.g., loading items 20-40 for new project with < 20 items)
State ref synchronization: stateRef.current.hasMore retained old value when filter changed, preventing new filter from loading if previous filter had no more data
Data mixing between projects: Batched state updates caused data from different projects to appear together in the UI
useEffect dependency cycle: handleLoadMore in dependencies caused double renders when filter changed
NULL projects in dropdown: Empty/NULL project values appeared in the project filter dropdown

Technical Improvements:

Combined two separate useEffect hooks into one for guaranteed execution order (reset → load)
Removed redundant filter change detection logic (DRY principle)
Simplified validation in mergeAndDeduplicateByProject function
Added investigated field to Summary interface for better session tracking

Files Changed:

src/ui/viewer/App.tsx - Fixed filter change detection and data reset logic
src/ui/viewer/hooks/usePagination.ts - Improved offset and state ref handling
src/ui/viewer/utils/data.ts - Simplified validation logic
src/services/sqlite/SessionStore.ts - Filter NULL/empty projects from dropdown
src/ui/viewer/types.ts - Added investigated field to Summary interface
src/ui/viewer/components/SummaryCard.tsx - Display investigated field

All changes follow CLAUDE.md coding standards: DRY, YAGNI, and fail-fast error handling.

Testing

Verified fixes work correctly:

✅ Select project from dropdown → Data loads immediately
✅ Switch between multiple projects → Only selected project's data shown (no mixing)
✅ Rapid switching between projects → No race conditions or stale data
✅ Switch back to "All Projects" → All data appears correctly with SSE updates

[5.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

SDK Agent Narrative Assignment (commit e22edad)
- Fixed: Changed from obs.title to obs.narrative
- Impact: Observations now correctly preserve narrative content
PostToolUse Hook Field Name (commit 13643a5)
- Fixed: Corrected field reference in hook output
- Impact: Tool usage properly captured
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
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:

Pull latest: git pull
Rebuild: npm run build
Sync to marketplace: npm run sync-marketplace
Restart worker: npm run worker:restart
Start new Claude Code session

📖 Related

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

[5.1.4] - 2025-11-07

Bugfix Release: PostToolUse Hook Schema Compliance

Changes:

Fixed parameter naming in save-hook to match Claude Code PostToolUse API schema
Renamed tool_output to tool_response throughout the codebase
Updated worker-service to handle tool_response field correctly

Technical Details:

Modified files:
- src/hooks/save-hook.ts: Updated interface and parameter destructuring
- src/services/worker-service.ts: Updated observation message handling
- plugin/scripts/save-hook.js: Rebuilt with corrected names
- plugin/scripts/worker-service.cjs: Rebuilt with corrected names

Why This Matters: The Claude Code PostToolUse hook API provides tool_response not tool_output. This fix ensures proper schema compliance and prevents potential errors when capturing tool executions.

[5.1.2] - 2025-11-06

Breaking Changes: None (patch version)

Features:

Theme toggle functionality with light, dark, and system preferences
User-selectable theme with persistent settings across sessions
Automatic system preference detection and matching

Technical Details:

Enhanced viewer UI with theme toggle controls
Theme preference stored in localStorage
Seamless integration with existing viewer interface
Version bumped from 5.1.1 → 5.1.2

Usage: Access the viewer at http://localhost:37777 and use the theme toggle to switch between light mode, dark mode, or system preference.

[5.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.

[5.1.0] - 2025-11-06

🎉 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

Update claude-mem to v5.1.0
Start a Claude Code session (worker auto-starts)
Open http://localhost:37777 in your browser
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: https://github.com/thedotmack/claude-mem/compare/v5.0.3...v5.1.0

[5.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:

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

[5.0.2] - 2025-11-05

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

[5.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.

[5.0.0] - 2025-11-04

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

[4.3.4] - 2025-11-02

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

[4.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)

[4.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.

[4.3.1] - 2025-10-26

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: https://github.com/thedotmack/claude-mem/compare/v4.3.0...v4.3.1

[4.3.0] - 2025-10-25

What's Changed

feat: Enhanced context hook with session observations and cross-platform improvements by @thedotmack in thedotmack#25

New Contributors

@thedotmack made their first contribution in thedotmack#25

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v4.2.11...v4.3.0

[4.2.10] - 2025-10-25

Fixed

Windows compatibility: Removed hardcoded macOS-specific Claude executable path that prevented worker service from running on Windows

Changes

Removed hardcoded path: /Users/alexnewman/.nvm/versions/node/v24.5.0/bin/claude
Removed pathToClaudeCodeExecutable parameter from SDK query() calls
SDK now automatically detects Claude Code executable path on all platforms
Improved cross-platform compatibility (Windows, macOS, Linux)

Technical Details

Updated src/sdk/worker.ts to remove hardcoded Claude path and pathToClaudeCodeExecutable parameter
Updated src/services/worker-service.ts to remove hardcoded Claude path and parameter
Built plugin/scripts/worker-service.cjs reflects changes
Affects all SDK agent initialization in worker service

Impact

Before: Worker service failed on Windows due to hardcoded macOS path
After: Worker service works correctly on all platforms

Files Changed

src/sdk/worker.ts
src/services/worker-service.ts
plugin/scripts/worker-service.cjs (rebuilt)

[4.2.3] - 2025-10-24

[4.2.1] - 2025-10-23

[3.9.16] - 2025-10-07

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.9.16

Quick Start

claude-mem install

For full documentation, visit the README.

[3.9.14] - 2025-10-04

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.9.14

Quick Start

claude-mem install

For full documentation, visit the README.

[3.9.13] - 2025-10-04

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.9.13

Quick Start

claude-mem install

For full documentation, visit the README.

[3.9.12] - 2025-10-04

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.9.12

Quick Start

claude-mem install

For full documentation, visit the README.

[3.9.11] - 2025-10-04

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.9.11

Quick Start

claude-mem install

For full documentation, visit the README.

[3.9.10] - 2025-10-03

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.9.10

Quick Start

claude-mem install

For full documentation, visit the README.

[3.9.9] - 2025-10-03

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.9.9

Quick Start

claude-mem install

For full documentation, visit the README.

[3.7.2] - 2025-09-22

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.7.2

Quick Start

claude-mem install

For full documentation, visit the README.

[3.7.1] - 2025-09-18

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.7.1

Quick Start

claude-mem install

For full documentation, visit the README.

[3.7.0] - 2025-09-18

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.7.0

Quick Start

claude-mem install

For full documentation, visit the README.

[3.6.10] - 2025-09-17

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.6.10

Quick Start

claude-mem install

For full documentation, visit the README.

[3.6.9] - 2025-09-15

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.6.9

Quick Start

claude-mem install

For full documentation, visit the README.

[3.6.8] - 2025-09-14

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.6.8

Quick Start

claude-mem install

For full documentation, visit the README.

[3.6.6] - 2025-09-14

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.6.6

Quick Start

claude-mem install

For full documentation, visit the README.

[3.6.5] - 2025-09-14

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.6.5

Quick Start

claude-mem install

For full documentation, visit the README.

[3.6.4] - 2025-09-14

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.6.4

Quick Start

claude-mem install

For full documentation, visit the README.

[3.6.3] - 2025-09-11

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.6.3

Quick Start

claude-mem install

For full documentation, visit the README.

[3.6.2] - 2025-09-11

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.6.2

Quick Start

claude-mem install

For full documentation, visit the README.

[3.6.1] - 2025-09-10

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.6.1

Quick Start

claude-mem install

For full documentation, visit the README.

[3.6.0] - 2025-09-10

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.6.0

Quick Start

claude-mem install

For full documentation, visit the README.

[3.5.9] - 2025-09-10

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.5.9

Quick Start

claude-mem install

For full documentation, visit the README.

[3.5.8] - 2025-09-10

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.5.8

Quick Start

claude-mem install

For full documentation, visit the README.

[3.5.7] - 2025-09-10

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.5.7

Quick Start

claude-mem install

For full documentation, visit the README.

[3.5.6] - 2025-09-09

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.5.6

Quick Start

claude-mem install

For full documentation, visit the README.

[3.5.5] - 2025-09-09

What's New

This release includes the latest updates from the npm package.

Installation

npm install -g claude-mem@3.5.5

Quick Start

claude-mem install

For full documentation, visit the README.

[3.5.4] - 2025-09-09

🎉 claude-mem v3.5.4

Installation

npm install -g claude-mem
claude-mem install

What's New

Enhanced memory compression and loading
Improved hook system reliability
Better error handling and logging
Updated dependencies
Bug fixes and performance improvements

Key Features

🧠 Intelligent Memory Compression - Automatically extracts key learnings from Claude Code conversations
🔄 Seamless Integration - Works invisibly in the background with /compact and /clear commands
🎯 Smart Context Loading - Loads relevant memories when starting new sessions
📚 Comprehensive Knowledge Base - Stores solutions, patterns, and decisions
🔍 Powerful Search - Vector-based semantic search across all memories

Files Included

dist/claude-mem.min.js - Minified CLI executable
hooks/ - Claude Code integration hooks
commands/ - Claude Code custom commands
package.json - Package configuration

Requirements

Node.js 18+
Claude Code CLI
uv (automatically installed if missing)

For documentation and support, visit the GitHub repository.

FilesExpand file tree

CHANGELOG.md

Latest commit

History

CHANGELOG.md

File metadata and controls

Changelog

[7.0.11] - 2025-12-12

[7.0.9] - 2025-12-10

Bug Fixes

Changes

[7.0.8] - 2025-12-10

Bug Fixes

Technical Details

[7.0.7] - 2025-12-10

What's Changed

Code Quality Improvements

New Features

Technical Improvements

[7.0.6] - 2025-12-10

Bug Fixes

Contributors

[7.0.5] - 2025-12-09

What's Changed

Bug Fixes

Improvements

[7.0.4] - 2025-12-09

What's Changed

Bug Fixes

[7.0.3] - 2025-12-09

What's Changed

[7.0.2] - 2025-12-09

What's Changed

[7.0.1] - 2025-12-09

Bug Fixes

Technical Changes

[7.0.0] - 2025-12-08

Major Architectural Refactor

Breaking Changes

What Changed

Hooks → HTTP Clients

Worker Service Modularization

New Service Layer

Database Improvements

Testing Infrastructure

Type Safety

Stats

Migration Notes

[6.5.3] - 2025-12-05

Bug Fixes

[6.5.2] - 2025-12-04

What's Changed

Fixes

[6.5.1] - 2025-12-04

What's New

Changes

[6.5.0] - 2025-12-04

Documentation Overhaul

Changes

[6.4.9] - 2025-12-02

New Features

Context Configuration (11 new settings)

What's Next

Technical Details

[6.4.1] - 2025-12-01

Hey there, claude-mem community! 👋

🔴 When You'll See Us Live

What Changed in This Release

Why We're Doing This

Join the Community

Technical Details

[6.4.0] - 2025-12-01

🎯 Highlights

✨ New Features

Dual-Tag Privacy System

User Experience

🔧 Improvements

Search API

Performance

📚 Documentation