🐛 Bug Fixes
**Windows Installation**
- Fixed Bun PATH detection on Windows after fresh install
- Added fallback to check common install paths before PATH reload
- Improved smart-install.js to use full Bun path when not in PATH
- Added proper path quoting for Windows usernames with spaces
**Worker Startup**
- Fixed worker connection failures in Stop hook
- Added health check retry loop (5 attempts, 500ms intervals)
- Worker now waits up to 2.5s for responsiveness before returning
- Improved error detection for Bun's ConnectionRefused error format
🎯 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Created README.zh.md for Chinese localization of the project.
- Developed a README translation script to support multiple languages using Claude Agent SDK.
- Implemented CLI and programmatic usage for the translation tool.
- Added examples for integrating the translation tool into build scripts and CI/CD pipelines.
- Enhanced error handling and logging for translation processes.
- Included support for various languages and output customization options.
- Delete BinaryManager.ts - no longer needed
- Simplify ProcessManager.ts - single Bun spawn path for all platforms
- Update smart-install.js - auto-install Bun if missing (Windows/Unix)
- Update documentation to reflect Bun requirement
This simplifies the codebase by:
- Using Bun consistently across all platforms (hooks + worker)
- Eliminating binary download/hosting complexity
- Zero native dependencies with bun:sqlite
- Auto-installing Bun on first run if not present
Co-authored-by: Claude <noreply@anthropic.com>
- Updated shebangs in user-message-hook.js, worker-cli.js, and worker-service.cjs to use Bun instead of Node.
- Modified build-hooks.js to generate Bun-compatible shebangs in built scripts.
- Enhanced sync-marketplace.cjs to trigger a worker restart after syncing files via an HTTP request.
- Improved worker-cli.ts to exit with appropriate status codes after executing commands.
- Added build-worker-binary.js to create a Windows executable for the worker service using Bun's compile feature.
- Updated build-hooks.js to remove better-sqlite3 dependency and use bun:sqlite.
- Modified smart-install.js to eliminate checks and installations related to better-sqlite3.
- Refactored Database.ts, SessionSearch.ts, SessionStore.ts, and migrations.ts to import and utilize bun:sqlite.
- Replaced exec and pragma calls with appropriate run methods for bun:sqlite compatibility.
- Removed unnecessary native module verification and installation logic for better-sqlite3.
- Replaced instances of silentDebug with happy_path_error__with_fallback across multiple files to improve error logging and handling.
- Updated the utility function to provide clearer semantics for error handling when expected values are missing.
- Introduced a script to find potential silent failures in the codebase that may need to be addressed with the new error handling approach.
The bundled hook scripts use `external: ['better-sqlite3']` during esbuild,
meaning the dependency must be resolved at runtime. When hooks run from the
cache directory (~/.claude/plugins/cache/thedotmack/claude-mem/X.X.X/),
they couldn't find better-sqlite3 because:
1. Cache directory had no package.json
2. smart-install.js was hardcoded to install in marketplace directory only
This fix:
- Adds plugin/package.json declaring runtime dependencies (better-sqlite3)
- Updates build-hooks.js to auto-generate plugin/package.json from main package.json
- Updates smart-install.js to detect execution context (cache vs marketplace)
and install dependencies in the correct location
The script now detects if it's running from cache (via path pattern matching)
and installs dependencies there, where the hooks actually execute.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This PR addresses issue #193 affecting Windows installations of claude-mem.
## Bug 1: Missing ecosystem.config.cjs in packaged plugin
**Problem**: The ecosystem.config.cjs file was not included in the plugin
package, causing PM2 to fail when trying to start the worker from cache.
**Fix**: Added `plugin/ecosystem.config.cjs` with correct path for packaged
structure (`./scripts/worker-service.cjs` instead of `./plugin/scripts/`).
## Bug 2: Incorrect MCP Server Path (src/services/worker-service.ts)
**Problem**: Path `__dirname, '..', '..', 'plugin', 'scripts', 'mcp-server.cjs'`
only worked in dev structure, failed in packaged plugin.
**Error produced**:
```
Error: Cannot find module 'C:\Users\...\claude-mem\plugin\scripts\mcp-server.cjs'
[ERROR] [SYSTEM] Background initialization failed MCP error -32000: Connection closed
```
**Fix**: Changed to `path.join(__dirname, 'mcp-server.cjs')` since mcp-server.cjs
is in the same directory as worker-service.cjs after bundling.
## Bug 3: Missing smart-install.js in plugin package
**Problem**: smart-install.js was referenced in hooks.json but not included
in the plugin/ directory for cache deployment.
**Fix**: Added `plugin/scripts/smart-install.js` that uses `createRequire()`
to resolve modules from MARKETPLACE_ROOT.
## Bug 4: hooks.json incorrect path
**Problem**: Referenced `/../scripts/smart-install.js` but CLAUDE_PLUGIN_ROOT
points to the plugin/ directory.
**Fix**: Changed to `/scripts/smart-install.js`.
## Bug 5: Windows Worker Startup - Visible Console Windows
**Problem**: PM2 ignores windowsHide option on Windows, opening visible
console windows when starting the worker service.
**Fix**: Use PowerShell `Start-Process -WindowStyle Hidden` on Windows while
keeping PM2 for Unix systems (src/shared/worker-utils.ts).
## Additional Improvements
- Increased worker startup timeouts for Windows (500ms health check, 1000ms
wait between retries, 15 retries = 15s total vs previous 5s)
- Added `windowsHide: true` to root ecosystem.config.cjs for PM2
## Note on Assertion Failure
The Windows libuv assertion failure `!(handle->flags & UV_HANDLE_CLOSING)`
at `src\win\async.c:76` is a known upstream issue in Claude Code (Issue #7579),
triggered by fetch() calls on Windows. This is NOT caused by worker spawning
and cannot be fixed in claude-mem.
Tested on Windows 11 with Node.js v24.
Fixes#193🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Extracted timeline-related functionality from mcp-server.ts to a dedicated TimelineService class.
- Added methods to build, filter, and format timeline items based on observations, sessions, and prompts.
- Introduced interfaces for TimelineItem and TimelineData to standardize data structures.
- Implemented sorting and grouping of timeline items by date, with markdown formatting for output.
- Included utility methods for date and time formatting, as well as token estimation.
- Updated logging in `search-server.ts` to use `silentDebug` for non-critical messages, reducing console noise.
- Added a health check endpoint in `worker-service.ts` to improve service monitoring.
- Modified the worker service startup process to start the HTTP server immediately and perform slow initialization in the background.
- Refactored database initialization in `Database.ts` to use the correct `Database` class.
- Implemented a port availability check in `context-hook.ts` to ensure the worker service is ready before making requests.
Major architectural improvements to the worker service:
- Extracted monolithic WorkerService (~1900 lines) into organized route classes
- New HTTP layer with dedicated route handlers:
- SessionRoutes: Session lifecycle operations
- DataRoutes: Data retrieval endpoints
- SearchRoutes: Search/MCP proxy operations
- SettingsRoutes: Settings and configuration
- ViewerRoutes: Health, UI, and SSE streaming
- Added comprehensive README documenting worker architecture
- Improved build script to handle worker service compilation
- Added context-generator for hook context operations
This is Phase 1 of worker refactoring - pure code reorganization with zero
functional changes. All existing behavior preserved while improving
maintainability and code organization.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes a SyntaxError where an extra closing brace on line 392 was causing
"Missing catch or finally after try" error. The PM2 worker startup
try/catch block was properly formed but had an orphaned closing brace
that didn't match any opening brace.
This was breaking the SessionStart hook and preventing the plugin from
loading correctly.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements three-layer defense against native module version mismatches:
Layer 1: Node.js Version Tracking
- Track Node.js version alongside package version in .install-version marker
- Auto-trigger npm install when Node.js version changes
- Backward compatible with old plain-text version marker format
Layer 2: Native Module Verification
- Add verifyNativeModules() function to test better-sqlite3 loads correctly
- Verify after install completes to catch corrupted builds
- Retry with force flag if initial install verification fails
Layer 3: Graceful Failure
- Catch ERR_DLOPEN_FAILED in context-hook and delete version marker
- Exit cleanly to avoid error spam in Claude Code UI
- Auto-fix on next session start
Changes:
- scripts/smart-install.js: Add Node.js version tracking and verification
- src/hooks/context-hook.ts: Add graceful failure handling for native module errors
- tests/smart-install.test.js: Add tests for version marker format compatibility
- plugin/scripts/context-hook.js: Built output from TypeScript source
Fixes the issue where users see ERR_DLOPEN_FAILED errors after Node.js upgrades,
requiring manual npm install. Now automatically detects and fixes the issue.
Related design doc: docs/context/native-module-auto-fix-design.md
Implementation plan: docs/context/native-module-auto-fix-implementation.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Alex Newman <thedotmack@gmail.com>
Replace execSync with shell string interpolation with spawnSync and
array arguments. This eliminates potential command injection if paths
contain special characters.
- Use .cmd extension for PM2 on Windows (pm2.cmd vs pm2)
- Add shell: true to execSync for proper path quoting on Windows
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Refactor code structure for improved readability and maintainability
* Add test results for search API and related functionalities
- Created test result files for various search-related functionalities, including:
- test-11-search-server-changes.json
- test-12-context-hook-changes.json
- test-13-worker-service-changes.json
- test-14-patterns.json
- test-15-gotchas.json
- test-16-discoveries.json
- test-17-all-bugfixes.json
- test-18-all-features.json
- test-19-all-decisions.json
- test-20-session-search.json
- test-21-prompt-search.json
- test-22-decisions-endpoint.json
- test-23-changes-endpoint.json
- test-24-how-it-works-endpoint.json
- test-25-contextualize-endpoint.json
- test-26-timeline-around-observation.json
- test-27-multi-param-combo.json
- test-28-file-type-combo.json
- Each test result file captures specific search failures or outcomes, including issues with undefined properties and successful execution of search queries.
- Enhanced documentation of search architecture and testing strategies, ensuring compliance with established guidelines and improving overall search functionality.
* feat: Enhance unified search API with catch-all parameters and backward compatibility
- Implemented a unified search API at /api/search that accepts catch-all parameters for filtering by type, observation type, concepts, and files.
- Maintained backward compatibility by keeping granular endpoints functional while routing through the same infrastructure.
- Completed comprehensive testing of search capabilities with real-world query scenarios.
fix: Address missing debug output in search API query tests
- Flushed PM2 logs and executed search queries to verify functionality.
- Diagnosed absence of "Raw Chroma" debug messages in worker logs, indicating potential issues with logging or query processing.
refactor: Improve build and deployment pipeline for claude-mem plugin
- Successfully built and synced all hooks and services to the marketplace directory.
- Ensured all dependencies are installed and up-to-date in the deployment location.
feat: Implement hybrid search filters with 90-day recency window
- Enhanced search server to apply a 90-day recency filter to Chroma results before categorizing by document type.
fix: Correct parameter handling in searchUserPrompts method
- Added support for filter-only queries and improved dual-path logic for clarity.
refactor: Rename FTS5 method to clarify fallback status
- Renamed escapeFTS5 to escapeFTS5_fallback_when_chroma_unavailable to indicate its temporary usage.
feat: Introduce contextualize tool for comprehensive project overview
- Added a new tool to fetch recent observations, sessions, and user prompts, providing a quick project overview.
feat: Add semantic shortcut tools for common search patterns
- Implemented 'decisions', 'changes', and 'how_it_works' tools for convenient access to frequently searched observation categories.
feat: Unified timeline tool supports anchor and query modes
- Combined get_context_timeline and get_timeline_by_query into a single interface for timeline exploration.
feat: Unified search tool added to MCP server
- New tool queries all memory types simultaneously, providing combined chronological results for improved search efficiency.
* Refactor search functionality to clarify FTS5 fallback usage
- Updated `worker-service.cjs` to replace FTS5 fallback function with a more descriptive name and improved error handling.
- Enhanced documentation in `SKILL.md` to specify the unified API endpoint and clarify the behavior of the search engine, including the conditions under which FTS5 is used.
- Modified `search-server.ts` to provide clearer logging and descriptions regarding the fallback to FTS5 when UVX/Python is unavailable.
- Renamed and updated the `SessionSearch.ts` methods to reflect the conditions for using FTS5, emphasizing the lack of semantic understanding in fallback scenarios.
* feat: Add ID-based fetch endpoints and simplify mem-search skill
**Problem:**
- Search returns IDs but no way to fetch by ID
- Skill documentation was bloated with too many options
- Claude wasn't using IDs because we didn't tell it how
**Solution:**
1. Added three new HTTP endpoints:
- GET /api/observation/:id
- GET /api/session/:id
- GET /api/prompt/:id
2. Completely rewrote SKILL.md:
- Stripped complexity down to essentials
- Clear 3-step prescriptive workflow: Search → Review IDs → Fetch by ID
- Emphasized ID usage: "The IDs are there for a reason - USE THEM"
- Removed confusing multi-endpoint documentation
- Kept only unified search with filters
**Impact:**
- Token efficiency: Claude can now fetch full details only for relevant IDs
- Clarity: One clear workflow instead of 10+ options to choose from
- Usability: IDs are no longer wasted context - they're actionable
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* chore: Move internal docs to private directory
Moved POSTMORTEM and planning docs to ./private to exclude from PR reviews.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: Remove experimental contextualize endpoint
- Removed contextualize MCP tool from search-server (saves ~4KB)
- Disabled FTS5 fallback paths in SessionSearch (now vector-first)
- Cleaned up CLAUDE.md documentation
- Removed contextualize-rewrite-plan.md doc
Rationale:
- Contextualize is better suited as a skill (LLM-powered) than an endpoint
- Search API already provides vector search with configurable limits
- Created issue #132 to track future contextualize skill implementation
Changes:
- src/servers/search-server.ts: Removed contextualize tool definition
- src/services/sqlite/SessionSearch.ts: Disabled FTS5 fallback, added deprecation warnings
- CLAUDE.md: Cleaned up outdated skill documentation
- docs/: Removed contextualize plan document
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: Complete FTS5 cleanup - remove all deprecated search code
This completes the FTS5 cleanup work by removing all commented-out
FTS5 search code while preserving database tables for backward compatibility.
Changes:
- Removed 200+ lines of commented FTS5 search code from SessionSearch.ts
- Removed deprecated degraded_search_query__when_uvx_unavailable method
- Updated all method documentation to clarify vector-first architecture
- Updated class documentation to reflect filter-only query support
- Updated CLAUDE.md to remove FTS5 search references
- Clarified that FTS5 tables exist for backward compatibility only
- Updated "Why SQLite FTS5" section to "Why Vector-First Search"
Database impact: NONE - FTS5 tables remain intact for existing installations
Search architecture:
- ChromaDB: All text-based vector search queries
- SQLite: Filter-only queries (date ranges, metadata, no query text)
- FTS5 tables: Maintained but unused (backward compatibility)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: Remove all FTS5 fallback execution code from search-server
Completes the FTS5 cleanup by removing all fallback execution paths
that attempted to use FTS5 when ChromaDB was unavailable.
Changes:
- Removed all FTS5 fallback code execution paths
- When ChromaDB fails or is unavailable, return empty results with helpful error messages
- Updated all deprecated tool descriptions (search_observations, search_sessions, search_user_prompts)
- Changed error messages to indicate FTS5 fallback has been removed
- Added installation instructions for UVX/Python when vector search is unavailable
- Updated comments from "hybrid search" to "vector-first search"
- Removed ~100 lines of dead FTS5 fallback code
Database impact: NONE - FTS5 tables remain intact (backward compatibility)
Search behavior when ChromaDB unavailable:
- Text queries: Return empty results with error explaining ChromaDB is required
- Filter-only queries (no text): Continue to work via direct SQLite
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Address PR 133 review feedback
Critical fixes:
- Remove contextualize endpoint from worker-service (route + handler)
- Fix build script logging to show correct .cjs extension (was .mjs)
Documentation improvements:
- Add comprehensive FTS5 retention rationale documentation
- Include v7.0.0 removal TODO for future cleanup
Testing:
- Build succeeds with correct output logging
- Worker restarts successfully (30th restart)
- Contextualize endpoint properly removed (404 response)
- Search endpoint verified working
This addresses all critical review feedback from PR 133.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
This fixes the issue where the worker service wouldn't start automatically
after installing the plugin, leaving users with confusing error messages.
Changes:
- Update worker-utils.ts to use local PM2 from node_modules instead of
requiring it in PATH
- Improve error messages to suggest npx pm2 commands
- Add auto-start attempt in smart-install.js after fresh installation
- Fall back gracefully if worker can't start (will auto-start on first use)
Fixes issue where users with PM2 not in their PATH couldn't start the worker.
- Added a new script to simulate token savings from Endless Mode using real observation data.
- Introduced functions to calculate token costs with and without Endless Mode, showcasing the differences in context handling.
- Enhanced output to display detailed token usage statistics and potential savings at scale.
- Integrated assumptions for user activity to estimate weekly and annual token savings.
- Updated worker-utils to automatically start the worker using PM2 if not running, improving service reliability.
- Introduced icon-thin-learned.svg with detailed path definitions and color styling.
- Added icon-thin-next-steps.svg featuring a unique design and color scheme.
* refactor: Reduce continuation prompt token usage by 95 lines
Removed redundant instructions from continuation prompt that were originally
added to mitigate a session continuity issue. That issue has since been
resolved, making these detailed instructions unnecessary on every continuation.
Changes:
- Reduced continuation prompt from ~106 lines to ~11 lines (~95 line reduction)
- Changed "User's Goal:" to "Next Prompt in Session:" (more accurate framing)
- Removed redundant WHAT TO RECORD, WHEN TO SKIP, and OUTPUT FORMAT sections
- Kept concise reminder: "Continue generating observations and progress summaries..."
- Initial prompt still contains all detailed instructions
Impact:
- Significant token savings on every continuation prompt
- Faster context injection with no loss of functionality
- Instructions remain comprehensive in initial prompt
Files modified:
- src/sdk/prompts.ts (buildContinuationPrompt function)
- plugin/scripts/worker-service.cjs (compiled output)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: Enhance observation and summary prompts for clarity and token efficiency
* Enhance prompt clarity and instructions in prompts.ts
- Added a reminder to think about instructions before starting work.
- Simplified the continuation prompt instruction by removing "for this ongoing session."
* feat: Enhance settings.json with permissions and deny access to sensitive files
refactor: Remove PLAN-full-observation-display.md and PR_SUMMARY.md as they are no longer needed
chore: Delete SECURITY_SUMMARY.md since it is redundant after recent changes
fix: Update worker-service.cjs to streamline observation generation instructions
cleanup: Remove src-analysis.md and src-tree.md for a cleaner codebase
refactor: Modify prompts.ts to clarify instructions for memory processing
* refactor: Remove legacy worker service implementation
* feat: Enhance summary hook to extract last assistant message and improve logging
- Added function to extract the last assistant message from the transcript.
- Updated summary hook to include last assistant message in the summary request.
- Modified SDKSession interface to store last assistant message.
- Adjusted buildSummaryPrompt to utilize last assistant message for generating summaries.
- Updated worker service and session manager to handle last assistant message in summarize requests.
- Introduced silentDebug utility for improved logging and diagnostics throughout the summary process.
* docs: Add comprehensive implementation plan for ROI metrics feature
Added detailed implementation plan covering:
- Token usage capture from Agent SDK
- Database schema changes (migration #8)
- Discovery cost tracking per observation
- Context hook display with ROI metrics
- Testing and rollout strategy
Timeline: ~20 hours over 4 days
Goal: Empirical data for YC application amendment
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* feat: Add transcript processing scripts for analysis and formatting
- Implemented `dump-transcript-readable.ts` to generate a readable markdown dump of transcripts, excluding certain entry types.
- Created `extract-rich-context-examples.ts` to extract and showcase rich context examples from transcripts, highlighting user requests and assistant reasoning.
- Developed `format-transcript-context.ts` to format transcript context into a structured markdown format for improved observation generation.
- Added `test-transcript-parser.ts` for validating data extraction from transcript JSONL files, including statistics and error reporting.
- Introduced `transcript-to-markdown.ts` for a complete representation of transcript data in markdown format, showing all context data.
- Enhanced type definitions in `transcript.ts` to support new features and ensure type safety.
- Built `transcript-parser.ts` to handle parsing of transcript JSONL files, including error handling and data extraction methods.
* Refactor hooks and SDKAgent for improved observation handling
- Updated `new-hook.ts` to clean user prompts by stripping leading slashes for better semantic clarity.
- Enhanced `save-hook.ts` to include additional tools in the SKIP_TOOLS set, preventing unnecessary observations from certain command invocations.
- Modified `prompts.ts` to change the structure of observation prompts, emphasizing the observational role and providing a detailed XML output format for observations.
- Adjusted `SDKAgent.ts` to enforce stricter tool usage restrictions, ensuring the memory agent operates solely as an observer without any tool access.
* feat: Enhance session initialization to accept user prompts and prompt numbers
- Updated `handleSessionInit` in `worker-service.ts` to extract `userPrompt` and `promptNumber` from the request body and pass them to `initializeSession`.
- Modified `initializeSession` in `SessionManager.ts` to handle optional `currentUserPrompt` and `promptNumber` parameters.
- Added logic to update the existing session's `userPrompt` and `lastPromptNumber` if a `currentUserPrompt` is provided.
- Implemented debug logging for session initialization and updates to track user prompts and prompt numbers.
---------
Co-authored-by: Claude <noreply@anthropic.com>
New Features:
- Created scripts/generate-changelog.js to auto-generate CHANGELOG.md
- Fetches all GitHub releases and formats into Keep a Changelog format
- Added npm run changelog:generate command
Version-Bump Skill Updates:
- Added Step 10: Generate CHANGELOG to workflow
- Updated verification checklist to include CHANGELOG generation
- Updated skill description and critical rules
- Single source of truth: GitHub releases
Technical Details:
- Script fetches releases via gh CLI
- Parses release bodies and formats to markdown
- Removes duplicate headers and Claude Code footers
- Sorts releases by date (newest first)
- Generates clean, consistent changelog
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Enhancements:
- Added search skill with 10 HTTP API endpoints for memory queries
- Refactored version-bump and troubleshoot skills using progressive disclosure pattern
- Added operations/ subdirectories for detailed skill documentation
- Updated CLAUDE.md with skill-based search architecture
- Enhanced worker service with search API endpoints
- Updated CHANGELOG.md with v5.4.0 migration details
Technical changes:
- New plugin/skills/search/ directory with SKILL.md
- New .claude/skills/version-bump/operations/ (workflow.md, scenarios.md)
- New plugin/skills/troubleshoot/operations/ (common-issues.md, worker.md)
- Modified src/services/worker-service.ts (added search endpoints)
- Modified plugin/scripts/worker-service.cjs (rebuilt with search API)
- Reduced main skill files by 89% using progressive disclosure
- Token savings: ~2,250 tokens per session start
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Introduced WorkerService class to handle HTTP requests and manage sessions.
- Added endpoints for health check, session management, and data retrieval.
- Integrated ChromaSync for background data synchronization.
- Implemented SSE for real-time updates to connected clients.
- Added error handling and logging throughout the service.
- Cached Claude executable path for improved performance.
- Included settings management for user configuration.
- Established database interactions for session and observation management.
* Add viewer HTML for claude-mem with live stream and settings interface
- Implemented a responsive layout with left and right columns for observations and settings.
- Added status indicators for connection state.
- Integrated server-sent events (SSE) for real-time updates on observations and summaries.
- Created dynamic project filter dropdown based on available observations.
- Developed settings section for environment variables and worker stats.
- Included functionality to save settings and load current stats from the server.
- Enhanced UI with custom styles for better user experience.
* Remove draft implementation plan for v5.1 web UI
* feat: Implement viewer UI with sidebar, feed, and settings management
- Add main viewer template (HTML) with styling for dark mode.
- Create App component to manage state and render Header, Feed, and Sidebar.
- Implement Feed component to display observations and summaries with filtering.
- Develop Header component for project selection and connection status.
- Create ObservationCard and SummaryCard components for displaying individual items.
- Implement Sidebar for settings management and displaying worker/database stats.
- Add hooks for managing SSE connections, settings, and stats fetching.
- Define types for observations, summaries, settings, and stats.
* Enhance UI components and improve layout
- Updated padding and layout for the feed and card components in viewer.html, viewer-template.html, and viewer.html to improve visual spacing and alignment.
- Increased card margins and padding for better readability and aesthetics.
- Adjusted font sizes, weights, and line heights for card titles and subtitles to enhance text clarity and hierarchy.
- Added a new feed-content class to center the feed items and limit their maximum width.
- Modified the Header component to improve the settings icon's SVG structure for better rendering.
- Enhanced the Sidebar component by adding a close button with an SVG icon, improving user experience for closing settings.
- Updated the Sidebar component's props to include an onClose function for handling sidebar closure.
* feat: Add user prompts feature with UI integration
- Implemented a new method in SessionStore to retrieve recent user prompts.
- Updated WorkerService to fetch and broadcast user prompts to clients.
- Enhanced the Feed component to display user prompts alongside observations and summaries.
- Created a new PromptCard component for rendering individual user prompts.
- Modified useSSE hook to handle new prompt events and processing status.
- Updated viewer templates and styles to accommodate the new prompts feature.
* feat: Add project filtering and pagination for observations
- Implemented `getAllProjects` method in `SessionStore` to retrieve unique projects from the database.
- Added `/api/observations` endpoint in `WorkerService` for paginated observations fetching.
- Enhanced `App` component to manage paginated observations and integrate with the new API.
- Updated `Feed` component to support infinite scrolling and loading more observations.
- Modified `Header` to display processing status.
- Refactored `PromptCard` to remove unnecessary processing indicator.
- Introduced `usePagination` hook to handle pagination logic for observations.
- Updated `useSSE` hook to include projects in the state.
- Adjusted types to accommodate new project data.
* Refactor viewer build process and remove deprecated HTML template
- Updated build-viewer.js to copy HTML template to build output with improved logging.
- Removed src/ui/viewer.html as it is no longer needed.
- Enhanced App component to merge observations while removing duplicates using useMemo.
- Improved Feed component to utilize a ref for onLoadMore callback and adjusted infinite scroll logic.
- Updated Sidebar component to use default settings from constants and removed redundant formatting functions.
- Refactored usePagination hook to streamline loading logic and prevent concurrent requests.
- Updated useSSE hook to use centralized API endpoints and improved reconnection logic.
- Refactored useSettings and useStats hooks to utilize constants for API endpoints and timing.
- Introduced ErrorBoundary component for better error handling in the viewer.
- Centralized API endpoint paths, default settings, timing constants, and UI-related constants into dedicated files.
- Added utility functions for formatting uptime and bytes for consistent display across components.
* feat: Enhance session management and pagination for user prompts, summaries, and observations
- Added project field to user prompts in the database and API responses.
- Implemented new API endpoints for fetching summaries and prompts with pagination.
- Updated WorkerService to handle new endpoints and filter results by project.
- Modified App component to manage paginated data for prompts and summaries.
- Refactored Feed component to remove unnecessary filtering and handle combined data.
- Improved usePagination hook to support multiple data types and project filtering.
- Adjusted useSSE hook to only load projects initially, with data fetched via pagination.
- Updated types to include project information for user prompts.
* feat: add SummarySkeleton component and data utility for merging items
- Introduced SummarySkeleton component for displaying loading state in the UI.
- Implemented mergeAndDeduplicateByProject utility function to merge real-time and paginated data while removing duplicates based on project filtering.
* Enhance UI and functionality of the viewer component
- Updated sidebar transition effects to use translate3d for improved performance.
- Added a sidebar header with title and connection status indicators.
- Modified the PromptCard to display project name instead of prompt number.
- Introduced a GitHub and X (Twitter) link in the header for easy access.
- Improved styling for setting descriptions and card hover effects.
- Enhanced Sidebar component to include connection status and updated layout.
* fix: reduce timeout for worker health checks and ensure proper responsiveness
* Fix Windows installation with smart caching installer
Fixes#52 - Windows users getting ERR_MODULE_NOT_FOUND for better-sqlite3
## Problem
Windows users (@adrianveen and others) were experiencing installation failures
with cryptic ERR_MODULE_NOT_FOUND errors. The root cause was:
1. npm install running on EVERY SessionStart (slow, wasteful)
2. Silent logging hiding actual installation errors
3. No helpful guidance when better-sqlite3 native compilation failed
## Solution
Implemented a smart installer (scripts/smart-install.js) that:
- Caches installation state with version marker (.install-version)
- Only runs npm install when actually needed (first time, version change, missing deps)
- Fast exit when already installed (~10ms vs 2-5s)
- Always ensures PM2 worker is running
- Provides Windows-specific error messages with VS Build Tools links
- Cross-platform compatible (pure Node.js)
## Changes
- Added: scripts/smart-install.js - Smart caching installer with PM2 worker management
- Modified: plugin/hooks/hooks.json - 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: plugin/scripts/worker-service.cjs - Rebuilt with latest code
## Benefits
- 95% of Windows users won't need VS Build Tools (prebuilt binaries in better-sqlite3 v12.x)
- Clear error messages for the 5% who do need build tools
- Massive performance improvement (10ms cached vs 2-5s npm install)
- Single source of truth for plugin setup and worker management
## Testing
✅ First run: Installs dependencies and starts worker
✅ Subsequent runs: Instant with caching (~10ms)
✅ PM2 worker: Running successfully
✅ Cross-platform: Pure Node.js, no shell scripts
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix Windows installation with smart caching installer
Improvements:
- Enhanced sync-marketplace to respect gitignore rules (package.json)
- Added dynamic Python version detection in Windows help text (scripts/smart-install.js)
- Fixed hardcoded Python version message to show actual installed version
Technical changes:
- Modified package.json sync-marketplace script to use --filter=':- .gitignore' --exclude=.git
- Added runtime Python version detection in getWindowsErrorHelp function
- Improved user experience by showing actual Python installation status
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Changes:
- Updated legend to show only observation types (bugfix, feature, refactor, change, discovery, decision)
- Mapped each type to a color dot emoji (🔴 bugfix, 🟢 feature, 🔵 refactor, ⚪ change, 🟡 discovery, 🟤 decision)
- Removed concept-based filtering and icon selection
- Simplified progressive disclosure instructions to reference types instead of concepts
- All observations now shown in timeline (no concept filtering)
Technical details:
- Modified: src/hooks/context-hook.ts:203-207 (legend)
- Modified: src/hooks/context-hook.ts:210-223 (progressive disclosure text)
- Modified: src/hooks/context-hook.ts:344-369 (icon mapping switched from concepts to types)
- Modified: src/hooks/context-hook.ts:168-173 (removed concept filtering)
- Rebuilt: plugin/scripts/context-hook.js
Rationale: Types are mutually exclusive and core to categorization, while concepts are multi-select metadata better accessed through MCP search tools. This simplifies the display and reduces visual noise.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Features:
- New UsageLogger utility that writes usage metrics to daily JSONL files
- Captures token counts, costs, timing, and cache metrics from SDK result messages
- Usage logs stored in ~/.claude-mem/usage-logs/ (one file per day)
- Added analyze-usage.js script for analyzing usage patterns
Usage data captured:
- Token counts (input, output, cache creation, cache read)
- Total cost in USD per API call
- Duration metrics (total and API time)
- Number of turns per session
- Session and project attribution
Analysis script features:
- Aggregates totals by project and model
- Shows cache hit rates and savings
- Displays cost breakdowns and averages
- npm scripts: usage:analyze and usage:today
Files:
- src/utils/usage-logger.ts (new)
- src/services/worker-service.ts (modified - captures SDK result messages)
- scripts/analyze-usage.js (new)
- package.json (added usage:* npm scripts)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Built search-server.mjs successfully (55KB)
- Configured with packages: 'external' to use node_modules dependencies
- MCP config points to ${CLAUDE_PLUGIN_ROOT}/scripts/search-server.mjs
- Ready for deployment to plugin directory
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changes:
- Renamed src/hooks/stderr-test-hook.ts to user-message-hook.ts
- Updated user-message-hook with production-ready messaging
- Updated scripts/build-hooks.js to build user-message-hook
- Updated plugin/hooks/hooks.json to reference user-message-hook.js
- Cleaned up old stderr-test-hook.js files
- Built and deployed user-message-hook.js to plugin directory
This hook displays context information to users via stderr, which is
currently the only way to show messages in Claude Code UI. It runs in
parallel with context-hook during SessionStart.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Removed bin/hooks/ wrapper layer
- Moved all hook logic into consolidated hooks/*-hook.ts files
- Each hook now handles its own stdin/stdout/JSON wrapping
- Removed ALL try-catch blocks from context-hook (let errors surface)
- Updated build script to reference new src/hooks/ paths
- Reduced from 12+ files to 6 hook files
This simplifies the architecture and makes debugging actually possible.
Fixed better-sqlite3 distribution by implementing self-bootstrapping hooks
that auto-install dependencies on first run. This eliminates the need for
users to have native compilation tools or manually install dependencies.
## Solution
Instead of bundling 25MB of better-sqlite3 binaries in git or requiring
manual npm install, hooks now bootstrap themselves on first execution:
1. Created `src/shared/bootstrap.ts` with `ensureDependencies()` function
2. Added bootstrap calls to all hook entry points (context, new, save, summary, cleanup)
3. Created `plugin/scripts/package.json` declaring better-sqlite3 dependency
4. Bootstrap checks if `node_modules` exists, runs `npm install` if missing
5. npm automatically downloads prebuilt better-sqlite3 binary for user's platform
## Changes
**Core Bootstrap System:**
- Added src/shared/bootstrap.ts: Auto-install dependencies using npm
- Modified all hooks (context, new, save, summary, cleanup) to call ensureDependencies()
- Created plugin/scripts/package.json with better-sqlite3 dependency
**Build & Distribution:**
- Removed node_modules copying logic from build script
- Build output is now compact (hooks + package.json, no binaries)
- Updated marketplace.json to point to GitHub for direct installation
**Documentation:**
- Updated README: GitHub Marketplace installation is now recommended method
- Installation instructions emphasize no compilation needed
- Version bumped to 4.0.5 throughout
## Benefits
- ✅ No git bloat (repo stays small, no 25MB binaries committed)
- ✅ No compilation needed (npm downloads prebuilt binaries)
- ✅ Works on all platforms (npm handles platform-specific binaries)
- ✅ Zero manual steps (hooks bootstrap themselves automatically)
- ✅ Idempotent (skips install if dependencies already exist)
Installation now works via simple:
```
/plugin marketplace add https://github.com/thedotmack/claude-mem
/plugin install claude-mem
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
BREAKING CHANGES:
- Data directory moved from ~/.claude-mem/ to ${CLAUDE_PLUGIN_ROOT}/data/
- Fresh start required - no migration from v3.x databases
- Worker service now auto-starts on SessionStart hook
New Features:
- MCP Search Server with 6 specialized search tools
- FTS5 full-text search across observations and sessions
- Auto-starting worker service in SessionStart hook
- Citation support for search results (claude-mem:// URIs)
Changes:
- Updated paths.ts to use CLAUDE_PLUGIN_ROOT for data directory
- Added worker auto-start logic to context hook
- Updated worker service to write port file to plugin data dir
- Bumped version to 4.0.0 in package.json and plugin.json
- Created comprehensive CHANGELOG.md documenting v4.0.0 changes
- Updated README.md with v4.0.0 breaking changes and features
- Rebuilt all hooks and worker service
Technical Improvements:
- Improved error handling and graceful degradation
- Structured logging across all components
- Enhanced plugin integration with Claude Code
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Alex Newman