chore: bump version to 7.1.6

Improved error messages with platform-specific worker restart instructions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Refactor error handling to use platform-specific worker restart instructions
2025-12-13 17:08:16 -05:00 · 2025-12-13 17:06:45 -05:00 · 2025-12-13 16:54:24 -05:00 · 2025-12-13 16:53:00 -05:00 · 2025-12-13 16:19:18 -05:00 · 2025-12-13 15:55:46 -05:00
134 changed files with 19365 additions and 10083 deletions
@@ -10,7 +10,7 @@
  "plugins": [
    {
      "name": "claude-mem",
-      "version": "6.5.3",
+      "version": "7.1.6",
      "source": "./plugin",
      "description": "Persistent memory system for Claude Code - context compression across sessions"
    }
@@ -0,0 +1 @@
+github: [thedotmack]
@@ -0,0 +1,34 @@
+name: Summarize new issues
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  summary:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      models: read
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Run AI inference
+        id: inference
+        uses: actions/ai-inference@v1
+        with:
+          prompt: |
+            Summarize the following GitHub issue in one paragraph:
+            Title: ${{ github.event.issue.title }}
+            Body: ${{ github.event.issue.body }}
+
+      - name: Comment with AI summary
+        run: |
+          gh issue comment $ISSUE_NUMBER --body '${{ steps.inference.outputs.response }}'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          RESPONSE: ${{ steps.inference.outputs.response }}
@@ -0,0 +1,116 @@
+{
+  "sourceHash": "9ab0d799179c66f9",
+  "lastUpdated": "2025-12-12T07:42:03.489Z",
+  "translations": {
+    "zh": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:06:55.026Z",
+      "costUsd": 0.12256679999999998
+    },
+    "ja": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:06:55.026Z",
+      "costUsd": 0.12973164999999998
+    },
+    "pt-br": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:06:55.026Z",
+      "costUsd": 0.11508539999999999
+    },
+    "ko": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:06:55.026Z",
+      "costUsd": 0.13952664999999997
+    },
+    "es": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:06:55.026Z",
+      "costUsd": 0.12530165
+    },
+    "de": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:06:55.026Z",
+      "costUsd": 0.12232164999999998
+    },
+    "fr": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:06:55.026Z",
+      "costUsd": 0.11906665
+    },
+    "he": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:25:00.076Z",
+      "costUsd": 0.151329
+    },
+    "ar": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:25:00.076Z",
+      "costUsd": 0.151952
+    },
+    "ru": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:25:00.076Z",
+      "costUsd": 0.13418499999999997
+    },
+    "pl": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:25:00.076Z",
+      "costUsd": 0.13196799999999997
+    },
+    "cs": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:25:00.076Z",
+      "costUsd": 0.12714599999999998
+    },
+    "nl": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:25:00.076Z",
+      "costUsd": 0.118389
+    },
+    "tr": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:25:00.076Z",
+      "costUsd": 0.13991199999999998
+    },
+    "uk": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:25:00.076Z",
+      "costUsd": 0.13786
+    },
+    "vi": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:42:03.489Z",
+      "costUsd": 0.15467299999999998
+    },
+    "id": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:42:03.489Z",
+      "costUsd": 0.185581
+    },
+    "th": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:42:03.489Z",
+      "costUsd": 0.177859
+    },
+    "hi": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:42:03.489Z",
+      "costUsd": 0.17412700000000003
+    },
+    "bn": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:42:03.489Z",
+      "costUsd": 0.202735
+    },
+    "ro": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:42:03.489Z",
+      "costUsd": 0.12212875
+    },
+    "sv": {
+      "hash": "9ab0d799179c66f9",
+      "translatedAt": "2025-12-12T07:42:03.489Z",
+      "costUsd": 0.12143675000000001
+    }
+  }
+}
@@ -0,0 +1,167 @@
+# Action Plan: Issues & PRs Cleanup
+Generated: 2025-12-12
+
+## Phase 1: Immediate Cleanup (Today)
+
+### Close Obsolete PRs
+
+- [ ] **#255** - Close PR "Fix PM2 worker MODULE_NOT_FOUND"
+  - Reason: v7.1.0 removed PM2 entirely, this fix is no longer relevant
+  - Comment: Explain that v7.1.0 migration to Bun eliminated PM2 dependency
+
+- [ ] **#206** - Close or request update on "Harden worker startup"
+  - Reason: Contains PM2-specific code that no longer exists
+  - Comment: Ask author if they want to update for Bun architecture, otherwise close as obsolete
+
+### Close/Update Fixed Issues
+
+- [ ] **#213** - Comment and close "Windows endless process spawning"
+  - Reason: v7.1.0 Bun migration eliminated PM2 process management
+  - Comment: Ask user to verify fix on v7.1.0, explain PM2 removal resolved issue
+
+- [ ] **#229** - Close as duplicate
+  - Reason: Duplicate of #227 (upstream Claude Code bug)
+  - Comment: Direct to #227 for full details and workaround
+
+- [ ] **#211** - Answer and close "Cursor IDE support question"
+  - Reason: Product question, not a bug report
+  - Comment: Explain focus is Claude Code, but plugin architecture may allow future expansion
+
+### Critical Bug Follow-Up
+
+- [ ] **#254** - Follow up on "Worker API fetch failed"
+  - Current status: Asked about PM2 logs (pre-v7.1.0 comment)
+  - Action: Update comment asking:
+    - What version of claude-mem are you running?
+    - If pre-v7.1.0: Please upgrade to v7.1.0 which fixes PM2 issues
+    - If v7.1.0+: Run troubleshoot skill and share logs
+
+## Phase 2: High-Priority Merges (This Week)
+
+### Security & Critical Fixes
+
+- [ ] **#236** - Review and merge "Localhost-only binding" 🔒 PRIORITY
+  - Impact: Security improvement (fixes network exposure)
+  - Status: 156 additions, all tests pass (42/42)
+  - Action: Final review, merge, update CHANGELOG
+
+- [ ] **#212** - Review and merge "Windows path quoting fix"
+  - Impact: Fixes Windows usernames with spaces
+  - Status: 6 lines changed, minimal risk
+  - Action: Quick cross-platform test, merge
+
+### Major Features (Maintainer-Authored)
+
+- [ ] **#225** - Review and merge "Export/Import scripts"
+  - Impact: Enables backup/restore, partially addresses #233
+  - Status: 927 additions, extensively tested by maintainer
+  - Action: Final review, merge, update docs
+
+- [ ] **#250** - Review and merge "README translations"
+  - Impact: International user onboarding (22 languages)
+  - Status: 10,209 additions (massive but low-risk)
+  - Action: Spot-check a few translations, merge
+
+### User-Requested Features
+
+- [ ] **#252** - Test and merge "Execution traces" (addresses #194)
+  - Impact: Shows tools/skills/MCPs in UI bubbles
+  - Status: 383 additions, comprehensive implementation
+  - Action: Test database migration, API endpoints, UI display
+
+- [ ] **#251** - Test and merge "Plan file context" (addresses #180)
+  - Impact: Injects last plan file into context
+  - Status: 85 additions, follows existing patterns
+  - Action: Test with real plan files, verify toggle works
+
+## Phase 3: Review & Consider (Next Week)
+
+### Quality Enhancements
+
+- [ ] **#230** - Review "Multi-language support" (addresses #228)
+  - Impact: Observations/summaries in user's language
+  - Status: 157 additions, Korean screenshot provided
+  - Action: Review prompt changes carefully, test with multiple languages
+
+- [ ] **#226** - Review "CLAUDE_CONFIG_DIR support"
+  - Impact: Supports non-standard Claude installations
+  - Status: 10 additions, minimal change
+  - Action: Test with custom config directory, merge if working
+
+### Developer Experience
+
+- [ ] **#216** - Review "Makefile shortcuts"
+  - Impact: DX improvement for contributors
+  - Status: 1,085 additions
+  - Priority: Low (not urgent)
+  - Action: Review when time permits
+
+## Phase 4: Issue Follow-Ups (Ongoing)
+
+### Awaiting User Verification
+
+- [ ] **#209** - Follow up if no response on Windows worker startup
+  - Status: Already commented asking for v7.1.0 verification
+  - Action: Close if verified fixed, or investigate if still broken
+
+- [ ] **#231** - Follow up if no response on module resolution
+  - Status: Already commented asking for v7.1.0 verification
+  - Action: Close if verified fixed, or investigate if still broken
+
+### Upstream Bugs (Keep Open)
+
+- [ ] **#227** - Keep open as documented upstream bug
+  - Reason: Claude Code CLI uses invalid Windows paths
+  - Action: No action needed, workaround documented
+
+### Active Bugs (Investigate)
+
+- [ ] **#208** - Investigate "Windows console windows appearing"
+  - Priority: Medium (cosmetic but annoying)
+  - Action: Reproduce on Windows, identify root cause
+
+## Phase 5: Future Feature Planning
+
+### Feature Requests Without PRs
+
+- [ ] **#240** - Plan "Move MCP scaffolding to separate file"
+  - Type: Internal refactoring
+  - Priority: Low
+  - Action: Design approach when time permits
+
+- [ ] **#239** - Plan "Track git branch as metadata"
+  - Type: Context enhancement
+  - Priority: Medium
+  - Action: Design schema changes, discuss approach
+
+- [ ] **#215** - Plan "PreCompact event hook"
+  - Type: Power user feature
+  - Priority: Low
+  - Action: Evaluate use cases, design API
+
+- [ ] **#233** - Plan "Multi-device sync" (partial solution exists)
+  - Type: Major feature
+  - Note: PR #225 provides export/import, full sync is more complex
+  - Action: Determine if export/import is sufficient, or plan cloud sync
+
+## Summary
+
+### Quick Wins (Do Today)
+- Close 2 obsolete PRs (#255, #206)
+- Close 3 resolved/duplicate issues (#213, #229, #211)
+- Follow up on critical bug (#254)
+
+### High-Impact Merges (This Week)
+- Merge security fix (#236)
+- Merge 2 simple fixes (#212, #225)
+- Merge 2 major features (#250, #252, #251)
+
+### Expected Impact
+- **Security**: Localhost-only by default
+- **Functionality**: Export/import, execution traces, plan context
+- **UX**: Multi-language support, Windows fixes
+- **Clarity**: Clean backlog, remove PM2 confusion
+
+---
+
+**Next Review**: After Phase 2 completion, reassess remaining items
@@ -4,6 +4,323 @@ All notable changes to this project will be documented in this file.

 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

+## [7.1.5] - 2025-12-13
+
+## What's Changed
+
+* fix: Use getWorkerHost() instead of hardcoded localhost in MCP server (#276)
+
+### Bug Fix
+Fixes Windows IPv6 issue where `localhost` resolves to `::1` (IPv6) but worker binds to `127.0.0.1` (IPv4), causing MCP tool connections to fail.
+
+**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v7.1.4...v7.1.5
+
+## [7.1.4] - 2025-12-13
+
+## What's Changed
+
+* fix: add npm fallback when bun install fails with alias packages (#265)
+
+**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v7.1.3...v7.1.4
+
+## [7.1.3] - 2025-12-13
+
+## Bug Fixes
+
+### Smart Install Script Refactoring
+
+Refactored the smart-install.js script to improve code quality and maintainability:
+- Extracted common installation paths as top-level constants (BUN_COMMON_PATHS, UV_COMMON_PATHS)
+- Simplified installation check functions to delegate to dedicated path-finding helpers
+- Streamlined installation verification logic with clearer error messages
+- Removed redundant post-installation verification checks
+- Improved error propagation by removing unnecessary retry logic
+
+This refactoring reduces code duplication and makes the installation process more maintainable while preserving the same functionality for detecting Bun and uv binaries across platforms.
+
+## [7.1.2] - 2025-12-13
+
+## 🐛 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
+
+---
+
+**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v7.1.1...v7.1.2
+
+## [7.1.1] - 2025-12-13
+
+## 🚨 Critical Fixes
+
+### Windows 11 Bun Auto-Install Fixed
+- **Problem**: v7.1.0 had a chicken-and-egg bug where `bun smart-install.js` failed if Bun wasn't installed
+- **Solution**: SessionStart hook now uses `node` (always available) for smart-install.js
+- **Impact**: Fresh Windows installations now work out-of-box
+
+### Path Quoting for Windows
+- Fixed `hooks.json` to quote all paths
+- Prevents SyntaxError for usernames with spaces (e.g., "C:\Users\John Doe\")
+
+## ✨ New Feature
+
+### Automatic Worker Restart on Version Updates
+- Worker now automatically restarts when plugin version changes
+- No more manual `npm run worker:restart` needed after upgrades
+- Eliminates connection errors from running old worker code
+
+## 📝 Notes
+
+- **No manual actions required** - worker auto-restarts on next session start
+- All future upgrades will automatically restart the worker
+- Fresh installs on Windows 11 work correctly
+
+## 🔗 Links
+
+- [Full Changelog](https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md#711---2025-12-12)
+- [Documentation](https://docs.claude-mem.ai)
+
+## [7.1.0] - 2025-12-13
+
+## Major Architectural Migration
+
+This release completely replaces PM2 with native Bun-based process management and migrates from better-sqlite3 to bun:sqlite.
+
+### Key Changes
+
+**Process Management**
+- Replace PM2 with custom Bun-based ProcessManager
+- PID file-based process tracking
+- Automatic legacy PM2 process cleanup on all platforms
+
+**Database Driver**
+- Migrate from better-sqlite3 npm package to bun:sqlite runtime module
+- Zero native compilation required
+- Same API compatibility
+
+**Auto-Installation**
+- Bun runtime auto-installed if missing
+- uv (Python package manager) auto-installed for Chroma vector search
+- Smart installer with platform-specific methods (curl/PowerShell)
+
+### Migration
+
+**Automatic**: First hook trigger after update performs one-time PM2 cleanup and transitions to new architecture. No user action required.
+
+### Documentation
+
+Complete technical documentation in `docs/PM2-TO-BUN-MIGRATION.md`
+
+## [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
@@ -6,7 +6,7 @@

 Claude-mem is a Claude Code plugin providing persistent memory across sessions. It captures tool usage, compresses observations using the Claude Agent SDK, and injects relevant context into future sessions.

-**Current Version**: 6.5.3
+**Current Version**: 7.1.6

 ## Architecture

@@ -14,7 +14,7 @@ Claude-mem is a Claude Code plugin providing persistent memory across sessions.

 **Hooks** (`src/hooks/*.ts`) - TypeScript → ESM, built to `plugin/scripts/*-hook.js`

-**Worker Service** (`src/services/worker-service.ts`) - Express API on port 37777, PM2-managed, handles AI processing asynchronously
+**Worker Service** (`src/services/worker-service.ts`) - Express API on port 37777, Bun-managed, handles AI processing asynchronously

 **Database** (`src/services/sqlite/`) - SQLite3 at `~/.claude-mem/claude-mem.db` with FTS5 full-text search

@@ -42,11 +42,29 @@ Claude-mem is a Claude Code plugin providing persistent memory across sessions.

 **Viewer UI**: `npm run build && npm run sync-marketplace && npm run worker:restart`

-## Environment Variables
+## Configuration

+Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created with defaults on first run.
+
+**Core Settings:**
 - `CLAUDE_MEM_MODEL` - Model for observations/summaries (default: claude-haiku-4-5)
 - `CLAUDE_MEM_CONTEXT_OBSERVATIONS` - Observations injected at SessionStart (default: 50)
 - `CLAUDE_MEM_WORKER_PORT` - Worker service port (default: 37777)
+- `CLAUDE_MEM_WORKER_HOST` - Worker bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)
+
+**System Configuration:**
+- `CLAUDE_MEM_DATA_DIR` - Data directory location (default: ~/.claude-mem)
+- `CLAUDE_MEM_LOG_LEVEL` - Log verbosity: DEBUG, INFO, WARN, ERROR, SILENT (default: INFO)
+- `CLAUDE_MEM_PYTHON_VERSION` - Python version for uvx/chroma-mcp (default: 3.13, avoids onnxruntime compatibility issues with Python 3.14+)
+- `CLAUDE_CODE_PATH` - Path to Claude executable (default: auto-detect via 'which claude')
+
+**Settings File Format:**
+```json
+{
+  "CLAUDE_MEM_MODEL": "claude-haiku-4-5",
+  "CLAUDE_MEM_WORKER_PORT": "37777"
+}
+```

 ## File Locations

@@ -57,15 +75,28 @@ Claude-mem is a Claude Code plugin providing persistent memory across sessions.
 - **Chroma**: `~/.claude-mem/chroma/`
 - **Usage Logs**: `~/.claude-mem/usage-logs/usage-YYYY-MM-DD.jsonl`

+## Requirements
+
+- **Bun** >= 1.0 (all platforms - auto-installed if missing)
+- **uv** (all platforms - auto-installed if missing, provides Python for Chroma)
+- Node.js >= 18 (build tools only)
+
 ## Quick Reference

 ```bash
 npm run build                 # Compile TypeScript
 npm run sync-marketplace      # Copy to ~/.claude/plugins
-npm run worker:restart        # Restart PM2 worker
+npm run worker:restart        # Restart worker service
+npm run worker:status         # Check worker status
 npm run worker:logs           # View worker logs
-pm2 list                      # Check worker status
-pm2 delete claude-mem-worker  # Force clean start
 ```

 **Viewer UI**: http://localhost:37777
+**Worker Logs**: `~/.claude-mem/logs/worker-YYYY-MM-DD.log`
+
+## Documentation
+
+**Public Docs**: https://docs.claude-mem.ai (Mintlify)
+**Source**: `docs/public/` - MDX files, edit `docs.json` for navigation
+**Deploy**: Auto-deploys from GitHub on push to main
+**Local Dev**: `cd docs/public && npx mintlify dev`
@@ -27,6 +27,16 @@
  </a>
 </p>

+<p align="center">
+  <a href="https://trendshift.io/repositories/15496" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
+      <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
+    </picture>
+  </a>
+</p>
+
 <br>

 <p align="center">
@@ -71,6 +81,7 @@ Restart Claude Code. Context from previous sessions will automatically appear in
 - 📊 **Progressive Disclosure** - Layered memory retrieval with token cost visibility
 - 🔍 **Skill-Based Search** - Query your project history with mem-search skill (~2,250 token savings)
 - 🖥️ **Web Viewer UI** - Real-time memory stream at http://localhost:37777
+- 💻 **Claude Desktop Skill** - Search memory from Claude Desktop conversations
 - 🔒 **Privacy Control** - Use `<private>` tags to exclude sensitive content from storage
 - ⚙️ **Context Configuration** - Fine-grained control over what context gets injected
 - 🤖 **Automatic Operation** - No manual intervention required
@@ -108,7 +119,7 @@ npx mintlify dev
 - **[Architecture Evolution](https://docs.claude-mem.ai/architecture-evolution)** - The journey from v3 to v5
 - **[Hooks Architecture](https://docs.claude-mem.ai/hooks-architecture)** - How Claude-Mem uses lifecycle hooks
 - **[Hooks Reference](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook scripts explained
- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & PM2 management
+- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & Bun management
 - **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite schema & FTS5 search
 - **[Search Architecture](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybrid search with Chroma vector database

@@ -148,7 +159,7 @@ npx mintlify dev

 1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
 2. **Smart Install** - Cached dependency checker (pre-hook script, not a lifecycle hook)
-3. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by PM2
+3. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by Bun
 4. **SQLite Database** - Stores sessions, observations, summaries with FTS5 full-text search
 5. **mem-search Skill** - Natural language queries with progressive disclosure (~2,250 token savings vs MCP)
 6. **Chroma Vector Database** - Hybrid semantic + keyword search for intelligent context retrieval
@@ -262,7 +273,8 @@ See [CHANGELOG.md](CHANGELOG.md) for complete version history.

 - **Node.js**: 18.0.0 or higher
 - **Claude Code**: Latest version with plugin support
- **PM2**: Process manager (bundled - no global install required)
+- **Bun**: JavaScript runtime and process manager (auto-installed if missing)
+- **uv**: Python package manager for vector search (auto-installed if missing)
 - **SQLite 3**: For persistent storage (bundled)

 ---
@@ -306,17 +318,43 @@ See [CHANGELOG.md](CHANGELOG.md) for complete version history.

 ## Configuration

-**Model Selection:**
+Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created with defaults on first run.
+
+**Available Settings:**
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `CLAUDE_MEM_MODEL` | `claude-haiku-4-5` | AI model for observations |
+| `CLAUDE_MEM_WORKER_PORT` | `37777` | Worker service port |
+| `CLAUDE_MEM_WORKER_HOST` | `127.0.0.1` | Worker bind address (use `0.0.0.0` for remote access) |
+| `CLAUDE_MEM_DATA_DIR` | `~/.claude-mem` | Data directory location |
+| `CLAUDE_MEM_LOG_LEVEL` | `INFO` | Log verbosity (DEBUG, INFO, WARN, ERROR, SILENT) |
+| `CLAUDE_MEM_PYTHON_VERSION` | `3.13` | Python version for chroma-mcp |
+| `CLAUDE_CODE_PATH` | _(auto-detect)_ | Path to Claude executable |
+| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | `50` | Number of observations to inject at SessionStart |
+
+**Settings Management:**

 ```bash
+# Edit settings via CLI helper
 ./claude-mem-settings.sh
+
+# Or edit directly
+nano ~/.claude-mem/settings.json
+
+# View current settings
+curl http://localhost:37777/api/settings
 ```

-**Environment Variables:**
+**Settings File Format:**

- `CLAUDE_MEM_MODEL` - AI model for processing (default: claude-haiku-4-5)
- `CLAUDE_MEM_WORKER_PORT` - Worker port (default: 37777)
- `CLAUDE_MEM_DATA_DIR` - Data directory override (dev only)
+```json
+{
+  "CLAUDE_MEM_MODEL": "claude-haiku-4-5",
+  "CLAUDE_MEM_WORKER_PORT": "37777",
+  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "50"
+}
+```

 See [Configuration Guide](https://docs.claude-mem.ai/configuration) for details.

@@ -0,0 +1,44 @@
+---
+name: mem-search
+description: Search your persistent memory database from previous coding sessions. Use when asked about past work, decisions, bugs fixed, or development history.
+---
+
+## Overview
+
+Search your local memory database for past sessions, decisions, code changes, and development history. This skill uses the `mem-search` MCP server tools.
+
+## Available MCP tools
+
+Use these tools from the `mem-search` MCP server:
+
+| Tool | Description |
+|------|-------------|
+| `search` | Unified search across all memory types |
+| `decisions` | Find architectural/design decisions |
+| `changes` | Find code changes and refactorings |
+| `timeline` | Get observations around a specific point in time |
+| `find_by_file` | Find observations for specific files |
+| `find_by_type` | Filter by type (decision, bugfix, feature, refactor, discovery, change) |
+| `find_by_concept` | Find by concept tags |
+| `how_it_works` | Understand system architecture and design patterns |
+
+## Common parameters
+
+- `query` - Natural language search query
+- `limit` - Max results (1-100, default 20)
+- `format` - `index` for titles only (recommended), `full` for complete content
+- `type` - Filter: observations, sessions, or prompts
+- `obs_type` - Filter observation type: decision, bugfix, feature, refactor, discovery, change
+
+## When to use
+
+- "Did we already solve this?"
+- "How did we do X last time?"
+- "Find the bug fix for..."
+- "What decisions did we make about..."
+- "Show me changes to [file]"
+- "What work did we do on [project]?"
+
+## Setup requirement
+
+The `mem-search` MCP server must be configured in Claude Desktop settings. See MCP configuration docs.
@@ -0,0 +1,113 @@
+# Branch Switching Test Plan: feature/bun-executable
+
+## Overview
+This document validates that switching to the `feature/bun-executable` branch will be seamless for users.
+
+## Branch Switching Mechanism
+
+When a user switches branches via the Settings UI:
+
+1. **Branch Switch Request**: User selects `feature/bun-executable` from Settings UI
+2. **Validation**: SettingsRoutes validates branch name against allowed list
+3. **Git Operations**: BranchManager performs:
+   - Discard local changes (`git checkout -- .` and `git clean -fd`)
+   - Fetch from origin (`git fetch origin`)
+   - Checkout target branch (`git checkout feature/bun-executable`)
+   - Pull latest (`git pull origin feature/bun-executable`)
+4. **Install Dependencies**: 
+   - Clear install marker (`.install-version`)
+   - Run `npm install` (2 minute timeout)
+5. **Worker Restart**: Worker process exits and PM2/supervisor restarts it
+
+## Feature Branch Changes
+
+The `feature/bun-executable` branch makes these key changes:
+
+### Dependencies Removed
+- `better-sqlite3` → Uses Bun's built-in SQLite
+- `pm2` → Custom worker CLI with process management
+- `@types/better-sqlite3`
+
+### New Features
+- Auto-installation of Bun runtime in smart-install.js
+- Simplified worker management via worker-cli.js
+- No native module compilation required (better-sqlite3 removed)
+
+## Installation Validation
+
+### Current Branch → feature/bun-executable
+
+**Step 1: Branch Switch (BranchManager)**
+```bash
+git checkout feature/bun-executable
+git pull origin feature/bun-executable
+rm .install-version
+npm install  # ✅ Works - package.json is npm-compatible
+```
+
+**Step 2: First Hook Execution**
+```bash
+node plugin/scripts/context-hook.js
+  ↓
+Calls smart-install.js
+  ↓
+Checks if Bun installed → Auto-installs if missing
+  ↓
+Runs: bun install (if needed)
+```
+
+**Step 3: Worker Management**
+- Old: PM2 manages worker-service.cjs
+- New: worker-cli.js manages worker as background process
+- Transition: Automatic on first worker start command
+
+## Seamless Installation Checklist
+
+- [x] **Branch Validation**: `feature/bun-executable` added to allowedBranches list
+- [x] **npm install Compatible**: Feature branch package.json works with npm
+- [x] **No Breaking Changes**: No hooks that would fail on first run
+- [x] **Auto-Install**: smart-install.js automatically installs Bun if missing
+- [x] **Graceful Degradation**: Scripts fall back to node if Bun unavailable
+- [x] **No Manual Steps**: User just clicks "Switch Branch" in UI
+
+## Potential Issues & Mitigations
+
+### Issue 1: Bun Not in PATH After Install
+**Mitigation**: smart-install.js checks common Bun installation paths and provides clear instructions to user
+
+### Issue 2: PM2 vs Worker CLI Transition
+**Mitigation**: Old PM2 worker continues running, new worker CLI starts separately. User can manually stop old PM2 worker if needed.
+
+### Issue 3: Windows Compatibility
+**Mitigation**: Feature branch uses PowerShell installer for Windows, curl for Unix/macOS
+
+## Test Results
+
+### Unit Tests
+```bash
+✓ tests/branch-selector.test.ts (5 tests)
+  ✓ should allow main branch
+  ✓ should allow beta/7.0 branch
+  ✓ should allow feature/bun-executable branch
+  ✓ should reject invalid branch names
+  ✓ should have exactly 3 allowed branches
+```
+
+### Integration Tests
+```bash
+✓ All existing tests pass (42 tests)
+✓ No regressions introduced
+✓ TypeScript compilation successful
+```
+
+## Conclusion
+
+✅ **SEAMLESS INSTALLATION VALIDATED**
+
+The installation process is seamless because:
+1. Branch switching uses standard git operations
+2. `npm install` works on feature branch
+3. Bun auto-installs on first hook execution
+4. No manual intervention required
+5. Clear error messages if issues occur
+6. Backward compatible with existing installations
@@ -0,0 +1,561 @@
+# Claude-Mem Smart Install & Plugin Hooks - Comprehensive Analysis
+
+**Generated:** 2025-12-09
+**Scope:** Smart install system, all plugin hooks, cross-platform compatibility, error handling, edge cases
+
+---
+
+## Executive Summary
+
+This report provides a comprehensive analysis of claude-mem's smart install system and plugin hook infrastructure. The analysis focuses on cross-platform compatibility, error handling patterns, artificial blockers, and edge case handling.
+
+**Key Findings:**
+- ✅ Overall architecture is well-designed with clear separation of concerns
+- ⚠️ Multiple cross-platform compatibility issues identified
+- ⚠️ Several silent failure patterns that hinder debugging
+- ⚠️ Artificial blockers that could prevent legitimate use cases
+- ⚠️ Inconsistent timeout values across different components
+- ✅ No nested try-catch anti-patterns found
+
+---
+
+## Architecture Overview
+
+### Smart Install System Flow
+
+```
+User Invokes Hook
+    ↓
+ensureWorkerRunning() [worker-utils.ts]
+    ↓
+isWorkerHealthy() → fetch /health endpoint
+    ↓
+    ├─ [HEALTHY] → Continue
+    └─ [UNHEALTHY] → startWorker()
+        ↓
+        ├─ [Windows] → PowerShell Start-Process (hidden window)
+        └─ [Unix] → Bun start ecosystem.config.cjs
+            ↓
+        Wait for health check (15 retries × 1000ms)
+            ↓
+            ├─ [SUCCESS] → Continue
+            └─ [FAILURE] → Throw error with manual recovery instructions
+```
+
+### Plugin Hook Lifecycle
+
+1. **SessionStart** (context-hook.ts + user-message-hook.ts)
+   - context-hook: Fetches context via HTTP/curl
+   - user-message-hook: Displays context to user via stderr
+
+2. **UserPromptSubmit** (new-hook.ts)
+   - Creates/retrieves SDK session
+   - Strips privacy tags from prompt
+   - Initializes session via HTTP
+
+3. **PostToolUse** (save-hook.ts)
+   - Filters skipped tools
+   - Sends observation to worker via HTTP
+
+4. **Stop** (summary-hook.ts)
+   - Parses transcript JSONL
+   - Extracts last user/assistant messages
+   - Requests summary generation via HTTP
+
+5. **SessionEnd** (cleanup-hook.ts)
+   - Marks session complete
+   - Fire-and-forget HTTP request
+
+---
+
+## Cross-Platform Compatibility Issues
+
+### 🔴 CRITICAL: curl Dependency (context-hook.ts)
+
+**Location:** `src/hooks/context-hook.ts:32`
+
+```typescript
+const result = execSync(`curl -s "${url}"`, { encoding: "utf-8", timeout: 5000 });
+```
+
+**Issues:**
+1. **Windows Compatibility:** curl is not guaranteed to be available on Windows systems (though included in Windows 10 1803+, it may be missing on older systems or custom installations)
+2. **Error Handling:** No try-catch around execSync - will throw unhandled exception if curl fails
+3. **Redundancy:** Uses curl when JavaScript's native `fetch` is already used everywhere else in the codebase
+
+**Impact:** High - SessionStart hook will crash if curl is unavailable or returns non-zero exit code
+
+**Edge Cases:**
+- Corporate proxies blocking curl
+- Systems without curl in PATH
+- curl returning non-zero exit with valid output (warnings, etc.)
+
+**Recommendation:**
+```typescript
+// Replace curl with fetch (already used in user-message-hook.ts)
+const response = await fetch(url, { signal: AbortSignal.timeout(5000) });
+const result = await response.text();
+```
+
+---
+
+### 🟡 MEDIUM: Platform-Specific Process Spawning (worker-utils.ts)
+
+**Location:** `src/shared/worker-utils.ts:55-93`
+
+**Windows Implementation:**
+```typescript
+spawnSync('powershell.exe', [
+  '-NoProfile',
+  '-NonInteractive',
+  '-Command',
+  `Start-Process -FilePath 'node' -ArgumentList '${workerScript}' -WorkingDirectory '${MARKETPLACE_ROOT}' -WindowStyle Hidden`
+])
+```
+
+**Issues:**
+1. **PowerShell Dependency:** Assumes PowerShell is available and in PATH
+2. **Command Injection Risk:** Worker script path inserted directly into command string without escaping
+3. **Process Monitoring:** Windows approach launches detached process with no Bun monitoring - harder to debug/restart
+4. **Health Check Timeout:** Comment says "Windows needs longer timeouts" but timeout is same for all platforms (500ms)
+
+**Edge Cases:**
+- Windows systems with PowerShell execution policy restrictions
+- Paths containing single quotes or special characters
+- Windows subsystem for Linux (WSL) environments
+- Wine/Proton compatibility layers
+
+**Unix Implementation:**
+```typescript
+const localBunBase = path.join(MARKETPLACE_ROOT, 'node_modules', '.bin', 'bun');
+const bunCommand = existsSync(localBunBase) ? localBunBase : 'bun';
+```
+
+**Issues:**
+1. **Bun Dependency:** Falls back to global bun if local not found, but doesn't verify it exists
+2. **Silent Failure:** If Bun not installed globally, spawnSync will fail with cryptic ENOENT error
+
+**Recommendation:**
+- Add bun existence check before spawn
+- Implement consistent process monitoring across platforms
+- Add path escaping for Windows command construction
+- Actually implement longer timeout for Windows if needed
+
+---
+
+### 🟡 MEDIUM: Git Dependency (paths.ts)
+
+**Location:** `src/shared/paths.ts:89-97`
+
+```typescript
+export function getCurrentProjectName(): string {
+  try {
+    const gitRoot = execSync('git rev-parse --show-toplevel', {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore']
+    }).trim();
+    return basename(gitRoot);
+  } catch {
+    return basename(process.cwd());
+  }
+}
+```
+
+**Issues:**
+1. **Git Assumption:** Assumes git is installed and available in PATH
+2. **Non-Git Projects:** Silently falls back to cwd basename, but this behavior is undocumented
+
+**Edge Cases:**
+- Projects not using git
+- Monorepos where cwd !== git root is desired
+- Systems without git installed
+
+**Status:** ✅ Already handled with fallback, but could benefit from debug logging
+
+---
+
+## Error Handling Analysis
+
+### 🔴 CRITICAL: Silent Failures Without Logging
+
+#### 1. Settings File Loading (early-settings.ts:20-28)
+
+```typescript
+try {
+  if (existsSync(SETTINGS_PATH)) {
+    const data = JSON.parse(readFileSync(SETTINGS_PATH, 'utf-8'));
+    const fileValue = data.env?.[key];
+    if (fileValue !== undefined) return fileValue;
+  }
+} catch {
+  // Fail silently - fall through to env var
+}
+```
+
+**Problem:**
+- Invalid JSON in settings file fails silently
+- File read permission errors fail silently
+- Users have no way to know their settings file is being ignored
+
+**Impact:** High - Users may think settings are applied when they're actually using defaults
+
+**Recommendation:**
+```typescript
+} catch (error) {
+  logger.warn('SETTINGS', 'Failed to load settings file', { path: SETTINGS_PATH }, error);
+}
+```
+
+---
+
+#### 2. Worker Startup Failure (worker-utils.ts:104-107)
+
+```typescript
+try {
+  // ... worker startup logic ...
+} catch (error) {
+  // Failed to start worker
+  return false;
+}
+```
+
+**Problem:**
+- Catches ALL errors during worker startup
+- Returns boolean with no information about what failed
+- User only gets generic error after all retries exhausted
+
+**Impact:** High - Makes debugging worker startup issues extremely difficult
+
+**Recommendation:**
+```typescript
+} catch (error) {
+  logger.error('WORKER', 'Failed to start worker', {}, error as Error);
+  return false;
+}
+```
+
+---
+
+#### 3. Worker Health Check (worker-utils.ts:30-40)
+
+```typescript
+async function isWorkerHealthy(): Promise<boolean> {
+  try {
+    const port = getWorkerPort();
+    const response = await fetch(`http://127.0.0.1:${port}/health`, {
+      signal: AbortSignal.timeout(HEALTH_CHECK_TIMEOUT_MS)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+```
+
+**Problem:**
+- Network errors, timeouts, and non-200 responses all indistinguishable
+- No logging at all - completely silent
+
+**Impact:** Medium - Hard to debug why health checks fail
+
+**Recommendation:**
+```typescript
+} catch (error) {
+  logger.debug('WORKER', 'Health check failed', { port }, error);
+  return false;
+}
+```
+
+---
+
+#### 4. Tool Formatting (logger.ts:122-124)
+
+```typescript
+try {
+  const input = typeof toolInput === 'string' ? JSON.parse(toolInput) : toolInput;
+  // ...
+} catch {
+  return toolName;
+}
+```
+
+**Problem:**
+- Invalid JSON in tool input fails silently
+- Could mask data corruption issues
+
+**Impact:** Low - Only affects log formatting
+
+**Status:** ✅ Acceptable for log formatting, but could log at DEBUG level
+
+---
+
+### 🟢 GOOD: No Nested Try-Catch Anti-Patterns
+
+Analysis confirmed zero instances of nested try-catch blocks. Error handling is consistently at single level per function.
+
+---
+
+## Artificial Blockers & Unnecessary Checks
+
+### 🔴 CRITICAL: First-Run Detection (user-message-hook.ts:14-40)
+
+```typescript
+const nodeModulesPath = join(pluginDir, 'node_modules');
+
+if (!existsSync(nodeModulesPath)) {
+  // Show first-time setup message
+  console.error(`...`);
+  process.exit(3);
+}
+```
+
+**Problems:**
+1. **False Positive:** Will trigger if user manually deletes node_modules (e.g., for troubleshooting)
+2. **Installation Race:** Could fail if installation is still in progress
+3. **Hook-Level Check:** Runs on EVERY SessionStart, not just actual first run
+
+**Impact:** High - Prevents usage until node_modules exists, even if dependencies are installed elsewhere
+
+**Edge Cases:**
+- User runs `rm -rf node_modules` for troubleshooting
+- Package manager installation interrupted
+- Symlinked node_modules (some package managers)
+
+**Recommendation:**
+- Use a `.first-run-complete` marker file instead
+- Move check to npm postinstall script
+- Make check more robust (check for specific required modules)
+
+---
+
+### 🟡 MEDIUM: Overly Specific Validation (paths.ts:117-119)
+
+```typescript
+if (!existsSync(join(commandsDir, 'save.md'))) {
+  throw new Error('Package commands directory missing required files');
+}
+```
+
+**Problem:**
+- Checks for ONE specific file to validate entire directory
+- Hardcoded filename could break if files reorganized
+- Error message doesn't specify what's missing
+
+**Impact:** Medium - Could prevent package from working after internal refactoring
+
+**Recommendation:**
+- Remove check entirely (let actual command invocation fail with better error)
+- Or check all required files if validation is critical
+
+---
+
+### 🟡 MEDIUM: Duplicate Health Endpoints
+
+**Locations:**
+- `src/services/worker-service.ts:107` - `/api/health`
+- `src/services/worker/http/routes/ViewerRoutes.ts:27` - `/health`
+
+**Usage:**
+- `worker-utils.ts` uses `/health`
+- `mcp-server.ts` uses `/api/health`
+
+**Problem:**
+- Redundant endpoints doing the same thing
+- Inconsistent usage across codebase
+- Maintenance burden
+
+**Impact:** Low - Both work, but creates confusion
+
+**Recommendation:**
+- Standardize on `/api/health` (follows REST convention)
+- Remove `/health` endpoint
+- Update worker-utils.ts to use `/api/health`
+
+---
+
+## Timeout Configuration Issues
+
+### Inconsistent Timeouts Across Components
+
+| Component | Timeout | Location | Purpose |
+|-----------|---------|----------|---------|
+| Health check | 500ms | worker-utils.ts:13 | Check if worker alive |
+| Worker startup wait | 1000ms | worker-utils.ts:14 | Wait between health checks |
+| Worker startup retries | 15x | worker-utils.ts:15 | Max retries (15s total) |
+| Hook HTTP requests | 2000ms | cleanup-hook.ts:61, save-hook.ts:70, summary-hook.ts:164 | Send data to worker |
+| New hook session init | 5000ms | new-hook.ts:129 | Initialize session |
+| Context hook fetch | 5000ms | context-hook.ts:32 | Fetch context via curl |
+| User message hook | 5000ms | user-message-hook.ts:52 | Fetch context display |
+
+**Problems:**
+1. **Health Check Too Aggressive:** 500ms may be too short for loaded systems or slow network
+2. **No Platform Adjustment:** Comment says "Windows needs longer timeouts" but values are same
+3. **Hook Timeout Variation:** Some hooks use 2s, others use 5s with no clear reasoning
+
+**Recommendations:**
+- Increase health check timeout to 1000ms minimum
+- Actually implement longer timeouts for Windows
+- Standardize hook timeouts to 5000ms across the board
+- Make timeouts configurable via settings
+
+---
+
+## Edge Case Analysis
+
+### Handled Well ✅
+
+1. **JSONL Parsing:** summary-hook.ts continues on malformed lines (60-64, 117-121)
+2. **Git Not Available:** paths.ts falls back to cwd basename (89-97)
+3. **Settings File Missing:** early-settings.ts falls back to env vars and defaults (20-28)
+4. **Privacy Tags:** new-hook.ts handles fully-private prompts (99-109)
+5. **Tool Skipping:** save-hook.ts filters low-value tools (24-30)
+
+### Missing Edge Case Handling ⚠️
+
+1. **curl Failure:** context-hook.ts has no error handling for curl failures
+2. **Bun Not Installed:** worker-utils.ts assumes bun exists globally
+3. **PowerShell Restrictions:** worker-utils.ts doesn't check execution policy
+4. **Concurrent Worker Starts:** No locking to prevent multiple hooks from starting worker simultaneously
+5. **Port Already In Use:** No detection or recovery if worker port is taken
+6. **Zombie Processes:** Windows approach doesn't track PIDs, can't detect/kill zombies
+
+---
+
+## Recommendations Summary
+
+### High Priority 🔴
+
+1. **Replace curl with fetch** in context-hook.ts
+   - Eliminates external dependency
+   - Consistent with rest of codebase
+   - Better error handling
+
+2. **Add logging to silent failures**
+   - early-settings.ts: Log when settings file fails to load
+   - worker-utils.ts: Log startup failures with details
+   - worker-utils.ts: Log health check failures at debug level
+
+3. **Fix first-run detection**
+   - Use marker file instead of node_modules check
+   - More reliable and intentional
+
+### Medium Priority 🟡
+
+4. **Verify Bun availability** before attempting to use it
+   - Check existence before spawn
+   - Provide clear error message if missing
+
+5. **Implement platform-specific timeouts**
+   - Actually use longer timeouts on Windows as comment suggests
+   - Make timeouts configurable
+
+6. **Standardize health endpoints**
+   - Remove duplicate `/health` endpoint
+   - Use `/api/health` everywhere
+
+7. **Add path escaping** for Windows PowerShell commands
+   - Prevent injection issues
+   - Handle paths with special characters
+
+### Low Priority 🟢
+
+8. **Standardize HTTP timeouts** across all hooks
+9. **Add concurrent startup protection** (locking mechanism)
+10. **Improve error messages** with actionable recovery steps
+
+---
+
+## Testing Recommendations
+
+### Cross-Platform Testing Needed
+
+1. **Windows Environments:**
+   - Windows 10 (various versions)
+   - Windows 11
+   - Windows Server
+   - WSL/WSL2
+   - PowerShell execution policies (Restricted, RemoteSigned, Unrestricted)
+
+2. **Unix Environments:**
+   - macOS (Intel + Apple Silicon)
+   - Linux (Ubuntu, Fedora, Arch)
+   - FreeBSD
+
+3. **Edge Environments:**
+   - Docker containers
+   - CI/CD environments
+   - Systems without git installed
+   - Systems without curl (or with restricted curl)
+   - Corporate networks with proxies
+   - Low-spec systems (slow startup)
+
+### Test Scenarios
+
+1. **Cold Start:** First run with no existing data
+2. **Corrupt Settings:** Invalid JSON in settings.json
+3. **Missing Dependencies:** No Bun, no git, no curl
+4. **Port Conflicts:** Worker port already in use
+5. **Rapid Hook Invocations:** Multiple hooks trying to start worker simultaneously
+6. **Permission Issues:** Read-only filesystem, restricted execution
+7. **Network Issues:** Localhost blocked, slow network
+
+---
+
+## Code Quality Assessment
+
+### Strengths ✅
+
+- Clean separation of concerns (hooks → worker → database)
+- No nested try-catch anti-patterns
+- Consistent use of modern async/await
+- Good use of TypeScript for type safety
+- Idempotent database operations
+- Clear documentation in critical sections
+
+### Weaknesses ⚠️
+
+- Silent failures hinder debugging
+- Inconsistent error handling patterns
+- Platform-specific code not fully tested/documented
+- Timeout configuration hardcoded and inconsistent
+- Some artificial blockers prevent legitimate use cases
+
+### Technical Debt
+
+- Duplicate health endpoints
+- curl dependency when fetch available
+- Bun dependency on Unix but not Windows (inconsistent monitoring)
+- First-run detection using node_modules existence
+- Hardcoded timeout values
+
+---
+
+## Conclusion
+
+The claude-mem smart install and plugin hook system is architecturally sound with a well-designed separation of concerns. However, several cross-platform compatibility issues and silent failure patterns could cause problems in production, particularly on Windows systems or in edge case scenarios.
+
+The highest priority improvements are:
+1. Removing the curl dependency
+2. Adding proper logging to silent failures
+3. Fixing the fragile first-run detection
+4. Verifying external dependencies before use
+
+These changes would significantly improve debuggability and cross-platform reliability without requiring major architectural changes.
+
+---
+
+**Analysis Methodology:**
+- Systematic review of all TypeScript source files
+- Static analysis of error handling patterns
+- Cross-platform compatibility assessment
+- Edge case identification through code path analysis
+- Comparison against best practices and KISS principles
+
+**Files Analyzed:**
+- src/hooks/*.ts (6 files)
+- src/services/worker-service.ts
+- src/services/worker/*.ts (10+ files)
+- src/servers/mcp-server.ts
+- src/shared/*.ts (worker-utils, early-settings, paths)
+- src/utils/*.ts (logger, silent-debug, tag-stripping)
@@ -0,0 +1,83 @@
+# Claude-Mem Hooks Cleanup Todo
+
+## ✅ Phase 1: Delete Dead Code (Modified)
+
+**hook-response.ts**
+
+- [ ] Remove `| string` from HookType union to restore type safety
+- [ ] Delete PreCompact branch (lines 23-36, 14 lines)
+- [x] ~~Delete pointless branches~~ — SKIP (intentional)
+- [x] ~~Simplify wrapper function~~ — SKIP (intentional)
+
+**new-hook.ts**
+
+- [ ] Delete 34-line architecture comment block (lines 1-34)
+- [ ] Replace 18 lines of debug logging with single 4-line log call (lines 64-81)
+
+**cleanup-hook.ts**
+
+- [ ] Remove `cwd`, `transcript_path`, `hook_event_name` from SessionEndInput interface
+- [ ] Replace 12-line manual mode help with simple error throw
+
+**user-message-hook.ts**
+
+- [ ] Delete all 40 lines of expired announcement code (lines 31-70)
+- [ ] Add comment explaining exit code 3: `// exit code 3 = show user message that Claude does NOT receive as context`
+
+---
+
+## ✅ Phase 2: Extract Shared Utilities
+
+- [ ] Create `src/shared/hook-error-handler.ts` with `handleWorkerError()`
+- [ ] Update all 4 hooks to use shared error handler (context-hook, new-hook, save-hook, summary-hook)
+- [ ] Create `src/shared/transcript-parser.ts` — merge `extractLastUserMessage` + `extractLastAssistantMessage` into single parameterized function
+- [ ] Create `src/shared/hook-constants.ts` for exit codes, timeouts
+
+---
+
+## ❌ Phase 3: SKIPPED
+
+_(Entry points stay as-is, hook-response.ts wrapper stays as-is)_
+
+---
+
+## ✅ Phase 4: Restore Type Safety
+
+**context-hook.ts**
+
+- [ ] Make `session_id`, `cwd`, `transcript_path` required in SessionStartInput
+- [ ] Remove `[key: string]: any`
+- [ ] Remove unused `source` field
+- [ ] Keep using `happy_path_error__with_fallback` for defaults (hooks use exit codes, logging tool is appropriate)
+
+**All 4 hook interfaces**
+
+- [ ] Remove `[key: string]: any` from all interfaces
+
+**save-hook.ts**
+
+- [ ] Keep `happy_path_error__with_fallback` usage (it's appropriate for hook context)
+
+**summary-hook.ts**
+
+- [ ] Add timeout (2s) and error logging to spinner stop request
+
+---
+
+## ✅ Phase 5: Relocate Business Logic (Modified)
+
+- [ ] Move `SKIP_TOOLS` from save-hook.ts to worker service
+- [ ] Make `SKIP_TOOLS` configurable via settings.json
+- [x] ~~Move announcements to database~~ — SKIP
+- [x] ~~Merge context-hook + user-message-hook~~ — SKIP (intentionally separate)
+
+---
+
+## Summary
+
+| Action            | Count |
+| ----------------- | ----- |
+| Lines to delete   | ~150  |
+| New shared files  | 3     |
+| Interfaces to fix | 4     |
+| Items skipped     | 5     |
@@ -1,4 +1,9 @@
-# Architecture Evolution: The Journey from v3 to v5
+---
+title: "Architecture Evolution"
+description: "How claude-mem evolved from v3 to v5+"
+---
+
+# Architecture Evolution

 ## The Problem We Solved

@@ -46,22 +51,15 @@ const ThemeProvider = ({ children }) => {

 **Why It Matters**: Users working in different lighting conditions can now customize the viewer for comfort.

-### v5.1.1: PM2 Windows Fix (November 2025)
+### v5.1.1: Worker Startup Fix (November 2025) - Now Deprecated

-**The Problem**: PM2 startup failed on Windows with ENOENT error
+**Note**: This section describes a historical PM2-based approach that has been replaced with Bun in later versions.

-**Root Cause**:
-```typescript
-// ❌ Failed on Windows - PM2 not in PATH
-execSync('pm2 start ecosystem.config.cjs');
-```
+**The Problem**: Worker startup failed on Windows with ENOENT error when using PM2

-**The Fix**:
-```typescript
-// ✅ Use full path to PM2 binary
-const PM2_PATH = join(PLUGIN_ROOT, 'node_modules', '.bin', 'pm2');
-execSync(`"${PM2_PATH}" start "${ECOSYSTEM_CONFIG}"`);
-```
+**Historical Solution**: Used full path to PM2 binary instead of relying on PATH
+
+**Current Approach**: The project now uses Bun for process management, which provides better cross-platform compatibility and eliminates these PATH-related issues.

 **Impact**: Cross-platform compatibility restored, Windows users can now use claude-mem without issues.

@@ -158,7 +156,7 @@ if (currentVersion !== installedVersion) {
 **Cached Check Logic**:
 1. Does `node_modules` exist?
 2. Does `.install-version` match `package.json` version?
-3. Is `better-sqlite3` present?
+3. Is `better-sqlite3` present? (Legacy: now uses bun:sqlite which requires no installation)

 **Impact**:
 - SessionStart hook: 2-5 seconds → 10ms (99.5% faster)
@@ -203,7 +201,7 @@ async function ensureWorkerHealthy() {
 **Key Fixes**:
 - Fixed race conditions in observation queue processing
 - Improved error handling in SDK worker
- Better cleanup of stale PM2 processes
+- Better cleanup of stale worker processes
 - Enhanced logging for debugging

 ### v5.0.0: Hybrid Search Architecture (October 2025)
@@ -520,7 +518,7 @@ const response = query({

    **Key change from v3:**
    - ✅ Stores raw prompts for search
-    - ✅ Auto-starts PM2 worker
+    - ✅ Auto-starts worker service
  </Tab>

  <Tab title="PostToolUse">
@@ -1062,7 +1060,7 @@ The result is a memory system that's both powerful and invisible. Users never no
 - [Progressive Disclosure](progressive-disclosure) - The philosophy behind v4
 - [Hooks Architecture](hooks-architecture) - How hooks power the system
 - [Context Engineering](context-engineering) - Foundational principles
- [Viewer UI](VIEWER) - Real-time visualization (v5.1.0+)
+- [Worker Service](/architecture/worker-service) - Real-time visualization (v5.1.0+)

 ---

@@ -5,17 +5,17 @@ description: "SQLite schema, FTS5 search, and data storage"

 # Database Architecture

-Claude-Mem uses SQLite 3 with the better-sqlite3 native module for persistent storage and FTS5 for full-text search.
+Claude-Mem uses SQLite 3 with the bun:sqlite native module for persistent storage and FTS5 for full-text search.

 ## Database Location

- **Current**: `~/.claude-mem/claude-mem.db`
+**Path**: `~/.claude-mem/claude-mem.db`

-**Note**: Despite the README claiming v4.0.0+ moved the database to `${CLAUDE_PLUGIN_ROOT}/data/`, the actual implementation still uses `~/.claude-mem/`.
+The database uses SQLite's WAL (Write-Ahead Logging) mode for concurrent reads/writes.

 ## Database Implementation

-**Primary Implementation**: better-sqlite3 (native SQLite module)
+**Primary Implementation**: bun:sqlite (native SQLite module)
 - Used by: SessionStore and SessionSearch
 - Format: Synchronous API with better performance
 - **Note**: Database.ts (using bun:sqlite) is legacy code
@@ -301,8 +301,8 @@ Database schema is managed via migrations in `src/services/sqlite/migrations.ts`
 - **Indexes**: All foreign keys and frequently queried columns are indexed
 - **FTS5**: Full-text search is significantly faster than LIKE queries
 - **Triggers**: Automatic synchronization has minimal overhead
- **Connection Pooling**: better-sqlite3 reuses connections efficiently
- **Synchronous API**: better-sqlite3 uses synchronous API for better performance
+- **Connection Pooling**: bun:sqlite reuses connections efficiently
+- **Synchronous API**: bun:sqlite uses synchronous API for better performance

 ## Troubleshooting

@@ -22,14 +22,14 @@ Claude-Mem operates as a Claude Code plugin with five core components:
 |------------------------|-------------------------------------------|
 | **Language**           | TypeScript (ES2022, ESNext modules)       |
 | **Runtime**            | Node.js 18+                               |
-| **Database**           | SQLite 3 with better-sqlite3 driver       |
+| **Database**           | SQLite 3 with bun:sqlite driver           |
 | **Vector Store**       | ChromaDB (optional, for semantic search)  |
 | **HTTP Server**        | Express.js 4.18                           |
 | **Real-time**          | Server-Sent Events (SSE)                  |
 | **UI Framework**       | React + TypeScript                        |
 | **AI SDK**             | @anthropic-ai/claude-agent-sdk            |
 | **Build Tool**         | esbuild (bundles TypeScript)              |
-| **Process Manager**    | PM2                                       |
+| **Process Manager**    | Bun                                       |
 | **Testing**            | Node.js built-in test runner              |

 ## Data Flow
@@ -70,7 +70,7 @@ User Query → mem-search Skill Invoked → HTTP API → SessionSearch Service
                              ↓
 ┌─────────────────────────────────────────────────────────────────┐
 │ 1. Session Starts → Context Hook Fires                          │
-│    Starts PM2 worker if needed, injects context from previous   │
+│    Starts Bun worker if needed, injects context from previous   │
 │    sessions (configurable observation count)                    │
 └─────────────────────────────────────────────────────────────────┘
                              ↓
@@ -177,13 +177,13 @@ claude-mem/
 │
 ├── tests/                      # Test suite
 ├── docs/                       # Documentation
-└── ecosystem.config.cjs        # PM2 configuration
+└── ecosystem.config.cjs        # Process configuration (deprecated)
 ```

 ## Component Details

 ### 1. Plugin Hooks (6 Hooks)
- **context-hook.js** - SessionStart: Starts PM2 worker, injects context
+- **context-hook.js** - SessionStart: Starts Bun worker, injects context
 - **user-message-hook.js** - UserMessage: Debugging hook
 - **new-hook.js** - UserPromptSubmit: Creates session, saves prompt
 - **save-hook.js** - PostToolUse: Captures tool executions
@@ -200,12 +200,12 @@ Express.js HTTP server on port 37777 (configurable) with:
 - 8 viewer UI HTTP/SSE endpoints
 - Async observation processing via Claude Agent SDK
 - Real-time updates via Server-Sent Events
- Auto-managed by PM2 process manager
+- Auto-managed by Bun

 See [Worker Service](/architecture/worker-service) for HTTP API and endpoints.

 ### 3. Database Layer
-SQLite3 with better-sqlite3 driver featuring:
+SQLite3 with bun:sqlite driver featuring:
 - FTS5 virtual tables for full-text search
 - SessionStore for CRUD operations
 - SessionSearch for FTS5 queries
@@ -0,0 +1,551 @@
+---
+title: "PM2 to Bun Migration"
+description: "Complete technical documentation for the process management and database driver migration in v7.1.0"
+---
+
+# PM2 to Bun Migration: Complete Technical Documentation
+
+**Version**: 7.1.0
+**Date**: December 2025
+**Migration Type**: Process Management (PM2 → Bun) + Database Driver (better-sqlite3 → bun:sqlite)
+
+## Executive Summary
+
+Claude-mem version 7.1.0 introduces two major architectural migrations:
+
+1. **Process Management**: PM2 → Custom Bun-based ProcessManager
+2. **Database Driver**: better-sqlite3 npm package → bun:sqlite runtime module
+
+Both migrations are **automatic** and **transparent** to end users. The first time a hook fires after updating to 7.1.0+, the system performs a one-time cleanup of legacy PM2 processes and transitions to the new architecture.
+
+### Key Benefits
+
+- **Simplified Dependencies**: Removes PM2 and better-sqlite3 npm packages
+- **Improved Cross-Platform Support**: Better Windows compatibility
+- **Faster Installation**: No native module compilation required
+- **Built-in Runtime**: Leverages Bun's built-in process management and SQLite
+- **Reduced Complexity**: Custom ProcessManager is simpler than PM2 integration
+
+### Migration Impact
+
+- **Data Preservation**: User data, settings, and database remain unchanged
+- **Automatic Cleanup**: Old PM2 processes automatically terminated (all platforms)
+- **No User Action Required**: Migration happens automatically on first hook trigger
+- **Backward Compatible**: SQLite database format unchanged (only driver changed)
+
+## Architecture Comparison
+
+### Old System (PM2-based)
+
+<AccordionGroup>
+<Accordion title="Process Management (PM2)">
+**Component**: PM2 (Process Manager 2)
+- **Package**: `pm2` npm dependency
+- **Process Name**: `claude-mem-worker`
+- **Management**: External PM2 daemon manages lifecycle
+- **Discovery**: `pm2 list`, `pm2 describe` commands
+- **Auto-restart**: PM2 automatically restarts on crash
+- **Logs**: `~/.pm2/logs/claude-mem-worker-*.log`
+- **PID File**: `~/.pm2/pids/claude-mem-worker.pid`
+
+**Lifecycle Commands**:
+```bash
+pm2 start <script>           # Start worker
+pm2 stop claude-mem-worker   # Stop worker
+pm2 restart claude-mem-worker # Restart worker
+pm2 delete claude-mem-worker  # Remove from PM2
+pm2 logs claude-mem-worker    # View logs
+```
+
+**Pain Points**:
+- Additional npm dependency required
+- PM2 daemon must be running
+- Potential conflicts with other PM2 processes
+- Windows compatibility issues
+- Complex configuration for simple use case
+</Accordion>
+
+<Accordion title="Database Driver (better-sqlite3)">
+**Component**: better-sqlite3
+- **Package**: `better-sqlite3` npm package (native module)
+- **Installation**: Requires native compilation (node-gyp)
+- **Windows**: Requires Visual Studio build tools + Python
+- **Import**: `import Database from 'better-sqlite3'`
+
+**Installation Requirements**:
+- Node.js development headers
+- C++ compiler (gcc/clang on Mac/Linux, MSVC on Windows)
+- Python (for node-gyp)
+- Windows: Visual Studio Build Tools
+</Accordion>
+</AccordionGroup>
+
+### New System (Bun-based)
+
+<AccordionGroup>
+<Accordion title="Process Management (Custom ProcessManager)">
+**Component**: Custom ProcessManager (`src/services/process/ProcessManager.ts`)
+- **Package**: Built-in Bun APIs (no external dependency)
+- **Process Spawn**: `Bun.spawn()` with detached mode
+- **Management**: Direct process control via PID file
+- **Discovery**: PID file + process existence check + HTTP health check
+- **Auto-restart**: Hook-triggered restart on failure detection
+- **Logs**: `~/.claude-mem/logs/worker-YYYY-MM-DD.log`
+- **PID File**: `~/.claude-mem/.worker.pid`
+- **Port File**: `~/.claude-mem/.worker.port` (new)
+
+**Lifecycle Commands**:
+```bash
+npm run worker:start    # Start worker
+npm run worker:stop     # Stop worker
+npm run worker:restart  # Restart worker
+npm run worker:status   # Check status
+npm run worker:logs     # View logs
+```
+
+**Core Mechanisms**:
+
+1. **PID File Management**:
+   - File: `~/.claude-mem/.worker.pid`
+   - Content: Process ID (e.g., "35557")
+   - Validation: Process existence via `kill(pid, 0)` signal
+
+2. **Port File Management**:
+   - File: `~/.claude-mem/.worker.port`
+   - Content: Two lines (port number, PID)
+   - Purpose: Track port binding and validate PID match
+
+3. **Health Checking**:
+   - Layer 1: PID file exists?
+   - Layer 2: Process alive? (`kill(pid, 0)`)
+   - Layer 3: HTTP health check (`GET /health`)
+   - All three must pass for "healthy" status
+
+**Advantages**:
+- No external dependencies
+- Simpler codebase (direct control)
+- Better error handling and validation
+- Platform-agnostic (Bun handles platform differences)
+</Accordion>
+
+<Accordion title="Database Driver (bun:sqlite)">
+**Component**: bun:sqlite
+- **Package**: Built into Bun runtime (no npm package)
+- **Installation**: None required (comes with Bun ≥1.0)
+- **Platform**: Works anywhere Bun works
+- **Import**: `import { Database } from 'bun:sqlite'`
+- **API**: Similar to better-sqlite3 (synchronous)
+
+**Installation Requirements**:
+- Bun ≥1.0 (automatically installed if missing)
+- No native compilation required
+- No platform-specific build tools needed
+
+**Compatibility**:
+- SQLite database format: **Unchanged**
+- Database file: `~/.claude-mem/claude-mem.db` (same location)
+- Query syntax: **Identical** (both use SQLite SQL)
+</Accordion>
+</AccordionGroup>
+
+## Migration Mechanics
+
+### One-Time PM2 Cleanup
+
+The migration system uses a marker-based approach to perform PM2 cleanup exactly once.
+
+**Implementation**: `src/shared/worker-utils.ts:73-86`
+
+```typescript
+// Clean up legacy PM2 (one-time migration)
+const pm2MigratedMarker = join(DATA_DIR, '.pm2-migrated');
+
+if (!existsSync(pm2MigratedMarker)) {
+  try {
+    spawnSync('pm2', ['delete', 'claude-mem-worker'], { stdio: 'ignore' });
+    // Mark migration as complete
+    writeFileSync(pm2MigratedMarker, new Date().toISOString(), 'utf-8');
+    logger.debug('SYSTEM', 'PM2 cleanup completed and marked');
+  } catch {
+    // PM2 not installed or process doesn't exist - still mark as migrated
+    writeFileSync(pm2MigratedMarker, new Date().toISOString(), 'utf-8');
+  }
+}
+```
+
+### Migration Trigger Points
+
+<Steps>
+<Step title="Hook Execution">
+SessionStart, UserPromptSubmit, or PostToolUse hooks execute using new 7.1.0 code
+</Step>
+<Step title="Worker Status Check">
+`ensureWorkerRunning()` checks if `~/.claude-mem/.worker.pid` exists (it doesn't for first run after update)
+</Step>
+<Step title="Start Worker Decision">
+Worker not running → Call `startWorker()`
+</Step>
+<Step title="Migration Check">
+Check if `~/.claude-mem/.pm2-migrated` exists
+</Step>
+<Step title="PM2 Cleanup">
+Execute `pm2 delete claude-mem-worker` (errors ignored), create marker file
+</Step>
+<Step title="New Worker Start">
+Spawn new Bun-managed worker process with PID and port files
+</Step>
+</Steps>
+
+### Marker File
+
+**Location**: `~/.claude-mem/.pm2-migrated`
+
+**Content**: ISO 8601 timestamp
+```
+2025-12-13T00:18:39.673Z
+```
+
+**Purpose**:
+- One-time migration flag
+- Prevents repeated PM2 cleanup on every start
+- Persists across restarts and reboots
+
+**Lifecycle**:
+- Created: First hook trigger after update to 7.1.0+ (all platforms)
+- Updated: Never
+- Deleted: Never (user could manually delete to force re-migration)
+
+## User Experience Timeline
+
+### First Session After Update
+
+<Note>
+This is the critical migration moment. The process takes approximately 2-5 seconds.
+</Note>
+
+**Step-by-Step Execution**:
+
+1. **Hook fires** (SessionStart most common)
+2. **Worker status check**: No PID file → worker not running
+3. **Migration check**: No marker file → run PM2 cleanup
+4. **PM2 cleanup**: `pm2 delete claude-mem-worker` (old worker terminated)
+5. **Marker creation**: `~/.claude-mem/.pm2-migrated` with timestamp
+6. **New worker start**: Bun process spawned, PID/port files created
+7. **Verification**: Process check + HTTP health check
+8. **Hook completes**: Claude Code session starts normally
+
+**User Observable Behavior**:
+- Slight delay on first startup (PM2 cleanup + new worker spawn)
+- No error messages (cleanup failures silently handled)
+- Worker appears running via `npm run worker:status`
+- Old PM2 worker no longer in `pm2 list`
+
+### Subsequent Sessions
+
+After migration completes, every hook trigger follows the fast path:
+
+1. PID file exists? **YES**
+2. Process alive? **YES**
+3. HTTP health check? **SUCCESS**
+4. Result: Worker already running, done (~50ms)
+
+No migration logic runs on subsequent sessions.
+
+## Platform-Specific Behavior
+
+### Platform Comparison
+
+| Feature | macOS | Linux | Windows |
+|---------|-------|-------|---------|
+| PM2 Cleanup | Attempted | Attempted | Attempted |
+| Marker File | Created | Created | Created |
+| Process Signals | POSIX (native) | POSIX (native) | Bun abstraction |
+| Bun Support | Full | Full | Full |
+| PID File | Yes | Yes | Yes |
+| Port File | Yes | Yes | Yes |
+| Health Check | HTTP | HTTP | HTTP |
+| Migration Delay | ~2-5s first time | ~2-5s first time | ~2-5s first time |
+
+### Platform Notes
+
+<Tabs>
+<Tab title="macOS">
+- POSIX signal handling works natively
+- Bun fully supported
+- No platform-specific workarounds needed
+</Tab>
+<Tab title="Linux">
+- Identical behavior to macOS
+- POSIX signal handling
+- Works on Ubuntu, Debian, RHEL, CentOS, Arch
+- Alpine may require glibc (not musl)
+</Tab>
+<Tab title="Windows">
+- PM2 cleanup now runs (safe due to try/catch)
+- Bun abstracts signal handling differences
+- Path module handles Windows separators
+- File locking handled by SQLite
+</Tab>
+</Tabs>
+
+## Observable Changes
+
+### Command Changes
+
+| Old (PM2) | New (Bun) | Notes |
+|-----------|-----------|-------|
+| `pm2 list` | `npm run worker:status` | Shows worker status |
+| `pm2 start <script>` | `npm run worker:start` | Start worker |
+| `pm2 stop claude-mem-worker` | `npm run worker:stop` | Stop worker |
+| `pm2 restart claude-mem-worker` | `npm run worker:restart` | Restart worker |
+| `pm2 delete claude-mem-worker` | `npm run worker:stop` | Remove worker |
+| `pm2 logs claude-mem-worker` | `npm run worker:logs` | View logs |
+| `pm2 describe claude-mem-worker` | `npm run worker:status` | Detailed status |
+| `pm2 monit` | No equivalent | PM2-specific monitoring |
+
+### File Location Changes
+
+**Logs**:
+```
+Old: ~/.pm2/logs/claude-mem-worker-out.log
+     ~/.pm2/logs/claude-mem-worker-error.log
+
+New: ~/.claude-mem/logs/worker-YYYY-MM-DD.log
+```
+
+**PID Files**:
+```
+Old: ~/.pm2/pids/claude-mem-worker.pid
+
+New: ~/.claude-mem/.worker.pid
+```
+
+**Process State**:
+```
+Old: PM2 daemon memory (pm2 save)
+
+New: ~/.claude-mem/.worker.pid
+     ~/.claude-mem/.worker.port
+     ~/.claude-mem/.pm2-migrated (all platforms)
+```
+
+**Database** (unchanged):
+```
+Same: ~/.claude-mem/claude-mem.db
+```
+
+### User-Visible Changes
+
+**Before Update**:
+```bash
+$ pm2 list
+┌────┬────────────────────┬─────────┬─────────┬──────────┐
+│ id │ name               │ status  │ restart │ uptime   │
+├────┼────────────────────┼─────────┼─────────┼──────────┤
+│ 0  │ claude-mem-worker  │ online  │ 0       │ 2d 5h    │
+└────┴────────────────────┴─────────┴─────────┴──────────┘
+```
+
+**After Update**:
+```bash
+$ pm2 list
+# Empty - worker no longer managed by PM2
+
+$ npm run worker:status
+Worker is running
+PID: 35557
+Port: 37777
+Uptime: 2h 15m
+```
+
+### Orphaned Files
+
+After migration, these PM2 files may remain (safe to delete):
+
+```
+~/.pm2/                    # Entire PM2 directory
+~/.pm2/logs/               # Old logs
+~/.pm2/pids/               # Old PID files
+~/.pm2/pm2.log             # PM2 daemon log
+~/.pm2/dump.pm2            # PM2 process dump
+```
+
+**Cleanup (optional)**:
+```bash
+# Remove PM2 entirely (if not used for other processes)
+pm2 kill
+rm -rf ~/.pm2
+
+# Or just remove claude-mem logs
+rm -f ~/.pm2/logs/claude-mem-worker-*.log
+rm -f ~/.pm2/pids/claude-mem-worker.pid
+```
+
+## File System State
+
+### State Directory Structure
+
+**Before Migration** (PM2 system):
+```
+~/.claude-mem/
+├── claude-mem.db          # Database (unchanged)
+├── chroma/                # Vector embeddings (unchanged)
+├── logs/                  # Application logs (unchanged)
+└── settings.json          # User settings (unchanged)
+
+~/.pm2/
+├── logs/
+│   ├── claude-mem-worker-out.log
+│   └── claude-mem-worker-error.log
+├── pids/
+│   └── claude-mem-worker.pid
+└── pm2.log
+```
+
+**After Migration** (Bun system):
+```
+~/.claude-mem/
+├── claude-mem.db          # Database (same file)
+├── chroma/                # Vector embeddings (unchanged)
+├── logs/
+│   └── worker-2025-12-13.log  # New log format
+├── settings.json          # User settings (unchanged)
+├── .worker.pid            # NEW: Process ID
+├── .worker.port           # NEW: Port + PID
+└── .pm2-migrated          # NEW: Migration marker (all platforms)
+
+~/.pm2/                    # Orphaned (safe to delete)
+├── logs/                  # Old logs (no longer written)
+├── pids/                  # Old PID (no longer updated)
+└── pm2.log                # PM2 daemon log (not used)
+```
+
+## Edge Cases and Troubleshooting
+
+### Scenario 1: Migration Fails (PM2 Still Running)
+
+<Warning>
+This is rare but can happen if PM2 has watch mode enabled or the process is manually restarted.
+</Warning>
+
+**Symptoms**:
+- `pm2 list` still shows `claude-mem-worker`
+- Port conflict errors in logs
+- Worker fails to start
+
+**Resolution**:
+```bash
+# Manual cleanup
+pm2 delete claude-mem-worker
+pm2 save  # Persist the deletion
+
+# Force re-migration (optional)
+rm ~/.claude-mem/.pm2-migrated
+
+# Restart worker
+npm run worker:restart
+```
+
+### Scenario 2: Stale PID File (Process Dead)
+
+**Symptoms**:
+- `npm run worker:status` shows "not running"
+- `.worker.pid` file exists
+- Process ID doesn't exist
+
+**Automatic Recovery**: Next hook trigger detects dead process and starts a fresh worker.
+
+**Manual Resolution**:
+```bash
+rm ~/.claude-mem/.worker.pid
+rm ~/.claude-mem/.worker.port
+npm run worker:start
+```
+
+### Scenario 3: Port Already in Use
+
+**Error**: `EADDRINUSE: address already in use`
+
+**Resolution**:
+```bash
+# Check what's using the port
+lsof -i :37777
+
+# Kill the process
+kill -9 <PID>
+
+# Restart worker
+npm run worker:restart
+```
+
+### Common Error Messages
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `EADDRINUSE` | Port already in use | `lsof -i :37777` then kill conflicting process |
+| `No such process` | Stale PID file | Automatic cleanup on next hook trigger |
+| `pm2: command not found` | PM2 not installed | None needed (error is caught and ignored) |
+| `Invalid port X` | Port validation failed | Update `CLAUDE_MEM_WORKER_PORT` in settings |
+
+## Developer Notes
+
+### Testing the Migration
+
+```bash
+# 1. Install old version (with PM2)
+git checkout <pre-7.1.0-tag>
+npm install && npm run build && npm run sync-marketplace
+
+# 2. Start PM2 worker
+pm2 start plugin/scripts/worker-cli.js --name claude-mem-worker
+
+# 3. Update to new version
+git checkout main
+npm install && npm run build && npm run sync-marketplace
+
+# 4. Trigger hook
+node plugin/scripts/session-start-hook.js
+
+# 5. Verify migration
+pm2 list  # Should NOT show claude-mem-worker
+cat ~/.claude-mem/.pm2-migrated  # Should exist
+npm run worker:status  # Should show Bun worker running
+```
+
+### Architecture Decisions
+
+**Why Custom ProcessManager Instead of PM2?**
+1. **Simplicity**: Direct control, no external daemon
+2. **Dependencies**: Remove npm dependency
+3. **Cross-platform**: Bun handles platform differences
+4. **Bundle Size**: Reduce plugin package size
+5. **Control**: Fine-grained error handling and validation
+
+**Why One-Time Marker Instead of Always Running PM2 Delete?**
+1. **Performance**: Avoid unnecessary process spawning
+2. **Idempotency**: Migration runs exactly once
+3. **Debugging**: Timestamp shows when migration occurred
+4. **Simplicity**: Clear migration state
+
+**Why Run PM2 Cleanup on All Platforms?**
+1. **Quality Migration**: Clean up orphaned processes
+2. **Consistency**: Same behavior across all platforms
+3. **Safety**: Error handling already in place (try/catch)
+4. **No Downside**: If PM2 not installed, error is caught and ignored
+
+## Summary
+
+The migration from PM2 to Bun-based ProcessManager is a **one-time, automatic, transparent** transition that:
+
+1. **Removes external dependencies** (PM2, better-sqlite3)
+2. **Simplifies architecture** (direct process control)
+3. **Improves cross-platform support** (especially Windows)
+4. **Preserves user data** (database, settings, logs unchanged)
+5. **Requires no user action** (automatic on first hook trigger)
+
+**Key Migration Moment**: First hook trigger after update to 7.1.0+
+**Duration**: ~2-5 seconds (one-time delay)
+**Impact**: Seamless transition, user-invisible
+**Rollback**: Not needed (migration is forward-only, safe)
+
+For most users, the migration will be completely transparent - they'll see no errors, no data loss, and experience improved reliability and simpler troubleshooting going forward.
@@ -379,7 +379,7 @@ Claude translates to appropriate API call.

 ### 4. Performance

-**Fast Queries**: FTS5 full-text search <10ms for typical queries
+**Fast Queries**: FTS5 full-text search under 10ms for typical queries

 **Caching**: HTTP layer allows response caching

@@ -397,7 +397,7 @@ Claude translates to appropriate API call.

 ### For Developers

-**Deprecated**: MCP search server (`src/servers/search-server.ts`)
+**Renamed**: MCP server (formerly `search-server.ts`, now `src/servers/mcp-server.ts`)
 - Source file kept for reference
 - No longer built or registered
 - MCP configuration removed from `plugin/.mcp.json`
@@ -415,7 +415,7 @@ Claude translates to appropriate API call.
 If searches fail, check worker service:

 ```bash
-pm2 list                    # Check status
+npm run worker:status       # Check status
 npm run worker:restart      # Restart worker
 npm run worker:logs         # View logs
 ```
@@ -1,20 +1,21 @@
 ---
 title: "Worker Service"
-description: "HTTP API and PM2 process management"
+description: "HTTP API and Bun process management"
 ---

 # Worker Service

-The worker service is a long-running HTTP API built with Express.js and managed by PM2. It processes observations through the Claude Agent SDK separately from hook execution to prevent timeout issues.
+The worker service is a long-running HTTP API built with Express.js and managed natively by Bun. It processes observations through the Claude Agent SDK separately from hook execution to prevent timeout issues.

 ## Overview

 - **Technology**: Express.js HTTP server
- **Process Manager**: PM2
+- **Runtime**: Bun (auto-installed if missing)
+- **Process Manager**: Native Bun process management via ProcessManager
 - **Port**: Fixed port 37777 (configurable via `CLAUDE_MEM_WORKER_PORT`)
 - **Location**: `src/services/worker-service.ts`
 - **Built Output**: `plugin/scripts/worker-service.cjs`
- **Model**: Configurable via `CLAUDE_MEM_MODEL` environment variable (default: claude-sonnet-4-5)
+- **Model**: Configurable via `CLAUDE_MEM_MODEL` environment variable (default: sonnet)

 ## REST API Endpoints

@@ -322,28 +323,15 @@ DELETE /sessions/:sessionDbId

 **Note**: As of v4.1.0, the cleanup hook no longer calls this endpoint. Sessions are marked complete instead of deleted to allow graceful worker shutdown.

-## PM2 Management
+## Bun Process Management

-### Configuration
+### Overview

-The worker is configured via `ecosystem.config.cjs`:
-
-```javascript
-module.exports = {
-  apps: [{
-    name: 'claude-mem-worker',
-    script: './plugin/scripts/worker-service.cjs',
-    instances: 1,
-    autorestart: true,
-    watch: false,
-    max_memory_restart: '1G',
-    env: {
-      NODE_ENV: 'production',
-      FORCE_COLOR: '1'
-    }
-  }]
-};
-```
+The worker is managed by the native `ProcessManager` class which handles:
+- Process spawning with Bun runtime
+- PID file tracking at `~/.claude-mem/worker.pid`
+- Health checks with automatic retry
+- Graceful shutdown with SIGTERM/SIGKILL fallback

 ### Commands

@@ -366,7 +354,18 @@ npm run worker:status

 ### Auto-Start Behavior

-As of v4.0.0, the worker service auto-starts when the SessionStart hook fires. Manual start is optional.
+The worker service auto-starts when the SessionStart hook fires. Manual start is optional.
+
+### Bun Requirement
+
+Bun is required to run the worker service. If Bun is not installed, the smart-install script will automatically install it on first run:
+
+- **Windows**: `powershell -c "irm bun.sh/install.ps1 | iex"`
+- **macOS/Linux**: `curl -fsSL https://bun.sh/install | bash`
+
+You can also install manually via:
+- `winget install Oven-sh.Bun` (Windows)
+- `brew install oven-sh/bun/bun` (macOS)

 ## Claude Agent SDK Integration

@@ -390,14 +389,13 @@ The worker service routes observations to the Claude Agent SDK for AI-powered pr
 Set the AI model used for processing via environment variable:

 ```bash
-export CLAUDE_MEM_MODEL=claude-sonnet-4-5
+export CLAUDE_MEM_MODEL=sonnet
 ```

-Available models:
- `claude-haiku-4-5` - Fast, cost-efficient
- `claude-sonnet-4-5` - Balanced (default)
- `claude-opus-4` - Most capable
- `claude-3-7-sonnet` - Alternative version
+Available shorthand models (forward to latest version):
+- `haiku` - Fast, cost-efficient
+- `sonnet` - Balanced (default)
+- `opus` - Most capable

 ## Port Allocation

@@ -411,15 +409,15 @@ If port 37777 is in use, the worker will fail to start. Set a custom port via en

 ## Data Storage

-The worker service stores data in the plugin data directory:
+The worker service stores data in the user data directory:

 ```
-${CLAUDE_PLUGIN_ROOT}/data/
-├── claude-mem.db           # SQLite database
-├── worker.port             # Current worker port file
+~/.claude-mem/
+├── claude-mem.db           # SQLite database (bun:sqlite)
+├── worker.pid              # PID file for process tracking
+├── settings.json           # User settings
 └── logs/
-    ├── worker-out.log      # Worker stdout logs
-    └── worker-error.log    # Worker stderr logs
+    └── worker-YYYY-MM-DD.log  # Daily rotating logs
 ```

 ## Error Handling
@@ -5,18 +5,27 @@ description: "Environment variables and settings for Claude-Mem"

 # Configuration

-## Environment Variables
+## Settings File

-| Variable                      | Default                         | Description                           |
+Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created with defaults on first run.
+
+### Core Settings
+
+| Setting                       | Default                         | Description                           |
 |-------------------------------|---------------------------------|---------------------------------------|
-| `CLAUDE_PLUGIN_ROOT`          | Set by Claude Code              | Plugin installation directory         |
-| `CLAUDE_MEM_DATA_DIR`         | `~/.claude-mem/`                | Data directory (production default)   |
-| `CLAUDE_CODE_PATH`            | Auto-detected                   | Path to Claude Code CLI (for Windows) |
-| `CLAUDE_MEM_WORKER_PORT`      | `37777`                         | Worker service port                   |
-| `CLAUDE_MEM_MODEL`            | `claude-haiku-4-5`              | AI model for processing observations  |
+| `CLAUDE_MEM_MODEL`            | `haiku`                         | AI model for processing observations  |
 | `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | `50`                        | Number of observations to inject      |
-| `NODE_ENV`                    | `production`                    | Environment mode                      |
-| `FORCE_COLOR`                 | `1`                             | Enable colored logs                   |
+| `CLAUDE_MEM_WORKER_PORT`      | `37777`                         | Worker service port                   |
+| `CLAUDE_MEM_SKIP_TOOLS`       | `ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion` | Comma-separated tools to exclude from observations |
+
+### System Configuration
+
+| Setting                       | Default                         | Description                           |
+|-------------------------------|---------------------------------|---------------------------------------|
+| `CLAUDE_MEM_DATA_DIR`         | `~/.claude-mem`                 | Data directory location               |
+| `CLAUDE_MEM_LOG_LEVEL`        | `INFO`                          | Log verbosity (DEBUG, INFO, WARN, ERROR, SILENT) |
+| `CLAUDE_MEM_PYTHON_VERSION`   | `3.13`                          | Python version for chroma-mcp         |
+| `CLAUDE_CODE_PATH`            | _(auto-detect)_                 | Path to Claude Code CLI (for Windows) |

 ## Model Configuration

@@ -24,10 +33,11 @@ Configure which AI model processes your observations.

 ### Available Models

- `claude-haiku-4-5` - Fast, cost-efficient (default)
- `claude-sonnet-4-5` - Balanced
- `claude-opus-4` - Most capable
- `claude-3-7-sonnet` - Alternative version
+Shorthand model names automatically forward to the latest version:
+
+- `haiku` - Fast, cost-efficient (default)
+- `sonnet` - Balanced
+- `opus` - Most capable

 ### Using the Interactive Script

@@ -35,15 +45,15 @@ Configure which AI model processes your observations.
 ./claude-mem-settings.sh
 ```

-This script manages `CLAUDE_MEM_MODEL` in `~/.claude/settings.json`.
+This script manages settings in `~/.claude-mem/settings.json`.

 ### Manual Configuration

-Edit `~/.claude/settings.json`:
+Edit `~/.claude-mem/settings.json`:

 ```json
 {
-  "CLAUDE_MEM_MODEL": "claude-haiku-4-5"
+  "CLAUDE_MEM_MODEL": "haiku"
 }
 ```

@@ -82,7 +92,7 @@ ${CLAUDE_PLUGIN_ROOT}/
 │   ├── summary-hook.js     # Summary generation hook
 │   ├── cleanup-hook.js     # Session cleanup hook
 │   ├── worker-service.cjs  # Worker service (CJS)
-│   └── search-server.cjs   # MCP search server (CJS)
+│   └── mcp-server.cjs      # MCP search server (CJS)
 └── ui/
    └── viewer.html         # Web viewer UI bundle
 ```
@@ -171,33 +181,9 @@ Claude-Mem supports switching between stable and beta versions via the web viewe

 See [Beta Features](beta-features) for details on what's available in beta.

-## PM2 Configuration
+## Worker Service Management

-Worker service is managed by PM2 via `ecosystem.config.cjs`:
-
-```javascript
-module.exports = {
-  apps: [{
-    name: 'claude-mem-worker',
-    script: './plugin/scripts/worker-service.cjs',
-    instances: 1,
-    autorestart: true,
-    watch: false,
-    max_memory_restart: '1G',
-    env: {
-      NODE_ENV: 'production',
-      FORCE_COLOR: '1'
-    }
-  }]
-};
-```
-
-### PM2 Settings
-
- **instances**: 1 (single instance)
- **autorestart**: true (auto-restart on crash)
- **watch**: false (no file watching)
- **max_memory_restart**: 1G (restart if memory exceeds 1GB)
+Worker service is managed by Bun as a background process. The worker auto-starts on first session and runs continuously in the background.

 ## Context Injection Configuration

@@ -276,7 +262,7 @@ Token economics help you understand the value of cached observations vs. re-read

 | Setting | Default | Description |
 |---------|---------|-------------|
-| **Model** | claude-haiku-4-5 | AI model for generating observations |
+| **Model** | haiku | AI model for generating observations |
 | **Worker Port** | 37777 | Port for background worker service |
 | **MCP search server** | true | Enable Model Context Protocol search tools |
 | **Include last summary** | false | Add previous session's summary to context |
@@ -284,56 +270,91 @@ Token economics help you understand the value of cached observations vs. re-read

 ### Manual Configuration

-Settings are stored in `~/.claude-mem/settings.json`. You can also configure via environment variables in `~/.claude/settings.json`:
+Settings are stored in `~/.claude-mem/settings.json`:

 ```json
 {
-  "env": {
-    "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "100",
-    "CLAUDE_MEM_CONTEXT_SESSION_COUNT": "20",
-    "CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES": "bugfix,decision,discovery",
-    "CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS": "how-it-works,gotcha",
-    "CLAUDE_MEM_CONTEXT_FULL_COUNT": "10",
-    "CLAUDE_MEM_CONTEXT_FULL_FIELD": "narrative",
-    "CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS": "true",
-    "CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS": "true",
-    "CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT": "true",
-    "CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY": "false",
-    "CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE": "false"
-  }
+  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "100",
+  "CLAUDE_MEM_CONTEXT_SESSION_COUNT": "20",
+  "CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES": "bugfix,decision,discovery",
+  "CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS": "how-it-works,gotcha",
+  "CLAUDE_MEM_CONTEXT_FULL_COUNT": "10",
+  "CLAUDE_MEM_CONTEXT_FULL_FIELD": "narrative",
+  "CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS": "true",
+  "CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS": "true",
+  "CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT": "true",
+  "CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY": "false",
+  "CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE": "false"
 }
 ```

-**Note**: The Context Settings Modal is the recommended way to configure these settings, as it provides live preview of changes.
+**Note**: The Context Settings Modal (at http://localhost:37777) is the recommended way to configure these settings, as it provides live preview of changes.

 ## Customization

+Settings can be customized in `~/.claude-mem/settings.json`.
+
 ### Custom Data Directory

-For development or testing, override the data directory:
-
-```bash
-export CLAUDE_MEM_DATA_DIR=/custom/path
+Edit `~/.claude-mem/settings.json`:
+```json
+{
+  "CLAUDE_MEM_DATA_DIR": "/custom/path"
+}
 ```

 ### Custom Worker Port

-If port 37777 is in use:
+Edit `~/.claude-mem/settings.json`:
+```json
+{
+  "CLAUDE_MEM_WORKER_PORT": "38000"
+}
+```

+Then restart the worker:
 ```bash
-export CLAUDE_MEM_WORKER_PORT=38000
 npm run worker:restart
 ```

 ### Custom Model

-Use a different AI model:
+Edit `~/.claude-mem/settings.json`:
+```json
+{
+  "CLAUDE_MEM_MODEL": "opus"
+}
+```

+Then restart the worker:
 ```bash
-export CLAUDE_MEM_MODEL=claude-opus-4
+export CLAUDE_MEM_MODEL=opus
 npm run worker:restart
 ```

+### Custom Skip Tools
+
+Control which tools are excluded from observations. Edit `~/.claude-mem/settings.json`:
+```json
+{
+  "CLAUDE_MEM_SKIP_TOOLS": "ListMcpResourcesTool,SlashCommand,Skill"
+}
+```
+
+**Default excluded tools:**
+- `ListMcpResourcesTool`
+- `SlashCommand`
+- `Skill`
+- `TodoWrite`
+- `AskUserQuestion`
+
+**Common customizations:**
+- Include TodoWrite: Remove from skip list to track task planning
+- Include AskUserQuestion: Remove to capture decision-making conversations
+- Skip additional tools: Add tool names to reduce observation noise
+
+Changes take effect on the next tool execution (no worker restart needed).
+
 ## Advanced Configuration

 ### Hook Timeouts
@@ -357,13 +378,7 @@ Recommended values:

 ### Worker Memory Limit

-Modify PM2 memory limit in `ecosystem.config.cjs`:
-
-```javascript
-{
-  max_memory_restart: '2G'  // Increase if needed
-}
-```
+The worker service is managed by Bun and will automatically restart if it encounters issues. Memory usage is typically low (~100-200MB).

 ### Logging Verbosity

@@ -405,13 +420,12 @@ npm run worker:logs

 ### Invalid Model Name

-If you specify an invalid model name, the worker will fall back to `claude-haiku-4-5` and log a warning.
+If you specify an invalid model name, the worker will fall back to `haiku` and log a warning.

-Valid models:
- claude-haiku-4-5
- claude-sonnet-4-5
- claude-opus-4
- claude-3-7-sonnet
+Valid shorthand models (forward to latest version):
+- haiku
+- sonnet
+- opus

 ### Port Already in Use

@@ -1,4 +1,9 @@
-# Context Engineering for AI Agents: Best Practices Cheat Sheet
+---
+title: "Context Engineering"
+description: "Best practices for curating optimal token sets for AI agents"
+---
+
+# Context Engineering for AI Agents

 ## Core Principle
 **Find the smallest possible set of high-signal tokens that maximize the likelihood of your desired outcome.**
@@ -33,7 +33,7 @@ The build process uses esbuild to compile TypeScript:

 1. Compiles TypeScript to JavaScript
 2. Creates standalone executables for each hook in `plugin/scripts/`
-3. Bundles MCP search server to `plugin/scripts/search-server.cjs`
+3. Bundles MCP search server to `plugin/scripts/mcp-server.cjs`
 4. Bundles worker service to `plugin/scripts/worker-service.cjs`
 5. Bundles web viewer UI to `plugin/ui/viewer.html`

@@ -41,7 +41,7 @@ The build process uses esbuild to compile TypeScript:
 - Hook executables: `*-hook.js` (ESM format)
 - Smart installer: `smart-install.js` (ESM format)
 - Worker service: `worker-service.cjs` (CJS format)
- Search server: `search-server.cjs` (CJS format)
+- MCP server: `mcp-server.cjs` (CJS format)
 - Viewer UI: `viewer.html` (self-contained HTML bundle)

 ### Build Scripts
@@ -342,7 +342,7 @@ npm test

 ### Adding MCP Search Tools

-1. Add tool definition in `src/servers/search-server.ts`:
+1. Add tool definition in `src/servers/mcp-server.ts`:

 ```typescript
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -650,7 +650,7 @@ rm -rf plugin/scripts/*.js plugin/scripts/*.cjs

 1. Kill existing process:
   ```bash
-   pm2 delete claude-mem-worker
+   npm run worker:stop
   ```

 2. Check port:
@@ -37,6 +37,7 @@
          "installation",
          "usage/getting-started",
          "usage/search-tools",
+          "usage/claude-desktop",
          "usage/private-tags",
          "beta-features"
        ]
@@ -55,7 +56,8 @@
        "pages": [
          "configuration",
          "development",
-          "troubleshooting"
+          "troubleshooting",
+          "platform-integration"
        ]
      },
      {
@@ -68,7 +70,8 @@
          "architecture/hooks",
          "architecture/worker-service",
          "architecture/database",
-          "architecture/search-architecture"
+          "architecture/search-architecture",
+          "architecture/pm2-to-bun-migration"
        ]
      }
    ]
@@ -85,9 +85,8 @@ Claude-Mem uses 6 lifecycle hook scripts across 5 lifecycle events, plus 1 pre-h
 2. Only runs `npm install` when necessary:
   - First-time installation
   - Version changed in package.json
-   - Critical dependency missing (better-sqlite3)
 3. Provides Windows-specific error messages
-4. Starts PM2 worker service
+4. Starts Bun worker service

 **Configuration:**
 ```json
@@ -215,7 +214,7 @@ Claude-Mem uses 6 lifecycle hook scripts across 5 lifecycle events, plus 1 pre-h
 1. Reads user prompt and session ID from stdin
 2. Creates new session record in SQLite
 3. Saves raw user prompt for full-text search (v4.2.0+)
-4. Starts PM2 worker service if not running
+4. Starts Bun worker service if not running
 5. Returns immediately (non-blocking)

 **Configuration:**
@@ -512,49 +511,33 @@ sequenceDiagram
 └─────────────────────────────────────────────────────────┘
 ```

-### PM2 Process Management
+### Bun Process Management

-**Technology:** PM2 (process manager for Node.js)
+**Technology:** Bun (JavaScript runtime and process manager)

-**Why PM2:**
+**Why Bun:**
 - Auto-restart on failure
- Log management
- Process monitoring
+- Fast startup and low memory footprint
+- Built-in TypeScript support
 - Cross-platform (works on macOS, Linux, Windows)
- No systemd/launchd needed
-
-**Configuration:**
-```javascript
-// ecosystem.config.cjs
-module.exports = {
-  apps: [{
-    name: 'claude-mem-worker',
-    script: './plugin/scripts/worker-service.cjs',
-    instances: 1,
-    autorestart: true,
-    watch: false,
-    max_memory_restart: '500M',
-    env: {
-      NODE_ENV: 'production',
-      CLAUDE_MEM_WORKER_PORT: 37777
-    }
-  }]
-};
-```
+- No separate process manager needed

 **Worker lifecycle:**
 ```bash
-# Started by new-hook (if not running)
-pm2 start ecosystem.config.cjs
+# Started by hooks automatically (if not running)
+npm run worker:start

 # Status check
-pm2 status claude-mem-worker
+npm run worker:status

 # View logs
-pm2 logs claude-mem-worker
+npm run worker:logs

 # Restart
-pm2 restart claude-mem-worker
+npm run worker:restart
+
+# Stop
+npm run worker:stop
 ```

 ### Worker HTTP API
@@ -632,7 +615,7 @@ try {

 **Failure modes:**
 - Database locked → Skip observation, log error
- Worker crashed → Auto-restart via PM2
+- Worker crashed → Auto-restart via Bun
 - Network issue → Retry with exponential backoff
 - Disk full → Warn user, disable memory

@@ -708,8 +691,8 @@ claude --debug
    **Debugging:**
    1. Check database: `sqlite3 ~/.claude-mem/claude-mem.db "SELECT * FROM observation_queue"`
    2. Verify session exists: `SELECT * FROM sdk_sessions`
-    3. Check worker status: `pm2 status`
-    4. View worker logs: `pm2 logs claude-mem-worker`
+    3. Check worker status: `npm run worker:status`
+    4. View worker logs: `npm run worker:logs`
  </Accordion>
 </AccordionGroup>

@@ -761,7 +744,7 @@ claude --debug
 **Why smart-install is sometimes slow:**
 - First-time: Full npm install (2-5 seconds)
 - Cached: Version check only (~10ms)
- Version change: Full npm install + PM2 restart
+- Version change: Full npm install + worker restart

 **Optimization (v5.0.3):**
 - Version caching with `.install-version` marker
@@ -16,7 +16,7 @@ Install Claude-Mem directly from the plugin marketplace:

 That's it! The plugin will automatically:
 - Download prebuilt binaries (no compilation needed)
- Install all dependencies (including PM2 and SQLite binaries)
+- Install all dependencies (including SQLite binaries)
 - Configure hooks for session lifecycle management
 - Auto-start the worker service on first session

@@ -26,7 +26,7 @@ Start a new Claude Code session and you'll see context from previous sessions au

 - **Node.js**: 18.0.0 or higher
 - **Claude Code**: Latest version with plugin support
- **PM2**: Process manager (bundled with plugin - no global install required)
+- **Bun**: JavaScript runtime and process manager (auto-installed if missing)
 - **SQLite 3**: For persistent storage (bundled)

 ## Advanced Installation
@@ -69,12 +69,14 @@ cat plugin/hooks/hooks.json

 #### 3. Data Directory Location

-v4.0.0+ stores data in `${CLAUDE_PLUGIN_ROOT}/data/`:
- Database: `${CLAUDE_PLUGIN_ROOT}/data/claude-mem.db`
- Worker port file: `${CLAUDE_PLUGIN_ROOT}/data/worker.port`
- Logs: `${CLAUDE_PLUGIN_ROOT}/data/logs/`
+Data is stored in `~/.claude-mem/`:
+- Database: `~/.claude-mem/claude-mem.db`
+- PID file: `~/.claude-mem/.worker.pid`
+- Port file: `~/.claude-mem/.worker.port`
+- Logs: `~/.claude-mem/logs/worker-YYYY-MM-DD.log`
+- Settings: `~/.claude-mem/settings.json`

-For development/testing, you can override:
+Override with environment variable:
 ```bash
 export CLAUDE_MEM_DATA_DIR=/custom/path
 ```
@@ -91,19 +93,17 @@ npm run worker:logs
 npm run test:context
 ```

-## Upgrading from v3.x
+## Upgrading

-**BREAKING CHANGES - Please Read:**
+Upgrades are automatic when updating via the plugin marketplace. Key changes in recent versions:

-v4.0.0 introduces breaking changes:
+**v7.1.0**: PM2 replaced with native Bun process management. Migration is automatic on first hook trigger.

- **Data Location Changed**: Database moved from `~/.claude-mem/` to `${CLAUDE_PLUGIN_ROOT}/data/` (inside plugin directory)
- **Fresh Start Required**: No automatic migration from v3.x. You must start with a clean database
- **Worker Auto-Starts**: Worker service now starts automatically - no manual `npm run worker:start` needed
- **MCP Search Server**: 7 new search tools with full-text search and citations
- **Enhanced Architecture**: Improved plugin integration and data organization
+**v7.0.0+**: 11 configuration settings, dual-tag privacy system.

-See [CHANGELOG](https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md) for complete details.
+**v5.4.0+**: Skill-based search replaces MCP tools, saving ~2,250 tokens per session.
+
+See [CHANGELOG](https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md) for complete version history.

 ## Next Steps

@@ -58,7 +58,7 @@ Restart Claude Code. Context from previous sessions will automatically appear in
 **Core Components:**
 1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
 2. **Smart Install** - Cached dependency checker (pre-hook script)
-3. **Worker Service** - HTTP API on port 37777 managed by PM2
+3. **Worker Service** - HTTP API on port 37777 managed by Bun
 4. **SQLite Database** - Stores sessions, observations, summaries with FTS5 search
 5. **mem-search Skill** - Query historical context with natural language
 6. **Web Viewer UI** - Real-time visualization with SSE and infinite scroll
@@ -69,26 +69,25 @@ See [Architecture Overview](architecture/overview) for details.

 - **Node.js**: 18.0.0 or higher
 - **Claude Code**: Latest version with plugin support
- **PM2**: Process manager (bundled - no global install required)
+- **Bun**: JavaScript runtime and process manager (auto-installed if missing)
 - **SQLite 3**: For persistent storage (bundled)

 ## What's New

-**v6.4.9 - Context Configuration Settings:**
- 11 new settings for fine-grained control over context injection
- Configure token economics display, observation filtering by type/concept
+**v7.1.0 - Bun Migration:**
+- Replaced PM2 with native Bun process management
+- Switched from better-sqlite3 to bun:sqlite for faster database access
+- Automatic one-time migration on first hook trigger
+- Simplified cross-platform support

-**v6.4.0 - Dual-Tag Privacy System:**
- `<private>` tags for user-controlled privacy - wrap sensitive content to exclude from storage
- Edge processing ensures private content never reaches database
-
-**v6.3.0 - Version Channel:**
- Switch between stable and beta versions from the web viewer UI
+**v7.0.0 - Context Configuration:**
+- 11 settings for fine-grained control over context injection
+- Dual-tag privacy system (`<private>` tags)

 **Previous Highlights:**
- **v6.0.0**: Major session management & transcript processing improvements
- **v5.5.0**: mem-search skill enhancement with 100% effectiveness rate
- **v5.4.0**: Skill-based search architecture (~2,250 tokens saved per session)
+- **v5.5.0**: mem-search skill with 100% effectiveness rate
+- **v5.4.0**: Skill-based search (~2,250 tokens saved per session)
+- **v5.1.0**: Web viewer UI at http://localhost:37777

 ## Next Steps

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+  <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 250 53" width="250" height="55" data-date-format="longDate">
+    <rect xmlns="http://www.w3.org/2000/svg" stroke="#b5a0d9" stroke-width="1" fill="#1a1a1a" x="0.5" y="0.5" width="249" height="53" rx="10"/>
+    <foreignObject width="198" height="17" style="font-size: 9px;color: rgb(200, 180, 230);font-family: Arial;font-weight: 400;text-align: center;letter-spacing: 0em;line-height: 1.5;" x="6" y="10" selection="true">
+      <div xmlns="http://www.w3.org/1999/xhtml">GITHUB TRENDING</div>
+    </foreignObject>
+    <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" id="&#x421;&#x43B;&#x43E;&#x439;_1" viewBox="0 0 80 80" width="48" height="45" x="10" y="8">
+  <path fill="#b5a0d9" d="M70.71,40.31C75.74,44.3,80,37.86,80,37.86s-5.64-2.17-8.55,0.61c0.59-1.62,1.02-3.31,1.28-5.01  c4.08,2.16,6.44-2.95,6.44-2.95s-4.41-0.97-6.26,1.4c0.08-0.91,0.12-1.82,0.1-2.73c-0.01-0.36-0.02-0.73-0.05-1.09  c2.96-3.68-1.73-6.99-1.73-6.99s-2.14,5.09,0.98,7.09c0.02,0.33,0.03,0.66,0.03,1c0.01,0.76-0.03,1.52-0.1,2.27  c-0.85-2.69-4.91-3.69-4.91-3.69s-0.13,5.78,4.68,5.48c-0.28,1.69-0.73,3.35-1.34,4.95c-0.19-4.03-5.79-6.33-5.79-6.33  s-1.33,7.55,5.01,8.16c-0.38,0.8-0.8,1.57-1.25,2.32c-0.56,0.95-1.21,1.84-1.89,2.71c0.97-3.99-3.96-7.72-3.96-7.72  s-3.18,6.94,2.73,9.15c-0.38,0.43-0.8,0.81-1.2,1.21c-0.21,0.2-0.43,0.38-0.64,0.58l-0.32,0.29c-0.11,0.09-0.22,0.18-0.33,0.27  l-0.67,0.54l-0.7,0.51c-0.08,0.05-0.16,0.11-0.23,0.16c1.62-3.42-2.07-7.77-2.07-7.77s-4.21,5.55,0.49,8.78  c-1.34,0.79-2.74,1.45-4.2,1.98c1.91-2.59-0.23-6.89-0.23-6.89s-4.66,3.77-1.52,7.46c-1.15,0.33-2.33,0.57-3.51,0.74  c1.46-1.68,0.55-4.83,0.55-4.83s-3.7,2.03-2.18,5c-0.52,0.03-1.05,0.07-1.57,0.06c-0.29,0-0.57,0.01-0.86,0l-0.86-0.04  c-0.85-0.06-1.7-0.15-2.54-0.28l0.68-0.27l0.42-0.17l0.41-0.19l0.82-0.38c0,0,0.01,0,0.01,0c0.39-0.18,0.55-0.65,0.37-1.03  c-0.18-0.39-0.65-0.55-1.03-0.37l-0.04,0.02l-0.77,0.37l-0.39,0.18l-0.39,0.16l-0.79,0.33l-0.8,0.29l-0.4,0.14l-0.41,0.12L40,53.6  l-0.51-0.15l-0.41-0.12l-0.4-0.14l-0.8-0.29l-0.79-0.33l-0.39-0.16l-0.39-0.18l-0.77-0.37l-0.04-0.02c0,0,0,0-0.01,0  c-0.39-0.18-0.85-0.01-1.03,0.38c-0.18,0.39-0.01,0.85,0.38,1.03l0.82,0.38l0.41,0.19l0.42,0.17l0.68,0.27  c-0.84,0.14-1.69,0.22-2.54,0.28l-0.86,0.04c-0.29,0.01-0.57,0-0.86,0c-0.53,0.01-1.05-0.03-1.57-0.06c1.51-2.98-2.18-5-2.18-5  s-0.92,3.15,0.55,4.83c-1.19-0.16-2.36-0.41-3.51-0.74c3.15-3.7-1.52-7.46-1.52-7.46s-2.14,4.31-0.23,6.89  c-1.46-0.53-2.86-1.19-4.2-1.98c4.7-3.22,0.49-8.78,0.49-8.78s-3.69,4.34-2.07,7.77c-0.08-0.05-0.16-0.1-0.23-0.16l-0.7-0.51  l-0.67-0.54c-0.11-0.09-0.23-0.18-0.33-0.27l-0.32-0.29c-0.21-0.19-0.43-0.38-0.64-0.58c-0.4-0.4-0.82-0.79-1.2-1.21  c5.91-2.21,2.73-9.15,2.73-9.15s-4.93,3.73-3.96,7.72c-0.68-0.86-1.33-1.76-1.89-2.71c-0.46-0.75-0.87-1.53-1.25-2.32  c6.33-0.61,5.01-8.16,5.01-8.16s-5.6,2.31-5.79,6.33c-0.61-1.6-1.06-3.26-1.34-4.95c4.81,0.3,4.68-5.48,4.68-5.48  s-4.05,0.99-4.91,3.69c-0.07-0.76-0.1-1.51-0.1-2.27c0-0.33,0.01-0.66,0.03-1c3.11-2.01,0.98-7.09,0.98-7.09s-4.69,3.31-1.73,6.99  C7,28.46,6.99,28.82,6.98,29.18c-0.02,0.91,0.01,1.82,0.1,2.73c-1.84-2.38-6.26-1.4-6.26-1.4s2.37,5.11,6.44,2.95  c0.26,1.71,0.69,3.39,1.28,5.01C5.64,35.69,0,37.86,0,37.86s4.26,6.43,9.29,2.45c0.39,0.87,0.83,1.72,1.31,2.54  c0.47,0.83,1.01,1.63,1.58,2.4C8.71,43.7,4.11,47,4.11,47s5.7,5.1,9.56,0.08c0.04,0.04,0.07,0.08,0.11,0.12  c0.39,0.45,0.82,0.87,1.24,1.3c0.21,0.21,0.44,0.41,0.66,0.61l0.33,0.3c0.11,0.1,0.23,0.19,0.34,0.29l0.69,0.57l0.23,0.17  c-3.34-0.34-6.58,3.29-6.58,3.29s6.19,3.47,8.69-1.83c1.2,0.75,2.47,1.41,3.78,1.96c-2.76,0.6-4.62,4.13-4.62,4.13  s5.89,1.62,6.98-3.26c1.03,0.32,2.07,0.58,3.13,0.78c-1.63,0.99-2.39,3.38-2.39,3.38s4.31,0.39,4.61-3.07  c0.07,0.01,0.14,0.02,0.21,0.02c0.6,0.04,1.2,0.1,1.8,0.09c0.3,0,0.6,0.02,0.9,0.01l0.9-0.03c1.2-0.07,2.41-0.18,3.59-0.42  l0.45-0.08c0.15-0.03,0.29-0.07,0.44-0.1L40,55.13l0.81,0.19c0.15,0.03,0.29,0.07,0.44,0.1l0.45,0.08c1.18,0.23,2.39,0.35,3.59,0.42  l0.9,0.03c0.3,0.01,0.6-0.01,0.9-0.01c0.6,0,1.2-0.06,1.8-0.09c0.07-0.01,0.14-0.02,0.21-0.02c0.31,3.45,4.61,3.07,4.61,3.07  s-0.76-2.39-2.39-3.38c1.06-0.2,2.11-0.46,3.13-0.78c1.09,4.88,6.98,3.26,6.98,3.26s-1.86-3.52-4.62-4.13  c1.31-0.55,2.57-1.21,3.78-1.96c2.5,5.3,8.69,1.83,8.69,1.83s-3.24-3.63-6.58-3.29l0.23-0.17l0.69-0.57  c0.11-0.1,0.23-0.19,0.34-0.29l0.33-0.3c0.22-0.2,0.45-0.4,0.66-0.61c0.42-0.43,0.85-0.84,1.24-1.3c0.03-0.04,0.07-0.08,0.11-0.12  C70.19,52.1,75.89,47,75.89,47s-4.6-3.31-8.08-1.75c0.57-0.77,1.11-1.56,1.58-2.4C69.88,42.03,70.31,41.18,70.71,40.31z"/>
+  </svg>
+    <foreignObject width="230" height="35" style="font-size: 14px;color: rgb(200, 180, 230);font-family: Arial;font-weight: 700;text-align: left;letter-spacing: 0em;line-height: 1.5;" x="64" y="24">
+      <div xmlns="http://www.w3.org/1999/xhtml">#1 Repository Of The Day</div>
+    </foreignObject>
+    <foreignObject width="141" height="36" style="font-size: 18px;color: rgb(180, 160, 217);font-family: Arial;font-weight: 400;text-align: center;letter-spacing: 0em;line-height: 1.5;" x="-36" y="9">
+      <div xmlns="http://www.w3.org/1999/xhtml">1</div>
+    </foreignObject>
+  </svg>
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+  <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 250 53" width="250" height="55" data-date-format="longDate">
+    <rect xmlns="http://www.w3.org/2000/svg" stroke="#4a0e99" stroke-width="1" fill="#FFFFFF" x="0.5" y="0.5" width="249" height="53" rx="10"/>
+    <foreignObject width="198" height="17" style="font-size: 9px;color: rgb(67, 39, 135);font-family: Arial;font-weight: 400;text-align: center;letter-spacing: 0em;line-height: 1.5;" x="6" y="10" selection="true">
+      <div xmlns="http://www.w3.org/1999/xhtml">GITHUB TRENDING</div>
+    </foreignObject>
+    <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" id="&#x421;&#x43B;&#x43E;&#x439;_1" viewBox="0 0 80 80" width="48" height="45" x="10" y="8">
+  <path fill="#49278e" d="M70.71,40.31C75.74,44.3,80,37.86,80,37.86s-5.64-2.17-8.55,0.61c0.59-1.62,1.02-3.31,1.28-5.01  c4.08,2.16,6.44-2.95,6.44-2.95s-4.41-0.97-6.26,1.4c0.08-0.91,0.12-1.82,0.1-2.73c-0.01-0.36-0.02-0.73-0.05-1.09  c2.96-3.68-1.73-6.99-1.73-6.99s-2.14,5.09,0.98,7.09c0.02,0.33,0.03,0.66,0.03,1c0.01,0.76-0.03,1.52-0.1,2.27  c-0.85-2.69-4.91-3.69-4.91-3.69s-0.13,5.78,4.68,5.48c-0.28,1.69-0.73,3.35-1.34,4.95c-0.19-4.03-5.79-6.33-5.79-6.33  s-1.33,7.55,5.01,8.16c-0.38,0.8-0.8,1.57-1.25,2.32c-0.56,0.95-1.21,1.84-1.89,2.71c0.97-3.99-3.96-7.72-3.96-7.72  s-3.18,6.94,2.73,9.15c-0.38,0.43-0.8,0.81-1.2,1.21c-0.21,0.2-0.43,0.38-0.64,0.58l-0.32,0.29c-0.11,0.09-0.22,0.18-0.33,0.27  l-0.67,0.54l-0.7,0.51c-0.08,0.05-0.16,0.11-0.23,0.16c1.62-3.42-2.07-7.77-2.07-7.77s-4.21,5.55,0.49,8.78  c-1.34,0.79-2.74,1.45-4.2,1.98c1.91-2.59-0.23-6.89-0.23-6.89s-4.66,3.77-1.52,7.46c-1.15,0.33-2.33,0.57-3.51,0.74  c1.46-1.68,0.55-4.83,0.55-4.83s-3.7,2.03-2.18,5c-0.52,0.03-1.05,0.07-1.57,0.06c-0.29,0-0.57,0.01-0.86,0l-0.86-0.04  c-0.85-0.06-1.7-0.15-2.54-0.28l0.68-0.27l0.42-0.17l0.41-0.19l0.82-0.38c0,0,0.01,0,0.01,0c0.39-0.18,0.55-0.65,0.37-1.03  c-0.18-0.39-0.65-0.55-1.03-0.37l-0.04,0.02l-0.77,0.37l-0.39,0.18l-0.39,0.16l-0.79,0.33l-0.8,0.29l-0.4,0.14l-0.41,0.12L40,53.6  l-0.51-0.15l-0.41-0.12l-0.4-0.14l-0.8-0.29l-0.79-0.33l-0.39-0.16l-0.39-0.18l-0.77-0.37l-0.04-0.02c0,0,0,0-0.01,0  c-0.39-0.18-0.85-0.01-1.03,0.38c-0.18,0.39-0.01,0.85,0.38,1.03l0.82,0.38l0.41,0.19l0.42,0.17l0.68,0.27  c-0.84,0.14-1.69,0.22-2.54,0.28l-0.86,0.04c-0.29,0.01-0.57,0-0.86,0c-0.53,0.01-1.05-0.03-1.57-0.06c1.51-2.98-2.18-5-2.18-5  s-0.92,3.15,0.55,4.83c-1.19-0.16-2.36-0.41-3.51-0.74c3.15-3.7-1.52-7.46-1.52-7.46s-2.14,4.31-0.23,6.89  c-1.46-0.53-2.86-1.19-4.2-1.98c4.7-3.22,0.49-8.78,0.49-8.78s-3.69,4.34-2.07,7.77c-0.08-0.05-0.16-0.1-0.23-0.16l-0.7-0.51  l-0.67-0.54c-0.11-0.09-0.23-0.18-0.33-0.27l-0.32-0.29c-0.21-0.19-0.43-0.38-0.64-0.58c-0.4-0.4-0.82-0.79-1.2-1.21  c5.91-2.21,2.73-9.15,2.73-9.15s-4.93,3.73-3.96,7.72c-0.68-0.86-1.33-1.76-1.89-2.71c-0.46-0.75-0.87-1.53-1.25-2.32  c6.33-0.61,5.01-8.16,5.01-8.16s-5.6,2.31-5.79,6.33c-0.61-1.6-1.06-3.26-1.34-4.95c4.81,0.3,4.68-5.48,4.68-5.48  s-4.05,0.99-4.91,3.69c-0.07-0.76-0.1-1.51-0.1-2.27c0-0.33,0.01-0.66,0.03-1c3.11-2.01,0.98-7.09,0.98-7.09s-4.69,3.31-1.73,6.99  C7,28.46,6.99,28.82,6.98,29.18c-0.02,0.91,0.01,1.82,0.1,2.73c-1.84-2.38-6.26-1.4-6.26-1.4s2.37,5.11,6.44,2.95  c0.26,1.71,0.69,3.39,1.28,5.01C5.64,35.69,0,37.86,0,37.86s4.26,6.43,9.29,2.45c0.39,0.87,0.83,1.72,1.31,2.54  c0.47,0.83,1.01,1.63,1.58,2.4C8.71,43.7,4.11,47,4.11,47s5.7,5.1,9.56,0.08c0.04,0.04,0.07,0.08,0.11,0.12  c0.39,0.45,0.82,0.87,1.24,1.3c0.21,0.21,0.44,0.41,0.66,0.61l0.33,0.3c0.11,0.1,0.23,0.19,0.34,0.29l0.69,0.57l0.23,0.17  c-3.34-0.34-6.58,3.29-6.58,3.29s6.19,3.47,8.69-1.83c1.2,0.75,2.47,1.41,3.78,1.96c-2.76,0.6-4.62,4.13-4.62,4.13  s5.89,1.62,6.98-3.26c1.03,0.32,2.07,0.58,3.13,0.78c-1.63,0.99-2.39,3.38-2.39,3.38s4.31,0.39,4.61-3.07  c0.07,0.01,0.14,0.02,0.21,0.02c0.6,0.04,1.2,0.1,1.8,0.09c0.3,0,0.6,0.02,0.9,0.01l0.9-0.03c1.2-0.07,2.41-0.18,3.59-0.42  l0.45-0.08c0.15-0.03,0.29-0.07,0.44-0.1L40,55.13l0.81,0.19c0.15,0.03,0.29,0.07,0.44,0.1l0.45,0.08c1.18,0.23,2.39,0.35,3.59,0.42  l0.9,0.03c0.3,0.01,0.6-0.01,0.9-0.01c0.6,0,1.2-0.06,1.8-0.09c0.07-0.01,0.14-0.02,0.21-0.02c0.31,3.45,4.61,3.07,4.61,3.07  s-0.76-2.39-2.39-3.38c1.06-0.2,2.11-0.46,3.13-0.78c1.09,4.88,6.98,3.26,6.98,3.26s-1.86-3.52-4.62-4.13  c1.31-0.55,2.57-1.21,3.78-1.96c2.5,5.3,8.69,1.83,8.69,1.83s-3.24-3.63-6.58-3.29l0.23-0.17l0.69-0.57  c0.11-0.1,0.23-0.19,0.34-0.29l0.33-0.3c0.22-0.2,0.45-0.4,0.66-0.61c0.42-0.43,0.85-0.84,1.24-1.3c0.03-0.04,0.07-0.08,0.11-0.12  C70.19,52.1,75.89,47,75.89,47s-4.6-3.31-8.08-1.75c0.57-0.77,1.11-1.56,1.58-2.4C69.88,42.03,70.31,41.18,70.71,40.31z"/>
+  </svg>
+    <foreignObject width="230" height="35" style="font-size: 14px;color: rgb(67, 39, 135);font-family: Arial;font-weight: 700;text-align: left;letter-spacing: 0em;line-height: 1.5;" x="64" y="24">
+      <div xmlns="http://www.w3.org/1999/xhtml">#1 Repository Of The Day</div>
+    </foreignObject>
+    <foreignObject width="141" height="36" style="font-size: 18px;color: rgb(74, 14, 153);font-family: Arial;font-weight: 400;text-align: center;letter-spacing: 0em;line-height: 1.5;" x="-36" y="9">
+      <div xmlns="http://www.w3.org/1999/xhtml">1</div>
+    </foreignObject>
+  </svg>
@@ -10,7 +10,7 @@ description: "Common issues and solutions for Claude-Mem"
 Describe any issues you're experiencing to Claude, and the troubleshoot skill will automatically activate to provide diagnosis and fixes.

 The troubleshoot skill will:
- ✅ Check PM2 worker status and health
+- ✅ Check worker status and health
 - ✅ Verify database existence and integrity
 - ✅ Test worker service connectivity
 - ✅ Validate dependencies installation
@@ -170,39 +170,18 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de

 4. Restart Claude Code after manual install

-### PM2 ENOENT Error on Windows (v5.1.1 Fix)
-
-**Symptoms**: Worker fails to start with "ENOENT" error on Windows.
-
-**Solutions**:
-
-1. This was fixed in v5.1.1 - update to latest version:
-   ```bash
-   /plugin update claude-mem
-   ```
-
-2. If still experiencing issues, verify PM2 path:
-   ```bash
-   cd ~/.claude/plugins/marketplaces/thedotmack
-   dir node_modules\.bin\pm2.cmd
-   ```
-
-3. Manual PM2 install if needed:
-   ```bash
-   npm install pm2@latest
-   ```

 ## Worker Service Issues

 ### Worker Service Not Starting

-**Symptoms**: Worker doesn't start, or `pm2 status` shows no processes.
+**Symptoms**: Worker doesn't start, or worker status shows it's not running.

 **Solutions**:

-1. Check if PM2 is running:
+1. Check worker status:
   ```bash
-   pm2 status
+   npm run worker:status
   ```

 2. Try starting manually:
@@ -217,14 +196,14 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de

 4. Full reset:
   ```bash
-   pm2 delete claude-mem-worker
+   npm run worker:stop
   npm run worker:start
   ```

-5. Verify PM2 is installed:
+5. Verify Bun is installed:
   ```bash
-   which pm2
-   npm list pm2
+   which bun
+   bun --version
   ```

 ### Port Allocation Failed
@@ -256,7 +235,7 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de

 ### Worker Keeps Crashing

-**Symptoms**: Worker restarts repeatedly, PM2 shows high restart count.
+**Symptoms**: Worker restarts repeatedly or fails to stay running.

 **Solutions**:

@@ -265,23 +244,21 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
   npm run worker:logs
   ```

-2. Check memory usage:
+2. Check worker status:
   ```bash
-   pm2 status
+   npm run worker:status
   ```

-3. Increase memory limit in `ecosystem.config.cjs`:
-   ```javascript
-   {
-     max_memory_restart: '2G'  // Increase if needed
-   }
-   ```
-
-4. Check database for corruption:
+3. Check database for corruption:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
   ```

+4. Verify Bun installation:
+   ```bash
+   bun --version
+   ```
+
 ### Worker Not Processing Observations

 **Symptoms**: Observations saved but not processed, no summaries generated.
@@ -424,7 +401,7 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de

 1. Close all connections:
   ```bash
-   pm2 stop claude-mem-worker
+   npm run worker:stop
   ```

 2. Check for stale locks:
@@ -542,7 +519,7 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de

 2. Verify search server is built:
   ```bash
-   ls -l plugin/scripts/search-server.js
+   ls -l plugin/scripts/mcp-server.cjs
   ```

 3. Rebuild if needed:
@@ -656,29 +633,21 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de

 ### High Memory Usage

-**Symptoms**: Worker uses too much memory, frequent restarts.
+**Symptoms**: Worker uses too much memory.

 **Solutions**:

 1. Check current usage:
   ```bash
-   pm2 status
+   npm run worker:status
   ```

-2. Increase memory limit:
-   ```javascript
-   // In ecosystem.config.cjs
-   {
-     max_memory_restart: '2G'
-   }
-   ```
-
-3. Restart worker:
+2. Restart worker:
   ```bash
   npm run worker:restart
   ```

-4. Clean up old data (see "Database Too Large" above)
+3. Clean up old data (see "Database Too Large" above)

 ## Installation Issues

@@ -773,10 +742,10 @@ sqlite3 ~/.claude-mem/claude-mem.db "

 ```bash
 # Check if worker is running
-pm2 status
+npm run worker:status

 # View logs
-pm2 logs claude-mem-worker
+npm run worker:logs

 # Check port file
 cat ~/.claude-mem/worker.port
@@ -0,0 +1,169 @@
+---
+title: Claude Desktop Skill
+description: Use claude-mem memory search in Claude Desktop with the mem-search skill
+icon: desktop
+---
+
+<Note>
+**Availability:** The mem-search skill works with Claude Desktop on macOS and Windows.
+</Note>
+
+## Overview
+
+Claude Desktop can access your claude-mem memory database through the **mem-search** skill. This allows you to search past sessions, decisions, and observations directly from Claude Desktop conversations.
+
+## Prerequisites
+
+Before installing the skill, ensure:
+
+1. **claude-mem is installed** and the worker service is running
+2. **MCP server is configured** in Claude Desktop (the skill uses the `mem-search` MCP server)
+
+### Verify Worker is Running
+
+```bash
+curl http://localhost:37777/api/health
+# Should return: {"status":"ok"}
+```
+
+## Installation
+
+### Step 1: Download the Skill
+
+Download the skill package from the repository:
+
+<Card title="mem-search.zip" icon="download" href="https://github.com/thedotmack/claude-mem/raw/main/desktop-skill/mem-search.zip">
+  Download the mem-search skill for Claude Desktop
+</Card>
+
+Or build from source:
+
+```bash
+cd desktop-skill
+zip -r mem-search.zip Skill.md
+```
+
+### Step 2: Install in Claude Desktop
+
+1. Open **Claude Desktop**
+2. Go to **Settings** (gear icon)
+3. Navigate to **Skills**
+4. Click **Install Skill** or drag the `mem-search.zip` file
+5. Confirm installation
+
+### Step 3: Configure MCP Server
+
+The skill requires the `mem-search` MCP server. Add this to your Claude Desktop configuration:
+
+<Tabs>
+  <Tab title="macOS">
+    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+    ```json
+    {
+      "mcpServers": {
+        "mem-search": {
+          "command": "node",
+          "args": [
+            "/Users/YOUR_USERNAME/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs"
+          ]
+        }
+      }
+    }
+    ```
+  </Tab>
+  <Tab title="Windows">
+    Edit `%APPDATA%\Claude\claude_desktop_config.json`:
+
+    ```json
+    {
+      "mcpServers": {
+        "mem-search": {
+          "command": "node",
+          "args": [
+            "C:\\Users\\YOUR_USERNAME\\.claude\\plugins\\marketplaces\\thedotmack\\plugin\\scripts\\mcp-server.cjs"
+          ]
+        }
+      }
+    }
+    ```
+  </Tab>
+</Tabs>
+
+<Warning>
+Replace `YOUR_USERNAME` with your actual username. Restart Claude Desktop after editing the configuration.
+</Warning>
+
+### Step 4: Restart Claude Desktop
+
+Close and reopen Claude Desktop for the MCP server configuration to take effect.
+
+## Usage
+
+Once installed, the skill auto-activates when you ask about past work:
+
+```
+"What did we do last session?"
+"Did we fix this bug before?"
+"How did we implement authentication?"
+"What decisions did we make about the API?"
+"Show me changes to worker-service.ts"
+```
+
+## Available Search Tools
+
+The skill provides access to these MCP tools:
+
+| Tool | Description |
+|------|-------------|
+| `search` | Unified search across all memory types |
+| `decisions` | Find architectural/design decisions |
+| `changes` | Find code changes and refactorings |
+| `timeline` | Get observations around a specific point in time |
+| `find_by_file` | Find observations for specific files |
+| `find_by_type` | Filter by type (decision, bugfix, feature, refactor, discovery, change) |
+| `find_by_concept` | Find by concept tags |
+| `how_it_works` | Understand system architecture and design patterns |
+
+## Troubleshooting
+
+### Skill Not Appearing
+
+1. Verify the zip file was properly installed
+2. Check Claude Desktop's skill installation logs
+3. Restart Claude Desktop
+
+### MCP Server Connection Failed
+
+1. Verify the worker is running: `curl http://localhost:37777/api/health`
+2. Check the MCP server path in configuration
+3. Look for errors in Claude Desktop logs
+
+<Tabs>
+  <Tab title="macOS">
+    ```bash
+    # View Claude Desktop logs
+    tail -f ~/Library/Logs/Claude/claude.log
+    ```
+  </Tab>
+  <Tab title="Windows">
+    Check `%APPDATA%\Claude\logs\`
+  </Tab>
+</Tabs>
+
+### Search Returns No Results
+
+1. Ensure claude-mem has recorded sessions (check http://localhost:37777)
+2. Verify the database exists: `ls ~/.claude-mem/claude-mem.db`
+3. Test the API directly: `curl "http://localhost:37777/api/search?query=test"`
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Search Tools" icon="magnifying-glass" href="/usage/search-tools">
+    Complete search API reference
+  </Card>
+  <Card title="Platform Integration" icon="plug" href="/platform-integration">
+    Build custom integrations
+  </Card>
+</CardGroup>
@@ -1,6 +1,6 @@
 ---
 title: "Private Tags"
-description: "Control what gets stored in memory with <private> tags"
+description: "Control what gets stored in memory with privacy tags"
 ---

 # Private Tags
@@ -165,8 +165,8 @@ This design ensures that private content never reaches the database, search indi

 ## Related Features

- [Search Tools](search-tools) - How to search past observations
- [Getting Started](getting-started) - Basic usage guide
+- [Search Tools](/usage/search-tools) - How to search past observations
+- [Getting Started](/usage/getting-started) - Basic usage guide
 - [Configuration](/configuration) - System settings and environment variables

 ## Troubleshooting
@@ -175,7 +175,7 @@ This design ensures that private content never reaches the database, search indi

 1. Verify correct syntax: `<private>content</private>`
 2. Check `~/.claude-mem/silent.log` for errors
-3. Ensure worker is running: `pm2 list`
+3. Ensure worker is running: `npm run worker:status`
 4. Restart worker: `npm run worker:restart`

 ### Partial Content Stored
@@ -364,7 +364,7 @@ search_sessions with query="[YOUR PROJECT NAME]" and orderBy="date_desc"
 If search isn't working, check the worker service:

 ```bash
-pm2 list                    # Check worker status
+npm run worker:status       # Check worker status
 npm run worker:restart      # Restart if needed
 npm run worker:logs         # View logs
 ```
@@ -1,38 +0,0 @@
-/**
- * PM2 Ecosystem Configuration for claude-mem Worker Service
- *
- * Usage:
- *   pm2 start ecosystem.config.cjs
- *   pm2 stop claude-mem-worker
- *   pm2 restart claude-mem-worker
- *   pm2 logs claude-mem-worker
- *   pm2 status
- */
-
-module.exports = {
-  apps: [
-    {
-      name: 'claude-mem-worker',
-      script: './plugin/scripts/worker-service.cjs',
-      // INTENTIONAL: Watch mode enables auto-restart on plugin updates
-      //
-      // Why this is enabled:
-      // - When you run `npm run sync-marketplace` or rebuild the plugin,
-      //   files in ~/.claude/plugins/marketplaces/thedotmack/ change
-      // - Watch mode detects these changes and auto-restarts the worker
-      // - Users get the latest code without manually running `pm2 restart`
-      //
-      // This is a feature, not a bug - it ensures users always run the
-      // latest version after plugin updates.
-      watch: true,
-      ignore_watch: [
-        'node_modules',
-        'logs',
-        '*.log',
-        '*.db',
-        '*.db-*',
-        '.git'
-      ]
-    }
-  ]
-};
@@ -1,6 +1,6 @@
 {
  "name": "claude-mem",
-  "version": "6.5.3",
+  "version": "7.1.6",
  "description": "Memory compression system for Claude Code - persist context across sessions",
  "keywords": [
    "claude",
@@ -27,39 +27,40 @@
  },
  "type": "module",
  "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
  },
  "scripts": {
    "build": "node scripts/build-hooks.js",
-    "test": "node --test tests/",
+    "test": "vitest",
    "test:parser": "npx tsx src/sdk/parser.test.ts",
    "test:context": "echo '{\"session_id\":\"test-'$(date +%s)'\",\"cwd\":\"'$(pwd)'\",\"source\":\"startup\"}' | node plugin/scripts/context-hook.js 2>/dev/null",
    "test:context:verbose": "echo '{\"session_id\":\"test-'$(date +%s)'\",\"cwd\":\"'$(pwd)'\",\"source\":\"startup\"}' | node plugin/scripts/context-hook.js",
-    "sync-marketplace": "rsync -av --delete --exclude=.git ./ ~/.claude/plugins/marketplaces/thedotmack/ && cd ~/.claude/plugins/marketplaces/thedotmack/ && npm install",
-    "worker:start": "pm2 start ecosystem.config.cjs",
-    "worker:stop": "pm2 stop claude-mem-worker",
-    "worker:restart": "pm2 restart claude-mem-worker",
-    "worker:logs": "pm2 flush claude-mem-worker && pm2 logs claude-mem-worker --lines 100 --nostream",
-    "worker:logs:no-flush": "pm2 logs claude-mem-worker --lines 100 --nostream",
+    "sync-marketplace": "node scripts/sync-marketplace.cjs",
+    "sync-marketplace:force": "node scripts/sync-marketplace.cjs --force",
+    "build:binaries": "node scripts/build-worker-binary.js",
+    "worker:start": "bun plugin/scripts/worker-cli.js start",
+    "worker:stop": "bun plugin/scripts/worker-cli.js stop",
+    "worker:restart": "bun plugin/scripts/worker-cli.js restart",
+    "worker:status": "bun plugin/scripts/worker-cli.js status",
+    "worker:logs": "tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log",
    "changelog:generate": "node scripts/generate-changelog.js",
    "usage:analyze": "node scripts/analyze-usage.js",
-    "usage:today": "node scripts/analyze-usage.js $(date +%Y-%m-%d)"
+    "usage:today": "node scripts/analyze-usage.js $(date +%Y-%m-%d)",
+    "translate-readme": "npx tsx scripts/translate-readme/cli.ts -v README.md zh ko ja"
  },
  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.1.27",
+    "@anthropic-ai/claude-agent-sdk": "^0.1.67",
    "@modelcontextprotocol/sdk": "^1.20.1",
    "ansi-to-html": "^0.7.2",
-    "better-sqlite3": "^12.5.0",
    "express": "^4.18.2",
    "glob": "^11.0.3",
    "handlebars": "^4.7.8",
-    "pm2": "^6.0.13",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "zod-to-json-schema": "^3.24.6"
  },
  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.8",
    "@types/cors": "^2.8.19",
    "@types/express": "^4.17.21",
    "@types/node": "^20.0.0",
@@ -67,6 +68,7 @@
    "@types/react-dom": "^18.3.0",
    "esbuild": "^0.25.12",
    "tsx": "^4.20.6",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.15"
  }
 }
@@ -1,6 +1,6 @@
 {
  "name": "claude-mem",
-  "version": "6.5.3",
+  "version": "7.1.6",
  "description": "Persistent memory system for Claude Code - seamlessly preserve context across sessions",
  "author": {
    "name": "Alex Newman"
@@ -2,7 +2,7 @@
  "mcpServers": {
    "claude-mem-search": {
      "type": "stdio",
-      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/search-server.cjs"
+      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/mcp-server.cjs"
    }
  }
 }
@@ -7,12 +7,12 @@
        "hooks": [
          {
            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/../scripts/smart-install.js\" && node ${CLAUDE_PLUGIN_ROOT}/scripts/context-hook.js",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/smart-install.js\" && bun \"${CLAUDE_PLUGIN_ROOT}/scripts/context-hook.js\"",
            "timeout": 300
          },
          {
            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/user-message-hook.js",
+            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/user-message-hook.js\"",
            "timeout": 10
          }
        ]
@@ -23,7 +23,7 @@
        "hooks": [
          {
            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/new-hook.js",
+            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/new-hook.js\"",
            "timeout": 120
          }
        ]
@@ -35,7 +35,7 @@
        "hooks": [
          {
            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/save-hook.js",
+            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/save-hook.js\"",
            "timeout": 120
          }
        ]
@@ -46,7 +46,7 @@
        "hooks": [
          {
            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/summary-hook.js",
+            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/summary-hook.js\"",
            "timeout": 120
          }
        ]
@@ -57,7 +57,7 @@
        "hooks": [
          {
            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-hook.js",
+            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-hook.js\"",
            "timeout": 120
          }
        ]
@@ -0,0 +1,12 @@
+{
+  "name": "claude-mem-plugin",
+  "version": "7.1.6",
+  "private": true,
+  "description": "Runtime dependencies for claude-mem bundled hooks",
+  "type": "module",
+  "dependencies": {},
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
+  }
+}
@@ -1,111 +0,0 @@
-#!/bin/bash
-# claude-mem-settings.sh - User settings manager for claude-mem plugin
-
-USER_SETTINGS_FILE="$HOME/.claude/settings.json"
-
-# Function to check if jq is available
-check_jq() {
-    if ! command -v jq &> /dev/null; then
-        echo "Error: jq is required for JSON manipulation"
-        echo "Install with: brew install jq"
-        exit 1
-    fi
-}
-
-# Function to create settings file if it doesn't exist
-ensure_settings_file() {
-    if [ ! -f "$USER_SETTINGS_FILE" ]; then
-        mkdir -p "$(dirname "$USER_SETTINGS_FILE")"
-        echo '{}' > "$USER_SETTINGS_FILE"
-    fi
-}
-
-# Function to get current model setting
-get_model() {
-    if [ -f "$USER_SETTINGS_FILE" ]; then
-        jq -r '.env.CLAUDE_MEM_MODEL // "claude-sonnet-4-5"' "$USER_SETTINGS_FILE"
-    else
-        echo "claude-sonnet-4-5"
-    fi
-}
-
-# Function to set model setting
-set_model() {
-    local model=$1
-
-    ensure_settings_file
-
-    # Update or create the env.CLAUDE_MEM_MODEL setting
-    jq --arg model "$model" '.env.CLAUDE_MEM_MODEL = $model' "$USER_SETTINGS_FILE" > tmp.json && mv tmp.json "$USER_SETTINGS_FILE"
-    echo "Set CLAUDE_MEM_MODEL to: $model"
-}
-
-# Function to remove model setting
-remove_model() {
-    if [ -f "$USER_SETTINGS_FILE" ]; then
-        jq 'del(.env.CLAUDE_MEM_MODEL)' "$USER_SETTINGS_FILE" > tmp.json && mv tmp.json "$USER_SETTINGS_FILE"
-        echo "Removed CLAUDE_MEM_MODEL (will use default: claude-sonnet-4-5)"
-    fi
-}
-
-# Function to list available models
-list_models() {
-    echo "Available models:"
-    echo "  claude-haiku-4-5     - Fast and efficient"
-    echo "  claude-sonnet-4-5    - Balanced (default)"
-    echo "  claude-opus-4        - Most capable"
-    echo "  claude-3-7-sonnet    - Alternative version"
-}
-
-# Interactive menu
-show_menu() {
-    echo "Claude Mem Plugin - Model Configuration"
-    echo "======================================"
-    echo "Current model: $(get_model)"
-    echo "Settings file: $USER_SETTINGS_FILE"
-    echo ""
-    echo "1) Set model"
-    echo "2) Remove model setting (use default)"
-    echo "3) List available models"
-    echo "4) Exit"
-    echo ""
-}
-
-# Main interactive loop
-main() {
-    check_jq
-
-    while true; do
-        show_menu
-        read -p "Choose an option (1-4): " choice
-
-        case $choice in
-            1)
-                list_models
-                echo ""
-                read -p "Enter model name: " model
-                set_model "$model"
-                ;;
-            2)
-                remove_model
-                ;;
-            3)
-                list_models
-                ;;
-            4)
-                echo "Goodbye!"
-                exit 0
-                ;;
-            *)
-                echo "Invalid option. Please choose 1-4."
-                ;;
-        esac
-        echo ""
-        read -p "Press Enter to continue..."
-    done
-}
-
-# Run main if script is executed directly
-if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
-    main "$@"
-fi
@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+/**
+ * Smart Install Script for claude-mem
+ *
+ * Ensures Bun runtime and uv (Python package manager) are installed
+ * (auto-installs if missing) and handles dependency installation when needed.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { execSync, spawnSync } from 'child_process';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const ROOT = join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');
+const MARKER = join(ROOT, '.install-version');
+const IS_WINDOWS = process.platform === 'win32';
+
+/**
+ * Check if Bun is installed and accessible
+ */
+function isBunInstalled() {
+  try {
+    const result = spawnSync('bun', ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    if (result.status === 0) return true;
+  } catch {
+    // PATH check failed, try common installation paths
+  }
+
+  // Check common installation paths (handles fresh installs before PATH reload)
+  const bunPaths = IS_WINDOWS
+    ? [join(homedir(), '.bun', 'bin', 'bun.exe')]
+    : [join(homedir(), '.bun', 'bin', 'bun'), '/usr/local/bin/bun'];
+
+  return bunPaths.some(existsSync);
+}
+
+/**
+ * Get the Bun executable path (from PATH or common install locations)
+ */
+function getBunPath() {
+  // Try PATH first
+  try {
+    const result = spawnSync('bun', ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    if (result.status === 0) return 'bun';
+  } catch {
+    // Not in PATH
+  }
+
+  // Check common installation paths
+  const bunPaths = IS_WINDOWS
+    ? [join(homedir(), '.bun', 'bin', 'bun.exe')]
+    : [join(homedir(), '.bun', 'bin', 'bun'), '/usr/local/bin/bun'];
+
+  for (const bunPath of bunPaths) {
+    if (existsSync(bunPath)) return bunPath;
+  }
+
+  return null;
+}
+
+/**
+ * Get Bun version if installed
+ */
+function getBunVersion() {
+  const bunPath = getBunPath();
+  if (!bunPath) return null;
+
+  try {
+    const result = spawnSync(bunPath, ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    return result.status === 0 ? result.stdout.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if uv is installed and accessible
+ */
+function isUvInstalled() {
+  try {
+    const result = spawnSync('uv', ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    if (result.status === 0) return true;
+  } catch {
+    // PATH check failed, try common installation paths
+  }
+
+  // Check common installation paths (handles fresh installs before PATH reload)
+  const uvPaths = IS_WINDOWS
+    ? [join(homedir(), '.local', 'bin', 'uv.exe'), join(homedir(), '.cargo', 'bin', 'uv.exe')]
+    : [join(homedir(), '.local', 'bin', 'uv'), join(homedir(), '.cargo', 'bin', 'uv'), '/usr/local/bin/uv'];
+
+  return uvPaths.some(existsSync);
+}
+
+/**
+ * Get uv version if installed
+ */
+function getUvVersion() {
+  try {
+    const result = spawnSync('uv', ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    return result.status === 0 ? result.stdout.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Install Bun automatically based on platform
+ */
+function installBun() {
+  console.error('🔧 Bun not found. Installing Bun runtime...');
+
+  try {
+    if (IS_WINDOWS) {
+      // Windows: Use PowerShell installer
+      console.error('   Installing via PowerShell...');
+      execSync('powershell -c "irm bun.sh/install.ps1 | iex"', {
+        stdio: 'inherit',
+        shell: true
+      });
+    } else {
+      // Unix/macOS: Use curl installer
+      console.error('   Installing via curl...');
+      execSync('curl -fsSL https://bun.sh/install | bash', {
+        stdio: 'inherit',
+        shell: true
+      });
+    }
+
+    // Verify installation
+    if (isBunInstalled()) {
+      const version = getBunVersion();
+      console.error(`✅ Bun ${version} installed successfully`);
+      return true;
+    } else {
+      // Bun may be installed but not in PATH yet for this session
+      // Try common installation paths
+      const bunPaths = IS_WINDOWS
+        ? [join(homedir(), '.bun', 'bin', 'bun.exe')]
+        : [join(homedir(), '.bun', 'bin', 'bun'), '/usr/local/bin/bun'];
+
+      for (const bunPath of bunPaths) {
+        if (existsSync(bunPath)) {
+          console.error(`✅ Bun installed at ${bunPath}`);
+          console.error('⚠️  Please restart your terminal or add Bun to PATH:');
+          if (IS_WINDOWS) {
+            console.error(`   $env:Path += ";${join(homedir(), '.bun', 'bin')}"`);
+          } else {
+            console.error(`   export PATH="$HOME/.bun/bin:$PATH"`);
+          }
+          return true;
+        }
+      }
+
+      throw new Error('Bun installation completed but binary not found');
+    }
+  } catch (error) {
+    console.error('❌ Failed to install Bun automatically');
+    console.error('   Please install manually:');
+    if (IS_WINDOWS) {
+      console.error('   - winget install Oven-sh.Bun');
+      console.error('   - Or: powershell -c "irm bun.sh/install.ps1 | iex"');
+    } else {
+      console.error('   - curl -fsSL https://bun.sh/install | bash');
+      console.error('   - Or: brew install oven-sh/bun/bun');
+    }
+    console.error('   Then restart your terminal and try again.');
+    throw error;
+  }
+}
+
+/**
+ * Install uv automatically based on platform
+ */
+function installUv() {
+  console.error('🐍 Installing uv for Python/Chroma support...');
+
+  try {
+    if (IS_WINDOWS) {
+      // Windows: Use PowerShell installer
+      console.error('   Installing via PowerShell...');
+      execSync('powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"', {
+        stdio: 'inherit',
+        shell: true
+      });
+    } else {
+      // Unix/macOS: Use curl installer
+      console.error('   Installing via curl...');
+      execSync('curl -LsSf https://astral.sh/uv/install.sh | sh', {
+        stdio: 'inherit',
+        shell: true
+      });
+    }
+
+    // Verify installation
+    if (isUvInstalled()) {
+      const version = getUvVersion();
+      console.error(`✅ uv ${version} installed successfully`);
+      return true;
+    } else {
+      // uv may be installed but not in PATH yet for this session
+      // Try common installation paths
+      const uvPaths = IS_WINDOWS
+        ? [join(homedir(), '.local', 'bin', 'uv.exe'), join(homedir(), '.cargo', 'bin', 'uv.exe')]
+        : [join(homedir(), '.local', 'bin', 'uv'), join(homedir(), '.cargo', 'bin', 'uv'), '/usr/local/bin/uv'];
+
+      for (const uvPath of uvPaths) {
+        if (existsSync(uvPath)) {
+          console.error(`✅ uv installed at ${uvPath}`);
+          console.error('⚠️  Please restart your terminal or add uv to PATH:');
+          if (IS_WINDOWS) {
+            console.error(`   $env:Path += ";${join(homedir(), '.local', 'bin')}"`);
+          } else {
+            console.error(`   export PATH="$HOME/.local/bin:$PATH"`);
+          }
+          return true;
+        }
+      }
+
+      throw new Error('uv installation completed but binary not found');
+    }
+  } catch (error) {
+    console.error('❌ Failed to install uv automatically');
+    console.error('   Please install manually:');
+    if (IS_WINDOWS) {
+      console.error('   - winget install astral-sh.uv');
+      console.error('   - Or: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"');
+    } else {
+      console.error('   - curl -LsSf https://astral.sh/uv/install.sh | sh');
+      console.error('   - Or: brew install uv (macOS)');
+    }
+    console.error('   Then restart your terminal and try again.');
+    throw error;
+  }
+}
+
+/**
+ * Check if dependencies need to be installed
+ */
+function needsInstall() {
+  if (!existsSync(join(ROOT, 'node_modules'))) return true;
+  try {
+    const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
+    const marker = JSON.parse(readFileSync(MARKER, 'utf-8'));
+    return pkg.version !== marker.version || getBunVersion() !== marker.bun;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Install dependencies using Bun with npm fallback
+ *
+ * Bun has issues with npm alias packages (e.g., string-width-cjs, strip-ansi-cjs)
+ * that are defined in package-lock.json. When bun fails with 404 errors for these
+ * packages, we fall back to npm which handles aliases correctly.
+ */
+function installDeps() {
+  const bunPath = getBunPath();
+  if (!bunPath) {
+    throw new Error('Bun executable not found');
+  }
+
+  console.error('📦 Installing dependencies with Bun...');
+
+  // Quote path for Windows paths with spaces
+  const bunCmd = IS_WINDOWS && bunPath.includes(' ') ? `"${bunPath}"` : bunPath;
+
+  let bunSucceeded = false;
+  try {
+    execSync(`${bunCmd} install`, { cwd: ROOT, stdio: 'inherit', shell: IS_WINDOWS });
+    bunSucceeded = true;
+  } catch {
+    // First attempt failed, try with force flag
+    try {
+      execSync(`${bunCmd} install --force`, { cwd: ROOT, stdio: 'inherit', shell: IS_WINDOWS });
+      bunSucceeded = true;
+    } catch {
+      // Bun failed completely, will try npm fallback
+    }
+  }
+
+  // Fallback to npm if bun failed (handles npm alias packages correctly)
+  if (!bunSucceeded) {
+    console.error('⚠️  Bun install failed, falling back to npm...');
+    console.error('   (This can happen with npm alias packages like *-cjs)');
+    try {
+      execSync('npm install', { cwd: ROOT, stdio: 'inherit', shell: IS_WINDOWS });
+    } catch (npmError) {
+      throw new Error('Both bun and npm install failed: ' + npmError.message);
+    }
+  }
+
+  // Write version marker
+  const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
+  writeFileSync(MARKER, JSON.stringify({
+    version: pkg.version,
+    bun: getBunVersion(),
+    uv: getUvVersion(),
+    installedAt: new Date().toISOString()
+  }));
+}
+
+// Main execution
+try {
+  // Step 1: Ensure Bun is installed (REQUIRED)
+  if (!isBunInstalled()) {
+    installBun();
+
+    // Re-check after installation
+    if (!isBunInstalled()) {
+      console.error('❌ Bun is required but not available in PATH');
+      console.error('   Please restart your terminal after installation');
+      process.exit(1);
+    }
+  }
+
+  // Step 2: Ensure uv is installed (REQUIRED for vector search)
+  if (!isUvInstalled()) {
+    installUv();
+
+    // Re-check after installation
+    if (!isUvInstalled()) {
+      console.error('❌ uv is required but not available in PATH');
+      console.error('   Please restart your terminal after installation');
+      process.exit(1);
+    }
+  }
+
+  // Step 3: Install dependencies if needed
+  if (needsInstall()) {
+    installDeps();
+    console.error('✅ Dependencies installed');
+  }
+} catch (e) {
+  console.error('❌ Installation failed:', e.message);
+  process.exit(1);
+}
@@ -87,7 +87,7 @@ Quick fixes for frequently encountered claude-mem problems.
 **Fix:**
 1. Check the observation count setting:
   ```bash
-   grep CLAUDE_MEM_CONTEXT_OBSERVATIONS ~/.claude/settings.json
+   grep CLAUDE_MEM_CONTEXT_OBSERVATIONS ~/.claude-mem/settings.json
   ```

 2. Default is 50 observations - you can adjust this:
@@ -6,7 +6,7 @@ SQLite database troubleshooting for claude-mem.

 Claude-mem uses SQLite3 for persistent storage:
 - **Location:** `~/.claude-mem/claude-mem.db`
- **Library:** better-sqlite3 (synchronous, not bun:sqlite)
+- **Library:** bun:sqlite (native Bun SQLite, synchronous)
 - **Features:** FTS5 full-text search, triggers, indexes
 - **Tables:** observations, sessions, user_prompts, observations_fts, sessions_fts, prompts_fts

@@ -97,7 +97,6 @@ cd ~/.claude/plugins/marketplaces/thedotmack/

 # Check for critical packages
 ls node_modules/@anthropic-ai/claude-agent-sdk 2>&1 | head -1
-ls node_modules/better-sqlite3 2>&1 | head -1
 ls node_modules/express 2>&1 | head -1
 ls node_modules/pm2 2>&1 | head -1
 ```
@@ -188,7 +187,7 @@ echo "   Health check: $(curl -s http://127.0.0.1:37777/health 2>/dev/null || ec
 echo ""
 echo "5. Configuration"
 echo "   Port setting: $(cat ~/.claude-mem/settings.json 2>/dev/null | grep CLAUDE_MEM_WORKER_PORT || echo 'default (37777)')"
-echo "   Observation count: $(cat ~/.claude/settings.json 2>/dev/null | grep CLAUDE_MEM_CONTEXT_OBSERVATIONS || echo 'default (50)')"
+echo "   Observation count: $(cat ~/.claude-mem/settings.json 2>/dev/null | grep CLAUDE_MEM_CONTEXT_OBSERVATIONS || echo 'default (50)')"
 echo ""
 echo "6. Recent Activity"
 echo "   Latest observation: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT created_at FROM observations ORDER BY created_at DESC LIMIT 1;' 2>/dev/null || echo 'N/A')"
@@ -85,7 +85,7 @@ cat ~/.claude/settings.json
 echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json

 # Change context observation count
-# Edit ~/.claude/settings.json and add:
+# Edit ~/.claude-mem/settings.json and add:
 {
  "env": {
    "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "25"
@@ -187,7 +187,6 @@ pm2 delete claude-mem-worker
   ```bash
   cd ~/.claude/plugins/marketplaces/thedotmack/
   ls node_modules/@anthropic-ai/claude-agent-sdk
-   ls node_modules/better-sqlite3
   ls node_modules/express
   ls node_modules/pm2
   ```
@@ -26,9 +26,19 @@ const WORKER_SERVICE = {
  source: 'src/services/worker-service.ts'
 };

-const SEARCH_SERVER = {
-  name: 'search-server',
-  source: 'src/servers/search-server.ts'
+const MCP_SERVER = {
+  name: 'mcp-server',
+  source: 'src/servers/mcp-server.ts'
+};
+
+const CONTEXT_GENERATOR = {
+  name: 'context-generator',
+  source: 'src/services/context-generator.ts'
+};
+
+const WORKER_CLI = {
+  name: 'worker-cli',
+  source: 'src/cli/worker-cli.ts'
 };

 async function buildHooks() {
@@ -53,6 +63,24 @@ async function buildHooks() {
    }
    console.log('✓ Output directories ready');

+    // Generate plugin/package.json for cache directory dependency installation
+    // Note: bun:sqlite is a Bun built-in, no external dependencies needed for SQLite
+    console.log('\n📦 Generating plugin package.json...');
+    const pluginPackageJson = {
+      name: 'claude-mem-plugin',
+      version: version,
+      private: true,
+      description: 'Runtime dependencies for claude-mem bundled hooks',
+      type: 'module',
+      dependencies: {},
+      engines: {
+        node: '>=18.0.0',
+        bun: '>=1.0.0'
+      }
+    };
+    fs.writeFileSync('plugin/package.json', JSON.stringify(pluginPackageJson, null, 2) + '\n');
+    console.log('✓ plugin/package.json generated');
+
    // Build React viewer
    console.log('\n📋 Building React viewer...');
    const { spawn } = await import('child_process');
@@ -78,12 +106,12 @@ async function buildHooks() {
      outfile: `${hooksDir}/${WORKER_SERVICE.name}.cjs`,
      minify: true,
      logLevel: 'error', // Suppress warnings (import.meta warning is benign)
-      external: ['better-sqlite3'],
+      external: ['bun:sqlite'],
      define: {
        '__DEFAULT_PACKAGE_VERSION__': `"${version}"`
      },
      banner: {
-        js: '#!/usr/bin/env node'
+        js: '#!/usr/bin/env bun'
      }
    });

@@ -92,30 +120,75 @@ async function buildHooks() {
    const workerStats = fs.statSync(`${hooksDir}/${WORKER_SERVICE.name}.cjs`);
    console.log(`✓ worker-service built (${(workerStats.size / 1024).toFixed(2)} KB)`);

-    // Build search server
-    console.log(`\n🔧 Building search server...`);
+    // Build MCP server
+    console.log(`\n🔧 Building MCP server...`);
    await build({
-      entryPoints: [SEARCH_SERVER.source],
+      entryPoints: [MCP_SERVER.source],
      bundle: true,
      platform: 'node',
      target: 'node18',
      format: 'cjs',
-      outfile: `${hooksDir}/${SEARCH_SERVER.name}.cjs`,
+      outfile: `${hooksDir}/${MCP_SERVER.name}.cjs`,
      minify: true,
      logLevel: 'error',
-      external: ['better-sqlite3'],
+      external: ['bun:sqlite'],
      define: {
        '__DEFAULT_PACKAGE_VERSION__': `"${version}"`
      },
      banner: {
-        js: '#!/usr/bin/env node'
+        js: '#!/usr/bin/env bun'
      }
    });

-    // Make search server executable
-    fs.chmodSync(`${hooksDir}/${SEARCH_SERVER.name}.cjs`, 0o755);
-    const searchServerStats = fs.statSync(`${hooksDir}/${SEARCH_SERVER.name}.cjs`);
-    console.log(`✓ search-server built (${(searchServerStats.size / 1024).toFixed(2)} KB)`);
+    // Make MCP server executable
+    fs.chmodSync(`${hooksDir}/${MCP_SERVER.name}.cjs`, 0o755);
+    const mcpServerStats = fs.statSync(`${hooksDir}/${MCP_SERVER.name}.cjs`);
+    console.log(`✓ mcp-server built (${(mcpServerStats.size / 1024).toFixed(2)} KB)`);
+
+    // Build context generator
+    console.log(`\n🔧 Building context generator...`);
+    await build({
+      entryPoints: [CONTEXT_GENERATOR.source],
+      bundle: true,
+      platform: 'node',
+      target: 'node18',
+      format: 'cjs',
+      outfile: `${hooksDir}/${CONTEXT_GENERATOR.name}.cjs`,
+      minify: true,
+      logLevel: 'error',
+      external: ['bun:sqlite'],
+      define: {
+        '__DEFAULT_PACKAGE_VERSION__': `"${version}"`
+      }
+    });
+
+    const contextGenStats = fs.statSync(`${hooksDir}/${CONTEXT_GENERATOR.name}.cjs`);
+    console.log(`✓ context-generator built (${(contextGenStats.size / 1024).toFixed(2)} KB)`);
+
+    // Build worker CLI
+    console.log(`\n🔧 Building worker CLI...`);
+    await build({
+      entryPoints: [WORKER_CLI.source],
+      bundle: true,
+      platform: 'node',
+      target: 'node18',
+      format: 'esm',
+      outfile: `${hooksDir}/${WORKER_CLI.name}.js`,
+      minify: true,
+      logLevel: 'error',
+      external: ['bun:sqlite'],
+      define: {
+        '__DEFAULT_PACKAGE_VERSION__': `"${version}"`
+      },
+      banner: {
+        js: '#!/usr/bin/env bun'
+      }
+    });
+
+    // Make worker CLI executable
+    fs.chmodSync(`${hooksDir}/${WORKER_CLI.name}.js`, 0o755);
+    const workerCliStats = fs.statSync(`${hooksDir}/${WORKER_CLI.name}.js`);
+    console.log(`✓ worker-cli built (${(workerCliStats.size / 1024).toFixed(2)} KB)`);

    // Build each hook
    for (const hook of HOOKS) {
@@ -131,12 +204,12 @@ async function buildHooks() {
        format: 'esm',
        outfile,
        minify: true,
-        external: ['better-sqlite3'],
+        external: ['bun:sqlite'],
        define: {
          '__DEFAULT_PACKAGE_VERSION__': `"${version}"`
        },
        banner: {
-          js: '#!/usr/bin/env node'
+          js: '#!/usr/bin/env bun'
        }
      });

@@ -149,11 +222,11 @@ async function buildHooks() {
      console.log(`✓ ${hook.name} built (${sizeInKB} KB)`);
    }

-    console.log('\n✅ All hooks, worker service, and search server built successfully!');
+    console.log('\n✅ All hooks, worker service, and MCP server built successfully!');
    console.log(`   Output: ${hooksDir}/`);
    console.log(`   - Hooks: *-hook.js`);
    console.log(`   - Worker: worker-service.cjs`);
-    console.log(`   - Search Server: search-server.cjs`);
+    console.log(`   - MCP Server: mcp-server.cjs`);
    console.log(`   - Skills: plugin/skills/`);
    console.log('\n💡 Note: Dependencies will be auto-installed on first hook execution');

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * Build Windows executable for claude-mem worker service
+ * Uses Bun's compile feature to create a standalone exe
+ */
+
+import { execSync } from 'child_process';
+import fs from 'fs';
+
+const version = JSON.parse(fs.readFileSync('package.json', 'utf-8')).version;
+const outDir = 'dist/binaries';
+
+fs.mkdirSync(outDir, { recursive: true });
+
+console.log(`Building Windows exe v${version}...`);
+
+try {
+  execSync(
+    `bun build --compile --minify --target=bun-windows-x64 ./src/services/worker-service.ts --outfile ${outDir}/worker-service-v${version}-win-x64.exe`,
+    { stdio: 'inherit' }
+  );
+  console.log(`\nBuilt: ${outDir}/worker-service-v${version}-win-x64.exe`);
+} catch (error) {
+  console.error('Failed to build Windows binary:', error.message);
+  process.exit(1);
+}
@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+/**
+ * One-time script to extract tool handlers from mcp-server.ts into SearchManager.ts
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const projectRoot = join(__dirname, '..');
+
+const mcpServerPath = join(projectRoot, 'src/servers/mcp-server.ts');
+const outputPath = join(projectRoot, 'src/services/worker/SearchManager.ts');
+
+console.log('Reading mcp-server.ts...');
+const content = readFileSync(mcpServerPath, 'utf-8');
+
+// Extract just the sections we need by finding line numbers
+// This is more reliable than parsing
+
+// Extract tool handler bodies by finding each "handler: async (args: any) => {"
+// and extracting until the matching closing brace
+
+const extractHandlerBody = (content, startPattern) => {
+  const lines = content.split('\n');
+  const startIdx = lines.findIndex(line => line.includes(startPattern));
+
+  if (startIdx === -1) return null;
+
+  // Find the "handler: async (args: any) => {" line
+  let handlerIdx = -1;
+  for (let i = startIdx; i < Math.min(startIdx + 30, lines.length); i++) {
+    if (lines[i].includes('handler: async (args: any) => {')) {
+      handlerIdx = i;
+      break;
+    }
+  }
+
+  if (handlerIdx === -1) return null;
+
+  // Extract the body by counting braces
+  let braceCount = 0;
+  let bodyLines = [];
+  let started = false;
+
+  for (let i = handlerIdx; i < lines.length; i++) {
+    const line = lines[i];
+
+    for (const char of line) {
+      if (char === '{') {
+        braceCount++;
+        started = true;
+      } else if (char === '}') {
+        braceCount--;
+      }
+    }
+
+    if (started) {
+      bodyLines.push(line);
+    }
+
+    if (started && braceCount === 0) {
+      break;
+    }
+  }
+
+  // Remove the first line (handler wrapper) and last line (closing brace)
+  if (bodyLines.length > 2) {
+    bodyLines = bodyLines.slice(1, -1);
+  }
+
+  return bodyLines.join('\n');
+};
+
+// Tool name to search pattern mapping
+const tools = {
+  'search': "name: 'search'",
+  'timeline': "name: 'timeline'",
+  'decisions': "name: 'decisions'",
+  'changes': "name: 'changes'",
+  'how_it_works': "name: 'how_it_works'",
+  'search_observations': "name: 'search_observations'",
+  'search_sessions': "name: 'search_sessions'",
+  'search_user_prompts': "name: 'search_user_prompts'",
+  'find_by_concept': "name: 'find_by_concept'",
+  'find_by_file': "name: 'find_by_file'",
+  'find_by_type': "name: 'find_by_type'",
+  'get_recent_context': "name: 'get_recent_context'",
+  'get_context_timeline': "name: 'get_context_timeline'",
+  'get_timeline_by_query': "name: 'get_timeline_by_query'"
+};
+
+console.log('Extracting tool handlers...');
+const handlers = {};
+
+for (const [toolName, pattern] of Object.entries(tools)) {
+  console.log(`  Extracting ${toolName}...`);
+  const body = extractHandlerBody(content, pattern);
+  if (body) {
+    handlers[toolName] = body;
+    console.log(`    ✓ ${body.split('\n').length} lines`);
+  } else {
+    console.log(`    ✗ Not found`);
+  }
+}
+
+console.log(`\nExtracted ${Object.keys(handlers).length}/${Object.keys(tools).length} handlers`);
+
+// Now generate SearchManager.ts
+console.log('\nGenerating SearchManager.ts...');
+
+const methodBodies = Object.entries(handlers).map(([toolName, body]) => {
+  // Convert tool name to camelCase method name
+  const methodName = toolName.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+
+  // Replace standalone function calls with class methods
+  let processedBody = body
+    .replace(/formatSearchTips\(\)/g, 'this.formatter.formatSearchTips()')
+    .replace(/formatObservationIndex\(/g, 'this.formatter.formatObservationIndex(')
+    .replace(/formatSessionIndex\(/g, 'this.formatter.formatSessionIndex(')
+    .replace(/formatUserPromptIndex\(/g, 'this.formatter.formatUserPromptIndex(')
+    .replace(/formatObservationResult\(/g, 'this.formatter.formatObservationResult(')
+    .replace(/formatSessionResult\(/g, 'this.formatter.formatSessionResult(')
+    .replace(/formatUserPromptResult\(/g, 'this.formatter.formatUserPromptResult(')
+    .replace(/filterTimelineByDepth\(/g, 'this.timeline.filterByDepth(')
+    .replace(/\bsearch\./g, 'this.sessionSearch.')
+    .replace(/\bstore\./g, 'this.sessionStore.')
+    .replace(/queryChroma\(/g, 'this.queryChroma(')
+    .replace(/normalizeParams\(/g, 'this.normalizeParams(')
+    .replace(/chromaClient/g, 'this.chromaSync');
+
+  return `  /**
+   * Tool handler: ${toolName}
+   */
+  async ${methodName}(args: any): Promise<any> {
+${processedBody}
+  }`;
+}).join('\n\n');
+
+const searchManagerContent = `/**
+ * SearchManager - Core search orchestration for claude-mem
+ * Extracted from mcp-server.ts to centralize business logic in Worker services
+ *
+ * This class contains all tool handler logic that was previously in the MCP server.
+ * The MCP server now acts as a thin HTTP wrapper that calls these methods via HTTP.
+ */
+
+import { SessionSearch } from '../sqlite/SessionSearch.js';
+import { SessionStore } from '../sqlite/SessionStore.js';
+import { ChromaSync } from '../sync/ChromaSync.js';
+import { FormattingService } from './FormattingService.js';
+import { TimelineService, TimelineItem } from './TimelineService.js';
+import { ObservationSearchResult, SessionSummarySearchResult, UserPromptSearchResult } from '../sqlite/types.js';
+import { silentDebug } from '../../utils/silent-debug.js';
+
+const COLLECTION_NAME = 'cm__claude-mem';
+
+export class SearchManager {
+  constructor(
+    private sessionSearch: SessionSearch,
+    private sessionStore: SessionStore,
+    private chromaSync: ChromaSync,
+    private formatter: FormattingService,
+    private timeline: TimelineService
+  ) {}
+
+  /**
+   * Query Chroma vector database via ChromaSync
+   */
+  private async queryChroma(
+    query: string,
+    limit: number,
+    whereFilter?: Record<string, any>
+  ): Promise<{ ids: number[]; distances: number[]; metadatas: any[] }> {
+    return await this.chromaSync.queryChroma(query, limit, whereFilter);
+  }
+
+  /**
+   * Helper to normalize query parameters from URL-friendly format
+   * Converts comma-separated strings to arrays and flattens date params
+   */
+  private normalizeParams(args: any): any {
+    const normalized: any = { ...args };
+
+    // Parse comma-separated concepts into array
+    if (normalized.concepts && typeof normalized.concepts === 'string') {
+      normalized.concepts = normalized.concepts.split(',').map((s: string) => s.trim()).filter(Boolean);
+    }
+
+    // Parse comma-separated files into array
+    if (normalized.files && typeof normalized.files === 'string') {
+      normalized.files = normalized.files.split(',').map((s: string) => s.trim()).filter(Boolean);
+    }
+
+    // Parse comma-separated obs_type into array
+    if (normalized.obs_type && typeof normalized.obs_type === 'string') {
+      normalized.obs_type = normalized.obs_type.split(',').map((s: string) => s.trim()).filter(Boolean);
+    }
+
+    // Parse comma-separated type (for filterSchema) into array
+    if (normalized.type && typeof normalized.type === 'string' && normalized.type.includes(',')) {
+      normalized.type = normalized.type.split(',').map((s: string) => s.trim()).filter(Boolean);
+    }
+
+    // Flatten dateStart/dateEnd into dateRange object
+    if (normalized.dateStart || normalized.dateEnd) {
+      normalized.dateRange = {
+        start: normalized.dateStart,
+        end: normalized.dateEnd
+      };
+      delete normalized.dateStart;
+      delete normalized.dateEnd;
+    }
+
+    return normalized;
+  }
+
+${methodBodies}
+}
+`;
+
+writeFileSync(outputPath, searchManagerContent, 'utf-8');
+
+console.log(`\n✅ SearchManager.ts generated at ${outputPath}`);
+console.log(`   Total methods: ${Object.keys(handlers).length + 2} (${Object.keys(handlers).length} tools + queryChroma + normalizeParams)`);
+console.log(`   File size: ${(searchManagerContent.length / 1024).toFixed(1)} KB`);
@@ -0,0 +1,38 @@
+#!/bin/bash
+# Find Silent Failure Patterns
+#
+# This script searches for defensive OR patterns (|| '' || null || undefined)
+# that should potentially use happy_path_error__with_fallback instead.
+#
+# Usage: ./scripts/find-silent-failures.sh
+
+echo "=================================================="
+echo "Searching for defensive OR patterns in src/"
+echo "These MAY be silent failures that should log errors"
+echo "=================================================="
+echo ""
+
+echo "🔍 Searching for: || ''"
+echo "---"
+grep -rn "|| ''" src/ --include="*.ts" --color=always || echo "  (none found)"
+echo ""
+
+echo "🔍 Searching for: || \"\""
+echo "---"
+grep -rn '|| ""' src/ --include="*.ts" --color=always || echo "  (none found)"
+echo ""
+
+echo "🔍 Searching for: || null"
+echo "---"
+grep -rn "|| null" src/ --include="*.ts" --color=always || echo "  (none found)"
+echo ""
+
+echo "🔍 Searching for: || undefined"
+echo "---"
+grep -rn "|| undefined" src/ --include="*.ts" --color=always || echo "  (none found)"
+echo ""
+
+echo "=================================================="
+echo "Review each match and determine if it should use:"
+echo "  happy_path_error__with_fallback('description', data, fallback)"
+echo "=================================================="
@@ -1,403 +1,259 @@
 #!/usr/bin/env node
-
 /**
 * Smart Install Script for claude-mem
 *
- * Features:
- * - Only runs npm install when necessary (version change or missing deps)
- * - Caches installation state with version marker
- * - Provides helpful Windows-specific error messages
- * - Cross-platform compatible (pure Node.js)
- * - Fast when already installed (just version check)
+ * Ensures Bun runtime and uv (Python package manager) are installed
+ * (auto-installs if missing) and handles dependency installation when needed.
 */
-
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { execSync, spawnSync } from 'child_process';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { join } from 'path';
+import { homedir } from 'os';

-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+const ROOT = join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');
+const MARKER = join(ROOT, '.install-version');
+const IS_WINDOWS = process.platform === 'win32';

-// Plugin root is parent directory of scripts/
-const PLUGIN_ROOT = join(__dirname, '..');
-const PACKAGE_JSON_PATH = join(PLUGIN_ROOT, 'package.json');
-const VERSION_MARKER_PATH = join(PLUGIN_ROOT, '.install-version');
-const NODE_MODULES_PATH = join(PLUGIN_ROOT, 'node_modules');
-const BETTER_SQLITE3_PATH = join(NODE_MODULES_PATH, 'better-sqlite3');
+// Common installation paths (handles fresh installs before PATH reload)
+const BUN_COMMON_PATHS = IS_WINDOWS
+  ? [join(homedir(), '.bun', 'bin', 'bun.exe')]
+  : [join(homedir(), '.bun', 'bin', 'bun'), '/usr/local/bin/bun'];

-// Colors for output
-const colors = {
-  reset: '\x1b[0m',
-  bright: '\x1b[1m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  red: '\x1b[31m',
-  cyan: '\x1b[36m',
-  dim: '\x1b[2m',
-};
+const UV_COMMON_PATHS = IS_WINDOWS
+  ? [join(homedir(), '.local', 'bin', 'uv.exe'), join(homedir(), '.cargo', 'bin', 'uv.exe')]
+  : [join(homedir(), '.local', 'bin', 'uv'), join(homedir(), '.cargo', 'bin', 'uv'), '/usr/local/bin/uv'];

-function log(message, color = colors.reset) {
-  console.error(`${color}${message}${colors.reset}`);
+/**
+ * Get the Bun executable path (from PATH or common install locations)
+ */
+function getBunPath() {
+  // Try PATH first
+  try {
+    const result = spawnSync('bun', ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    if (result.status === 0) return 'bun';
+  } catch {
+    // Not in PATH
+  }
+
+  // Check common installation paths
+  return BUN_COMMON_PATHS.find(existsSync) || null;
 }

-function getPackageVersion() {
+/**
+ * Check if Bun is installed and accessible
+ */
+function isBunInstalled() {
+  return getBunPath() !== null;
+}
+
+/**
+ * Get Bun version if installed
+ */
+function getBunVersion() {
+  const bunPath = getBunPath();
+  if (!bunPath) return null;
+
  try {
-    const packageJson = JSON.parse(readFileSync(PACKAGE_JSON_PATH, 'utf-8'));
-    return packageJson.version;
-  } catch (error) {
-    log(`⚠️  Failed to read package.json: ${error.message}`, colors.yellow);
+    const result = spawnSync(bunPath, ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    return result.status === 0 ? result.stdout.trim() : null;
+  } catch {
    return null;
  }
 }

-function getNodeVersion() {
-  return process.version; // e.g., "v22.21.1"
-}
-
-function getInstalledVersion() {
+/**
+ * Get the uv executable path (from PATH or common install locations)
+ */
+function getUvPath() {
+  // Try PATH first
  try {
-    if (existsSync(VERSION_MARKER_PATH)) {
-      const content = readFileSync(VERSION_MARKER_PATH, 'utf-8').trim();
-
-      // Try parsing as JSON (new format)
-      try {
-        const marker = JSON.parse(content);
-        return {
-          packageVersion: marker.packageVersion,
-          nodeVersion: marker.nodeVersion,
-          installedAt: marker.installedAt
-        };
-      } catch {
-        // Fallback: old format (plain text version string)
-        return {
-          packageVersion: content,
-          nodeVersion: null, // Unknown
-          installedAt: null
-        };
-      }
-    }
-  } catch (error) {
-    // Marker doesn't exist or can't be read
-  }
-  return null;
-}
-
-function setInstalledVersion(packageVersion, nodeVersion) {
-  try {
-    const marker = {
-      packageVersion,
-      nodeVersion,
-      installedAt: new Date().toISOString()
-    };
-    writeFileSync(VERSION_MARKER_PATH, JSON.stringify(marker, null, 2), 'utf-8');
-  } catch (error) {
-    log(`⚠️  Failed to write version marker: ${error.message}`, colors.yellow);
-  }
-}
-
-function needsInstall() {
-  // Check if node_modules exists
-  if (!existsSync(NODE_MODULES_PATH)) {
-    log('📦 Dependencies not found - first time setup', colors.cyan);
-    return true;
+    const result = spawnSync('uv', ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    if (result.status === 0) return 'uv';
+  } catch {
+    // Not in PATH
  }

-  // Check if better-sqlite3 is installed
-  if (!existsSync(BETTER_SQLITE3_PATH)) {
-    log('📦 better-sqlite3 missing - reinstalling', colors.cyan);
-    return true;
-  }
-
-  // Check version marker
-  const currentPackageVersion = getPackageVersion();
-  const currentNodeVersion = getNodeVersion();
-  const installed = getInstalledVersion();
-
-  if (!installed) {
-    log('📦 No version marker found - installing', colors.cyan);
-    return true;
-  }
-
-  // Check package version
-  if (currentPackageVersion !== installed.packageVersion) {
-    log(`📦 Version changed (${installed.packageVersion} → ${currentPackageVersion}) - updating`, colors.cyan);
-    return true;
-  }
-
-  // Check Node.js version
-  if (installed.nodeVersion && currentNodeVersion !== installed.nodeVersion) {
-    log(`📦 Node.js version changed (${installed.nodeVersion} → ${currentNodeVersion}) - rebuilding native modules`, colors.cyan);
-    return true;
-  }
-
-  // If old format (no nodeVersion), assume needs install
-  if (!installed.nodeVersion) {
-    log('📦 Old version marker format - updating', colors.cyan);
-    return true;
-  }
-
-  // All good - no install needed
-  log(`✓ Dependencies already installed (v${currentPackageVersion})`, colors.dim);
-  return false;
+  // Check common installation paths
+  return UV_COMMON_PATHS.find(existsSync) || null;
 }

 /**
- * Verify that better-sqlite3 native module loads correctly
- * This catches ABI mismatches and corrupted builds
+ * Check if uv is installed and accessible
 */
-async function verifyNativeModules() {
+function isUvInstalled() {
+  return getUvPath() !== null;
+}
+
+/**
+ * Get uv version if installed
+ */
+function getUvVersion() {
+  const uvPath = getUvPath();
+  if (!uvPath) return null;
+
  try {
-    log('🔍 Verifying native modules...', colors.dim);
-
-    // Try to actually load better-sqlite3
-    const { default: Database } = await import('better-sqlite3');
-
-    // Try to create a test in-memory database
-    const db = new Database(':memory:');
-
-    // Run a simple query to ensure it works
-    const result = db.prepare('SELECT 1 + 1 as result').get();
-
-    // Clean up
-    db.close();
-
-    if (result.result !== 2) {
-      throw new Error('SQLite math check failed');
-    }
-
-    log('✓ Native modules verified', colors.dim);
-    return true;
-
-  } catch (error) {
-    if (error.code === 'ERR_DLOPEN_FAILED') {
-      log('⚠️  Native module ABI mismatch detected', colors.yellow);
-      return false;
-    }
-
-    // Other errors are unexpected - log and fail
-    log(`❌ Native module verification failed: ${error.message}`, colors.red);
-    return false;
+    const result = spawnSync(uvPath, ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    return result.status === 0 ? result.stdout.trim() : null;
+  } catch {
+    return null;
  }
 }

-function getWindowsErrorHelp(errorOutput) {
-  // Detect Python version at runtime
-  let pythonStatus = '   Python not detected or version unknown';
+/**
+ * Install Bun automatically based on platform
+ */
+function installBun() {
+  console.error('🔧 Bun not found. Installing Bun runtime...');
+
  try {
-    const pythonVersion = execSync('python --version', { encoding: 'utf-8', stdio: 'pipe' }).trim();
-    const versionMatch = pythonVersion.match(/Python\s+([\d.]+)/);
-    if (versionMatch) {
-      pythonStatus = `   You have ${versionMatch[0]} installed ✓`;
-    }
-  } catch (error) {
-    // Python not available or failed to detect - use default message
-  }
-
-  const help = [
-    '',
-    '╔══════════════════════════════════════════════════════════════════════╗',
-    '║                    Windows Installation Help                        ║',
-    '╚══════════════════════════════════════════════════════════════════════╝',
-    '',
-    '📋 better-sqlite3 requires build tools to compile native modules.',
-    '',
-    '🔧 Option 1: Install Visual Studio Build Tools (Recommended)',
-    '   1. Download: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022',
-    '   2. Install "Desktop development with C++"',
-    '   3. Restart your terminal',
-    '   4. Try again',
-    '',
-    '🔧 Option 2: Install via npm (automated)',
-    '   Run as Administrator:',
-    '   npm install --global windows-build-tools',
-    '',
-    '🐍 Python Requirement:',
-    '   Python 3.6+ is required.',
-    pythonStatus,
-    '',
-  ];
-
-  // Check for specific error patterns
-  if (errorOutput.includes('MSBuild.exe')) {
-    help.push('❌ MSBuild not found - install Visual Studio Build Tools');
-  }
-  if (errorOutput.includes('MSVS')) {
-    help.push('❌ Visual Studio not detected - install Build Tools');
-  }
-  if (errorOutput.includes('permission') || errorOutput.includes('EPERM')) {
-    help.push('❌ Permission denied - try running as Administrator');
-  }
-
-  help.push('');
-  help.push('📖 Full documentation: https://github.com/WiseLibs/better-sqlite3/blob/master/docs/troubleshooting.md');
-  help.push('');
-
-  return help.join('\n');
-}
-
-async function runNpmInstall() {
-  const isWindows = process.platform === 'win32';
-
-  log('', colors.cyan);
-  log('🔨 Installing dependencies...', colors.bright);
-  log('', colors.reset);
-
-  // Try normal install first, then retry with force if it fails
-  const strategies = [
-    { command: 'npm install', label: 'normal' },
-    { command: 'npm install --force', label: 'with force flag' },
-  ];
-
-  let lastError = null;
-
-  for (const { command, label } of strategies) {
-    try {
-      log(`Attempting install ${label}...`, colors.dim);
-
-      // Run npm install silently
-      execSync(command, {
-        cwd: PLUGIN_ROOT,
-        stdio: 'pipe', // Silent output unless error
-        encoding: 'utf-8',
+    if (IS_WINDOWS) {
+      console.error('   Installing via PowerShell...');
+      execSync('powershell -c "irm bun.sh/install.ps1 | iex"', {
+        stdio: 'inherit',
+        shell: true
+      });
+    } else {
+      console.error('   Installing via curl...');
+      execSync('curl -fsSL https://bun.sh/install | bash', {
+        stdio: 'inherit',
+        shell: true
      });
-
-      // Verify better-sqlite3 was installed
-      if (!existsSync(BETTER_SQLITE3_PATH)) {
-        throw new Error('better-sqlite3 installation verification failed');
-      }
-
-      // NEW: Verify native modules actually work
-      const nativeModulesWork = await verifyNativeModules();
-      if (!nativeModulesWork) {
-        throw new Error('Native modules failed to load after install');
-      }
-
-      const packageVersion = getPackageVersion();
-      const nodeVersion = getNodeVersion();
-      setInstalledVersion(packageVersion, nodeVersion);
-
-      log('', colors.green);
-      log('✅ Dependencies installed successfully!', colors.bright);
-      log(`   Package version: ${packageVersion}`, colors.dim);
-      log(`   Node.js version: ${nodeVersion}`, colors.dim);
-      log('', colors.reset);
-
-      return true;
-
-    } catch (error) {
-      lastError = error;
-      // Continue to next strategy
-    }
-  }
-
-  // All strategies failed - show error
-  log('', colors.red);
-  log('❌ Installation failed after retrying!', colors.bright);
-  log('', colors.reset);
-
-  // Provide Windows-specific help
-  if (isWindows && lastError && lastError.message && lastError.message.includes('better-sqlite3')) {
-    log(getWindowsErrorHelp(lastError.message), colors.yellow);
-  }
-
-  // Show generic error info with troubleshooting steps
-  if (lastError) {
-    if (lastError.stderr) {
-      log('Error output:', colors.dim);
-      log(lastError.stderr.toString(), colors.red);
-    } else if (lastError.message) {
-      log(lastError.message, colors.red);
    }

-    log('', colors.yellow);
-    log('📋 Troubleshooting Steps:', colors.bright);
-    log('', colors.reset);
-    log('1. Check your internet connection', colors.yellow);
-    log('2. Try running: npm cache clean --force', colors.yellow);
-    log('3. Try running: npm install (in plugin directory)', colors.yellow);
-    log('4. Check npm version: npm --version (requires npm 7+)', colors.yellow);
-    log('5. Try updating npm: npm install -g npm@latest', colors.yellow);
-    log('', colors.reset);
-  }
+    if (!isBunInstalled()) {
+      throw new Error(
+        'Bun installation completed but binary not found. ' +
+        'Please restart your terminal and try again.'
+      );
+    }

-  return false;
+    const version = getBunVersion();
+    console.error(`✅ Bun ${version} installed successfully`);
+  } catch (error) {
+    console.error('❌ Failed to install Bun');
+    console.error('   Please install manually:');
+    if (IS_WINDOWS) {
+      console.error('   - winget install Oven-sh.Bun');
+      console.error('   - Or: powershell -c "irm bun.sh/install.ps1 | iex"');
+    } else {
+      console.error('   - curl -fsSL https://bun.sh/install | bash');
+      console.error('   - Or: brew install oven-sh/bun/bun');
+    }
+    console.error('   Then restart your terminal and try again.');
+    throw error;
+  }
 }

 /**
- * Check if we should fail when worker startup fails
- * Returns true if worker failed AND dependencies are missing
+ * Install uv automatically based on platform
 */
-function shouldFailOnWorkerStartup(workerStarted) {
-  return !workerStarted && !existsSync(NODE_MODULES_PATH);
-}
+function installUv() {
+  console.error('🐍 Installing uv for Python/Chroma support...');

-async function main() {
  try {
-    // Check if we need to install dependencies
-    const installNeeded = needsInstall();
-
-    if (installNeeded) {
-      // Run installation (now async)
-      const installSuccess = await runNpmInstall();
-
-      if (!installSuccess) {
-        log('', colors.red);
-        log('⚠️  Installation failed', colors.yellow);
-        log('', colors.reset);
-        process.exit(1);
-      }
+    if (IS_WINDOWS) {
+      console.error('   Installing via PowerShell...');
+      execSync('powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"', {
+        stdio: 'inherit',
+        shell: true
+      });
    } else {
-      // NEW: Even if install not needed, verify native modules work
-      const nativeModulesWork = await verifyNativeModules();
-
-      if (!nativeModulesWork) {
-        log('📦 Native modules need rebuild - reinstalling', colors.cyan);
-        const installSuccess = await runNpmInstall();
-
-        if (!installSuccess) {
-          log('', colors.red);
-          log('⚠️  Native module rebuild failed', colors.yellow);
-          log('', colors.reset);
-          process.exit(1);
-        }
-      }
+      console.error('   Installing via curl...');
+      execSync('curl -LsSf https://astral.sh/uv/install.sh | sh', {
+        stdio: 'inherit',
+        shell: true
+      });
    }

-      // Try to start the PM2 worker after fresh install
-      try {
-        log('🚀 Starting worker service...', colors.cyan);
-        // On Windows, PM2 executable is pm2.cmd, not pm2
-        const localPm2Base = join(NODE_MODULES_PATH, '.bin', 'pm2');
-        const localPm2Cmd = process.platform === 'win32' ? localPm2Base + '.cmd' : localPm2Base;
-        const pm2Command = existsSync(localPm2Cmd) ? localPm2Cmd : 'pm2';
-        const ecosystemPath = join(PLUGIN_ROOT, 'ecosystem.config.cjs');
-
-        // Using spawnSync with array args to avoid command injection risks
-        const result = spawnSync(pm2Command, ['start', ecosystemPath], {
-          cwd: PLUGIN_ROOT,
-          stdio: 'pipe',
-          encoding: 'utf-8'
-        });
-        if (result.status !== 0) {
-          throw new Error(result.stderr || 'PM2 start failed');
-        }
-
-        log('✅ Worker service started', colors.green);
-      } catch (error) {
-        // Worker might already be running or PM2 not available - that's okay
-        // The ensureWorkerRunning() function will handle auto-start when needed
-        log('ℹ️  Worker will start automatically when needed', colors.dim);
-      }
-
-    // Success - dependencies installed (if needed)
-    process.exit(0);
+    if (!isUvInstalled()) {
+      throw new Error(
+        'uv installation completed but binary not found. ' +
+        'Please restart your terminal and try again.'
+      );
+    }

+    const version = getUvVersion();
+    console.error(`✅ uv ${version} installed successfully`);
  } catch (error) {
-    log(`❌ Unexpected error: ${error.message}`, colors.red);
-    log('', colors.reset);
-    process.exit(1);
+    console.error('❌ Failed to install uv');
+    console.error('   Please install manually:');
+    if (IS_WINDOWS) {
+      console.error('   - winget install astral-sh.uv');
+      console.error('   - Or: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"');
+    } else {
+      console.error('   - curl -LsSf https://astral.sh/uv/install.sh | sh');
+      console.error('   - Or: brew install uv (macOS)');
+    }
+    console.error('   Then restart your terminal and try again.');
+    throw error;
  }
 }

-main();
+/**
+ * Check if dependencies need to be installed
+ */
+function needsInstall() {
+  if (!existsSync(join(ROOT, 'node_modules'))) return true;
+  try {
+    const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
+    const marker = JSON.parse(readFileSync(MARKER, 'utf-8'));
+    return pkg.version !== marker.version || getBunVersion() !== marker.bun;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Install dependencies using Bun
+ */
+function installDeps() {
+  const bunPath = getBunPath();
+  if (!bunPath) {
+    throw new Error('Bun executable not found');
+  }
+
+  console.error('📦 Installing dependencies with Bun...');
+
+  // Quote path for Windows paths with spaces
+  const bunCmd = IS_WINDOWS && bunPath.includes(' ') ? `"${bunPath}"` : bunPath;
+
+  execSync(`${bunCmd} install`, { cwd: ROOT, stdio: 'inherit', shell: IS_WINDOWS });
+
+  // Write version marker
+  const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
+  writeFileSync(MARKER, JSON.stringify({
+    version: pkg.version,
+    bun: getBunVersion(),
+    uv: getUvVersion(),
+    installedAt: new Date().toISOString()
+  }));
+}
+
+// Main execution
+try {
+  if (!isBunInstalled()) installBun();
+  if (!isUvInstalled()) installUv();
+  if (needsInstall()) {
+    installDeps();
+    console.error('✅ Dependencies installed');
+  }
+} catch (e) {
+  console.error('❌ Installation failed:', e.message);
+  process.exit(1);
+}
@@ -7,11 +7,12 @@
 */

 const { execSync } = require('child_process');
-const { existsSync } = require('fs');
+const { existsSync, readFileSync } = require('fs');
 const path = require('path');
 const os = require('os');

 const INSTALLED_PATH = path.join(os.homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');
+const CACHE_BASE_PATH = path.join(os.homedir(), '.claude', 'plugins', 'cache', 'thedotmack', 'claude-mem');

 function getCurrentBranch() {
  try {
@@ -29,8 +30,9 @@ function getCurrentBranch() {
 }

 const branch = getCurrentBranch();
+const isForce = process.argv.includes('--force');

-if (branch && branch !== 'main') {
+if (branch && branch !== 'main' && !isForce) {
  console.log('');
  console.log('\x1b[33m%s\x1b[0m', `WARNING: Installed plugin is on beta branch: ${branch}`);
  console.log('\x1b[33m%s\x1b[0m', 'Running rsync would overwrite beta code.');
@@ -43,6 +45,18 @@ if (branch && branch !== 'main') {
  process.exit(1);
 }

+// Get version from plugin.json
+function getPluginVersion() {
+  try {
+    const pluginJsonPath = path.join(__dirname, '..', 'plugin', '.claude-plugin', 'plugin.json');
+    const pluginJson = JSON.parse(readFileSync(pluginJsonPath, 'utf-8'));
+    return pluginJson.version;
+  } catch (error) {
+    console.error('\x1b[31m%s\x1b[0m', 'Failed to read plugin version:', error.message);
+    process.exit(1);
+  }
+}
+
 // Normal rsync for main branch or fresh install
 console.log('Syncing to marketplace...');
 try {
@@ -57,7 +71,43 @@ try {
    { stdio: 'inherit' }
  );

+  // Sync to cache folder with version
+  const version = getPluginVersion();
+  const CACHE_VERSION_PATH = path.join(CACHE_BASE_PATH, version);
+
+  console.log(`Syncing to cache folder (version ${version})...`);
+  execSync(
+    `rsync -av --delete --exclude=.git plugin/ "${CACHE_VERSION_PATH}/"`,
+    { stdio: 'inherit' }
+  );
+
  console.log('\x1b[32m%s\x1b[0m', 'Sync complete!');
+
+  // Trigger worker restart after file sync
+  console.log('\n🔄 Triggering worker restart...');
+  const http = require('http');
+  const req = http.request({
+    hostname: '127.0.0.1',
+    port: 37777,
+    path: '/api/admin/restart',
+    method: 'POST',
+    timeout: 2000
+  }, (res) => {
+    if (res.statusCode === 200) {
+      console.log('\x1b[32m%s\x1b[0m', '✓ Worker restart triggered');
+    } else {
+      console.log('\x1b[33m%s\x1b[0m', `ℹ Worker restart returned status ${res.statusCode}`);
+    }
+  });
+  req.on('error', () => {
+    console.log('\x1b[33m%s\x1b[0m', 'ℹ Worker not running, will start on next hook');
+  });
+  req.on('timeout', () => {
+    req.destroy();
+    console.log('\x1b[33m%s\x1b[0m', 'ℹ Worker restart timed out');
+  });
+  req.end();
+
 } catch (error) {
  console.error('\x1b[31m%s\x1b[0m', 'Sync failed:', error.message);
  process.exit(1);
@@ -0,0 +1,235 @@
+# README Translator
+
+Translate README.md files to multiple languages using the Claude Agent SDK. Perfect for build scripts and CI/CD pipelines.
+
+## Installation
+
+```bash
+npm install readme-translator
+# or
+npm install -g readme-translator  # for CLI usage
+```
+
+## Requirements
+
+- Node.js 18+
+- **Authentication** (one of the following):
+  - Claude Code installed and authenticated (Pro/Max subscription) - **no API key needed**
+  - `ANTHROPIC_API_KEY` environment variable set (for API-based usage)
+  - AWS Bedrock (`CLAUDE_CODE_USE_BEDROCK=1` + AWS credentials)
+  - Google Vertex AI (`CLAUDE_CODE_USE_VERTEX=1` + GCP credentials)
+
+If you have Claude Code installed and logged in with your Pro/Max subscription, the SDK will automatically use that authentication.
+
+## CLI Usage
+
+```bash
+# Basic usage
+translate-readme README.md es fr de
+
+# With options
+translate-readme -v -o ./i18n --pattern docs.{lang}.md README.md es fr de ja zh
+
+# List supported languages
+translate-readme --list-languages
+```
+
+### CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <dir>` | Output directory (default: same as source) |
+| `-p, --pattern <pat>` | Output filename pattern (default: `README.{lang}.md`) |
+| `--no-preserve-code` | Translate code blocks too (not recommended) |
+| `-m, --model <model>` | Claude model to use (default: `sonnet`) |
+| `--max-budget <usd>` | Maximum budget in USD |
+| `-v, --verbose` | Show detailed progress |
+| `-h, --help` | Show help message |
+| `--list-languages` | List all supported language codes |
+
+## Programmatic Usage
+
+```typescript
+import { translateReadme } from "readme-translator";
+
+const result = await translateReadme({
+  source: "./README.md",
+  languages: ["es", "fr", "de", "ja", "zh"],
+  verbose: true,
+});
+
+console.log(`Translated ${result.successful} files`);
+console.log(`Total cost: $${result.totalCostUsd.toFixed(4)}`);
+```
+
+### API Options
+
+```typescript
+interface TranslationOptions {
+  /** Source README file path */
+  source: string;
+
+  /** Target language codes */
+  languages: string[];
+
+  /** Output directory (defaults to same directory as source) */
+  outputDir?: string;
+
+  /** Output filename pattern (use {lang} placeholder) */
+  pattern?: string; // default: "README.{lang}.md"
+
+  /** Preserve code blocks without translation */
+  preserveCode?: boolean; // default: true
+
+  /** Claude model to use */
+  model?: string; // default: "sonnet"
+
+  /** Maximum budget in USD */
+  maxBudgetUsd?: number;
+
+  /** Verbose output */
+  verbose?: boolean;
+}
+```
+
+### Return Value
+
+```typescript
+interface TranslationJobResult {
+  results: TranslationResult[];
+  totalCostUsd: number;
+  successful: number;
+  failed: number;
+}
+
+interface TranslationResult {
+  language: string;
+  outputPath: string;
+  success: boolean;
+  error?: string;
+  costUsd?: number;
+}
+```
+
+## Build Script Integration
+
+### package.json
+
+```json
+{
+  "scripts": {
+    "translate": "translate-readme README.md es fr de ja zh",
+    "translate:all": "translate-readme -v -o ./i18n README.md es fr de it pt ja ko zh ru ar",
+    "prebuild": "npm run translate"
+  }
+}
+```
+
+### GitHub Actions
+
+Note: CI/CD environments require an API key since Claude Code won't be authenticated there.
+
+```yaml
+name: Translate README
+on:
+  push:
+    branches: [main]
+    paths: [README.md]
+
+jobs:
+  translate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      
+      - run: npm install -g readme-translator
+      
+      - name: Translate README
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          translate-readme -v -o ./i18n README.md es fr de ja zh
+      
+      - name: Commit translations
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add i18n/
+          git diff --staged --quiet || git commit -m "chore: update README translations"
+          git push
+```
+
+### Programmatic Build Script
+
+```typescript
+// scripts/translate.ts
+import { translateReadme } from "readme-translator";
+
+async function main() {
+  const result = await translateReadme({
+    source: "./README.md",
+    languages: (process.env.TRANSLATE_LANGS || "es,fr,de").split(","),
+    outputDir: "./docs/i18n",
+    maxBudgetUsd: 5.0,
+    verbose: !process.env.CI,
+  });
+
+  if (result.failed > 0) {
+    console.error("Some translations failed");
+    process.exit(1);
+  }
+}
+
+main();
+```
+
+## Supported Languages
+
+| Code | Language | Code | Language |
+|------|----------|------|----------|
+| `ar` | Arabic | `ko` | Korean |
+| `bg` | Bulgarian | `lt` | Lithuanian |
+| `cs` | Czech | `lv` | Latvian |
+| `da` | Danish | `nl` | Dutch |
+| `de` | German | `no` | Norwegian |
+| `el` | Greek | `pl` | Polish |
+| `es` | Spanish | `pt` | Portuguese |
+| `et` | Estonian | `pt-br` | Brazilian Portuguese |
+| `fi` | Finnish | `ro` | Romanian |
+| `fr` | French | `ru` | Russian |
+| `he` | Hebrew | `sk` | Slovak |
+| `hi` | Hindi | `sl` | Slovenian |
+| `hu` | Hungarian | `sv` | Swedish |
+| `id` | Indonesian | `th` | Thai |
+| `it` | Italian | `tr` | Turkish |
+| `ja` | Japanese | `uk` | Ukrainian |
+| | | `vi` | Vietnamese |
+| | | `zh` | Chinese (Simplified) |
+| | | `zh-tw` | Chinese (Traditional) |
+
+## Best Practices
+
+1. **Preserve Code Blocks**: Keep `preserveCode: true` (default) to avoid breaking code examples
+
+2. **Set Budget Limits**: Use `maxBudgetUsd` to prevent runaway costs
+
+3. **Run on Releases Only**: In CI/CD, trigger translations only on main branch or releases
+
+4. **Review Translations**: Automated translations are good but not perfect - consider human review for critical docs
+
+5. **Cache Results**: Don't re-translate unchanged content - check if README changed before running
+
+## Cost Estimation
+
+Typical costs per language (varies by README length):
+- Short README (~500 words): ~$0.01-0.02
+- Medium README (~2000 words): ~$0.05-0.10
+- Long README (~5000 words): ~$0.15-0.25
+
+## License
+
+MIT
@@ -0,0 +1,233 @@
+#!/usr/bin/env npx tsx
+
+import { translateReadme, SUPPORTED_LANGUAGES } from "./index.ts";
+
+interface CliArgs {
+  source: string;
+  languages: string[];
+  outputDir?: string;
+  pattern?: string;
+  preserveCode: boolean;
+  model?: string;
+  maxBudget?: number;
+  verbose: boolean;
+  help: boolean;
+  listLanguages: boolean;
+}
+
+function printHelp(): void {
+  console.log(`
+readme-translator - Translate README.md files using Claude Agent SDK
+
+AUTHENTICATION:
+  If Claude Code is installed and authenticated (Pro/Max subscription),
+  no API key is needed. Otherwise, set ANTHROPIC_API_KEY environment variable.
+
+USAGE:
+  translate-readme [options] <source> <languages...>
+  translate-readme --help
+  translate-readme --list-languages
+
+ARGUMENTS:
+  source          Path to the source README.md file
+  languages       Target language codes (e.g., es fr de ja zh)
+
+OPTIONS:
+  -o, --output <dir>      Output directory (default: same as source)
+  -p, --pattern <pat>     Output filename pattern (default: README.{lang}.md)
+  --no-preserve-code      Translate code blocks too (not recommended)
+  -m, --model <model>     Claude model to use (default: sonnet)
+  --max-budget <usd>      Maximum budget in USD
+  -v, --verbose           Show detailed progress
+  -h, --help              Show this help message
+  --list-languages        List all supported language codes
+
+EXAMPLES:
+  # Translate to Spanish and French
+  translate-readme README.md es fr
+
+  # Translate to multiple languages with custom output
+  translate-readme -v -o ./i18n --pattern docs.{lang}.md README.md de ja ko zh
+
+  # Use in npm scripts
+  # package.json: "translate": "translate-readme README.md es fr de"
+
+SUPPORTED LANGUAGES:
+  Run with --list-languages to see all supported language codes
+`);
+}
+
+function printLanguages(): void {
+  const LANGUAGE_NAMES: Record<string, string> = {
+    ar: "Arabic",
+    bg: "Bulgarian",
+    cs: "Czech",
+    da: "Danish",
+    de: "German",
+    el: "Greek",
+    es: "Spanish",
+    et: "Estonian",
+    fi: "Finnish",
+    fr: "French",
+    he: "Hebrew",
+    hi: "Hindi",
+    hu: "Hungarian",
+    id: "Indonesian",
+    it: "Italian",
+    ja: "Japanese",
+    ko: "Korean",
+    lt: "Lithuanian",
+    lv: "Latvian",
+    nl: "Dutch",
+    no: "Norwegian",
+    pl: "Polish",
+    pt: "Portuguese",
+    "pt-br": "Brazilian Portuguese",
+    ro: "Romanian",
+    ru: "Russian",
+    sk: "Slovak",
+    sl: "Slovenian",
+    sv: "Swedish",
+    th: "Thai",
+    tr: "Turkish",
+    uk: "Ukrainian",
+    vi: "Vietnamese",
+    zh: "Chinese (Simplified)",
+    "zh-tw": "Chinese (Traditional)",
+  };
+
+  console.log("\nSupported Language Codes:\n");
+  const sorted = Object.entries(LANGUAGE_NAMES).sort((a, b) =>
+    a[1].localeCompare(b[1])
+  );
+  for (const [code, name] of sorted) {
+    console.log(`  ${code.padEnd(8)} ${name}`);
+  }
+  console.log("");
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {
+    source: "",
+    languages: [],
+    preserveCode: true,
+    verbose: false,
+    help: false,
+    listLanguages: false,
+  };
+
+  const positional: string[] = [];
+  let i = 2; // Skip node and script path
+
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    switch (arg) {
+      case "-h":
+      case "--help":
+        args.help = true;
+        break;
+      case "--list-languages":
+        args.listLanguages = true;
+        break;
+      case "-v":
+      case "--verbose":
+        args.verbose = true;
+        break;
+      case "--no-preserve-code":
+        args.preserveCode = false;
+        break;
+      case "-o":
+      case "--output":
+        args.outputDir = argv[++i];
+        break;
+      case "-p":
+      case "--pattern":
+        args.pattern = argv[++i];
+        break;
+      case "-m":
+      case "--model":
+        args.model = argv[++i];
+        break;
+      case "--max-budget":
+        args.maxBudget = parseFloat(argv[++i]);
+        break;
+      default:
+        if (arg.startsWith("-")) {
+          console.error(`Unknown option: ${arg}`);
+          process.exit(1);
+        }
+        positional.push(arg);
+    }
+    i++;
+  }
+
+  if (positional.length > 0) {
+    args.source = positional[0];
+    args.languages = positional.slice(1);
+  }
+
+  return args;
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv);
+
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (args.listLanguages) {
+    printLanguages();
+    process.exit(0);
+  }
+
+  if (!args.source) {
+    console.error("Error: No source file specified");
+    console.error("Run with --help for usage information");
+    process.exit(1);
+  }
+
+  if (args.languages.length === 0) {
+    console.error("Error: No target languages specified");
+    console.error("Run with --help for usage information");
+    process.exit(1);
+  }
+
+  // Validate language codes
+  const invalidLangs = args.languages.filter(
+    (lang) => !SUPPORTED_LANGUAGES.includes(lang.toLowerCase())
+  );
+  if (invalidLangs.length > 0) {
+    console.error(`Error: Unknown language codes: ${invalidLangs.join(", ")}`);
+    console.error("Run with --list-languages to see supported codes");
+    process.exit(1);
+  }
+
+  try {
+    const result = await translateReadme({
+      source: args.source,
+      languages: args.languages,
+      outputDir: args.outputDir,
+      pattern: args.pattern,
+      preserveCode: args.preserveCode,
+      model: args.model,
+      maxBudgetUsd: args.maxBudget,
+      verbose: args.verbose,
+    });
+
+    // Exit with error code if any translations failed
+    if (result.failed > 0) {
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(
+      "Translation failed:",
+      error instanceof Error ? error.message : error
+    );
+    process.exit(1);
+  }
+}
+
+main();
@@ -0,0 +1,147 @@
+/**
+ * Example: Using readme-translator in build scripts
+ *
+ * These examples show how to integrate the translator into your build pipeline.
+ */
+
+import { translateReadme, TranslationJobResult, SUPPORTED_LANGUAGES } from "./index.js";
+
+// Example 1: Simple usage - translate to a few common languages
+async function translateToCommonLanguages(): Promise<void> {
+  const result = await translateReadme({
+    source: "./README.md",
+    languages: ["es", "fr", "de", "ja", "zh"],
+    verbose: true,
+  });
+
+  console.log(`Translated to ${result.successful} languages`);
+}
+
+// Example 2: Full i18n setup with custom output directory
+async function fullI18nSetup(): Promise<void> {
+  const result = await translateReadme({
+    source: "./README.md",
+    languages: ["es", "fr", "de", "it", "pt", "ja", "ko", "zh", "ru", "ar"],
+    outputDir: "./docs/i18n",
+    pattern: "README.{lang}.md",
+    preserveCode: true,
+    model: "sonnet",
+    maxBudgetUsd: 5.0, // Cap spending at $5
+    verbose: true,
+  });
+
+  // Handle results programmatically
+  for (const r of result.results) {
+    if (!r.success) {
+      console.error(`Failed to translate to ${r.language}: ${r.error}`);
+    }
+  }
+}
+
+// Example 3: Build script integration with error handling
+// Note: If Claude Code is authenticated, no API key needed locally.
+// CI/CD environments will need ANTHROPIC_API_KEY set.
+async function buildScriptIntegration(): Promise<number> {
+  try {
+    const result = await translateReadme({
+      source: process.env.README_PATH || "./README.md",
+      languages: (process.env.TRANSLATE_LANGS || "es,fr,de").split(","),
+      outputDir: process.env.I18N_OUTPUT || "./i18n",
+      verbose: process.env.CI !== "true", // Quiet in CI
+    });
+
+    // Return exit code for build scripts
+    return result.failed > 0 ? 1 : 0;
+  } catch (error) {
+    console.error("Translation failed:", error);
+    return 1;
+  }
+}
+
+// Example 4: Batch translation of multiple READMEs
+async function batchTranslation(): Promise<void> {
+  const readmes = [
+    "./README.md",
+    "./packages/core/README.md",
+    "./packages/cli/README.md",
+  ];
+
+  const languages = ["es", "fr", "de"];
+
+  for (const readme of readmes) {
+    console.log(`\nProcessing: ${readme}`);
+    await translateReadme({
+      source: readme,
+      languages,
+      verbose: true,
+    });
+  }
+}
+
+// Example 5: Custom output pattern for docs sites
+async function docsiteSetup(): Promise<void> {
+  // For docusaurus/vitepress style: docs/README.es.md
+  await translateReadme({
+    source: "./README.md",
+    languages: ["es", "fr", "de", "ja", "zh"],
+    outputDir: "./docs",
+    pattern: "README.{lang}.md",
+    verbose: true,
+  });
+}
+
+// Example 6: Conditional translation in CI/CD
+async function cicdTranslation(): Promise<void> {
+  // Only translate on main branch releases
+  const isRelease = process.env.GITHUB_REF === "refs/heads/main";
+  const isManualTrigger = process.env.GITHUB_EVENT_NAME === "workflow_dispatch";
+
+  if (!isRelease && !isManualTrigger) {
+    console.log("Skipping translation - not a release build");
+    return;
+  }
+
+  const result = await translateReadme({
+    source: "./README.md",
+    languages: ["es", "fr", "de", "ja", "ko", "zh", "pt-br"],
+    outputDir: "./dist/i18n",
+    maxBudgetUsd: 10.0,
+    verbose: true,
+  });
+
+  // Write summary for GitHub Actions
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    const summary = `
+## Translation Summary
+- ✅ Successful: ${result.successful}
+- ❌ Failed: ${result.failed}
+- 💰 Cost: $${result.totalCostUsd.toFixed(4)}
+`;
+    // In real usage, write to GITHUB_STEP_SUMMARY
+    console.log(summary);
+  }
+}
+
+// Run an example
+const example = process.argv[2];
+
+switch (example) {
+  case "simple":
+    translateToCommonLanguages();
+    break;
+  case "full":
+    fullI18nSetup();
+    break;
+  case "batch":
+    batchTranslation();
+    break;
+  case "docs":
+    docsiteSetup();
+    break;
+  case "ci":
+    cicdTranslation();
+    break;
+  default:
+    console.log("Available examples: simple, full, batch, docs, ci");
+    console.log("\nSupported languages:", SUPPORTED_LANGUAGES.join(", "));
+}
@@ -0,0 +1,292 @@
+import { query, type SDKMessage, type SDKResultMessage } from "@anthropic-ai/claude-agent-sdk";
+import * as fs from "fs/promises";
+import * as path from "path";
+
+export interface TranslationOptions {
+  /** Source README file path */
+  source: string;
+  /** Target languages (e.g., ['es', 'fr', 'de', 'ja', 'zh']) */
+  languages: string[];
+  /** Output directory (defaults to same directory as source) */
+  outputDir?: string;
+  /** Output filename pattern (use {lang} placeholder, defaults to 'README.{lang}.md') */
+  pattern?: string;
+  /** Preserve code blocks without translation */
+  preserveCode?: boolean;
+  /** Model to use (defaults to 'sonnet') */
+  model?: string;
+  /** Maximum budget in USD for the entire translation job */
+  maxBudgetUsd?: number;
+  /** Verbose output */
+  verbose?: boolean;
+}
+
+export interface TranslationResult {
+  language: string;
+  outputPath: string;
+  success: boolean;
+  error?: string;
+  costUsd?: number;
+}
+
+export interface TranslationJobResult {
+  results: TranslationResult[];
+  totalCostUsd: number;
+  successful: number;
+  failed: number;
+}
+
+const LANGUAGE_NAMES: Record<string, string> = {
+  ar: "Arabic",
+  bg: "Bulgarian",
+  cs: "Czech",
+  da: "Danish",
+  de: "German",
+  el: "Greek",
+  es: "Spanish",
+  et: "Estonian",
+  fi: "Finnish",
+  fr: "French",
+  he: "Hebrew",
+  hi: "Hindi",
+  hu: "Hungarian",
+  id: "Indonesian",
+  it: "Italian",
+  ja: "Japanese",
+  ko: "Korean",
+  lt: "Lithuanian",
+  lv: "Latvian",
+  nl: "Dutch",
+  no: "Norwegian",
+  pl: "Polish",
+  pt: "Portuguese",
+  "pt-br": "Brazilian Portuguese",
+  ro: "Romanian",
+  ru: "Russian",
+  sk: "Slovak",
+  sl: "Slovenian",
+  sv: "Swedish",
+  th: "Thai",
+  tr: "Turkish",
+  uk: "Ukrainian",
+  vi: "Vietnamese",
+  zh: "Chinese (Simplified)",
+  "zh-tw": "Chinese (Traditional)",
+};
+
+function getLanguageName(code: string): string {
+  return LANGUAGE_NAMES[code.toLowerCase()] || code;
+}
+
+async function translateToLanguage(
+  content: string,
+  targetLang: string,
+  options: Pick<TranslationOptions, "preserveCode" | "model" | "verbose">
+): Promise<{ translation: string; costUsd: number }> {
+  const languageName = getLanguageName(targetLang);
+
+  const preserveCodeInstructions = options.preserveCode
+    ? `
+IMPORTANT: Preserve all code blocks exactly as they are. Do NOT translate:
+- Code inside \`\`\` blocks
+- Inline code inside \` backticks
+- Command examples
+- File paths
+- Variable names, function names, and technical identifiers
+- URLs and links
+`
+    : "";
+
+  const prompt = `Translate the following README.md content from English to ${languageName} (${targetLang}).
+
+${preserveCodeInstructions}
+Guidelines:
+- Maintain all Markdown formatting (headers, lists, links, etc.)
+- Keep the same document structure
+- Translate headings, descriptions, and explanatory text naturally
+- Preserve technical accuracy
+- Use appropriate technical terminology for ${languageName}
+- Keep proper nouns (product names, company names) unchanged unless they have official translations
+
+Here is the README content to translate:
+
+---
+${content}
+---
+
+Output ONLY the translated README content, nothing else. Do not include any preamble or explanation.`;
+
+  let translation = "";
+  let costUsd = 0;
+  let charCount = 0;
+  const startTime = Date.now();
+
+  const stream = query({
+    prompt,
+    options: {
+      model: options.model || "sonnet",
+      systemPrompt: `You are an expert technical translator specializing in software documentation.
+You translate README files while preserving Markdown formatting and technical accuracy.
+Always output only the translated content without any surrounding explanation.`,
+      permissionMode: "bypassPermissions",
+      allowDangerouslySkipPermissions: true,
+      includePartialMessages: true, // Enable streaming events
+    },
+  });
+
+  // Progress spinner frames
+  const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  let spinnerIdx = 0;
+
+  for await (const message of stream) {
+    // Handle streaming text deltas
+    if (message.type === "stream_event") {
+      const event = message.event as { type: string; delta?: { type: string; text?: string } };
+      if (event.type === "content_block_delta" && event.delta?.type === "text_delta" && event.delta.text) {
+        translation += event.delta.text;
+        charCount += event.delta.text.length;
+
+        if (options.verbose) {
+          const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+          const spinner = spinnerFrames[spinnerIdx++ % spinnerFrames.length];
+          process.stdout.write(`\r   ${spinner} Translating... ${charCount} chars (${elapsed}s)`);
+        }
+      }
+    }
+
+    // Handle full assistant messages (fallback)
+    if (message.type === "assistant") {
+      for (const block of message.message.content) {
+        if (block.type === "text" && !translation) {
+          translation = block.text;
+          charCount = translation.length;
+        }
+      }
+    }
+
+    if (message.type === "result") {
+      const result = message as SDKResultMessage;
+      if (result.subtype === "success") {
+        costUsd = result.total_cost_usd;
+        // Use the result text if we didn't get it from streaming
+        if (!translation && result.result) {
+          translation = result.result;
+          charCount = translation.length;
+        }
+      }
+    }
+  }
+
+  // Clear the progress line
+  if (options.verbose) {
+    process.stdout.write("\r" + " ".repeat(60) + "\r");
+  }
+
+  return { translation: translation.trim(), costUsd };
+}
+
+export async function translateReadme(
+  options: TranslationOptions
+): Promise<TranslationJobResult> {
+  const {
+    source,
+    languages,
+    outputDir,
+    pattern = "README.{lang}.md",
+    preserveCode = true,
+    model,
+    maxBudgetUsd,
+    verbose = false,
+  } = options;
+
+  // Read source file
+  const sourcePath = path.resolve(source);
+  const content = await fs.readFile(sourcePath, "utf-8");
+
+  // Determine output directory
+  const outDir = outputDir ? path.resolve(outputDir) : path.dirname(sourcePath);
+  await fs.mkdir(outDir, { recursive: true });
+
+  const results: TranslationResult[] = [];
+  let totalCostUsd = 0;
+
+  if (verbose) {
+    console.log(`📖 Source: ${sourcePath}`);
+    console.log(`📂 Output: ${outDir}`);
+    console.log(`🌍 Languages: ${languages.join(", ")}`);
+    console.log("");
+  }
+
+  for (const lang of languages) {
+    // Check budget
+    if (maxBudgetUsd && totalCostUsd >= maxBudgetUsd) {
+      results.push({
+        language: lang,
+        outputPath: "",
+        success: false,
+        error: "Budget exceeded",
+      });
+      continue;
+    }
+
+    const outputFilename = pattern.replace("{lang}", lang);
+    const outputPath = path.join(outDir, outputFilename);
+
+    if (verbose) {
+      console.log(`🔄 Translating to ${getLanguageName(lang)} (${lang})...`);
+    }
+
+    try {
+      const { translation, costUsd } = await translateToLanguage(content, lang, {
+        preserveCode,
+        model,
+        verbose,
+      });
+
+      await fs.writeFile(outputPath, translation, "utf-8");
+      totalCostUsd += costUsd;
+
+      results.push({
+        language: lang,
+        outputPath,
+        success: true,
+        costUsd,
+      });
+
+      if (verbose) {
+        console.log(`   ✅ Saved to ${outputFilename} ($${costUsd.toFixed(4)})`);
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      results.push({
+        language: lang,
+        outputPath,
+        success: false,
+        error: errorMessage,
+      });
+
+      if (verbose) {
+        console.log(`   ❌ Failed: ${errorMessage}`);
+      }
+    }
+  }
+
+  const successful = results.filter((r) => r.success).length;
+  const failed = results.filter((r) => !r.success).length;
+
+  if (verbose) {
+    console.log("");
+    console.log(`📊 Summary: ${successful} succeeded, ${failed} failed`);
+    console.log(`💰 Total cost: $${totalCostUsd.toFixed(4)}`);
+  }
+
+  return {
+    results,
+    totalCostUsd,
+    successful,
+    failed,
+  };
+}
+
+// Export language codes for convenience
+export const SUPPORTED_LANGUAGES = Object.keys(LANGUAGE_NAMES);
@@ -0,0 +1,63 @@
+import { ProcessManager } from '../services/process/ProcessManager.js';
+import { getWorkerPort } from '../shared/worker-utils.js';
+
+const command = process.argv[2];
+const port = getWorkerPort();
+
+async function main() {
+  switch (command) {
+    case 'start': {
+      const result = await ProcessManager.start(port);
+      if (result.success) {
+        console.log(`Worker started (PID: ${result.pid})`);
+        const date = new Date().toISOString().slice(0, 10);
+        console.log(`Logs: ~/.claude-mem/logs/worker-${date}.log`);
+        process.exit(0);
+      } else {
+        console.error(`Failed to start: ${result.error}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'stop': {
+      await ProcessManager.stop();
+      console.log('Worker stopped');
+      process.exit(0);
+    }
+
+    case 'restart': {
+      const result = await ProcessManager.restart(port);
+      if (result.success) {
+        console.log(`Worker restarted (PID: ${result.pid})`);
+        process.exit(0);
+      } else {
+        console.error(`Failed to restart: ${result.error}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'status': {
+      const status = await ProcessManager.status();
+      if (status.running) {
+        console.log('Worker is running');
+        console.log(`  PID: ${status.pid}`);
+        console.log(`  Port: ${status.port}`);
+        console.log(`  Uptime: ${status.uptime}`);
+      } else {
+        console.log('Worker is not running');
+      }
+      process.exit(0);
+    }
+
+    default:
+      console.log('Usage: worker-cli.js <start|stop|restart|status>');
+      process.exit(1);
+  }
+}
+
+main().catch(error => {
+  console.error(error);
+  process.exit(1);
+});
@@ -1,89 +1,67 @@
 /**
 * Cleanup Hook - SessionEnd
- * Consolidated entry point + logic
+ *
+ * Pure HTTP client - sends data to worker, worker handles all database operations.
+ * This allows the hook to run under any runtime (Node.js or Bun) since it has no
+ * native module dependencies.
 */

 import { stdin } from 'process';
-import { SessionStore } from '../services/sqlite/SessionStore.js';
-import { getWorkerPort } from '../shared/worker-utils.js';
+import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
+import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
+import { HOOK_TIMEOUTS } from '../shared/hook-constants.js';

 export interface SessionEndInput {
  session_id: string;
-  cwd: string;
-  transcript_path?: string;
-  hook_event_name: string;
  reason: 'exit' | 'clear' | 'logout' | 'prompt_input_exit' | 'other';
 }

 /**
- * Cleanup Hook Main Logic
+ * Cleanup Hook Main Logic - Fire-and-forget HTTP client
 */
 async function cleanupHook(input?: SessionEndInput): Promise<void> {
-  // Log hook entry point
-  console.error('[claude-mem cleanup] Hook fired', {
-    input: input ? {
-      session_id: input.session_id,
-      cwd: input.cwd,
-      reason: input.reason
-    } : null
+  // Ensure worker is running before any other logic
+  await ensureWorkerRunning();
+
+  happy_path_error__with_fallback('[cleanup-hook] Hook fired', {
+    session_id: input?.session_id,
+    reason: input?.reason
  });

-  // Handle standalone execution (no input provided)
  if (!input) {
-    console.log('No input provided - this script is designed to run as a Claude Code SessionEnd hook');
-    console.log('\nExpected input format:');
-    console.log(JSON.stringify({
-      session_id: "string",
-      cwd: "string",
-      transcript_path: "string",
-      hook_event_name: "SessionEnd",
-      reason: "exit"
-    }, null, 2));
-    process.exit(0);
+    throw new Error('cleanup-hook requires input from Claude Code');
  }

  const { session_id, reason } = input;
-  console.error('[claude-mem cleanup] Searching for active SDK session', { session_id, reason });

-  // Find active SDK session
-  const db = new SessionStore();
-  const session = db.findActiveSDKSession(session_id);
+  const port = getWorkerPort();

-  if (!session) {
-    // No active session - nothing to clean up
-    console.error('[claude-mem cleanup] No active SDK session found', { session_id });
-    db.close();
-    console.log('{"continue": true, "suppressOutput": true}');
-    process.exit(0);
-  }
-
-  console.error('[claude-mem cleanup] Active SDK session found', {
-    session_id: session.id,
-    sdk_session_id: session.sdk_session_id,
-    project: session.project,
-    worker_port: session.worker_port
-  });
-
-  // Mark session as completed in DB
-  db.markSessionCompleted(session.id);
-  console.error('[claude-mem cleanup] Session marked as completed in database');
-
-  db.close();
-
-  // Tell worker to stop spinner
  try {
-    const workerPort = session.worker_port || getWorkerPort();
-    await fetch(`http://127.0.0.1:${workerPort}/sessions/${session.id}/complete`, {
+    // Send to worker - worker handles finding session, marking complete, and stopping spinner
+    const response = await fetch(`http://127.0.0.1:${port}/api/sessions/complete`, {
      method: 'POST',
-      signal: AbortSignal.timeout(1000)
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        claudeSessionId: session_id,
+        reason
+      }),
+      signal: AbortSignal.timeout(HOOK_TIMEOUTS.DEFAULT)
+    });
+
+    if (response.ok) {
+      const result = await response.json();
+      happy_path_error__with_fallback('[cleanup-hook] Session cleanup completed', result);
+    } else {
+      // Non-fatal - session might not exist
+      happy_path_error__with_fallback('[cleanup-hook] Session not found or already cleaned up');
+    }
+  } catch (error: any) {
+    // Worker might not be running - that's okay
+    happy_path_error__with_fallback('[cleanup-hook] Worker not reachable (non-critical)', {
+      error: error.message
    });
-    console.error('[claude-mem cleanup] Worker notified to stop processing indicator');
-  } catch (err) {
-    // Non-critical - worker might be down
-    console.error('[claude-mem cleanup] Failed to notify worker (non-critical):', err);
  }

-  console.error('[claude-mem cleanup] Cleanup completed successfully');
  console.log('{"continue": true, "suppressOutput": true}');
  process.exit(0);
 }
@@ -1,837 +1,73 @@
 /**
 * Context Hook - SessionStart
- * Consolidated entry point + logic
+ *
+ * Pure HTTP client - calls worker to generate context.
+ * This allows the hook to run under any runtime (Node.js or Bun) since it has no
+ * native module dependencies.
 */

-import path from 'path';
-import { homedir } from 'os';
-import { existsSync, readFileSync, unlinkSync } from 'fs';
-import { stdin } from 'process';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
-import { SessionStore } from '../services/sqlite/SessionStore.js';
-import {
-  OBSERVATION_TYPES,
-  OBSERVATION_CONCEPTS,
-  TYPE_ICON_MAP,
-  TYPE_WORK_EMOJI_MAP,
-  DEFAULT_OBSERVATION_TYPES_STRING,
-  DEFAULT_OBSERVATION_CONCEPTS_STRING
-} from '../constants/observation-metadata.js';
-import { logger } from '../utils/logger.js';
-
-// Get __dirname equivalent in ESM
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Version marker path (same as smart-install.js)
-// From src/hooks/ we need to go up to plugin root: ../../
-const VERSION_MARKER_PATH = path.join(__dirname, '../../.install-version');
-
-interface ContextConfig {
-  // Display counts
-  totalObservationCount: number;
-  fullObservationCount: number;
-  sessionCount: number;
-
-  // Token display toggles
-  showReadTokens: boolean;
-  showWorkTokens: boolean;
-  showSavingsAmount: boolean;
-  showSavingsPercent: boolean;
-
-  // Filters
-  observationTypes: Set<string>;
-  observationConcepts: Set<string>;
-
-  // Display options
-  fullObservationField: 'narrative' | 'facts';
-  showLastSummary: boolean;
-  showLastMessage: boolean;
-}
-
-/**
- * Load all context configuration settings
- * Priority: ~/.claude-mem/settings.json > env var > defaults
- */
-function loadContextConfig(): ContextConfig {
-  const defaults = {
-    totalObservationCount: parseInt(process.env.CLAUDE_MEM_CONTEXT_OBSERVATIONS || '50', 10),
-    fullObservationCount: 5,
-    sessionCount: 10,
-    showReadTokens: true,
-    showWorkTokens: true,
-    showSavingsAmount: true,
-    showSavingsPercent: true,
-    observationTypes: new Set(OBSERVATION_TYPES),
-    observationConcepts: new Set(OBSERVATION_CONCEPTS),
-    fullObservationField: 'narrative' as const,
-    showLastSummary: true,
-    showLastMessage: false,
-  };
-
-  try {
-    const settingsPath = path.join(homedir(), '.claude-mem', 'settings.json');
-    if (!existsSync(settingsPath)) return defaults;
-
-    const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-    const env = settings.env || {};
-
-    return {
-      totalObservationCount: parseInt(env.CLAUDE_MEM_CONTEXT_OBSERVATIONS || '50', 10),
-      fullObservationCount: parseInt(env.CLAUDE_MEM_CONTEXT_FULL_COUNT || '5', 10),
-      sessionCount: parseInt(env.CLAUDE_MEM_CONTEXT_SESSION_COUNT || '10', 10),
-      showReadTokens: env.CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS !== 'false',
-      showWorkTokens: env.CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS !== 'false',
-      showSavingsAmount: env.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT !== 'false',
-      showSavingsPercent: env.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_PERCENT !== 'false',
-      observationTypes: new Set(
-        (env.CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES || DEFAULT_OBSERVATION_TYPES_STRING)
-          .split(',').map((t: string) => t.trim()).filter(Boolean)
-      ),
-      observationConcepts: new Set(
-        (env.CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS || DEFAULT_OBSERVATION_CONCEPTS_STRING)
-          .split(',').map((c: string) => c.trim()).filter(Boolean)
-      ),
-      fullObservationField: (env.CLAUDE_MEM_CONTEXT_FULL_FIELD || 'narrative') as 'narrative' | 'facts',
-      showLastSummary: env.CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY !== 'false',
-      showLastMessage: env.CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE === 'true',
-    };
-  } catch (error) {
-    logger.warn('HOOK', 'Failed to load context settings, using defaults', {}, error as Error);
-    return defaults;
-  }
-}
-
-// Configuration constants
-const CHARS_PER_TOKEN_ESTIMATE = 4; // Rough estimate for token counting
-const SUMMARY_LOOKAHEAD = 1; // Fetch one extra summary for offset calculation
+import path from "path";
+import { stdin } from "process";
+import { ensureWorkerRunning, getWorkerPort } from "../shared/worker-utils.js";
+import { HOOK_TIMEOUTS } from "../shared/hook-constants.js";
+import { handleWorkerError } from "../shared/hook-error-handler.js";
+import { getWorkerRestartInstructions } from "../utils/error-messages.js";

 export interface SessionStartInput {
-  session_id?: string;
-  transcript_path?: string;
-  cwd?: string;
+  session_id: string;
+  transcript_path: string;
+  cwd: string;
  hook_event_name?: string;
-  source?: "startup" | "resume" | "clear" | "compact";
-  [key: string]: any;
 }

-// ANSI color codes for terminal output
-const colors = {
-  reset: '\x1b[0m',
-  bright: '\x1b[1m',
-  dim: '\x1b[2m',
-  cyan: '\x1b[36m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  magenta: '\x1b[35m',
-  gray: '\x1b[90m',
-  red: '\x1b[31m',
-};
+async function contextHook(input?: SessionStartInput): Promise<string> {
+  // Ensure worker is running before any other logic
+  await ensureWorkerRunning();

-interface Observation {
-  id: number;
-  sdk_session_id: string;
-  type: string;
-  title: string | null;
-  subtitle: string | null;
-  narrative: string | null;
-  facts: string | null;
-  concepts: string | null;
-  files_read: string | null;
-  files_modified: string | null;
-  discovery_tokens: number | null;
-  created_at: string;
-  created_at_epoch: number;
-}
-
-interface SessionSummary {
-  id: number;
-  sdk_session_id: string;
-  request: string | null;
-  investigated: string | null;
-  learned: string | null;
-  completed: string | null;
-  next_steps: string | null;
-  created_at: string;
-  created_at_epoch: number;
-}
-
-// Helper: Parse JSON array safely
-function parseJsonArray(json: string | null): string[] {
-  if (!json) return [];
-  try {
-    const parsed = JSON.parse(json);
-    return Array.isArray(parsed) ? parsed : [];
-  } catch (err) {
-    return [];
-  }
-}
-
-// Helper: Format date with time
-function formatDateTime(dateStr: string): string {
-  const date = new Date(dateStr);
-  return date.toLocaleString('en-US', {
-    month: 'short',
-    day: 'numeric',
-    hour: 'numeric',
-    minute: '2-digit',
-    hour12: true
-  });
-}
-
-// Helper: Format just time (no date)
-function formatTime(dateStr: string): string {
-  const date = new Date(dateStr);
-  return date.toLocaleString('en-US', {
-    hour: 'numeric',
-    minute: '2-digit',
-    hour12: true
-  });
-}
-
-// Helper: Format just date
-function formatDate(dateStr: string): string {
-  const date = new Date(dateStr);
-  return date.toLocaleString('en-US', {
-    month: 'short',
-    day: 'numeric',
-    year: 'numeric'
-  });
-}
-
-// Helper: Convert absolute paths to relative paths
-function toRelativePath(filePath: string, cwd: string): string {
-  if (path.isAbsolute(filePath)) {
-    return path.relative(cwd, filePath);
-  }
-  return filePath;
-}
-
-// Helper: Render a summary field (investigated, learned, etc.)
-function renderSummaryField(label: string, value: string | null, color: string, useColors: boolean): string[] {
-  if (!value) return [];
-
-  if (useColors) {
-    return [`${color}${label}:${colors.reset} ${value}`, ''];
-  }
-  return [`**${label}**: ${value}`, ''];
-}
-
-// Helper: Convert cwd path to dashed format for transcript directory name
-function cwdToDashed(cwd: string): string {
-  // Convert all slashes to dashes (including leading slash)
-  return cwd.replace(/\//g, '-');
-}
-
-// Helper: Extract last assistant message from transcript file
-function extractPriorMessages(transcriptPath: string): { userMessage: string; assistantMessage: string } {
-  try {
-    if (!existsSync(transcriptPath)) {
-      return { userMessage: '', assistantMessage: '' };
-    }
-
-    const content = readFileSync(transcriptPath, 'utf-8').trim();
-    if (!content) {
-      return { userMessage: '', assistantMessage: '' };
-    }
-
-    const lines = content.split('\n').filter(line => line.trim());
-
-    // Find the last assistant message by filtering for assistant type and taking the last one
-    let lastAssistantMessage = '';
-
-    // Iterate backwards to find the most recent assistant message with text content
-    for (let i = lines.length - 1; i >= 0; i--) {
-      try {
-        const line = lines[i];
-
-        // Quick check if this line is an assistant message
-        if (!line.includes('"type":"assistant"')) {
-          continue;
-        }
-
-        const entry = JSON.parse(line);
-
-        if (entry.type === 'assistant' && entry.message?.content && Array.isArray(entry.message.content)) {
-          let text = '';
-          for (const block of entry.message.content) {
-            if (block.type === 'text') {
-              text += block.text;
-            }
-          }
-          // Remove system-reminder tags
-          text = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim();
-          if (text) {
-            lastAssistantMessage = text;
-            break; // Found it, stop searching
-          }
-        }
-      } catch (parseError) {
-        // Skip malformed lines
-        continue;
-      }
-    }
-
-    return { userMessage: '', assistantMessage: lastAssistantMessage };
-  } catch (error) {
-    logger.failure('HOOK', `Failed to extract prior messages from transcript`, { transcriptPath }, error as Error);
-    return { userMessage: '', assistantMessage: '' };
-  }
-}
-
-/**
- * Context Hook Main Logic
- */
-async function contextHook(input?: SessionStartInput, useColors: boolean = false): Promise<string> {
-  const config = loadContextConfig();
  const cwd = input?.cwd ?? process.cwd();
-  const project = cwd ? path.basename(cwd) : 'unknown-project';
+  const project = cwd ? path.basename(cwd) : "unknown-project";
+  const port = getWorkerPort();
+
+  const url = `http://127.0.0.1:${port}/api/context/inject?project=${encodeURIComponent(project)}`;

-  let db: SessionStore | null = null;
  try {
-    db = new SessionStore();
+    const response = await fetch(url, { signal: AbortSignal.timeout(HOOK_TIMEOUTS.DEFAULT) });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
+    }
+
+    const result = await response.text();
+    return result.trim();
  } catch (error: any) {
-    if (error.code === 'ERR_DLOPEN_FAILED') {
-      // Native module ABI mismatch - delete version marker to trigger reinstall
-      try {
-        unlinkSync(VERSION_MARKER_PATH);
-      } catch (unlinkError) {
-        // Marker might not exist, that's okay
-      }
-
-      // Log once (not error spam) and exit cleanly
-      console.error('⚠️  Native module rebuild needed - restart Claude Code to auto-fix');
-      console.error('   (This happens after Node.js version upgrades)');
-      process.exit(0); // Exit cleanly to avoid error spam
-    }
-
-    // Other errors should still throw
-    throw error;
+    handleWorkerError(error);
  }
-
-  // Build SQL WHERE clause for observation types
-  const typeArray = Array.from(config.observationTypes);
-  const typePlaceholders = typeArray.map(() => '?').join(',');
-
-  // Build SQL WHERE clause for concepts
-  const conceptArray = Array.from(config.observationConcepts);
-  const conceptPlaceholders = conceptArray.map(() => '?').join(',');
-
-  // Get recent observations filtered by type and concepts at SQL level
-  // This ensures we show observations even when summaries haven't been generated
-  // Configurable via settings (default: 50)
-  const observations = db.db.prepare(`
-    SELECT
-      id, sdk_session_id, type, title, subtitle, narrative,
-      facts, concepts, files_read, files_modified, discovery_tokens,
-      created_at, created_at_epoch
-    FROM observations
-    WHERE project = ?
-      AND type IN (${typePlaceholders})
-      AND EXISTS (
-        SELECT 1 FROM json_each(concepts)
-        WHERE value IN (${conceptPlaceholders})
-      )
-    ORDER BY created_at_epoch DESC
-    LIMIT ?
-  `).all(project, ...typeArray, ...conceptArray, config.totalObservationCount) as Observation[];
-
-  // Get recent summaries (optional - may not exist for recent sessions)
-  // Fetch one extra for offset calculation
-  const recentSummaries = db.db.prepare(`
-    SELECT id, sdk_session_id, request, investigated, learned, completed, next_steps, created_at, created_at_epoch
-    FROM session_summaries
-    WHERE project = ?
-    ORDER BY created_at_epoch DESC
-    LIMIT ?
-  `).all(project, config.sessionCount + SUMMARY_LOOKAHEAD) as SessionSummary[];
-
-  // Retrieve prior session messages if enabled
-  let priorUserMessage = '';
-  let priorAssistantMessage = '';
-  // let debugInfo: string[] = [];
-
-  if (config.showLastMessage && observations.length > 0) {
-    try {
-      const currentSessionId = input?.session_id;
-
-      // Find the first observation from a different session (the prior session)
-      const priorSessionObs = observations.find(obs => obs.sdk_session_id !== currentSessionId);
-
-      if (priorSessionObs) {
-        const priorSessionId = priorSessionObs.sdk_session_id;
-
-        // Construct transcript path: ~/.claude/projects/{dashed-cwd}/{session_id}.jsonl
-        const dashedCwd = cwdToDashed(cwd);
-        const transcriptPath = path.join(homedir(), '.claude', 'projects', dashedCwd, `${priorSessionId}.jsonl`);
-
-        // debugInfo.push(`📋 Prior Message Retrieval:`);
-        // debugInfo.push(`  Session ID: ${priorSessionId}`);
-        // debugInfo.push(`  Transcript: ${transcriptPath}`);
-        // debugInfo.push(`  Exists: ${existsSync(transcriptPath)}`);
-
-        // Extract messages from transcript
-        const messages = extractPriorMessages(transcriptPath);
-        priorUserMessage = messages.userMessage;
-        priorAssistantMessage = messages.assistantMessage;
-
-        // if (!priorUserMessage && !priorAssistantMessage) {
-        //   debugInfo.push(`  ⚠️  No messages extracted from transcript`);
-        // } else {
-        //   debugInfo.push(`  ✅ Found user message: ${!!priorUserMessage}`);
-        //   debugInfo.push(`  ✅ Found assistant message: ${!!priorAssistantMessage}`);
-        // }
-      } // else {
-      //   debugInfo.push(`📋 Prior Message Retrieval: No prior session found (all observations from current session)`);
-      // }
-    } catch (error) {
-      // debugInfo.push(`📋 Prior Message Retrieval Error: ${(error as Error).message}`);
-    }
-  }
-
-  // If we have neither observations nor summaries, show empty state
-  if (observations.length === 0 && recentSummaries.length === 0) {
-    db?.close();
-    if (useColors) {
-      return `\n${colors.bright}${colors.cyan}📝 [${project}] recent context${colors.reset}\n${colors.gray}${'─'.repeat(60)}${colors.reset}\n\n${colors.dim}No previous sessions found for this project yet.${colors.reset}\n`;
-    }
-    return `# [${project}] recent context\n\nNo previous sessions found for this project yet.`;
-  }
-
-  const displaySummaries = recentSummaries.slice(0, config.sessionCount);
-
-  // All filtered observations are shown in timeline
-  const timelineObs = observations;
-
-  // Build output
-  const output: string[] = [];
-
-  // Header
-  if (useColors) {
-    output.push('');
-    output.push(`${colors.bright}${colors.cyan}📝 [${project}] recent context${colors.reset}`);
-    output.push(`${colors.gray}${'─'.repeat(60)}${colors.reset}`);
-    output.push('');
-  } else {
-    output.push(`# [${project}] recent context`);
-    output.push('');
-  }
-
-  // Chronological Timeline
-  if (timelineObs.length > 0) {
-    // Legend/Key
-    if (useColors) {
-      output.push(`${colors.dim}Legend: 🎯 session-request | 🔴 bugfix | 🟣 feature | 🔄 refactor | ✅ change | 🔵 discovery | ⚖️  decision${colors.reset}`);
-    } else {
-      output.push(`**Legend:** 🎯 session-request | 🔴 bugfix | 🟣 feature | 🔄 refactor | ✅ change | 🔵 discovery | ⚖️  decision`);
-    }
-    output.push('');
-
-    // Column Key
-    if (useColors) {
-      output.push(`${colors.bright}💡 Column Key${colors.reset}`);
-      output.push(`${colors.dim}  Read: Tokens to read this observation (cost to learn it now)${colors.reset}`);
-      output.push(`${colors.dim}  Work: Tokens spent on work that produced this record (🔍 research, 🛠️ building, ⚖️  deciding)${colors.reset}`);
-    } else {
-      output.push(`💡 **Column Key**:`);
-      output.push(`- **Read**: Tokens to read this observation (cost to learn it now)`);
-      output.push(`- **Work**: Tokens spent on work that produced this record (🔍 research, 🛠️ building, ⚖️  deciding)`);
-    }
-    output.push('');
-
-    // Context Index Usage Instructions
-    if (useColors) {
-      output.push(`${colors.dim}💡 Context Index: This semantic index (titles, types, files, tokens) is usually sufficient to understand past work.${colors.reset}`);
-      output.push('');
-      output.push(`${colors.dim}When you need implementation details, rationale, or debugging context:${colors.reset}`);
-      output.push(`${colors.dim}  - Use the mem-search skill to fetch full observations on-demand${colors.reset}`);
-      output.push(`${colors.dim}  - Critical types (🔴 bugfix, ⚖️ decision) often need detailed fetching${colors.reset}`);
-      output.push(`${colors.dim}  - Trust this index over re-reading code for past decisions and learnings${colors.reset}`);
-    } else {
-      output.push(`💡 **Context Index:** This semantic index (titles, types, files, tokens) is usually sufficient to understand past work.`);
-      output.push('');
-      output.push(`When you need implementation details, rationale, or debugging context:`);
-      output.push(`- Use the mem-search skill to fetch full observations on-demand`);
-      output.push(`- Critical types (🔴 bugfix, ⚖️ decision) often need detailed fetching`);
-      output.push(`- Trust this index over re-reading code for past decisions and learnings`);
-    }
-    output.push('');
-
-    // Section 1: Aggregate ROI Metrics
-    const totalObservations = observations.length;
-    const totalReadTokens = observations.reduce((sum, obs) => {
-      // Estimate read tokens from observation size
-      const obsSize = (obs.title?.length || 0) +
-                      (obs.subtitle?.length || 0) +
-                      (obs.narrative?.length || 0) +
-                      JSON.stringify(obs.facts || []).length;
-      return sum + Math.ceil(obsSize / CHARS_PER_TOKEN_ESTIMATE);
-    }, 0);
-    const totalDiscoveryTokens = observations.reduce((sum, obs) => sum + (obs.discovery_tokens || 0), 0);
-    const savings = totalDiscoveryTokens - totalReadTokens;
-    const savingsPercent = totalDiscoveryTokens > 0
-      ? Math.round((savings / totalDiscoveryTokens) * 100)
-      : 0;
-
-    // Display Context Economics section only if at least one token setting is enabled
-    const showContextEconomics = config.showReadTokens || config.showWorkTokens ||
-                                   config.showSavingsAmount || config.showSavingsPercent;
-
-    if (showContextEconomics) {
-      if (useColors) {
-        output.push(`${colors.bright}${colors.cyan}📊 Context Economics${colors.reset}`);
-        output.push(`${colors.dim}  Loading: ${totalObservations} observations (${totalReadTokens.toLocaleString()} tokens to read)${colors.reset}`);
-        output.push(`${colors.dim}  Work investment: ${totalDiscoveryTokens.toLocaleString()} tokens spent on research, building, and decisions${colors.reset}`);
-        if (totalDiscoveryTokens > 0 && (config.showSavingsAmount || config.showSavingsPercent)) {
-          let savingsLine = '  Your savings: ';
-          if (config.showSavingsAmount && config.showSavingsPercent) {
-            savingsLine += `${savings.toLocaleString()} tokens (${savingsPercent}% reduction from reuse)`;
-          } else if (config.showSavingsAmount) {
-            savingsLine += `${savings.toLocaleString()} tokens`;
-          } else {
-            savingsLine += `${savingsPercent}% reduction from reuse`;
-          }
-          output.push(`${colors.green}${savingsLine}${colors.reset}`);
-        }
-        output.push('');
-      } else {
-        output.push(`📊 **Context Economics**:`);
-        output.push(`- Loading: ${totalObservations} observations (${totalReadTokens.toLocaleString()} tokens to read)`);
-        output.push(`- Work investment: ${totalDiscoveryTokens.toLocaleString()} tokens spent on research, building, and decisions`);
-        if (totalDiscoveryTokens > 0 && (config.showSavingsAmount || config.showSavingsPercent)) {
-          let savingsLine = '- Your savings: ';
-          if (config.showSavingsAmount && config.showSavingsPercent) {
-            savingsLine += `${savings.toLocaleString()} tokens (${savingsPercent}% reduction from reuse)`;
-          } else if (config.showSavingsAmount) {
-            savingsLine += `${savings.toLocaleString()} tokens`;
-          } else {
-            savingsLine += `${savingsPercent}% reduction from reuse`;
-          }
-          output.push(savingsLine);
-        }
-        output.push('');
-      }
-    }
-
-    // Prepare summaries for timeline display
-    // The most recent summary shows full details (investigated, learned, etc.)
-    // Older summaries only show as timeline markers (no link needed)
-    const mostRecentSummaryId = recentSummaries[0]?.id;
-
-    interface SummaryTimelineItem extends SessionSummary {
-      displayEpoch: number;
-      displayTime: string;
-      shouldShowLink: boolean;
-    }
-
-    const summariesForTimeline: SummaryTimelineItem[] = displaySummaries.map((summary, i) => {
-      // For visual grouping, display each summary at the time range it covers
-      // Most recent: shows at its own time (current session)
-      // Older: shows at the previous (older) summary's time to mark the session range
-      const olderSummary = i === 0 ? null : recentSummaries[i + 1];
-      return {
-        ...summary,
-        displayEpoch: olderSummary ? olderSummary.created_at_epoch : summary.created_at_epoch,
-        displayTime: olderSummary ? olderSummary.created_at : summary.created_at,
-        shouldShowLink: summary.id !== mostRecentSummaryId
-      };
-    });
-
-    // Identify which observations should show full details (most recent N)
-    const fullObservationIds = new Set(
-      observations
-        .slice(0, config.fullObservationCount)
-        .map(obs => obs.id)
-    );
-
-    type TimelineItem =
-      | { type: 'observation'; data: Observation }
-      | { type: 'summary'; data: SummaryTimelineItem };
-
-    const timeline: TimelineItem[] = [
-      ...timelineObs.map(obs => ({ type: 'observation' as const, data: obs })),
-      ...summariesForTimeline.map(summary => ({ type: 'summary' as const, data: summary }))
-    ];
-
-    // Sort chronologically
-    timeline.sort((a, b) => {
-      const aEpoch = a.type === 'observation' ? a.data.created_at_epoch : a.data.displayEpoch;
-      const bEpoch = b.type === 'observation' ? b.data.created_at_epoch : b.data.displayEpoch;
-      return aEpoch - bEpoch;
-    });
-
-    // Group by day for rendering
-    const itemsByDay = new Map<string, TimelineItem[]>();
-    for (const item of timeline) {
-      const itemDate = item.type === 'observation' ? item.data.created_at : item.data.displayTime;
-      const day = formatDate(itemDate);
-      if (!itemsByDay.has(day)) {
-        itemsByDay.set(day, []);
-      }
-      itemsByDay.get(day)!.push(item);
-    }
-
-    // Sort days chronologically
-    const sortedDays = Array.from(itemsByDay.entries()).sort((a, b) => {
-      const aDate = new Date(a[0]).getTime();
-      const bDate = new Date(b[0]).getTime();
-      return aDate - bDate;
-    });
-
-    // Render each day's timeline
-    for (const [day, dayItems] of sortedDays) {
-      // Day header
-      if (useColors) {
-        output.push(`${colors.bright}${colors.cyan}${day}${colors.reset}`);
-        output.push('');
-      } else {
-        output.push(`### ${day}`);
-        output.push('');
-      }
-
-      // Render items chronologically with visual file grouping
-      let currentFile: string | null = null;
-      let lastTime = '';
-      let tableOpen = false;
-
-      for (const item of dayItems) {
-        if (item.type === 'summary') {
-          // Close any open table
-          if (tableOpen) {
-            output.push('');
-            tableOpen = false;
-            currentFile = null;
-            lastTime = '';
-          }
-
-          // Render summary
-          const summary = item.data;
-          const summaryTitle = `${summary.request || 'Session started'} (${formatDateTime(summary.displayTime)})`;
-          const link = summary.shouldShowLink ? `claude-mem://session-summary/${summary.id}` : '';
-
-          if (useColors) {
-            const linkPart = link ? `${colors.dim}[${link}]${colors.reset}` : '';
-            output.push(`🎯 ${colors.yellow}#S${summary.id}${colors.reset} ${summaryTitle} ${linkPart}`);
-          } else {
-            const linkPart = link ? ` [→](${link})` : '';
-            output.push(`**🎯 #S${summary.id}** ${summaryTitle}${linkPart}`);
-          }
-          output.push('');
-        } else {
-          // Render observation
-          const obs = item.data;
-          const files = parseJsonArray(obs.files_modified);
-          const file = (files.length > 0 && files[0]) ? toRelativePath(files[0], cwd) : 'General';
-
-          // Check if we need a new file section
-          if (file !== currentFile) {
-            // Close previous table
-            if (tableOpen) {
-              output.push('');
-            }
-
-            // File header
-            if (useColors) {
-              output.push(`${colors.dim}${file}${colors.reset}`);
-            } else {
-              output.push(`**${file}**`);
-            }
-
-            // Table header (markdown only)
-            if (!useColors) {
-              output.push(`| ID | Time | T | Title | Read | Work |`);
-              output.push(`|----|------|---|-------|------|------|`);
-            }
-
-            currentFile = file;
-            tableOpen = true;
-            lastTime = '';
-          }
-
-          const time = formatTime(obs.created_at);
-          const title = obs.title || 'Untitled';
-
-          // Map observation type to emoji icon
-          const icon = TYPE_ICON_MAP[obs.type as keyof typeof TYPE_ICON_MAP] || '•';
-
-          // Section 2: Calculate read tokens (estimate from observation size)
-          const obsSize = (obs.title?.length || 0) +
-                          (obs.subtitle?.length || 0) +
-                          (obs.narrative?.length || 0) +
-                          JSON.stringify(obs.facts || []).length;
-          const readTokens = Math.ceil(obsSize / CHARS_PER_TOKEN_ESTIMATE);
-
-          // Get discovery tokens (handle old observations without this field)
-          const discoveryTokens = obs.discovery_tokens || 0;
-
-          // Map observation type to work emoji
-          const workEmoji = TYPE_WORK_EMOJI_MAP[obs.type as keyof typeof TYPE_WORK_EMOJI_MAP] || '🔍';
-
-          const discoveryDisplay = discoveryTokens > 0 ? `${workEmoji} ${discoveryTokens.toLocaleString()}` : '-';
-
-          const showTime = time !== lastTime;
-          const timeDisplay = showTime ? time : '';
-          lastTime = time;
-
-          // Check if this observation should show full details
-          const shouldShowFull = fullObservationIds.has(obs.id);
-
-          if (shouldShowFull) {
-            // Render with full details (narrative or facts)
-            const detailField = config.fullObservationField === 'narrative'
-              ? obs.narrative
-              : (obs.facts ? parseJsonArray(obs.facts).join('\n') : null);
-
-            if (useColors) {
-              const timePart = showTime ? `${colors.dim}${time}${colors.reset}` : ' '.repeat(time.length);
-              const readPart = (config.showReadTokens && readTokens > 0) ? `${colors.dim}(~${readTokens}t)${colors.reset}` : '';
-              const discoveryPart = (config.showWorkTokens && discoveryTokens > 0) ? `${colors.dim}(${workEmoji} ${discoveryTokens.toLocaleString()}t)${colors.reset}` : '';
-
-              output.push(`  ${colors.dim}#${obs.id}${colors.reset}  ${timePart}  ${icon}  ${colors.bright}${title}${colors.reset}`);
-              if (detailField) {
-                output.push(`    ${colors.dim}${detailField}${colors.reset}`);
-              }
-              if (readPart || discoveryPart) {
-                output.push(`    ${readPart} ${discoveryPart}`);
-              }
-              output.push('');
-            } else {
-              // Close table for full observation
-              if (tableOpen) {
-                output.push('');
-                tableOpen = false;
-              }
-
-              output.push(`**#${obs.id}** ${timeDisplay || '″'} ${icon} **${title}**`);
-              if (detailField) {
-                output.push('');
-                output.push(detailField);
-                output.push('');
-              }
-              const tokenParts: string[] = [];
-              if (config.showReadTokens) {
-                tokenParts.push(`Read: ~${readTokens}`);
-              }
-              if (config.showWorkTokens) {
-                tokenParts.push(`Work: ${discoveryDisplay}`);
-              }
-              if (tokenParts.length > 0) {
-                output.push(tokenParts.join(', '));
-              }
-              output.push('');
-
-              // Reopen table for next items if in same file
-              currentFile = null;
-            }
-          } else {
-            // Compact index rendering (existing code)
-            if (useColors) {
-              const timePart = showTime ? `${colors.dim}${time}${colors.reset}` : ' '.repeat(time.length);
-              const readPart = (config.showReadTokens && readTokens > 0) ? `${colors.dim}(~${readTokens}t)${colors.reset}` : '';
-              const discoveryPart = (config.showWorkTokens && discoveryTokens > 0) ? `${colors.dim}(${workEmoji} ${discoveryTokens.toLocaleString()}t)${colors.reset}` : '';
-              output.push(`  ${colors.dim}#${obs.id}${colors.reset}  ${timePart}  ${icon}  ${title} ${readPart} ${discoveryPart}`);
-            } else {
-              const readCol = config.showReadTokens ? `~${readTokens}` : '';
-              const workCol = config.showWorkTokens ? discoveryDisplay : '';
-              output.push(`| #${obs.id} | ${timeDisplay || '″'} | ${icon} | ${title} | ${readCol} | ${workCol} |`);
-            }
-          }
-        }
-      }
-
-      // Close final table if open
-      if (tableOpen) {
-        output.push('');
-      }
-    }
-
-    // Add full summary details for most recent session
-    // Only show if summary was generated AFTER the last observation
-    const mostRecentSummary = recentSummaries[0];
-    const mostRecentObservation = observations[0]; // observations are DESC by created_at_epoch
-
-    const shouldShowSummary = config.showLastSummary &&
-      mostRecentSummary &&
-      (mostRecentSummary.investigated || mostRecentSummary.learned || mostRecentSummary.completed || mostRecentSummary.next_steps) &&
-      (!mostRecentObservation || mostRecentSummary.created_at_epoch > mostRecentObservation.created_at_epoch);
-
-    if (shouldShowSummary) {
-      output.push(...renderSummaryField('Investigated', mostRecentSummary.investigated, colors.blue, useColors));
-      output.push(...renderSummaryField('Learned', mostRecentSummary.learned, colors.yellow, useColors));
-      output.push(...renderSummaryField('Completed', mostRecentSummary.completed, colors.green, useColors));
-      output.push(...renderSummaryField('Next Steps', mostRecentSummary.next_steps, colors.magenta, useColors));
-    }
-
-    // Previously section (last assistant message from prior session) - positioned at bottom for chronological sense
-    if (priorAssistantMessage) {
-      output.push('');
-      output.push('---');
-      output.push('');
-      if (useColors) {
-        output.push(`${colors.bright}${colors.magenta}📋 Previously${colors.reset}`);
-        output.push('');
-        output.push(`${colors.dim}A: ${priorAssistantMessage}${colors.reset}`);
-      } else {
-        output.push(`**📋 Previously**`);
-        output.push('');
-        output.push(`A: ${priorAssistantMessage}`);
-      }
-      output.push('');
-    }
-
-    // Footer with token savings message (only show if token economics is visible)
-    if (showContextEconomics && totalDiscoveryTokens > 0 && savings > 0) {
-      const workTokensK = Math.round(totalDiscoveryTokens / 1000);
-      output.push('');
-      if (useColors) {
-        output.push(`${colors.dim}💰 Access ${workTokensK}k tokens of past research & decisions for just ${totalReadTokens.toLocaleString()}t. Use the mem-search skill to access memories by ID instead of re-reading files.${colors.reset}`);
-      } else {
-        output.push(`💰 Access ${workTokensK}k tokens of past research & decisions for just ${totalReadTokens.toLocaleString()}t. Use the mem-search skill to access memories by ID instead of re-reading files.`);
-      }
-    }
-  }
-
-  db?.close();
-
-  // Add debug info directly to output
-  // if (debugInfo.length > 0) {
-  //   output.push('');
-  //   output.push('---');
-  //   output.push('');
-  //   output.push(...debugInfo);
-  // }
-
-  return output.join('\n').trimEnd();
 }

-// Export for use by worker service
-export { contextHook };
-
 // Entry Point - handle stdin/stdout
-const forceColors = process.argv.includes('--colors');
+const forceColors = process.argv.includes("--colors");

 if (stdin.isTTY || forceColors) {
-  // Running manually from terminal - print formatted output with colors
-  contextHook(undefined, true).then(contextOutput => {
-    console.log(contextOutput);
+  contextHook(undefined).then((text) => {
+    console.log(text);
    process.exit(0);
  });
 } else {
-  // Running from hook - wrap in hookSpecificOutput JSON format
-  let input = '';
-  stdin.on('data', (chunk) => input += chunk);
-  stdin.on('end', async () => {
+  let input = "";
+  stdin.on("data", (chunk) => (input += chunk));
+  stdin.on("end", async () => {
    const parsed = input.trim() ? JSON.parse(input) : undefined;
-    const contextOutput = await contextHook(parsed, false);
-    const result = {
-      hookSpecificOutput: {
-        hookEventName: "SessionStart",
-        additionalContext: contextOutput
-      }
-    };
-    console.log(JSON.stringify(result));
+    const text = await contextHook(parsed);
+
+    console.log(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "SessionStart",
+          additionalContext: text,
+        },
+      })
+    );
    process.exit(0);
  });
-}
+}
@@ -1,4 +1,4 @@
-export type HookType = 'PreCompact' | 'SessionStart' | 'UserPromptSubmit' | 'PostToolUse' | 'Stop' | string;
+export type HookType = 'SessionStart' | 'UserPromptSubmit' | 'PostToolUse' | 'Stop';

 export interface HookResponseOptions {
  reason?: string;
@@ -20,21 +20,6 @@ function buildHookResponse(
  success: boolean,
  options: HookResponseOptions
 ): HookResponse {
-  if (hookType === 'PreCompact') {
-    if (success) {
-      return {
-        continue: true,
-        suppressOutput: true
-      };
-    }
-
-    return {
-      continue: false,
-      stopReason: options.reason || 'Pre-compact operation failed',
-      suppressOutput: true
-    };
-  }
-
  if (hookType === 'SessionStart') {
    if (success && options.context) {
      return {
@@ -1,51 +1,15 @@
-/**
- * New Hook - UserPromptSubmit
- *
- * DUAL PURPOSE HOOK: Handles BOTH session initialization AND continuation
- * ==========================================================================
- *
- * CRITICAL ARCHITECTURE FACTS (NEVER FORGET):
- *
- * 1. SESSION ID THREADING - The Single Source of Truth
- *    - Claude Code assigns ONE session_id per conversation
- *    - ALL hooks in that conversation receive the SAME session_id
- *    - We ALWAYS use this session_id - NEVER generate our own
- *    - This is how NEW hook, SAVE hook, and SUMMARY hook stay connected
- *
- * 2. NO EXISTENCE CHECKS NEEDED
- *    - createSDKSession is idempotent (INSERT OR IGNORE)
- *    - Prompt #1: Creates new database row, returns new ID
- *    - Prompt #2+: Row exists, returns existing ID
- *    - We NEVER need to check "does session exist?" - just use the session_id
- *
- * 3. CONTINUATION LOGIC LOCATION
- *    - This hook does NOT contain continuation prompt logic
- *    - That lives in SDKAgent.ts (lines 125-127)
- *    - SDKAgent checks promptNumber to choose init vs continuation prompt
- *    - BOTH prompts receive the SAME session_id from this hook
- *
- * 4. UNIFIED WITH SAVE HOOK
- *    - SAVE hook uses: db.createSDKSession(session_id, '', '')
- *    - NEW hook uses: db.createSDKSession(session_id, project, prompt)
- *    - Both use session_id from hook context - this keeps everything connected
- *
- * This is KISS in action: Use the session_id we're given, trust idempotent
- * database operations, and let SDKAgent handle init vs continuation logic.
- */
-
 import path from 'path';
 import { stdin } from 'process';
-import { SessionStore } from '../services/sqlite/SessionStore.js';
 import { createHookResponse } from './hook-response.js';
 import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
-import { silentDebug } from '../utils/silent-debug.js';
-import { stripMemoryTagsFromPrompt } from '../utils/tag-stripping.js';
+import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
+import { handleWorkerError } from '../shared/hook-error-handler.js';
+import { getWorkerRestartInstructions } from '../utils/error-messages.js';

 export interface UserPromptSubmitInput {
  session_id: string;
  cwd: string;
  prompt: string;
-  [key: string]: any;
 }


@@ -53,93 +17,80 @@ export interface UserPromptSubmitInput {
 * New Hook Main Logic
 */
 async function newHook(input?: UserPromptSubmitInput): Promise<void> {
+  // Ensure worker is running before any other logic
+  await ensureWorkerRunning();
+
  if (!input) {
    throw new Error('newHook requires input');
  }

  const { session_id, cwd, prompt } = input;
+  const project = path.basename(cwd);

-  // Debug: Log what we received
-  silentDebug('[new-hook] Input received', {
+  happy_path_error__with_fallback('[new-hook] Input received', {
    session_id,
-    cwd,
-    cwd_type: typeof cwd,
-    cwd_length: cwd?.length,
-    has_cwd: !!cwd,
+    project,
    prompt_length: prompt?.length
  });

-  const project = path.basename(cwd);
-
-  silentDebug('[new-hook] Project extracted', {
-    project,
-    project_type: typeof project,
-    project_length: project?.length,
-    is_empty: project === '',
-    cwd_was: cwd
-  });
-
-  // Ensure worker is running
-  await ensureWorkerRunning();
-
-  const db = new SessionStore();
-
-  // CRITICAL: Use session_id from hook as THE source of truth
-  // createSDKSession is idempotent - creates new or returns existing
-  // This is how ALL hooks stay connected to the same session
-  const sessionDbId = db.createSDKSession(session_id, project, prompt);
-  const promptNumber = db.incrementPromptCounter(sessionDbId);
-
-  // Strip memory tags before saving user prompt to prevent privacy leaks
-  // Tags like <private> and <claude-mem-context> should not be stored or searchable
-  const cleanedUserPrompt = stripMemoryTagsFromPrompt(prompt);
-
-  // Skip memory operations for fully private prompts
-  // If the entire prompt was wrapped in <private> tags, don't create any observations
-  if (!cleanedUserPrompt || cleanedUserPrompt.trim() === '') {
-    silentDebug('[new-hook] Prompt entirely private, skipping memory operations', {
-      session_id,
-      promptNumber,
-      originalLength: prompt.length
-    });
-    db.close();
-    console.error(`[new-hook] Session ${sessionDbId}, prompt #${promptNumber} (fully private - skipped)`);
-    console.log(createHookResponse('UserPromptSubmit', true));
-    return;
-  }
-
-  db.saveUserPrompt(session_id, promptNumber, cleanedUserPrompt);
-
-  console.error(`[new-hook] Session ${sessionDbId}, prompt #${promptNumber}`);
-
-  db.close();
-
  const port = getWorkerPort();

+  // Initialize session via HTTP - handles DB operations and privacy checks
+  let sessionDbId: number;
+  let promptNumber: number;
+
+  try {
+    const initResponse = await fetch(`http://127.0.0.1:${port}/api/sessions/init`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        claudeSessionId: session_id,
+        project,
+        prompt
+      }),
+      signal: AbortSignal.timeout(5000)
+    });
+
+    if (!initResponse.ok) {
+      const errorText = await initResponse.text();
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
+    }
+
+    const initResult = await initResponse.json();
+    sessionDbId = initResult.sessionDbId;
+    promptNumber = initResult.promptNumber;
+
+    // Check if prompt was entirely private (worker performs privacy check)
+    if (initResult.skipped && initResult.reason === 'private') {
+      console.error(`[new-hook] Session ${sessionDbId}, prompt #${promptNumber} (fully private - skipped)`);
+      console.log(createHookResponse('UserPromptSubmit', true));
+      return;
+    }
+
+    console.error(`[new-hook] Session ${sessionDbId}, prompt #${promptNumber}`);
+  } catch (error: any) {
+    handleWorkerError(error);
+  }
+
  // Strip leading slash from commands for memory agent
  // /review 101 → review 101 (more semantic for observations)
  const cleanedPrompt = prompt.startsWith('/') ? prompt.substring(1) : prompt;

  try {
-    // Initialize session via HTTP
+    // Initialize SDK agent session via HTTP (starts the agent!)
    const response = await fetch(`http://127.0.0.1:${port}/sessions/${sessionDbId}/init`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ project, userPrompt: cleanedPrompt, promptNumber }),
+      body: JSON.stringify({ userPrompt: cleanedPrompt, promptNumber }),
      signal: AbortSignal.timeout(5000)
    });

    if (!response.ok) {
      const errorText = await response.text();
-      throw new Error(`Failed to initialize session: ${response.status} ${errorText}`);
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
    }
  } catch (error: any) {
-    // Only show restart message for connection errors, not HTTP errors
-    if (error.cause?.code === 'ECONNREFUSED' || error.name === 'TimeoutError' || error.message.includes('fetch failed')) {
-      throw new Error("There's a problem with the worker. If you just updated, type `pm2 restart claude-mem-worker` in your terminal to continue");
-    }
-    // Re-throw HTTP errors and other errors as-is
-    throw error;
+    handleWorkerError(error);
  }

  console.log(createHookResponse('UserPromptSubmit', true));
@@ -1,15 +1,19 @@
 /**
 * Save Hook - PostToolUse
- * Consolidated entry point + logic
+ *
+ * Pure HTTP client - sends data to worker, worker handles all database operations
+ * including privacy checks. This allows the hook to run under any runtime
+ * (Node.js or Bun) since it has no native module dependencies.
 */

 import { stdin } from 'process';
-import { SessionStore } from '../services/sqlite/SessionStore.js';
 import { createHookResponse } from './hook-response.js';
 import { logger } from '../utils/logger.js';
 import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
-import { silentDebug } from '../utils/silent-debug.js';
-import { stripMemoryTagsFromJson } from '../utils/tag-stripping.js';
+import { HOOK_TIMEOUTS } from '../shared/hook-constants.js';
+import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
+import { handleWorkerError } from '../shared/hook-error-handler.js';
+import { getWorkerRestartInstructions } from '../utils/error-messages.js';

 export interface PostToolUseInput {
  session_id: string;
@@ -17,125 +21,59 @@ export interface PostToolUseInput {
  tool_name: string;
  tool_input: any;
  tool_response: any;
-  [key: string]: any;
 }

-// Tools to skip (low value or too frequent)
-const SKIP_TOOLS = new Set([
-  'ListMcpResourcesTool',  // MCP infrastructure
-  'SlashCommand',          // Command invocation (observe what it produces, not the call)
-  'Skill',                 // Skill invocation (observe what it produces, not the call)
-  'TodoWrite',             // Task management meta-tool
-  'AskUserQuestion'        // User interaction, not substantive work
-]);
-
-
 /**
- * Save Hook Main Logic
+ * Save Hook Main Logic - Fire-and-forget HTTP client
 */
 async function saveHook(input?: PostToolUseInput): Promise<void> {
+  // Ensure worker is running before any other logic
+  await ensureWorkerRunning();
+
  if (!input) {
    throw new Error('saveHook requires input');
  }

  const { session_id, cwd, tool_name, tool_input, tool_response } = input;

-  if (SKIP_TOOLS.has(tool_name)) {
-    console.log(createHookResponse('PostToolUse', true));
-    return;
-  }
-
-  // Ensure worker is running
-  await ensureWorkerRunning();
-
-  const db = new SessionStore();
-
-  // Get or create session
-  const sessionDbId = db.createSDKSession(session_id, '', '');
-  const promptNumber = db.getPromptCounter(sessionDbId);
-
-  // Skip observation if user prompt was entirely private
-  // This respects the user's intent: if they marked the entire prompt as <private>,
-  // they don't want ANY observations from that interaction
-  const userPrompt = db.getUserPrompt(session_id, promptNumber);
-  if (!userPrompt || userPrompt.trim() === '') {
-    silentDebug('[save-hook] Skipping observation - user prompt was entirely private', {
-      session_id,
-      promptNumber,
-      tool_name
-    });
-    db.close();
-    console.log(createHookResponse('PostToolUse', true));
-    return;
-  }
-
-  db.close();
+  const port = getWorkerPort();

  const toolStr = logger.formatTool(tool_name, tool_input);

-  const port = getWorkerPort();
-
  logger.dataIn('HOOK', `PostToolUse: ${toolStr}`, {
-    sessionId: sessionDbId,
    workerPort: port
  });

  try {
-    // Serialize and strip memory tags from tool_input and tool_response
-    // This prevents recursive storage of context and respects <private> tags
-    let cleanedToolInput = '{}';
-    let cleanedToolResponse = '{}';
-
-    try {
-      cleanedToolInput = tool_input !== undefined
-        ? stripMemoryTagsFromJson(JSON.stringify(tool_input))
-        : '{}';
-    } catch (error) {
-      // Handle circular references or other JSON.stringify errors
-      silentDebug('[save-hook] Failed to stringify tool_input:', { error, tool_name });
-      cleanedToolInput = '{"error": "Failed to serialize tool_input"}';
-    }
-
-    try {
-      cleanedToolResponse = tool_response !== undefined
-        ? stripMemoryTagsFromJson(JSON.stringify(tool_response))
-        : '{}';
-    } catch (error) {
-      // Handle circular references or other JSON.stringify errors
-      silentDebug('[save-hook] Failed to stringify tool_response:', { error, tool_name });
-      cleanedToolResponse = '{"error": "Failed to serialize tool_response"}';
-    }
-
-    const response = await fetch(`http://127.0.0.1:${port}/sessions/${sessionDbId}/observations`, {
+    // Send to worker - worker handles privacy check and database operations
+    const response = await fetch(`http://127.0.0.1:${port}/api/sessions/observations`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
+        claudeSessionId: session_id,
        tool_name,
-        tool_input: cleanedToolInput,
-        tool_response: cleanedToolResponse,
-        prompt_number: promptNumber,
-        cwd: cwd || ''
+        tool_input,
+        tool_response,
+        cwd: happy_path_error__with_fallback(
+          'Missing cwd in PostToolUse hook input',
+          { session_id, tool_name },
+          cwd || ''
+        )
      }),
-      signal: AbortSignal.timeout(2000)
+      signal: AbortSignal.timeout(HOOK_TIMEOUTS.DEFAULT)
    });

    if (!response.ok) {
      const errorText = await response.text();
      logger.failure('HOOK', 'Failed to send observation', {
-        sessionId: sessionDbId,
        status: response.status
      }, errorText);
-      throw new Error(`Failed to send observation to worker: ${response.status} ${errorText}`);
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
    }

-    logger.debug('HOOK', 'Observation sent successfully', { sessionId: sessionDbId, toolName: tool_name });
+    logger.debug('HOOK', 'Observation sent successfully', { toolName: tool_name });
  } catch (error: any) {
-    // Only show restart message for connection errors, not HTTP errors
-    if (error.cause?.code === 'ECONNREFUSED' || error.name === 'TimeoutError' || error.message.includes('fetch failed')) {
-      throw new Error("There's a problem with the worker. If you just updated, type `pm2 restart claude-mem-worker` in your terminal to continue");
-    }
-    // Re-throw HTTP errors and other errors as-is
-    throw error;
+    handleWorkerError(error);
  }

  console.log(createHookResponse('PostToolUse', true));
@@ -1,240 +1,99 @@
 /**
 * Summary Hook - Stop
- * Consolidated entry point + logic
+ *
+ * Pure HTTP client - sends data to worker, worker handles all database operations
+ * including privacy checks. This allows the hook to run under any runtime
+ * (Node.js or Bun) since it has no native module dependencies.
+ *
+ * Transcript parsing stays in the hook because only the hook has access to
+ * the transcript file path.
 */

 import { stdin } from 'process';
-import { readFileSync, existsSync } from 'fs';
-import { SessionStore } from '../services/sqlite/SessionStore.js';
 import { createHookResponse } from './hook-response.js';
 import { logger } from '../utils/logger.js';
 import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
-import { silentDebug } from '../utils/silent-debug.js';
+import { HOOK_TIMEOUTS } from '../shared/hook-constants.js';
+import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
+import { handleWorkerError } from '../shared/hook-error-handler.js';
+import { extractLastMessage } from '../shared/transcript-parser.js';
+import { getWorkerRestartInstructions } from '../utils/error-messages.js';

 export interface StopInput {
  session_id: string;
  cwd: string;
-  transcript_path?: string;
-  [key: string]: any;
+  transcript_path: string;
 }

 /**
- * Extract last user message from transcript JSONL file
- */
-function extractLastUserMessage(transcriptPath: string): string {
-  if (!transcriptPath || !existsSync(transcriptPath)) {
-    return '';
-  }
-
-  try {
-    const content = readFileSync(transcriptPath, 'utf-8').trim();
-    if (!content) {
-      return '';
-    }
-
-    const lines = content.split('\n');
-
-    // Parse JSONL and find last user message
-    for (let i = lines.length - 1; i >= 0; i--) {
-      try {
-        const line = JSON.parse(lines[i]);
-
-        // Claude Code transcript format: {type: "user", message: {role: "user", content: [...]}}
-        if (line.type === 'user' && line.message?.content) {
-          const content = line.message.content;
-
-          // Extract text content (handle both string and array formats)
-          if (typeof content === 'string') {
-            return content;
-          } else if (Array.isArray(content)) {
-            const textParts = content
-              .filter((c: any) => c.type === 'text')
-              .map((c: any) => c.text);
-            return textParts.join('\n');
-          }
-        }
-      } catch (parseError) {
-        // Skip malformed lines
-        continue;
-      }
-    }
-  } catch (error) {
-    logger.error('HOOK', 'Failed to read transcript', { transcriptPath }, error as Error);
-  }
-
-  return '';
-}
-
-/**
- * Extract last assistant message from transcript JSONL file
- * Filters out system-reminder tags to avoid polluting summaries
- */
-function extractLastAssistantMessage(transcriptPath: string): string {
-  if (!transcriptPath || !existsSync(transcriptPath)) {
-    return '';
-  }
-
-  try {
-    const content = readFileSync(transcriptPath, 'utf-8').trim();
-    if (!content) {
-      return '';
-    }
-
-    const lines = content.split('\n');
-
-    // Parse JSONL and find last assistant message
-    for (let i = lines.length - 1; i >= 0; i--) {
-      try {
-        const line = JSON.parse(lines[i]);
-
-        // Claude Code transcript format: {type: "assistant", message: {role: "assistant", content: [...]}}
-        if (line.type === 'assistant' && line.message?.content) {
-          let text = '';
-          const content = line.message.content;
-
-          // Extract text content (handle both string and array formats)
-          if (typeof content === 'string') {
-            text = content;
-          } else if (Array.isArray(content)) {
-            const textParts = content
-              .filter((c: any) => c.type === 'text')
-              .map((c: any) => c.text);
-            text = textParts.join('\n');
-          }
-
-          // Filter out system-reminder tags and their content
-          text = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '');
-
-          // Clean up excessive whitespace
-          text = text.replace(/\n{3,}/g, '\n\n').trim();
-
-          return text;
-        }
-      } catch (parseError) {
-        // Skip malformed lines
-        continue;
-      }
-    }
-  } catch (error) {
-    logger.error('HOOK', 'Failed to read transcript', { transcriptPath }, error as Error);
-  }
-
-  return '';
-}
-
-/**
- * Summary Hook Main Logic
+ * Summary Hook Main Logic - Fire-and-forget HTTP client
 */
 async function summaryHook(input?: StopInput): Promise<void> {
+  // Ensure worker is running before any other logic
+  await ensureWorkerRunning();
+
  if (!input) {
    throw new Error('summaryHook requires input');
  }

  const { session_id } = input;

-  // Ensure worker is running
-  await ensureWorkerRunning();
-
-  const db = new SessionStore();
-
-  // Get or create session
-  const sessionDbId = db.createSDKSession(session_id, '', '');
-  const promptNumber = db.getPromptCounter(sessionDbId);
-
-  // Skip summary if user prompt was entirely private
-  // This respects the user's intent: if they marked the entire prompt as <private>,
-  // they don't want ANY memory operations including summaries
-  const userPrompt = db.getUserPrompt(session_id, promptNumber);
-  if (!userPrompt || userPrompt.trim() === '') {
-    silentDebug('[summary-hook] Skipping summary - user prompt was entirely private', {
-      session_id,
-      promptNumber
-    });
-    db.close();
-    console.log(createHookResponse('Stop', true));
-    return;
-  }
-
-  // DIAGNOSTIC: Check session and observations
-  const sessionInfo = db.db.prepare(`
-    SELECT id, claude_session_id, sdk_session_id, project
-    FROM sdk_sessions WHERE id = ?
-  `).get(sessionDbId) as any;
-
-  const obsCount = db.db.prepare(`
-    SELECT COUNT(*) as count
-    FROM observations
-    WHERE sdk_session_id = ?
-  `).get(sessionInfo?.sdk_session_id) as { count: number };
-
-  silentDebug('[summary-hook] Session diagnostics', {
-    claudeSessionId: session_id,
-    sessionDbId,
-    sdkSessionId: sessionInfo?.sdk_session_id,
-    project: sessionInfo?.project,
-    promptNumber,
-    observationCount: obsCount?.count || 0,
-    transcriptPath: input.transcript_path
-  });
-
-  db.close();
-
  const port = getWorkerPort();

  // Extract last user AND assistant messages from transcript
-  const lastUserMessage = extractLastUserMessage(input.transcript_path || '');
-  const lastAssistantMessage = extractLastAssistantMessage(input.transcript_path || '');
-
-  silentDebug('[summary-hook] Extracted messages', {
-    hasLastUserMessage: !!lastUserMessage,
-    hasLastAssistantMessage: !!lastAssistantMessage,
-    lastAssistantPreview: lastAssistantMessage.substring(0, 200),
-    lastAssistantLength: lastAssistantMessage.length
-  });
+  const transcriptPath = happy_path_error__with_fallback(
+    'Missing transcript_path in Stop hook input',
+    { session_id },
+    input.transcript_path || ''
+  );
+  const lastUserMessage = extractLastMessage(transcriptPath, 'user');
+  const lastAssistantMessage = extractLastMessage(transcriptPath, 'assistant', true);

  logger.dataIn('HOOK', 'Stop: Requesting summary', {
-    sessionId: sessionDbId,
    workerPort: port,
-    promptNumber,
    hasLastUserMessage: !!lastUserMessage,
    hasLastAssistantMessage: !!lastAssistantMessage
  });

  try {
-    const response = await fetch(`http://127.0.0.1:${port}/sessions/${sessionDbId}/summarize`, {
+    // Send to worker - worker handles privacy check and database operations
+    const response = await fetch(`http://127.0.0.1:${port}/api/sessions/summarize`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
-        prompt_number: promptNumber,
+        claudeSessionId: session_id,
        last_user_message: lastUserMessage,
        last_assistant_message: lastAssistantMessage
      }),
-      signal: AbortSignal.timeout(2000)
+      signal: AbortSignal.timeout(HOOK_TIMEOUTS.DEFAULT)
    });

    if (!response.ok) {
      const errorText = await response.text();
      logger.failure('HOOK', 'Failed to generate summary', {
-        sessionId: sessionDbId,
        status: response.status
      }, errorText);
-      throw new Error(`Failed to request summary from worker: ${response.status} ${errorText}`);
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
    }

-    logger.debug('HOOK', 'Summary request sent successfully', { sessionId: sessionDbId });
+    logger.debug('HOOK', 'Summary request sent successfully');
  } catch (error: any) {
-    // Only show restart message for connection errors, not HTTP errors
-    if (error.cause?.code === 'ECONNREFUSED' || error.name === 'TimeoutError' || error.message.includes('fetch failed')) {
-      throw new Error("There's a problem with the worker. If you just updated, type `pm2 restart claude-mem-worker` in your terminal to continue");
-    }
-    // Re-throw HTTP errors and other errors as-is
-    throw error;
+    handleWorkerError(error);
  } finally {
-    await fetch(`http://127.0.0.1:${port}/api/processing`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ isProcessing: false })
-    });
+    // Stop processing spinner
+    try {
+      const spinnerResponse = await fetch(`http://127.0.0.1:${port}/api/processing`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ isProcessing: false }),
+        signal: AbortSignal.timeout(2000)
+      });
+      if (!spinnerResponse.ok) {
+        logger.warn('HOOK', 'Failed to stop spinner', { status: spinnerResponse.status });
+      }
+    } catch (error: any) {
+      logger.warn('HOOK', 'Could not stop spinner', { error: error.message });
+    }
  }

  console.log(createHookResponse('Stop', true));
@@ -6,27 +6,50 @@
 * has been loaded into their session. Uses stderr as the communication channel
 * since it's currently the only way to display messages in Claude Code UI.
 */
-import { execSync } from "child_process";
-import { join } from "path";
-import { homedir } from "os";
-import { existsSync } from "fs";
-import { getWorkerPort } from "../shared/worker-utils.js";
+import { basename } from "path";
+import { ensureWorkerRunning, getWorkerPort } from "../shared/worker-utils.js";
+import { HOOK_EXIT_CODES } from "../shared/hook-constants.js";
+import { getWorkerRestartInstructions } from "../utils/error-messages.js";

-// Check if node_modules exists - if not, this is first run
-const pluginDir = join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');
-const nodeModulesPath = join(pluginDir, 'node_modules');
+try {
+  // Ensure worker is running
+  await ensureWorkerRunning();

-if (!existsSync(nodeModulesPath)) {
-  // First-time installation - dependencies not yet installed
+  const port = getWorkerPort();
+  const project = basename(process.cwd());
+
+  // Fetch formatted context directly from worker API
+  const response = await fetch(
+    `http://127.0.0.1:${port}/api/context/inject?project=${encodeURIComponent(project)}&colors=true`,
+    { method: 'GET', signal: AbortSignal.timeout(5000) }
+  );
+
+  if (!response.ok) {
+    throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
+  }
+
+  const output = await response.text();
+
+  console.error(
+    "\n\n📝 Claude-Mem Context Loaded\n" +
+    "   ℹ️  Note: This appears as stderr but is informational only\n\n" +
+    output +
+    "\n\n💡 New! Wrap all or part of any message with <private> ... </private> to prevent storing sensitive information in your observation history.\n" +
+    "\n💬 Community https://discord.gg/J4wttp9vDu" +
+    `\n📺 Watch live in browser http://localhost:${port}/\n`
+  );
+
+} catch (error) {
+  // Context not available yet - likely first run or worker starting up
  console.error(`
 ---
-🎉  Note: This appears under Plugin Hook Error, but it's not an error. That's the only option for 
+🎉  Note: This appears under Plugin Hook Error, but it's not an error. That's the only option for
   user messages in Claude Code UI until a better method is provided.
 ---

 ⚠️  Claude-Mem: First-Time Setup

-Dependencies have been installed in the background. This only happens once.
+Dependencies are installing in the background. This only happens once.

 💡 TIPS:
   • Memories will start generating while you work
@@ -37,73 +60,6 @@ Thank you for installing Claude-Mem!

 This message was not added to your startup context, so you can continue working as normal.
 `);
-  process.exit(3);
 }

-try {
-  // Cross-platform path to context-hook.js in the installed plugin
-  const contextHookPath = join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack', 'plugin', 'scripts', 'context-hook.js');
-  const output = execSync(`node "${contextHookPath}" --colors`, {
-    encoding: 'utf8',
-    windowsHide: true
-  });
-
-  const port = getWorkerPort();
-
-  // If it's after Dec 5, 2025 7pm EST, patch this out
-  const now = new Date();
-  const amaEndDate = new Date('2025-12-06T00:00:00Z'); // Dec 5, 2025 7pm EST
-
-  // Product Hunt launch announcement - expires Dec 5, 2025 12am EST (05:00 UTC)
-  const phLaunchEndDate = new Date('2025-12-05T05:00:00Z');
-  let productHuntAnnouncement = "";
-  if (now < phLaunchEndDate) {
-    productHuntAnnouncement = `
-
-🚀 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🚀
-
-   We launched on Product Hunt!
-   https://tinyurl.com/claude-mem-ph
-
-   ⭐ Your upvote means the world - thank you!
-
-🚀 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🚀
-`;
-  }
-
-  let amaAnnouncement = "";
-  if (now < amaEndDate) {
-    // Check if we're during the live event (Dec 1-5, 5pm-7pm EST daily)
-    const estOffset = 5 * 60; // EST is UTC-5
-    const nowUtcMinutes = now.getUTCHours() * 60 + now.getUTCMinutes();
-    const estHour = Math.floor((nowUtcMinutes - estOffset + 1440) % 1440 / 60);
-    const day = now.getUTCDate();
-    const month = now.getUTCMonth();
-    const year = now.getUTCFullYear();
-
-    const isDec1to5 = year === 2025 && month === 11 && day >= 1 && day <= 5;
-    const isDuringLiveHours = estHour >= 17 && estHour < 19; // 5pm-7pm EST
-
-    if (isDec1to5 && isDuringLiveHours) {
-      amaAnnouncement = "\n   🔴 LIVE NOW: AMA w/ Dev (@thedotmack) until 7pm EST\n";
-    } else {
-      amaAnnouncement = "\n   – LIVE AMA w/ Dev (@thedotmack) Dec 1st–5th, 5pm to 7pm EST\n";
-    }
-  }
-
-  console.error(
-    "\n\n📝 Claude-Mem Context Loaded\n" +
-    "   ℹ️  Note: This appears as stderr but is informational only\n\n" +
-    output +
-    "\n\n💡 New! Wrap all or part of any message with <private> ... </private> to prevent storing sensitive information in your observation history.\n" +
-    "\n💬 Community https://discord.gg/J4wttp9vDu" +
-    productHuntAnnouncement +
-    amaAnnouncement +
-    `\n📺 Watch live in browser http://localhost:${port}/\n`
-  );
-
-} catch (error) {
-  console.error(`❌ Failed to load context display: ${error}`);
-}
-
-process.exit(3);
+process.exit(HOOK_EXIT_CODES.USER_MESSAGE_ONLY);
@@ -3,6 +3,8 @@
 * Generates prompts for the Claude Agent SDK memory worker
 */

+import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
+
 export interface Observation {
  id: number;
  tool_name: string;
@@ -175,7 +177,11 @@ export function buildObservationPrompt(obs: Observation): string {
 * Build prompt to generate progress summary
 */
 export function buildSummaryPrompt(session: SDKSession): string {
-  const lastAssistantMessage = session.last_assistant_message || '';
+  const lastAssistantMessage = happy_path_error__with_fallback(
+    'Missing last_assistant_message in session for summary prompt',
+    session,
+    session.last_assistant_message || ''
+  );

  return `PROGRESS SUMMARY CHECKPOINT
 ===========================
@@ -0,0 +1,447 @@
+/**
+ * Claude-mem MCP Search Server - Thin HTTP Wrapper
+ *
+ * Refactored from 2,718 lines to ~600-800 lines
+ * Delegates all business logic to Worker HTTP API at localhost:37777
+ * Maintains MCP protocol handling and tool schemas
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
+import { getWorkerPort, getWorkerHost } from '../shared/worker-utils.js';
+
+/**
+ * Worker HTTP API configuration
+ */
+const WORKER_PORT = getWorkerPort();
+const WORKER_HOST = getWorkerHost();
+const WORKER_BASE_URL = `http://${WORKER_HOST}:${WORKER_PORT}`;
+
+/**
+ * Map tool names to Worker HTTP endpoints
+ */
+const TOOL_ENDPOINT_MAP: Record<string, string> = {
+  'search': '/api/search',
+  'timeline': '/api/timeline',
+  'decisions': '/api/decisions',
+  'changes': '/api/changes',
+  'how_it_works': '/api/how-it-works',
+  'search_observations': '/api/search/observations',
+  'search_sessions': '/api/search/sessions',
+  'search_user_prompts': '/api/search/prompts',
+  'find_by_concept': '/api/search/by-concept',
+  'find_by_file': '/api/search/by-file',
+  'find_by_type': '/api/search/by-type',
+  'get_recent_context': '/api/context/recent',
+  'get_context_timeline': '/api/context/timeline',
+  'get_timeline_by_query': '/api/timeline/by-query'
+};
+
+/**
+ * Call Worker HTTP API endpoint
+ */
+async function callWorkerAPI(
+  endpoint: string,
+  params: Record<string, any>
+): Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {
+  happy_path_error__with_fallback('[mcp-server] → Worker API', { endpoint, params });
+
+  try {
+    const searchParams = new URLSearchParams();
+
+    // Convert params to query string
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined && value !== null) {
+        searchParams.append(key, String(value));
+      }
+    }
+
+    const url = `${WORKER_BASE_URL}${endpoint}?${searchParams}`;
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Worker API error (${response.status}): ${errorText}`);
+    }
+
+    const data = await response.json() as { content: Array<{ type: 'text'; text: string }>; isError?: boolean };
+
+    happy_path_error__with_fallback('[mcp-server] ← Worker API success', { endpoint });
+
+    // Worker returns { content: [...] } format directly
+    return data;
+  } catch (error: any) {
+    happy_path_error__with_fallback('[mcp-server] ← Worker API error', { endpoint, error: error.message });
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Error calling Worker API: ${error.message}`
+      }],
+      isError: true
+    };
+  }
+}
+
+/**
+ * Verify Worker is accessible
+ */
+async function verifyWorkerConnection(): Promise<boolean> {
+  try {
+    const response = await fetch(`${WORKER_BASE_URL}/api/health`);
+    return response.ok;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Tool definitions with HTTP-based handlers
+ */
+const tools = [
+  {
+    name: 'search',
+    description: 'Unified search across all memory types (observations, sessions, and user prompts) using vector-first semantic search (ChromaDB). Returns combined results from all document types. IMPORTANT: Always use index format first (default) to get an overview with minimal token usage, then use format: "full" only for specific items of interest.',
+    inputSchema: z.object({
+      query: z.string().optional().describe('Natural language search query for semantic ranking via ChromaDB vector search. Optional - omit for date-filtered queries only (Chroma cannot filter by date, requires direct SQLite).'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED for initial search), "full" for complete details (use only after reviewing index results)'),
+      type: z.enum(['observations', 'sessions', 'prompts']).optional().describe('Filter by document type (observations, sessions, or prompts). Omit to search all types.'),
+      obs_type: z.string().optional().describe('Filter observations by type (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change). Only applies when type="observations"'),
+      concepts: z.string().optional().describe('Filter by concept tags (single value or comma-separated list). Only applies when type="observations"'),
+      files: z.string().optional().describe('Filter by file paths (single value or comma-separated list for partial match). Only applies when type="observations"'),
+      project: z.string().optional().describe('Filter by project name'),
+      dateStart: z.union([z.string(), z.number()]).optional().describe('Start date for filtering (ISO string or epoch timestamp)'),
+      dateEnd: z.union([z.string(), z.number()]).optional().describe('End date for filtering (ISO string or epoch timestamp)'),
+      limit: z.number().min(1).max(100).default(20).describe('Maximum number of results'),
+      offset: z.number().min(0).default(0).describe('Number of results to skip'),
+      orderBy: z.enum(['relevance', 'date_desc', 'date_asc']).default('date_desc').describe('Sort order')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['search'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'timeline',
+    description: 'Fetch timeline of observations around a specific point in time. Supports two modes: anchor-based (fetch observations before/after a specific observation ID) and query-based (semantic search for anchor point). IMPORTANT: Use anchor_id when you know the specific observation, or query to find an anchor point first.',
+    inputSchema: z.object({
+      query: z.string().optional().describe('Natural language query to find anchor observation (query-based mode). Mutually exclusive with anchor_id.'),
+      anchor_id: z.number().optional().describe('Observation ID to use as anchor (anchor-based mode). Mutually exclusive with query.'),
+      before: z.number().min(0).max(100).default(10).describe('Number of observations to fetch before anchor'),
+      after: z.number().min(0).max(100).default(10).describe('Number of observations to fetch after anchor'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
+      obs_type: z.string().optional().describe('Filter observations by type (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change)'),
+      concepts: z.string().optional().describe('Filter by concept tags (single value or comma-separated list)'),
+      files: z.string().optional().describe('Filter by file paths (single value or comma-separated list for partial match)'),
+      project: z.string().optional().describe('Filter by project name')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['timeline'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'decisions',
+    description: 'Semantic shortcut for finding architectural, design, and implementation decisions. Optimized for decision-type observations with relevant keyword boosting.',
+    inputSchema: z.object({
+      query: z.string().describe('Natural language query for finding decisions'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
+      limit: z.number().min(1).max(100).default(20).describe('Maximum number of results'),
+      dateStart: z.union([z.string(), z.number()]).optional().describe('Start date for filtering (ISO string or epoch timestamp)'),
+      dateEnd: z.union([z.string(), z.number()]).optional().describe('End date for filtering (ISO string or epoch timestamp)')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['decisions'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'changes',
+    description: 'Semantic shortcut for finding code changes, refactorings, and modifications. Optimized for change-type observations with relevant keyword boosting.',
+    inputSchema: z.object({
+      query: z.string().describe('Natural language query for finding changes'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
+      limit: z.number().min(1).max(100).default(20).describe('Maximum number of results'),
+      dateStart: z.union([z.string(), z.number()]).optional().describe('Start date for filtering (ISO string or epoch timestamp)'),
+      dateEnd: z.union([z.string(), z.number()]).optional().describe('End date for filtering (ISO string or epoch timestamp)')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['changes'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'how_it_works',
+    description: 'Semantic shortcut for understanding system architecture, design patterns, and implementation details. Optimized for discovery-type observations with architecture/design keyword boosting.',
+    inputSchema: z.object({
+      query: z.string().describe('Natural language query for understanding how something works'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
+      limit: z.number().min(1).max(100).default(20).describe('Maximum number of results'),
+      dateStart: z.union([z.string(), z.number()]).optional().describe('Start date for filtering (ISO string or epoch timestamp)'),
+      dateEnd: z.union([z.string(), z.number()]).optional().describe('End date for filtering (ISO string or epoch timestamp)')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['how_it_works'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'search_observations',
+    description: '[DEPRECATED - Use "search" with type="observations" instead] Search observations (facts/narratives) using FTS5 full-text search. Supports filtering by type, concepts, files, and date range.',
+    inputSchema: z.object({
+      query: z.string().optional().describe('Full-text search query (FTS5)'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
+      type: z.string().optional().describe('Filter by observation type (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change)'),
+      concepts: z.string().optional().describe('Filter by concept tags (single value or comma-separated list)'),
+      files: z.string().optional().describe('Filter by file paths (single value or comma-separated list for partial match)'),
+      project: z.string().optional().describe('Filter by project name'),
+      dateStart: z.union([z.string(), z.number()]).optional().describe('Start date for filtering (ISO string or epoch timestamp)'),
+      dateEnd: z.union([z.string(), z.number()]).optional().describe('End date for filtering (ISO string or epoch timestamp)'),
+      limit: z.number().min(1).max(100).default(20).describe('Maximum number of results'),
+      offset: z.number().min(0).default(0).describe('Number of results to skip'),
+      orderBy: z.enum(['relevance', 'date_desc', 'date_asc']).default('relevance').describe('Sort order (relevance only when query provided)')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['search_observations'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'search_sessions',
+    description: '[DEPRECATED - Use "search" with type="sessions" instead] Search session summaries using FTS5 full-text search. Returns both request_summary and learned_summary fields.',
+    inputSchema: z.object({
+      query: z.string().optional().describe('Full-text search query (FTS5)'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
+      project: z.string().optional().describe('Filter by project name'),
+      dateStart: z.union([z.string(), z.number()]).optional().describe('Start date for filtering (ISO string or epoch timestamp)'),
+      dateEnd: z.union([z.string(), z.number()]).optional().describe('End date for filtering (ISO string or epoch timestamp)'),
+      limit: z.number().min(1).max(100).default(20).describe('Maximum number of results'),
+      offset: z.number().min(0).default(0).describe('Number of results to skip'),
+      orderBy: z.enum(['relevance', 'date_desc', 'date_asc']).default('relevance').describe('Sort order (relevance only when query provided)')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['search_sessions'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'search_user_prompts',
+    description: '[DEPRECATED - Use "search" with type="prompts" instead] Search user prompts using FTS5 full-text search. Searches prompt text only.',
+    inputSchema: z.object({
+      query: z.string().optional().describe('Full-text search query (FTS5)'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
+      project: z.string().optional().describe('Filter by project name'),
+      dateStart: z.union([z.string(), z.number()]).optional().describe('Start date for filtering (ISO string or epoch timestamp)'),
+      dateEnd: z.union([z.string(), z.number()]).optional().describe('End date for filtering (ISO string or epoch timestamp)'),
+      limit: z.number().min(1).max(100).default(20).describe('Maximum number of results'),
+      offset: z.number().min(0).default(0).describe('Number of results to skip'),
+      orderBy: z.enum(['relevance', 'date_desc', 'date_asc']).default('relevance').describe('Sort order (relevance only when query provided)')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['search_user_prompts'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'find_by_concept',
+    description: 'Find observations tagged with specific concepts. Returns observations that match any of the provided concept tags.',
+    inputSchema: z.object({
+      concepts: z.string().describe('Concept tag(s) to filter by (single value or comma-separated list)'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
+      type: z.string().optional().describe('Filter by observation type (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change)'),
+      files: z.string().optional().describe('Filter by file paths (single value or comma-separated list for partial match)'),
+      project: z.string().optional().describe('Filter by project name'),
+      dateStart: z.union([z.string(), z.number()]).optional().describe('Start date for filtering (ISO string or epoch timestamp)'),
+      dateEnd: z.union([z.string(), z.number()]).optional().describe('End date for filtering (ISO string or epoch timestamp)'),
+      limit: z.number().min(1).max(100).default(20).describe('Maximum number of results'),
+      offset: z.number().min(0).default(0).describe('Number of results to skip'),
+      orderBy: z.enum(['date_desc', 'date_asc']).default('date_desc').describe('Sort order')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['find_by_concept'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'find_by_file',
+    description: 'Find observations related to specific file paths. Uses partial matching - searches for file paths containing the provided string.',
+    inputSchema: z.object({
+      files: z.string().describe('File path(s) to filter by (single value or comma-separated list for partial match)'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
+      type: z.string().optional().describe('Filter by observation type (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change)'),
+      concepts: z.string().optional().describe('Filter by concept tags (single value or comma-separated list)'),
+      project: z.string().optional().describe('Filter by project name'),
+      dateStart: z.union([z.string(), z.number()]).optional().describe('Start date for filtering (ISO string or epoch timestamp)'),
+      dateEnd: z.union([z.string(), z.number()]).optional().describe('End date for filtering (ISO string or epoch timestamp)'),
+      limit: z.number().min(1).max(100).default(20).describe('Maximum number of results'),
+      offset: z.number().min(0).default(0).describe('Number of results to skip'),
+      orderBy: z.enum(['date_desc', 'date_asc']).default('date_desc').describe('Sort order')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['find_by_file'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'find_by_type',
+    description: 'Find observations of specific types. Returns observations matching any of the provided observation types.',
+    inputSchema: z.object({
+      type: z.string().describe('Observation type(s) to filter by (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change)'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
+      concepts: z.string().optional().describe('Filter by concept tags (single value or comma-separated list)'),
+      files: z.string().optional().describe('Filter by file paths (single value or comma-separated list for partial match)'),
+      project: z.string().optional().describe('Filter by project name'),
+      dateStart: z.union([z.string(), z.number()]).optional().describe('Start date for filtering (ISO string or epoch timestamp)'),
+      dateEnd: z.union([z.string(), z.number()]).optional().describe('End date for filtering (ISO string or epoch timestamp)'),
+      limit: z.number().min(1).max(100).default(20).describe('Maximum number of results'),
+      offset: z.number().min(0).default(0).describe('Number of results to skip'),
+      orderBy: z.enum(['date_desc', 'date_asc']).default('date_desc').describe('Sort order')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['find_by_type'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'get_recent_context',
+    description: 'Get recent session context for timeline display. Returns recent observations, sessions, and user prompts with metadata for building timeline UI.',
+    inputSchema: z.object({
+      limit: z.number().min(1).max(100).default(30).describe('Maximum number of timeline items to return'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
+      type: z.string().optional().describe('Filter by observation type (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change)'),
+      concepts: z.string().optional().describe('Filter by concept tags (single value or comma-separated list)'),
+      files: z.string().optional().describe('Filter by file paths (single value or comma-separated list for partial match)'),
+      project: z.string().optional().describe('Filter by project name'),
+      dateStart: z.union([z.string(), z.number()]).optional().describe('Start date for filtering (ISO string or epoch timestamp)'),
+      dateEnd: z.union([z.string(), z.number()]).optional().describe('End date for filtering (ISO string or epoch timestamp)')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['get_recent_context'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'get_context_timeline',
+    description: 'Get timeline of observations around a specific observation ID. Returns observations before and after the anchor point with metadata for timeline display.',
+    inputSchema: z.object({
+      anchor_id: z.number().describe('Observation ID to use as anchor point'),
+      before: z.number().min(0).max(100).default(10).describe('Number of observations to fetch before anchor'),
+      after: z.number().min(0).max(100).default(10).describe('Number of observations to fetch after anchor'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
+      type: z.string().optional().describe('Filter by observation type (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change)'),
+      concepts: z.string().optional().describe('Filter by concept tags (single value or comma-separated list)'),
+      files: z.string().optional().describe('Filter by file paths (single value or comma-separated list for partial match)'),
+      project: z.string().optional().describe('Filter by project name')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['get_context_timeline'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  },
+  {
+    name: 'get_timeline_by_query',
+    description: 'Combined search + timeline tool. First searches for observations matching the query, then returns timeline around the best match. Useful for finding specific observations and viewing their context.',
+    inputSchema: z.object({
+      query: z.string().describe('Natural language query to find anchor observation'),
+      before: z.number().min(0).max(100).default(10).describe('Number of observations to fetch before anchor'),
+      after: z.number().min(0).max(100).default(10).describe('Number of observations to fetch after anchor'),
+      format: z.enum(['index', 'full']).default('index').describe('Output format: "index" for titles/dates only (default, RECOMMENDED), "full" for complete details'),
+      type: z.string().optional().describe('Filter by observation type (single value or comma-separated list: decision,bugfix,feature,refactor,discovery,change)'),
+      concepts: z.string().optional().describe('Filter by concept tags (single value or comma-separated list)'),
+      files: z.string().optional().describe('Filter by file paths (single value or comma-separated list for partial match)'),
+      project: z.string().optional().describe('Filter by project name'),
+      dateStart: z.union([z.string(), z.number()]).optional().describe('Start date for filtering (ISO string or epoch timestamp)'),
+      dateEnd: z.union([z.string(), z.number()]).optional().describe('End date for filtering (ISO string or epoch timestamp)')
+    }),
+    handler: async (args: any) => {
+      const endpoint = TOOL_ENDPOINT_MAP['get_timeline_by_query'];
+      return await callWorkerAPI(endpoint, args);
+    }
+  }
+];
+
+// Create the MCP server
+const server = new Server(
+  {
+    name: 'claude-mem-search-server',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Register tools/list handler
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: tools.map(tool => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: zodToJsonSchema(tool.inputSchema) as Record<string, unknown>
+    }))
+  };
+});
+
+// Register tools/call handler
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const tool = tools.find(t => t.name === request.params.name);
+
+  if (!tool) {
+    throw new Error(`Unknown tool: ${request.params.name}`);
+  }
+
+  try {
+    return await tool.handler(request.params.arguments || {});
+  } catch (error: any) {
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Tool execution failed: ${error.message}`
+      }],
+      isError: true
+    };
+  }
+});
+
+// Cleanup function
+async function cleanup() {
+  happy_path_error__with_fallback('[mcp-server] Shutting down...');
+  process.exit(0);
+}
+
+// Register cleanup handlers for graceful shutdown
+process.on('SIGTERM', cleanup);
+process.on('SIGINT', cleanup);
+
+// Start the server
+async function main() {
+  // Start the MCP server
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  happy_path_error__with_fallback('[mcp-server] Claude-mem search server started');
+
+  // Check Worker availability in background
+  setTimeout(async () => {
+    const workerAvailable = await verifyWorkerConnection();
+    if (!workerAvailable) {
+      happy_path_error__with_fallback('[mcp-server] WARNING: Worker not available at', WORKER_BASE_URL);
+      happy_path_error__with_fallback('[mcp-server] Tools will fail until Worker is started');
+      happy_path_error__with_fallback('[mcp-server] Start Worker with: npm run worker:restart');
+    } else {
+      happy_path_error__with_fallback('[mcp-server] Worker available at', WORKER_BASE_URL);
+    }
+  }, 0);
+}
+
+main().catch((error) => {
+  happy_path_error__with_fallback('[mcp-server] Fatal error:', error);
+  process.exit(1);
+});
@@ -0,0 +1,712 @@
+/**
+ * Context Generator - generates context injection for SessionStart
+ *
+ * This module contains all the logic for building the context injection string.
+ * It's used by the worker service and called via HTTP from the context-hook.
+ */
+
+import path from 'path';
+import { homedir } from 'os';
+import { existsSync, readFileSync, unlinkSync } from 'fs';
+import { SessionStore } from './sqlite/SessionStore.js';
+import {
+  OBSERVATION_TYPES,
+  OBSERVATION_CONCEPTS,
+  TYPE_ICON_MAP,
+  TYPE_WORK_EMOJI_MAP
+} from '../constants/observation-metadata.js';
+import { logger } from '../utils/logger.js';
+import { SettingsDefaultsManager } from '../shared/SettingsDefaultsManager.js';
+
+// Version marker path - use homedir-based path that works in both CJS and ESM contexts
+const VERSION_MARKER_PATH = path.join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack', 'plugin', '.install-version');
+
+interface ContextConfig {
+  // Display counts
+  totalObservationCount: number;
+  fullObservationCount: number;
+  sessionCount: number;
+
+  // Token display toggles
+  showReadTokens: boolean;
+  showWorkTokens: boolean;
+  showSavingsAmount: boolean;
+  showSavingsPercent: boolean;
+
+  // Filters
+  observationTypes: Set<string>;
+  observationConcepts: Set<string>;
+
+  // Display options
+  fullObservationField: 'narrative' | 'facts';
+  showLastSummary: boolean;
+  showLastMessage: boolean;
+}
+
+/**
+ * Load all context configuration settings
+ * Priority: ~/.claude-mem/settings.json > env var > defaults
+ */
+function loadContextConfig(): ContextConfig {
+  const settingsPath = path.join(homedir(), '.claude-mem', 'settings.json');
+  const settings = SettingsDefaultsManager.loadFromFile(settingsPath);
+
+  try {
+    return {
+      totalObservationCount: parseInt(settings.CLAUDE_MEM_CONTEXT_OBSERVATIONS, 10),
+      fullObservationCount: parseInt(settings.CLAUDE_MEM_CONTEXT_FULL_COUNT, 10),
+      sessionCount: parseInt(settings.CLAUDE_MEM_CONTEXT_SESSION_COUNT, 10),
+      showReadTokens: settings.CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS === 'true',
+      showWorkTokens: settings.CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS === 'true',
+      showSavingsAmount: settings.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT === 'true',
+      showSavingsPercent: settings.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_PERCENT === 'true',
+      observationTypes: new Set(
+        settings.CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES.split(',').map((t: string) => t.trim()).filter(Boolean)
+      ),
+      observationConcepts: new Set(
+        settings.CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS.split(',').map((c: string) => c.trim()).filter(Boolean)
+      ),
+      fullObservationField: settings.CLAUDE_MEM_CONTEXT_FULL_FIELD as 'narrative' | 'facts',
+      showLastSummary: settings.CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY === 'true',
+      showLastMessage: settings.CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE === 'true',
+    };
+  } catch (error) {
+    logger.warn('WORKER', 'Failed to load context settings, using defaults', {}, error as Error);
+    // Return defaults on error
+    return {
+      totalObservationCount: 50,
+      fullObservationCount: 5,
+      sessionCount: 10,
+      showReadTokens: true,
+      showWorkTokens: true,
+      showSavingsAmount: true,
+      showSavingsPercent: true,
+      observationTypes: new Set(OBSERVATION_TYPES),
+      observationConcepts: new Set(OBSERVATION_CONCEPTS),
+      fullObservationField: 'narrative' as const,
+      showLastSummary: true,
+      showLastMessage: false,
+    };
+  }
+}
+
+// Configuration constants
+const CHARS_PER_TOKEN_ESTIMATE = 4;
+const SUMMARY_LOOKAHEAD = 1;
+
+export interface ContextInput {
+  session_id?: string;
+  transcript_path?: string;
+  cwd?: string;
+  hook_event_name?: string;
+  source?: "startup" | "resume" | "clear" | "compact";
+  [key: string]: any;
+}
+
+// ANSI color codes for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  gray: '\x1b[90m',
+  red: '\x1b[31m',
+};
+
+interface Observation {
+  id: number;
+  sdk_session_id: string;
+  type: string;
+  title: string | null;
+  subtitle: string | null;
+  narrative: string | null;
+  facts: string | null;
+  concepts: string | null;
+  files_read: string | null;
+  files_modified: string | null;
+  discovery_tokens: number | null;
+  created_at: string;
+  created_at_epoch: number;
+}
+
+interface SessionSummary {
+  id: number;
+  sdk_session_id: string;
+  request: string | null;
+  investigated: string | null;
+  learned: string | null;
+  completed: string | null;
+  next_steps: string | null;
+  created_at: string;
+  created_at_epoch: number;
+}
+
+// Helper: Parse JSON array safely
+function parseJsonArray(json: string | null): string[] {
+  if (!json) return [];
+  try {
+    const parsed = JSON.parse(json);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch (err) {
+    return [];
+  }
+}
+
+// Helper: Format date with time
+function formatDateTime(dateStr: string): string {
+  const date = new Date(dateStr);
+  return date.toLocaleString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: true
+  });
+}
+
+// Helper: Format just time (no date)
+function formatTime(dateStr: string): string {
+  const date = new Date(dateStr);
+  return date.toLocaleString('en-US', {
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: true
+  });
+}
+
+// Helper: Format just date
+function formatDate(dateStr: string): string {
+  const date = new Date(dateStr);
+  return date.toLocaleString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric'
+  });
+}
+
+// Helper: Convert absolute paths to relative paths
+function toRelativePath(filePath: string, cwd: string): string {
+  if (path.isAbsolute(filePath)) {
+    return path.relative(cwd, filePath);
+  }
+  return filePath;
+}
+
+// Helper: Render a summary field
+function renderSummaryField(label: string, value: string | null, color: string, useColors: boolean): string[] {
+  if (!value) return [];
+
+  if (useColors) {
+    return [`${color}${label}:${colors.reset} ${value}`, ''];
+  }
+  return [`**${label}**: ${value}`, ''];
+}
+
+// Helper: Convert cwd path to dashed format
+function cwdToDashed(cwd: string): string {
+  return cwd.replace(/\//g, '-');
+}
+
+// Helper: Extract last assistant message from transcript file
+function extractPriorMessages(transcriptPath: string): { userMessage: string; assistantMessage: string } {
+  try {
+    if (!existsSync(transcriptPath)) {
+      return { userMessage: '', assistantMessage: '' };
+    }
+
+    const content = readFileSync(transcriptPath, 'utf-8').trim();
+    if (!content) {
+      return { userMessage: '', assistantMessage: '' };
+    }
+
+    const lines = content.split('\n').filter(line => line.trim());
+    let lastAssistantMessage = '';
+
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const line = lines[i];
+        if (!line.includes('"type":"assistant"')) {
+          continue;
+        }
+
+        const entry = JSON.parse(line);
+        if (entry.type === 'assistant' && entry.message?.content && Array.isArray(entry.message.content)) {
+          let text = '';
+          for (const block of entry.message.content) {
+            if (block.type === 'text') {
+              text += block.text;
+            }
+          }
+          text = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim();
+          if (text) {
+            lastAssistantMessage = text;
+            break;
+          }
+        }
+      } catch (parseError) {
+        continue;
+      }
+    }
+
+    return { userMessage: '', assistantMessage: lastAssistantMessage };
+  } catch (error) {
+    logger.failure('WORKER', `Failed to extract prior messages from transcript`, { transcriptPath }, error as Error);
+    return { userMessage: '', assistantMessage: '' };
+  }
+}
+
+/**
+ * Generate context for a project
+ */
+export async function generateContext(input?: ContextInput, useColors: boolean = false): Promise<string> {
+  const config = loadContextConfig();
+  const cwd = input?.cwd ?? process.cwd();
+  const project = cwd ? path.basename(cwd) : 'unknown-project';
+
+  let db: SessionStore | null = null;
+  try {
+    db = new SessionStore();
+  } catch (error: any) {
+    if (error.code === 'ERR_DLOPEN_FAILED') {
+      try {
+        unlinkSync(VERSION_MARKER_PATH);
+      } catch (unlinkError) {
+        // Marker might not exist
+      }
+      console.error('Native module rebuild needed - restart Claude Code to auto-fix');
+      return '';
+    }
+    throw error;
+  }
+
+  // Build SQL WHERE clause for observation types
+  const typeArray = Array.from(config.observationTypes);
+  const typePlaceholders = typeArray.map(() => '?').join(',');
+
+  // Build SQL WHERE clause for concepts
+  const conceptArray = Array.from(config.observationConcepts);
+  const conceptPlaceholders = conceptArray.map(() => '?').join(',');
+
+  // Get recent observations
+  const observations = db.db.prepare(`
+    SELECT
+      id, sdk_session_id, type, title, subtitle, narrative,
+      facts, concepts, files_read, files_modified, discovery_tokens,
+      created_at, created_at_epoch
+    FROM observations
+    WHERE project = ?
+      AND type IN (${typePlaceholders})
+      AND EXISTS (
+        SELECT 1 FROM json_each(concepts)
+        WHERE value IN (${conceptPlaceholders})
+      )
+    ORDER BY created_at_epoch DESC
+    LIMIT ?
+  `).all(project, ...typeArray, ...conceptArray, config.totalObservationCount) as Observation[];
+
+  // Get recent summaries
+  const recentSummaries = db.db.prepare(`
+    SELECT id, sdk_session_id, request, investigated, learned, completed, next_steps, created_at, created_at_epoch
+    FROM session_summaries
+    WHERE project = ?
+    ORDER BY created_at_epoch DESC
+    LIMIT ?
+  `).all(project, config.sessionCount + SUMMARY_LOOKAHEAD) as SessionSummary[];
+
+  // Retrieve prior session messages if enabled
+  let priorUserMessage = '';
+  let priorAssistantMessage = '';
+
+  if (config.showLastMessage && observations.length > 0) {
+    try {
+      const currentSessionId = input?.session_id;
+      const priorSessionObs = observations.find(obs => obs.sdk_session_id !== currentSessionId);
+
+      if (priorSessionObs) {
+        const priorSessionId = priorSessionObs.sdk_session_id;
+        const dashedCwd = cwdToDashed(cwd);
+        const transcriptPath = path.join(homedir(), '.claude', 'projects', dashedCwd, `${priorSessionId}.jsonl`);
+        const messages = extractPriorMessages(transcriptPath);
+        priorUserMessage = messages.userMessage;
+        priorAssistantMessage = messages.assistantMessage;
+      }
+    } catch (error) {
+      // Expected: Transcript file may not exist or be readable
+    }
+  }
+
+  // If we have neither observations nor summaries, show empty state
+  if (observations.length === 0 && recentSummaries.length === 0) {
+    db?.close();
+    if (useColors) {
+      return `\n${colors.bright}${colors.cyan}[${project}] recent context${colors.reset}\n${colors.gray}${'─'.repeat(60)}${colors.reset}\n\n${colors.dim}No previous sessions found for this project yet.${colors.reset}\n`;
+    }
+    return `# [${project}] recent context\n\nNo previous sessions found for this project yet.`;
+  }
+
+  const displaySummaries = recentSummaries.slice(0, config.sessionCount);
+  const timelineObs = observations;
+
+  // Build output
+  const output: string[] = [];
+
+  // Header
+  if (useColors) {
+    output.push('');
+    output.push(`${colors.bright}${colors.cyan}[${project}] recent context${colors.reset}`);
+    output.push(`${colors.gray}${'─'.repeat(60)}${colors.reset}`);
+    output.push('');
+  } else {
+    output.push(`# [${project}] recent context`);
+    output.push('');
+  }
+
+  // Chronological Timeline
+  if (timelineObs.length > 0) {
+    // Legend
+    if (useColors) {
+      output.push(`${colors.dim}Legend: 🎯 session-request | 🔴 bugfix | 🟣 feature | 🔄 refactor | ✅ change | 🔵 discovery | ⚖️  decision${colors.reset}`);
+    } else {
+      output.push(`**Legend:** 🎯 session-request | 🔴 bugfix | 🟣 feature | 🔄 refactor | ✅ change | 🔵 discovery | ⚖️  decision`);
+    }
+    output.push('');
+
+    // Column Key
+    if (useColors) {
+      output.push(`${colors.bright}💡 Column Key${colors.reset}`);
+      output.push(`${colors.dim}  Read: Tokens to read this observation (cost to learn it now)${colors.reset}`);
+      output.push(`${colors.dim}  Work: Tokens spent on work that produced this record (🔍 research, 🛠️ building, ⚖️  deciding)${colors.reset}`);
+    } else {
+      output.push(`💡 **Column Key**:`);
+      output.push(`- **Read**: Tokens to read this observation (cost to learn it now)`);
+      output.push(`- **Work**: Tokens spent on work that produced this record (🔍 research, 🛠️ building, ⚖️  deciding)`);
+    }
+    output.push('');
+
+    // Context Index Instructions
+    if (useColors) {
+      output.push(`${colors.dim}💡 Context Index: This semantic index (titles, types, files, tokens) is usually sufficient to understand past work.${colors.reset}`);
+      output.push('');
+      output.push(`${colors.dim}When you need implementation details, rationale, or debugging context:${colors.reset}`);
+      output.push(`${colors.dim}  - Use the mem-search skill to fetch full observations on-demand${colors.reset}`);
+      output.push(`${colors.dim}  - Critical types (🔴 bugfix, ⚖️ decision) often need detailed fetching${colors.reset}`);
+      output.push(`${colors.dim}  - Trust this index over re-reading code for past decisions and learnings${colors.reset}`);
+    } else {
+      output.push(`💡 **Context Index:** This semantic index (titles, types, files, tokens) is usually sufficient to understand past work.`);
+      output.push('');
+      output.push(`When you need implementation details, rationale, or debugging context:`);
+      output.push(`- Use the mem-search skill to fetch full observations on-demand`);
+      output.push(`- Critical types (🔴 bugfix, ⚖️ decision) often need detailed fetching`);
+      output.push(`- Trust this index over re-reading code for past decisions and learnings`);
+    }
+    output.push('');
+
+    // Context Economics
+    const totalObservations = observations.length;
+    const totalReadTokens = observations.reduce((sum, obs) => {
+      const obsSize = (obs.title?.length || 0) +
+                      (obs.subtitle?.length || 0) +
+                      (obs.narrative?.length || 0) +
+                      JSON.stringify(obs.facts || []).length;
+      return sum + Math.ceil(obsSize / CHARS_PER_TOKEN_ESTIMATE);
+    }, 0);
+    const totalDiscoveryTokens = observations.reduce((sum, obs) => sum + (obs.discovery_tokens || 0), 0);
+    const savings = totalDiscoveryTokens - totalReadTokens;
+    const savingsPercent = totalDiscoveryTokens > 0
+      ? Math.round((savings / totalDiscoveryTokens) * 100)
+      : 0;
+
+    const showContextEconomics = config.showReadTokens || config.showWorkTokens ||
+                                   config.showSavingsAmount || config.showSavingsPercent;
+
+    if (showContextEconomics) {
+      if (useColors) {
+        output.push(`${colors.bright}${colors.cyan}📊 Context Economics${colors.reset}`);
+        output.push(`${colors.dim}  Loading: ${totalObservations} observations (${totalReadTokens.toLocaleString()} tokens to read)${colors.reset}`);
+        output.push(`${colors.dim}  Work investment: ${totalDiscoveryTokens.toLocaleString()} tokens spent on research, building, and decisions${colors.reset}`);
+        if (totalDiscoveryTokens > 0 && (config.showSavingsAmount || config.showSavingsPercent)) {
+          let savingsLine = '  Your savings: ';
+          if (config.showSavingsAmount && config.showSavingsPercent) {
+            savingsLine += `${savings.toLocaleString()} tokens (${savingsPercent}% reduction from reuse)`;
+          } else if (config.showSavingsAmount) {
+            savingsLine += `${savings.toLocaleString()} tokens`;
+          } else {
+            savingsLine += `${savingsPercent}% reduction from reuse`;
+          }
+          output.push(`${colors.green}${savingsLine}${colors.reset}`);
+        }
+        output.push('');
+      } else {
+        output.push(`📊 **Context Economics**:`);
+        output.push(`- Loading: ${totalObservations} observations (${totalReadTokens.toLocaleString()} tokens to read)`);
+        output.push(`- Work investment: ${totalDiscoveryTokens.toLocaleString()} tokens spent on research, building, and decisions`);
+        if (totalDiscoveryTokens > 0 && (config.showSavingsAmount || config.showSavingsPercent)) {
+          let savingsLine = '- Your savings: ';
+          if (config.showSavingsAmount && config.showSavingsPercent) {
+            savingsLine += `${savings.toLocaleString()} tokens (${savingsPercent}% reduction from reuse)`;
+          } else if (config.showSavingsAmount) {
+            savingsLine += `${savings.toLocaleString()} tokens`;
+          } else {
+            savingsLine += `${savingsPercent}% reduction from reuse`;
+          }
+          output.push(savingsLine);
+        }
+        output.push('');
+      }
+    }
+
+    // Prepare summaries for timeline display
+    const mostRecentSummaryId = recentSummaries[0]?.id;
+
+    interface SummaryTimelineItem extends SessionSummary {
+      displayEpoch: number;
+      displayTime: string;
+      shouldShowLink: boolean;
+    }
+
+    const summariesForTimeline: SummaryTimelineItem[] = displaySummaries.map((summary, i) => {
+      const olderSummary = i === 0 ? null : recentSummaries[i + 1];
+      return {
+        ...summary,
+        displayEpoch: olderSummary ? olderSummary.created_at_epoch : summary.created_at_epoch,
+        displayTime: olderSummary ? olderSummary.created_at : summary.created_at,
+        shouldShowLink: summary.id !== mostRecentSummaryId
+      };
+    });
+
+    // Identify which observations should show full details
+    const fullObservationIds = new Set(
+      observations
+        .slice(0, config.fullObservationCount)
+        .map(obs => obs.id)
+    );
+
+    type TimelineItem =
+      | { type: 'observation'; data: Observation }
+      | { type: 'summary'; data: SummaryTimelineItem };
+
+    const timeline: TimelineItem[] = [
+      ...timelineObs.map(obs => ({ type: 'observation' as const, data: obs })),
+      ...summariesForTimeline.map(summary => ({ type: 'summary' as const, data: summary }))
+    ];
+
+    // Sort chronologically
+    timeline.sort((a, b) => {
+      const aEpoch = a.type === 'observation' ? a.data.created_at_epoch : a.data.displayEpoch;
+      const bEpoch = b.type === 'observation' ? b.data.created_at_epoch : b.data.displayEpoch;
+      return aEpoch - bEpoch;
+    });
+
+    // Group by day
+    const itemsByDay = new Map<string, TimelineItem[]>();
+    for (const item of timeline) {
+      const itemDate = item.type === 'observation' ? item.data.created_at : item.data.displayTime;
+      const day = formatDate(itemDate);
+      if (!itemsByDay.has(day)) {
+        itemsByDay.set(day, []);
+      }
+      itemsByDay.get(day)!.push(item);
+    }
+
+    // Sort days chronologically
+    const sortedDays = Array.from(itemsByDay.entries()).sort((a, b) => {
+      const aDate = new Date(a[0]).getTime();
+      const bDate = new Date(b[0]).getTime();
+      return aDate - bDate;
+    });
+
+    // Render each day's timeline
+    for (const [day, dayItems] of sortedDays) {
+      if (useColors) {
+        output.push(`${colors.bright}${colors.cyan}${day}${colors.reset}`);
+        output.push('');
+      } else {
+        output.push(`### ${day}`);
+        output.push('');
+      }
+
+      let currentFile: string | null = null;
+      let lastTime = '';
+      let tableOpen = false;
+
+      for (const item of dayItems) {
+        if (item.type === 'summary') {
+          if (tableOpen) {
+            output.push('');
+            tableOpen = false;
+            currentFile = null;
+            lastTime = '';
+          }
+
+          const summary = item.data;
+          const summaryTitle = `${summary.request || 'Session started'} (${formatDateTime(summary.displayTime)})`;
+          const link = summary.shouldShowLink ? `claude-mem://session-summary/${summary.id}` : '';
+
+          if (useColors) {
+            const linkPart = link ? `${colors.dim}[${link}]${colors.reset}` : '';
+            output.push(`🎯 ${colors.yellow}#S${summary.id}${colors.reset} ${summaryTitle} ${linkPart}`);
+          } else {
+            const linkPart = link ? ` [→](${link})` : '';
+            output.push(`**🎯 #S${summary.id}** ${summaryTitle}${linkPart}`);
+          }
+          output.push('');
+        } else {
+          const obs = item.data;
+          const files = parseJsonArray(obs.files_modified);
+          const file = (files.length > 0 && files[0]) ? toRelativePath(files[0], cwd) : 'General';
+
+          if (file !== currentFile) {
+            if (tableOpen) {
+              output.push('');
+            }
+
+            if (useColors) {
+              output.push(`${colors.dim}${file}${colors.reset}`);
+            } else {
+              output.push(`**${file}**`);
+            }
+
+            if (!useColors) {
+              output.push(`| ID | Time | T | Title | Read | Work |`);
+              output.push(`|----|------|---|-------|------|------|`);
+            }
+
+            currentFile = file;
+            tableOpen = true;
+            lastTime = '';
+          }
+
+          const time = formatTime(obs.created_at);
+          const title = obs.title || 'Untitled';
+          const icon = TYPE_ICON_MAP[obs.type as keyof typeof TYPE_ICON_MAP] || '•';
+
+          const obsSize = (obs.title?.length || 0) +
+                          (obs.subtitle?.length || 0) +
+                          (obs.narrative?.length || 0) +
+                          JSON.stringify(obs.facts || []).length;
+          const readTokens = Math.ceil(obsSize / CHARS_PER_TOKEN_ESTIMATE);
+          const discoveryTokens = obs.discovery_tokens || 0;
+          const workEmoji = TYPE_WORK_EMOJI_MAP[obs.type as keyof typeof TYPE_WORK_EMOJI_MAP] || '🔍';
+          const discoveryDisplay = discoveryTokens > 0 ? `${workEmoji} ${discoveryTokens.toLocaleString()}` : '-';
+
+          const showTime = time !== lastTime;
+          const timeDisplay = showTime ? time : '';
+          lastTime = time;
+
+          const shouldShowFull = fullObservationIds.has(obs.id);
+
+          if (shouldShowFull) {
+            const detailField = config.fullObservationField === 'narrative'
+              ? obs.narrative
+              : (obs.facts ? parseJsonArray(obs.facts).join('\n') : null);
+
+            if (useColors) {
+              const timePart = showTime ? `${colors.dim}${time}${colors.reset}` : ' '.repeat(time.length);
+              const readPart = (config.showReadTokens && readTokens > 0) ? `${colors.dim}(~${readTokens}t)${colors.reset}` : '';
+              const discoveryPart = (config.showWorkTokens && discoveryTokens > 0) ? `${colors.dim}(${workEmoji} ${discoveryTokens.toLocaleString()}t)${colors.reset}` : '';
+
+              output.push(`  ${colors.dim}#${obs.id}${colors.reset}  ${timePart}  ${icon}  ${colors.bright}${title}${colors.reset}`);
+              if (detailField) {
+                output.push(`    ${colors.dim}${detailField}${colors.reset}`);
+              }
+              if (readPart || discoveryPart) {
+                output.push(`    ${readPart} ${discoveryPart}`);
+              }
+              output.push('');
+            } else {
+              if (tableOpen) {
+                output.push('');
+                tableOpen = false;
+              }
+
+              output.push(`**#${obs.id}** ${timeDisplay || '″'} ${icon} **${title}**`);
+              if (detailField) {
+                output.push('');
+                output.push(detailField);
+                output.push('');
+              }
+              const tokenParts: string[] = [];
+              if (config.showReadTokens) {
+                tokenParts.push(`Read: ~${readTokens}`);
+              }
+              if (config.showWorkTokens) {
+                tokenParts.push(`Work: ${discoveryDisplay}`);
+              }
+              if (tokenParts.length > 0) {
+                output.push(tokenParts.join(', '));
+              }
+              output.push('');
+              currentFile = null;
+            }
+          } else {
+            if (useColors) {
+              const timePart = showTime ? `${colors.dim}${time}${colors.reset}` : ' '.repeat(time.length);
+              const readPart = (config.showReadTokens && readTokens > 0) ? `${colors.dim}(~${readTokens}t)${colors.reset}` : '';
+              const discoveryPart = (config.showWorkTokens && discoveryTokens > 0) ? `${colors.dim}(${workEmoji} ${discoveryTokens.toLocaleString()}t)${colors.reset}` : '';
+              output.push(`  ${colors.dim}#${obs.id}${colors.reset}  ${timePart}  ${icon}  ${title} ${readPart} ${discoveryPart}`);
+            } else {
+              const readCol = config.showReadTokens ? `~${readTokens}` : '';
+              const workCol = config.showWorkTokens ? discoveryDisplay : '';
+              output.push(`| #${obs.id} | ${timeDisplay || '″'} | ${icon} | ${title} | ${readCol} | ${workCol} |`);
+            }
+          }
+        }
+      }
+
+      if (tableOpen) {
+        output.push('');
+      }
+    }
+
+    // Add full summary details for most recent session
+    const mostRecentSummary = recentSummaries[0];
+    const mostRecentObservation = observations[0];
+
+    const shouldShowSummary = config.showLastSummary &&
+      mostRecentSummary &&
+      (mostRecentSummary.investigated || mostRecentSummary.learned || mostRecentSummary.completed || mostRecentSummary.next_steps) &&
+      (!mostRecentObservation || mostRecentSummary.created_at_epoch > mostRecentObservation.created_at_epoch);
+
+    if (shouldShowSummary) {
+      output.push(...renderSummaryField('Investigated', mostRecentSummary.investigated, colors.blue, useColors));
+      output.push(...renderSummaryField('Learned', mostRecentSummary.learned, colors.yellow, useColors));
+      output.push(...renderSummaryField('Completed', mostRecentSummary.completed, colors.green, useColors));
+      output.push(...renderSummaryField('Next Steps', mostRecentSummary.next_steps, colors.magenta, useColors));
+    }
+
+    // Previously section
+    if (priorAssistantMessage) {
+      output.push('');
+      output.push('---');
+      output.push('');
+      if (useColors) {
+        output.push(`${colors.bright}${colors.magenta}📋 Previously${colors.reset}`);
+        output.push('');
+        output.push(`${colors.dim}A: ${priorAssistantMessage}${colors.reset}`);
+      } else {
+        output.push(`**📋 Previously**`);
+        output.push('');
+        output.push(`A: ${priorAssistantMessage}`);
+      }
+      output.push('');
+    }
+
+    // Footer
+    if (showContextEconomics && totalDiscoveryTokens > 0 && savings > 0) {
+      const workTokensK = Math.round(totalDiscoveryTokens / 1000);
+      output.push('');
+      if (useColors) {
+        output.push(`${colors.dim}💰 Access ${workTokensK}k tokens of past research & decisions for just ${totalReadTokens.toLocaleString()}t. Use the mem-search skill to access memories by ID instead of re-reading files.${colors.reset}`);
+      } else {
+        output.push(`💰 Access ${workTokensK}k tokens of past research & decisions for just ${totalReadTokens.toLocaleString()}t. Use the mem-search skill to access memories by ID instead of re-reading files.`);
+      }
+    }
+  }
+
+  db?.close();
+  return output.join('\n').trimEnd();
+}
@@ -0,0 +1,263 @@
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'fs';
+import { createWriteStream } from 'fs';
+import { join } from 'path';
+import { spawn, spawnSync } from 'child_process';
+import { homedir } from 'os';
+import { DATA_DIR } from '../../shared/paths.js';
+
+const PID_FILE = join(DATA_DIR, 'worker.pid');
+const LOG_DIR = join(DATA_DIR, 'logs');
+const MARKETPLACE_ROOT = join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');
+
+// Timeout constants
+const PROCESS_STOP_TIMEOUT_MS = 5000;
+const HEALTH_CHECK_TIMEOUT_MS = 10000;
+const HEALTH_CHECK_INTERVAL_MS = 200;
+const HEALTH_CHECK_FETCH_TIMEOUT_MS = 1000;
+const PROCESS_EXIT_CHECK_INTERVAL_MS = 100;
+
+interface PidInfo {
+  pid: number;
+  port: number;
+  startedAt: string;
+  version: string;
+}
+
+export class ProcessManager {
+  static async start(port: number): Promise<{ success: boolean; pid?: number; error?: string }> {
+    // Validate port range
+    if (isNaN(port) || port < 1024 || port > 65535) {
+      return {
+        success: false,
+        error: `Invalid port ${port}. Must be between 1024 and 65535`
+      };
+    }
+
+    // Check if already running
+    if (await this.isRunning()) {
+      const info = this.getPidInfo();
+      return { success: true, pid: info?.pid };
+    }
+
+    // Ensure log directory exists
+    mkdirSync(LOG_DIR, { recursive: true });
+
+    // Get worker script path
+    const workerScript = join(MARKETPLACE_ROOT, 'plugin', 'scripts', 'worker-service.cjs');
+
+    if (!existsSync(workerScript)) {
+      return { success: false, error: `Worker script not found at ${workerScript}` };
+    }
+
+    const logFile = this.getLogFilePath();
+
+    // Use Bun on all platforms
+    return this.startWithBun(workerScript, logFile, port);
+  }
+
+  private static isBunAvailable(): boolean {
+    try {
+      const result = spawnSync('bun', ['--version'], { stdio: 'pipe', timeout: 5000 });
+      return result.status === 0;
+    } catch {
+      return false;
+    }
+  }
+
+  private static async startWithBun(script: string, logFile: string, port: number): Promise<{ success: boolean; pid?: number; error?: string }> {
+    if (!this.isBunAvailable()) {
+      return {
+        success: false,
+        error: 'Bun is required but not found in PATH. Install from https://bun.sh'
+      };
+    }
+
+    try {
+      const isWindows = process.platform === 'win32';
+
+      const child = spawn('bun', [script], {
+        detached: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, CLAUDE_MEM_WORKER_PORT: String(port) },
+        cwd: MARKETPLACE_ROOT,
+        // Hide console window on Windows
+        ...(isWindows && { windowsHide: true })
+      });
+
+      // Write logs
+      const logStream = createWriteStream(logFile, { flags: 'a' });
+      child.stdout?.pipe(logStream);
+      child.stderr?.pipe(logStream);
+
+      child.unref();
+
+      if (!child.pid) {
+        return { success: false, error: 'Failed to get PID from spawned process' };
+      }
+
+      // Write PID file
+      this.writePidFile({
+        pid: child.pid,
+        port,
+        startedAt: new Date().toISOString(),
+        version: process.env.npm_package_version || 'unknown'
+      });
+
+      // Wait for health
+      return this.waitForHealth(child.pid, port);
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+
+  static async stop(timeout: number = PROCESS_STOP_TIMEOUT_MS): Promise<boolean> {
+    const info = this.getPidInfo();
+    if (!info) return true;
+
+    try {
+      process.kill(info.pid, 'SIGTERM');
+      await this.waitForExit(info.pid, timeout);
+    } catch {
+      try {
+        process.kill(info.pid, 'SIGKILL');
+      } catch {
+        // Process already dead
+      }
+    }
+
+    this.removePidFile();
+    return true;
+  }
+
+  static async restart(port: number): Promise<{ success: boolean; pid?: number; error?: string }> {
+    await this.stop();
+    return this.start(port);
+  }
+
+  static async status(): Promise<{ running: boolean; pid?: number; port?: number; uptime?: string }> {
+    const info = this.getPidInfo();
+    if (!info) return { running: false };
+
+    const running = this.isProcessAlive(info.pid);
+    return {
+      running,
+      pid: running ? info.pid : undefined,
+      port: running ? info.port : undefined,
+      uptime: running ? this.formatUptime(info.startedAt) : undefined
+    };
+  }
+
+  static async isRunning(): Promise<boolean> {
+    const info = this.getPidInfo();
+    if (!info) return false;
+    const alive = this.isProcessAlive(info.pid);
+    if (!alive) {
+      this.removePidFile(); // Clean up stale PID file
+    }
+    return alive;
+  }
+
+  // Helper methods
+  private static getPidInfo(): PidInfo | null {
+    try {
+      if (!existsSync(PID_FILE)) return null;
+      const content = readFileSync(PID_FILE, 'utf-8');
+      const parsed = JSON.parse(content);
+      // Validate required fields have correct types
+      if (typeof parsed.pid !== 'number' || typeof parsed.port !== 'number') {
+        return null;
+      }
+      return parsed as PidInfo;
+    } catch {
+      return null;
+    }
+  }
+
+  private static writePidFile(info: PidInfo): void {
+    mkdirSync(DATA_DIR, { recursive: true });
+    writeFileSync(PID_FILE, JSON.stringify(info, null, 2));
+  }
+
+  private static removePidFile(): void {
+    try {
+      if (existsSync(PID_FILE)) {
+        unlinkSync(PID_FILE);
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  private static isProcessAlive(pid: number): boolean {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private static async waitForHealth(pid: number, port: number, timeoutMs: number = HEALTH_CHECK_TIMEOUT_MS): Promise<{ success: boolean; pid?: number; error?: string }> {
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeoutMs) {
+      // Check if process is still alive
+      if (!this.isProcessAlive(pid)) {
+        return { success: false, error: 'Process died during startup' };
+      }
+
+      // Try health check
+      try {
+        const response = await fetch(`http://127.0.0.1:${port}/health`, {
+          signal: AbortSignal.timeout(HEALTH_CHECK_FETCH_TIMEOUT_MS)
+        });
+        if (response.ok) {
+          return { success: true, pid };
+        }
+      } catch {
+        // Not ready yet
+      }
+
+      await new Promise(resolve => setTimeout(resolve, HEALTH_CHECK_INTERVAL_MS));
+    }
+
+    return { success: false, error: 'Health check timed out' };
+  }
+
+  private static async waitForExit(pid: number, timeout: number): Promise<void> {
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeout) {
+      if (!this.isProcessAlive(pid)) {
+        return;
+      }
+      await new Promise(resolve => setTimeout(resolve, PROCESS_EXIT_CHECK_INTERVAL_MS));
+    }
+
+    throw new Error('Process did not exit within timeout');
+  }
+
+  private static getLogFilePath(): string {
+    const date = new Date().toISOString().slice(0, 10);
+    return join(LOG_DIR, `worker-${date}.log`);
+  }
+
+  private static formatUptime(startedAt: string): string {
+    const startTime = new Date(startedAt).getTime();
+    const now = Date.now();
+    const diffMs = now - startTime;
+
+    const seconds = Math.floor(diffMs / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+
+    if (days > 0) return `${days}d ${hours % 24}h`;
+    if (hours > 0) return `${hours}h ${minutes % 60}m`;
+    if (minutes > 0) return `${minutes}m ${seconds % 60}s`;
+    return `${seconds}s`;
+  }
+}
@@ -1,8 +1,9 @@
-import { Database as BunDatabase } from 'bun:sqlite';
+import { Database } from 'bun:sqlite';
 import { DATA_DIR, DB_PATH, ensureDir } from '../../shared/paths.js';

-// Type alias for better-sqlite3 compatibility
-type Database = BunDatabase;
+// SQLite configuration constants
+const SQLITE_MMAP_SIZE_BYTES = 256 * 1024 * 1024; // 256MB
+const SQLITE_CACHE_SIZE_PAGES = 10_000;

 export interface Migration {
  version: number;
@@ -47,15 +48,15 @@ export class DatabaseManager {
    // Ensure the data directory exists
    ensureDir(DATA_DIR);

-    this.db = new BunDatabase(DB_PATH, { create: true, readwrite: true });
+    this.db = new Database(DB_PATH, { create: true, readwrite: true });

    // Apply optimized SQLite settings
    this.db.run('PRAGMA journal_mode = WAL');
    this.db.run('PRAGMA synchronous = NORMAL');
    this.db.run('PRAGMA foreign_keys = ON');
    this.db.run('PRAGMA temp_store = memory');
-    this.db.run('PRAGMA mmap_size = 268435456'); // 256MB
-    this.db.run('PRAGMA cache_size = 10000');
+    this.db.run(`PRAGMA mmap_size = ${SQLITE_MMAP_SIZE_BYTES}`);
+    this.db.run(`PRAGMA cache_size = ${SQLITE_CACHE_SIZE_PAGES}`);

    // Initialize schema_versions table
    this.initializeSchemaVersions();
@@ -171,4 +172,4 @@ export async function initializeDatabase(): Promise<Database> {
  return await manager.initialize();
 }

-export { BunDatabase as Database };
+export { Database };
@@ -1,4 +1,5 @@
-import Database from 'better-sqlite3';
+import { Database } from 'bun:sqlite';
+import { TableNameRow } from '../../types/database.js';
 import { DATA_DIR, DB_PATH, ensureDir } from '../../shared/paths.js';
 import {
  ObservationSearchResult,
@@ -17,7 +18,7 @@ import {
 * Vector search is handled by ChromaDB - this class only supports filtering without query text
 */
 export class SessionSearch {
-  private db: Database.Database;
+  private db: Database;

  constructor(dbPath?: string) {
    if (!dbPath) {
@@ -25,7 +26,7 @@ export class SessionSearch {
      dbPath = DB_PATH;
    }
    this.db = new Database(dbPath);
-    this.db.pragma('journal_mode = WAL');
+    this.db.run('PRAGMA journal_mode = WAL');

    // Ensure FTS tables exist
    this.ensureFTSTables();
@@ -48,8 +49,8 @@ export class SessionSearch {
  private ensureFTSTables(): void {
    try {
      // Check if FTS tables already exist
-      const tables = this.db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE '%_fts'").all() as any[];
-      const hasFTS = tables.some((t: any) => t.name === 'observations_fts' || t.name === 'session_summaries_fts');
+      const tables = this.db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE '%_fts'").all() as TableNameRow[];
+      const hasFTS = tables.some(t => t.name === 'observations_fts' || t.name === 'session_summaries_fts');

      if (hasFTS) {
        // Already migrated
@@ -59,7 +60,7 @@ export class SessionSearch {
      console.error('[SessionSearch] Creating FTS5 tables...');

      // Create observations_fts virtual table
-      this.db.exec(`
+      this.db.run(`
        CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
          title,
          subtitle,
@@ -73,14 +74,14 @@ export class SessionSearch {
      `);

      // Populate with existing data
-      this.db.exec(`
+      this.db.run(`
        INSERT INTO observations_fts(rowid, title, subtitle, narrative, text, facts, concepts)
        SELECT id, title, subtitle, narrative, text, facts, concepts
        FROM observations;
      `);

      // Create triggers for observations
-      this.db.exec(`
+      this.db.run(`
        CREATE TRIGGER IF NOT EXISTS observations_ai AFTER INSERT ON observations BEGIN
          INSERT INTO observations_fts(rowid, title, subtitle, narrative, text, facts, concepts)
          VALUES (new.id, new.title, new.subtitle, new.narrative, new.text, new.facts, new.concepts);
@@ -100,7 +101,7 @@ export class SessionSearch {
      `);

      // Create session_summaries_fts virtual table
-      this.db.exec(`
+      this.db.run(`
        CREATE VIRTUAL TABLE IF NOT EXISTS session_summaries_fts USING fts5(
          request,
          investigated,
@@ -114,14 +115,14 @@ export class SessionSearch {
      `);

      // Populate with existing data
-      this.db.exec(`
+      this.db.run(`
        INSERT INTO session_summaries_fts(rowid, request, investigated, learned, completed, next_steps, notes)
        SELECT id, request, investigated, learned, completed, next_steps, notes
        FROM session_summaries;
      `);

      // Create triggers for session_summaries
-      this.db.exec(`
+      this.db.run(`
        CREATE TRIGGER IF NOT EXISTS session_summaries_ai AFTER INSERT ON session_summaries BEGIN
          INSERT INTO session_summaries_fts(rowid, request, investigated, learned, completed, next_steps, notes)
          VALUES (new.id, new.request, new.investigated, new.learned, new.completed, new.next_steps, new.notes);
@@ -1,22 +1,33 @@
-import Database from 'better-sqlite3';
+import { Database } from 'bun:sqlite';
 import { DATA_DIR, DB_PATH, ensureDir } from '../../shared/paths.js';
 import { logger } from '../../utils/logger.js';
+import {
+  TableColumnInfo,
+  IndexInfo,
+  TableNameRow,
+  SchemaVersion,
+  SdkSessionRecord,
+  ObservationRecord,
+  SessionSummaryRecord,
+  UserPromptRecord,
+  LatestPromptResult
+} from '../../types/database.js';

 /**
 * Session data store for SDK sessions, observations, and summaries
 * Provides simple, synchronous CRUD operations for session-based memory
 */
 export class SessionStore {
-  public db: Database.Database;
+  public db: Database;

  constructor() {
    ensureDir(DATA_DIR);
    this.db = new Database(DB_PATH);

    // Ensure optimized settings
-    this.db.pragma('journal_mode = WAL');
-    this.db.pragma('synchronous = NORMAL');
-    this.db.pragma('foreign_keys = ON');
+    this.db.run('PRAGMA journal_mode = WAL');
+    this.db.run('PRAGMA synchronous = NORMAL');
+    this.db.run('PRAGMA foreign_keys = ON');

    // Initialize schema if needed (fresh database)
    this.initializeSchema();
@@ -38,7 +49,7 @@ export class SessionStore {
  private initializeSchema(): void {
    try {
      // Create schema_versions table if it doesn't exist
-      this.db.exec(`
+      this.db.run(`
        CREATE TABLE IF NOT EXISTS schema_versions (
          id INTEGER PRIMARY KEY,
          version INTEGER UNIQUE NOT NULL,
@@ -47,7 +58,7 @@ export class SessionStore {
      `);

      // Get applied migrations
-      const appliedVersions = this.db.prepare('SELECT version FROM schema_versions ORDER BY version').all() as Array<{version: number}>;
+      const appliedVersions = this.db.prepare('SELECT version FROM schema_versions ORDER BY version').all() as SchemaVersion[];
      const maxApplied = appliedVersions.length > 0 ? Math.max(...appliedVersions.map(v => v.version)) : 0;

      // Only run migration004 if no migrations have been applied
@@ -56,7 +67,7 @@ export class SessionStore {
        console.error('[SessionStore] Initializing fresh database with migration004...');

        // Migration004: SDK agent architecture tables
-        this.db.exec(`
+        this.db.run(`
          CREATE TABLE IF NOT EXISTS sdk_sessions (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            claude_session_id TEXT UNIQUE NOT NULL,
@@ -131,15 +142,15 @@ export class SessionStore {
  private ensureWorkerPortColumn(): void {
    try {
      // Check if migration already applied
-      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(5) as {version: number} | undefined;
+      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(5) as SchemaVersion | undefined;
      if (applied) return;

      // Check if column exists
-      const tableInfo = this.db.pragma('table_info(sdk_sessions)');
-      const hasWorkerPort = (tableInfo as any[]).some((col: any) => col.name === 'worker_port');
+      const tableInfo = this.db.query('PRAGMA table_info(sdk_sessions)').all() as TableColumnInfo[];
+      const hasWorkerPort = tableInfo.some(col => col.name === 'worker_port');

      if (!hasWorkerPort) {
-        this.db.exec('ALTER TABLE sdk_sessions ADD COLUMN worker_port INTEGER');
+        this.db.run('ALTER TABLE sdk_sessions ADD COLUMN worker_port INTEGER');
        console.error('[SessionStore] Added worker_port column to sdk_sessions table');
      }

@@ -156,33 +167,33 @@ export class SessionStore {
  private ensurePromptTrackingColumns(): void {
    try {
      // Check if migration already applied
-      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(6) as {version: number} | undefined;
+      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(6) as SchemaVersion | undefined;
      if (applied) return;

      // Check sdk_sessions for prompt_counter
-      const sessionsInfo = this.db.pragma('table_info(sdk_sessions)');
-      const hasPromptCounter = (sessionsInfo as any[]).some((col: any) => col.name === 'prompt_counter');
+      const sessionsInfo = this.db.query('PRAGMA table_info(sdk_sessions)').all() as TableColumnInfo[];
+      const hasPromptCounter = sessionsInfo.some(col => col.name === 'prompt_counter');

      if (!hasPromptCounter) {
-        this.db.exec('ALTER TABLE sdk_sessions ADD COLUMN prompt_counter INTEGER DEFAULT 0');
+        this.db.run('ALTER TABLE sdk_sessions ADD COLUMN prompt_counter INTEGER DEFAULT 0');
        console.error('[SessionStore] Added prompt_counter column to sdk_sessions table');
      }

      // Check observations for prompt_number
-      const observationsInfo = this.db.pragma('table_info(observations)');
-      const obsHasPromptNumber = (observationsInfo as any[]).some((col: any) => col.name === 'prompt_number');
+      const observationsInfo = this.db.query('PRAGMA table_info(observations)').all() as TableColumnInfo[];
+      const obsHasPromptNumber = observationsInfo.some(col => col.name === 'prompt_number');

      if (!obsHasPromptNumber) {
-        this.db.exec('ALTER TABLE observations ADD COLUMN prompt_number INTEGER');
+        this.db.run('ALTER TABLE observations ADD COLUMN prompt_number INTEGER');
        console.error('[SessionStore] Added prompt_number column to observations table');
      }

      // Check session_summaries for prompt_number
-      const summariesInfo = this.db.pragma('table_info(session_summaries)');
-      const sumHasPromptNumber = (summariesInfo as any[]).some((col: any) => col.name === 'prompt_number');
+      const summariesInfo = this.db.query('PRAGMA table_info(session_summaries)').all() as TableColumnInfo[];
+      const sumHasPromptNumber = summariesInfo.some(col => col.name === 'prompt_number');

      if (!sumHasPromptNumber) {
-        this.db.exec('ALTER TABLE session_summaries ADD COLUMN prompt_number INTEGER');
+        this.db.run('ALTER TABLE session_summaries ADD COLUMN prompt_number INTEGER');
        console.error('[SessionStore] Added prompt_number column to session_summaries table');
      }

@@ -199,12 +210,12 @@ export class SessionStore {
  private removeSessionSummariesUniqueConstraint(): void {
    try {
      // Check if migration already applied
-      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(7) as {version: number} | undefined;
+      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(7) as SchemaVersion | undefined;
      if (applied) return;

      // Check if UNIQUE constraint exists
-      const summariesIndexes = this.db.pragma('index_list(session_summaries)');
-      const hasUniqueConstraint = (summariesIndexes as any[]).some((idx: any) => idx.unique === 1);
+      const summariesIndexes = this.db.query('PRAGMA index_list(session_summaries)').all() as IndexInfo[];
+      const hasUniqueConstraint = summariesIndexes.some(idx => idx.unique === 1);

      if (!hasUniqueConstraint) {
        // Already migrated (no constraint exists)
@@ -215,11 +226,11 @@ export class SessionStore {
      console.error('[SessionStore] Removing UNIQUE constraint from session_summaries.sdk_session_id...');

      // Begin transaction
-      this.db.exec('BEGIN TRANSACTION');
+      this.db.run('BEGIN TRANSACTION');

      try {
        // Create new table without UNIQUE constraint
-        this.db.exec(`
+        this.db.run(`
          CREATE TABLE session_summaries_new (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            sdk_session_id TEXT NOT NULL,
@@ -240,7 +251,7 @@ export class SessionStore {
        `);

        // Copy data from old table
-        this.db.exec(`
+        this.db.run(`
          INSERT INTO session_summaries_new
          SELECT id, sdk_session_id, project, request, investigated, learned,
                 completed, next_steps, files_read, files_edited, notes,
@@ -249,20 +260,20 @@ export class SessionStore {
        `);

        // Drop old table
-        this.db.exec('DROP TABLE session_summaries');
+        this.db.run('DROP TABLE session_summaries');

        // Rename new table
-        this.db.exec('ALTER TABLE session_summaries_new RENAME TO session_summaries');
+        this.db.run('ALTER TABLE session_summaries_new RENAME TO session_summaries');

        // Recreate indexes
-        this.db.exec(`
+        this.db.run(`
          CREATE INDEX idx_session_summaries_sdk_session ON session_summaries(sdk_session_id);
          CREATE INDEX idx_session_summaries_project ON session_summaries(project);
          CREATE INDEX idx_session_summaries_created ON session_summaries(created_at_epoch DESC);
        `);

        // Commit transaction
-        this.db.exec('COMMIT');
+        this.db.run('COMMIT');

        // Record migration
        this.db.prepare('INSERT OR IGNORE INTO schema_versions (version, applied_at) VALUES (?, ?)').run(7, new Date().toISOString());
@@ -270,7 +281,7 @@ export class SessionStore {
        console.error('[SessionStore] Successfully removed UNIQUE constraint from session_summaries.sdk_session_id');
      } catch (error: any) {
        // Rollback on error
-        this.db.exec('ROLLBACK');
+        this.db.run('ROLLBACK');
        throw error;
      }
    } catch (error: any) {
@@ -284,12 +295,12 @@ export class SessionStore {
  private addObservationHierarchicalFields(): void {
    try {
      // Check if migration already applied
-      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(8) as {version: number} | undefined;
+      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(8) as SchemaVersion | undefined;
      if (applied) return;

      // Check if new fields already exist
-      const tableInfo = this.db.pragma('table_info(observations)');
-      const hasTitle = (tableInfo as any[]).some((col: any) => col.name === 'title');
+      const tableInfo = this.db.query('PRAGMA table_info(observations)').all() as TableColumnInfo[];
+      const hasTitle = tableInfo.some(col => col.name === 'title');

      if (hasTitle) {
        // Already migrated
@@ -300,7 +311,7 @@ export class SessionStore {
      console.error('[SessionStore] Adding hierarchical fields to observations table...');

      // Add new columns
-      this.db.exec(`
+      this.db.run(`
        ALTER TABLE observations ADD COLUMN title TEXT;
        ALTER TABLE observations ADD COLUMN subtitle TEXT;
        ALTER TABLE observations ADD COLUMN facts TEXT;
@@ -326,12 +337,12 @@ export class SessionStore {
  private makeObservationsTextNullable(): void {
    try {
      // Check if migration already applied
-      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(9) as {version: number} | undefined;
+      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(9) as SchemaVersion | undefined;
      if (applied) return;

      // Check if text column is already nullable
-      const tableInfo = this.db.pragma('table_info(observations)');
-      const textColumn = (tableInfo as any[]).find((col: any) => col.name === 'text');
+      const tableInfo = this.db.query('PRAGMA table_info(observations)').all() as TableColumnInfo[];
+      const textColumn = tableInfo.find(col => col.name === 'text');

      if (!textColumn || textColumn.notnull === 0) {
        // Already migrated or text column doesn't exist
@@ -342,11 +353,11 @@ export class SessionStore {
      console.error('[SessionStore] Making observations.text nullable...');

      // Begin transaction
-      this.db.exec('BEGIN TRANSACTION');
+      this.db.run('BEGIN TRANSACTION');

      try {
        // Create new table with text as nullable
-        this.db.exec(`
+        this.db.run(`
          CREATE TABLE observations_new (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            sdk_session_id TEXT NOT NULL,
@@ -368,7 +379,7 @@ export class SessionStore {
        `);

        // Copy data from old table (all existing columns)
-        this.db.exec(`
+        this.db.run(`
          INSERT INTO observations_new
          SELECT id, sdk_session_id, project, text, type, title, subtitle, facts,
                 narrative, concepts, files_read, files_modified, prompt_number,
@@ -377,13 +388,13 @@ export class SessionStore {
        `);

        // Drop old table
-        this.db.exec('DROP TABLE observations');
+        this.db.run('DROP TABLE observations');

        // Rename new table
-        this.db.exec('ALTER TABLE observations_new RENAME TO observations');
+        this.db.run('ALTER TABLE observations_new RENAME TO observations');

        // Recreate indexes
-        this.db.exec(`
+        this.db.run(`
          CREATE INDEX idx_observations_sdk_session ON observations(sdk_session_id);
          CREATE INDEX idx_observations_project ON observations(project);
          CREATE INDEX idx_observations_type ON observations(type);
@@ -391,7 +402,7 @@ export class SessionStore {
        `);

        // Commit transaction
-        this.db.exec('COMMIT');
+        this.db.run('COMMIT');

        // Record migration
        this.db.prepare('INSERT OR IGNORE INTO schema_versions (version, applied_at) VALUES (?, ?)').run(9, new Date().toISOString());
@@ -399,7 +410,7 @@ export class SessionStore {
        console.error('[SessionStore] Successfully made observations.text nullable');
      } catch (error: any) {
        // Rollback on error
-        this.db.exec('ROLLBACK');
+        this.db.run('ROLLBACK');
        throw error;
      }
    } catch (error: any) {
@@ -413,12 +424,12 @@ export class SessionStore {
  private createUserPromptsTable(): void {
    try {
      // Check if migration already applied
-      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(10) as {version: number} | undefined;
+      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(10) as SchemaVersion | undefined;
      if (applied) return;

      // Check if table already exists
-      const tableInfo = this.db.pragma('table_info(user_prompts)');
-      if ((tableInfo as any[]).length > 0) {
+      const tableInfo = this.db.query('PRAGMA table_info(user_prompts)').all() as TableColumnInfo[];
+      if (tableInfo.length > 0) {
        // Already migrated
        this.db.prepare('INSERT OR IGNORE INTO schema_versions (version, applied_at) VALUES (?, ?)').run(10, new Date().toISOString());
        return;
@@ -427,11 +438,11 @@ export class SessionStore {
      console.error('[SessionStore] Creating user_prompts table with FTS5 support...');

      // Begin transaction
-      this.db.exec('BEGIN TRANSACTION');
+      this.db.run('BEGIN TRANSACTION');

      try {
        // Create main table (using claude_session_id since sdk_session_id is set asynchronously by worker)
-        this.db.exec(`
+        this.db.run(`
          CREATE TABLE user_prompts (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            claude_session_id TEXT NOT NULL,
@@ -449,7 +460,7 @@ export class SessionStore {
        `);

        // Create FTS5 virtual table
-        this.db.exec(`
+        this.db.run(`
          CREATE VIRTUAL TABLE user_prompts_fts USING fts5(
            prompt_text,
            content='user_prompts',
@@ -458,7 +469,7 @@ export class SessionStore {
        `);

        // Create triggers to sync FTS5
-        this.db.exec(`
+        this.db.run(`
          CREATE TRIGGER user_prompts_ai AFTER INSERT ON user_prompts BEGIN
            INSERT INTO user_prompts_fts(rowid, prompt_text)
            VALUES (new.id, new.prompt_text);
@@ -478,7 +489,7 @@ export class SessionStore {
        `);

        // Commit transaction
-        this.db.exec('COMMIT');
+        this.db.run('COMMIT');

        // Record migration
        this.db.prepare('INSERT OR IGNORE INTO schema_versions (version, applied_at) VALUES (?, ?)').run(10, new Date().toISOString());
@@ -486,7 +497,7 @@ export class SessionStore {
        console.error('[SessionStore] Successfully created user_prompts table with FTS5 support');
      } catch (error: any) {
        // Rollback on error
-        this.db.exec('ROLLBACK');
+        this.db.run('ROLLBACK');
        throw error;
      }
    } catch (error: any) {
@@ -502,24 +513,24 @@ export class SessionStore {
  private ensureDiscoveryTokensColumn(): void {
    try {
      // Check if migration already applied to avoid unnecessary re-runs
-      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(11) as {version: number} | undefined;
+      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(11) as SchemaVersion | undefined;
      if (applied) return;

      // Check if discovery_tokens column exists in observations table
-      const observationsInfo = this.db.pragma('table_info(observations)');
-      const obsHasDiscoveryTokens = (observationsInfo as any[]).some((col: any) => col.name === 'discovery_tokens');
+      const observationsInfo = this.db.query('PRAGMA table_info(observations)').all() as TableColumnInfo[];
+      const obsHasDiscoveryTokens = observationsInfo.some(col => col.name === 'discovery_tokens');

      if (!obsHasDiscoveryTokens) {
-        this.db.exec('ALTER TABLE observations ADD COLUMN discovery_tokens INTEGER DEFAULT 0');
+        this.db.run('ALTER TABLE observations ADD COLUMN discovery_tokens INTEGER DEFAULT 0');
        console.error('[SessionStore] Added discovery_tokens column to observations table');
      }

      // Check if discovery_tokens column exists in session_summaries table
-      const summariesInfo = this.db.pragma('table_info(session_summaries)');
-      const sumHasDiscoveryTokens = (summariesInfo as any[]).some((col: any) => col.name === 'discovery_tokens');
+      const summariesInfo = this.db.query('PRAGMA table_info(session_summaries)').all() as TableColumnInfo[];
+      const sumHasDiscoveryTokens = summariesInfo.some(col => col.name === 'discovery_tokens');

      if (!sumHasDiscoveryTokens) {
-        this.db.exec('ALTER TABLE session_summaries ADD COLUMN discovery_tokens INTEGER DEFAULT 0');
+        this.db.run('ALTER TABLE session_summaries ADD COLUMN discovery_tokens INTEGER DEFAULT 0');
        console.error('[SessionStore] Added discovery_tokens column to session_summaries table');
      }

@@ -556,7 +567,7 @@ export class SessionStore {
      LIMIT ?
    `);

-    return stmt.all(project, limit) as any[];
+    return stmt.all(project, limit);
  }

  /**
@@ -581,7 +592,7 @@ export class SessionStore {
      LIMIT ?
    `);

-    return stmt.all(project, limit) as any[];
+    return stmt.all(project, limit);
  }

  /**
@@ -601,7 +612,7 @@ export class SessionStore {
      LIMIT ?
    `);

-    return stmt.all(project, limit) as any[];
+    return stmt.all(project, limit);
  }

  /**
@@ -625,7 +636,7 @@ export class SessionStore {
      LIMIT ?
    `);

-    return stmt.all(limit) as any[];
+    return stmt.all(limit);
  }

  /**
@@ -655,7 +666,7 @@ export class SessionStore {
      LIMIT ?
    `);

-    return stmt.all(limit) as any[];
+    return stmt.all(limit);
  }

  /**
@@ -685,7 +696,7 @@ export class SessionStore {
      LIMIT ?
    `);

-    return stmt.all(limit) as any[];
+    return stmt.all(limit);
  }

  /**
@@ -703,6 +714,34 @@ export class SessionStore {
    return rows.map(row => row.project);
  }

+  /**
+   * Get latest user prompt with session info for a Claude session
+   * Used for syncing prompts to Chroma during session initialization
+   */
+  getLatestUserPrompt(claudeSessionId: string): {
+    id: number;
+    claude_session_id: string;
+    sdk_session_id: string;
+    project: string;
+    prompt_number: number;
+    prompt_text: string;
+    created_at_epoch: number;
+  } | undefined {
+    const stmt = this.db.prepare(`
+      SELECT
+        up.*,
+        s.sdk_session_id,
+        s.project
+      FROM user_prompts up
+      JOIN sdk_sessions s ON up.claude_session_id = s.claude_session_id
+      WHERE up.claude_session_id = ?
+      ORDER BY up.created_at_epoch DESC
+      LIMIT 1
+    `);
+
+    return stmt.get(claudeSessionId) as LatestPromptResult | undefined;
+  }
+
  /**
   * Get recent sessions with their status and summary info
   */
@@ -732,7 +771,7 @@ export class SessionStore {
      ORDER BY started_at_epoch ASC
    `);

-    return stmt.all(project, limit) as any[];
+    return stmt.all(project, limit);
  }

  /**
@@ -751,20 +790,20 @@ export class SessionStore {
      ORDER BY created_at_epoch ASC
    `);

-    return stmt.all(sdkSessionId) as any[];
+    return stmt.all(sdkSessionId);
  }

  /**
   * Get a single observation by ID
   */
-  getObservationById(id: number): any | null {
+  getObservationById(id: number): ObservationRecord | null {
    const stmt = this.db.prepare(`
      SELECT *
      FROM observations
      WHERE id = ?
    `);

-    return stmt.get(id) as any || null;
+    return stmt.get(id) as ObservationRecord | undefined || null;
  }

  /**
@@ -773,7 +812,7 @@ export class SessionStore {
  getObservationsByIds(
    ids: number[],
    options: { orderBy?: 'date_desc' | 'date_asc'; limit?: number } = {}
-  ): any[] {
+  ): ObservationRecord[] {
    if (ids.length === 0) return [];

    const { orderBy = 'date_desc', limit } = options;
@@ -791,7 +830,7 @@ export class SessionStore {
      ${limitClause}
    `);

-    return stmt.all(...ids) as any[];
+    return stmt.all(...ids) as ObservationRecord[];
  }

  /**
@@ -819,7 +858,7 @@ export class SessionStore {
      LIMIT 1
    `);

-    return stmt.get(sdkSessionId) as any || null;
+    return stmt.get(sdkSessionId) || null;
  }

  /**
@@ -892,7 +931,7 @@ export class SessionStore {
      LIMIT 1
    `);

-    return stmt.get(id) as any || null;
+    return stmt.get(id) || null;
  }

  /**
@@ -911,7 +950,7 @@ export class SessionStore {
      LIMIT 1
    `);

-    return stmt.get(claudeSessionId) as any || null;
+    return stmt.get(claudeSessionId) || null;
  }

  /**
@@ -925,7 +964,7 @@ export class SessionStore {
      LIMIT 1
    `);

-    return stmt.get(claudeSessionId) as any || null;
+    return stmt.get(claudeSessionId) || null;
  }

  /**
@@ -1315,7 +1354,7 @@ export class SessionStore {
  getSessionSummariesByIds(
    ids: number[],
    options: { orderBy?: 'date_desc' | 'date_asc'; limit?: number } = {}
-  ): any[] {
+  ): SessionSummaryRecord[] {
    if (ids.length === 0) return [];

    const { orderBy = 'date_desc', limit } = options;
@@ -1330,7 +1369,7 @@ export class SessionStore {
      ${limitClause}
    `);

-    return stmt.all(...ids) as any[];
+    return stmt.all(...ids) as SessionSummaryRecord[];
  }

  /**
@@ -1340,7 +1379,7 @@ export class SessionStore {
  getUserPromptsByIds(
    ids: number[],
    options: { orderBy?: 'date_desc' | 'date_asc'; limit?: number } = {}
-  ): any[] {
+  ): UserPromptRecord[] {
    if (ids.length === 0) return [];

    const { orderBy = 'date_desc', limit } = options;
@@ -1360,7 +1399,7 @@ export class SessionStore {
      ${limitClause}
    `);

-    return stmt.all(...ids) as any[];
+    return stmt.all(...ids) as UserPromptRecord[];
  }

  /**
@@ -1423,8 +1462,8 @@ export class SessionStore {
      `;

      try {
-        const beforeRecords = this.db.prepare(beforeQuery).all(anchorObservationId, ...projectParams, depthBefore + 1) as any[];
-        const afterRecords = this.db.prepare(afterQuery).all(anchorObservationId, ...projectParams, depthAfter + 1) as any[];
+        const beforeRecords = this.db.prepare(beforeQuery).all(anchorObservationId, ...projectParams, depthBefore + 1) as Array<{id: number; created_at_epoch: number}>;
+        const afterRecords = this.db.prepare(afterQuery).all(anchorObservationId, ...projectParams, depthAfter + 1) as Array<{id: number; created_at_epoch: number}>;

        // Get the earliest and latest timestamps from boundary observations
        if (beforeRecords.length === 0 && afterRecords.length === 0) {
@@ -1456,8 +1495,8 @@ export class SessionStore {
      `;

      try {
-        const beforeRecords = this.db.prepare(beforeQuery).all(anchorEpoch, ...projectParams, depthBefore) as any[];
-        const afterRecords = this.db.prepare(afterQuery).all(anchorEpoch, ...projectParams, depthAfter + 1) as any[];
+        const beforeRecords = this.db.prepare(beforeQuery).all(anchorEpoch, ...projectParams, depthBefore) as Array<{created_at_epoch: number}>;
+        const afterRecords = this.db.prepare(afterQuery).all(anchorEpoch, ...projectParams, depthAfter + 1) as Array<{created_at_epoch: number}>;

        if (beforeRecords.length === 0 && afterRecords.length === 0) {
          return { observations: [], sessions: [], prompts: [] };
@@ -1495,9 +1534,9 @@ export class SessionStore {
    `;

    try {
-      const observations = this.db.prepare(obsQuery).all(startEpoch, endEpoch, ...projectParams) as any[];
-      const sessions = this.db.prepare(sessQuery).all(startEpoch, endEpoch, ...projectParams) as any[];
-      const prompts = this.db.prepare(promptQuery).all(startEpoch, endEpoch, ...projectParams) as any[];
+      const observations = this.db.prepare(obsQuery).all(startEpoch, endEpoch, ...projectParams) as ObservationRecord[];
+      const sessions = this.db.prepare(sessQuery).all(startEpoch, endEpoch, ...projectParams) as SessionSummaryRecord[];
+      const prompts = this.db.prepare(promptQuery).all(startEpoch, endEpoch, ...projectParams) as UserPromptRecord[];

      return {
        observations,
@@ -13,6 +13,9 @@ import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
 import { ParsedObservation, ParsedSummary } from '../../sdk/parser.js';
 import { SessionStore } from '../sqlite/SessionStore.js';
 import { logger } from '../../utils/logger.js';
+import { SettingsDefaultsManager } from '../../shared/SettingsDefaultsManager.js';
+import { USER_SETTINGS_PATH } from '../../shared/paths.js';
+import { happy_path_error__with_fallback } from '../../utils/silent-debug.js';
 import path from 'path';
 import os from 'os';

@@ -94,9 +97,14 @@ export class ChromaSync {
    logger.info('CHROMA_SYNC', 'Connecting to Chroma MCP server...', { project: this.project });

    try {
+      // Use Python 3.13 by default to avoid onnxruntime compatibility issues with Python 3.14+
+      // See: https://github.com/thedotmack/claude-mem/issues/170 (Python 3.14 incompatibility)
+      const settings = SettingsDefaultsManager.loadFromFile(USER_SETTINGS_PATH);
+      const pythonVersion = settings.CLAUDE_MEM_PYTHON_VERSION;
      const transport = new StdioClientTransport({
        command: 'uvx',
        args: [
+          '--python', pythonVersion,
          'chroma-mcp',
          '--client-type', 'persistent',
          '--data-dir', this.VECTOR_DB_DIR
@@ -729,6 +737,83 @@ export class ChromaSync {
    }
  }

+  /**
+   * Query Chroma collection for semantic search
+   * Used by SearchManager for vector-based search
+   */
+  async queryChroma(
+    query: string,
+    limit: number,
+    whereFilter?: Record<string, any>
+  ): Promise<{ ids: number[]; distances: number[]; metadatas: any[] }> {
+    await this.ensureConnection();
+
+    if (!this.client) {
+      throw new Error('Chroma client not initialized');
+    }
+
+    const whereStringified = whereFilter ? JSON.stringify(whereFilter) : undefined;
+
+    const arguments_obj = {
+      collection_name: this.collectionName,
+      query_texts: [query],
+      n_results: limit,
+      include: ['documents', 'metadatas', 'distances'],
+      where: whereStringified
+    };
+
+    const result = await this.client.callTool({
+      name: 'chroma_query_documents',
+      arguments: arguments_obj
+    });
+
+    const resultText = happy_path_error__with_fallback(
+      'Missing text in MCP chroma_query_documents result',
+      { project: this.project, query_text: query },
+      result.content[0]?.text || ''
+    );
+
+    // Parse JSON response
+    let parsed: any;
+    try {
+      parsed = JSON.parse(resultText);
+    } catch (error) {
+      logger.error('CHROMA_SYNC', 'Failed to parse Chroma response', { project: this.project }, error as Error);
+      return { ids: [], distances: [], metadatas: [] };
+    }
+
+    // Extract unique IDs from document IDs
+    const ids: number[] = [];
+    const docIds = parsed.ids?.[0] || [];
+    for (const docId of docIds) {
+      // Extract sqlite_id from document ID (supports three formats):
+      // - obs_{id}_narrative, obs_{id}_fact_0, etc (observations)
+      // - summary_{id}_request, summary_{id}_learned, etc (session summaries)
+      // - prompt_{id} (user prompts)
+      const obsMatch = docId.match(/obs_(\d+)_/);
+      const summaryMatch = docId.match(/summary_(\d+)_/);
+      const promptMatch = docId.match(/prompt_(\d+)/);
+
+      let sqliteId: number | null = null;
+      if (obsMatch) {
+        sqliteId = parseInt(obsMatch[1], 10);
+      } else if (summaryMatch) {
+        sqliteId = parseInt(summaryMatch[1], 10);
+      } else if (promptMatch) {
+        sqliteId = parseInt(promptMatch[1], 10);
+      }
+
+      if (sqliteId !== null && !ids.includes(sqliteId)) {
+        ids.push(sqliteId);
+      }
+    }
+
+    const distances = parsed.distances?.[0] || [];
+    const metadatas = parsed.metadatas?.[0] || [];
+
+    return { ids, distances, metadatas };
+  }
+
  /**
   * Close the Chroma client connection
   */
@@ -13,6 +13,11 @@ import { logger } from '../../utils/logger.js';

 const INSTALLED_PLUGIN_PATH = join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');

+// Timeout constants
+const GIT_COMMAND_TIMEOUT_MS = 30_000;
+const NPM_INSTALL_TIMEOUT_MS = 120_000;
+const DEFAULT_SHELL_TIMEOUT_MS = 60_000;
+
 export interface BranchInfo {
  branch: string | null;
  isBeta: boolean;
@@ -36,18 +41,20 @@ function execGit(command: string): string {
  return execSync(`git ${command}`, {
    cwd: INSTALLED_PLUGIN_PATH,
    encoding: 'utf-8',
-    timeout: 30000
+    timeout: GIT_COMMAND_TIMEOUT_MS,
+    windowsHide: true
  }).trim();
 }

 /**
 * Execute shell command in installed plugin directory
 */
-function execShell(command: string, timeoutMs: number = 60000): string {
+function execShell(command: string, timeoutMs: number = DEFAULT_SHELL_TIMEOUT_MS): string {
  return execSync(command, {
    cwd: INSTALLED_PLUGIN_PATH,
    encoding: 'utf-8',
-    timeout: timeoutMs
+    timeout: timeoutMs,
+    windowsHide: true
  }).trim();
 }

@@ -163,7 +170,7 @@ export async function switchBranch(targetBranch: string): Promise<SwitchResult>
    }

    logger.debug('BRANCH', 'Running npm install');
-    execShell('npm install', 120000); // 2 minute timeout for npm
+    execShell('npm install', NPM_INSTALL_TIMEOUT_MS);

    logger.success('BRANCH', 'Branch switch complete', {
      branch: targetBranch
@@ -221,7 +228,7 @@ export async function pullUpdates(): Promise<SwitchResult> {
    if (existsSync(installMarker)) {
      unlinkSync(installMarker);
    }
-    execShell('npm install', 120000);
+    execShell('npm install', NPM_INSTALL_TIMEOUT_MS);

    logger.success('BRANCH', 'Updates pulled', { branch: info.branch });

@@ -0,0 +1,246 @@
+/**
+ * FormattingService - Handles all formatting logic for search results
+ * Extracted from mcp-server.ts to follow worker service organization pattern
+ */
+
+import { ObservationSearchResult, SessionSummarySearchResult, UserPromptSearchResult } from '../sqlite/types.js';
+import { logger } from '../../utils/logger.js';
+
+export type FormatType = 'index' | 'full';
+
+export class FormattingService {
+  /**
+   * Format search tips footer
+   */
+  formatSearchTips(): string {
+    return `\n---
+💡 Search Strategy:
+ALWAYS search with index format FIRST to get an overview and identify relevant results.
+This is critical for token efficiency - index format uses ~10x fewer tokens than full format.
+
+Search workflow:
+1. Initial search: Use default (index) format to see titles, dates, and sources
+2. Review results: Identify which items are most relevant to your needs
+3. Deep dive: Only then use format: "full" on specific items of interest
+4. Narrow down: Use filters (type, dateStart/dateEnd, concepts, files) to refine results
+
+Other tips:
+• To search by concept: Use find_by_concept tool
+• To browse by type: Use find_by_type with ["decision", "feature", etc.]
+• To sort by date: Use orderBy: "date_desc" or "date_asc"`;
+  }
+
+  /**
+   * Format observation as index entry (title, date, ID only)
+   */
+  formatObservationIndex(obs: ObservationSearchResult, index: number): string {
+    const title = obs.title || `Observation #${obs.id}`;
+    const date = new Date(obs.created_at_epoch).toLocaleString();
+    const type = obs.type ? `[${obs.type}]` : '';
+
+    return `${index + 1}. ${type} ${title}
+   Date: ${date}
+   Source: claude-mem://observation/${obs.id}`;
+  }
+
+  /**
+   * Format session summary as index entry (title, date, ID only)
+   */
+  formatSessionIndex(session: SessionSummarySearchResult, index: number): string {
+    const title = session.request || `Session ${session.sdk_session_id?.substring(0, 8) || 'unknown'}`;
+    const date = new Date(session.created_at_epoch).toLocaleString();
+
+    return `${index + 1}. ${title}
+   Date: ${date}
+   Source: claude-mem://session/${session.sdk_session_id}`;
+  }
+
+  /**
+   * Format user prompt as index entry (full text - don't truncate context!)
+   */
+  formatUserPromptIndex(prompt: UserPromptSearchResult, index: number): string {
+    const date = new Date(prompt.created_at_epoch).toLocaleString();
+
+    return `${index + 1}. "${prompt.prompt_text}"
+   Date: ${date} | Prompt #${prompt.prompt_number}
+   Source: claude-mem://user-prompt/${prompt.id}`;
+  }
+
+  /**
+   * Format observation as text content with metadata
+   */
+  formatObservationResult(obs: ObservationSearchResult): string {
+    const title = obs.title || `Observation #${obs.id}`;
+
+    // Build content from available fields
+    const contentParts: string[] = [];
+    contentParts.push(`## ${title}`);
+    contentParts.push(`*Source: claude-mem://observation/${obs.id}*`);
+    contentParts.push('');
+
+    if (obs.subtitle) {
+      contentParts.push(`**${obs.subtitle}**`);
+      contentParts.push('');
+    }
+
+    if (obs.narrative) {
+      contentParts.push(obs.narrative);
+      contentParts.push('');
+    }
+
+    if (obs.text) {
+      contentParts.push(obs.text);
+      contentParts.push('');
+    }
+
+    // Add metadata
+    const metadata: string[] = [];
+    metadata.push(`Type: ${obs.type}`);
+
+    if (obs.facts) {
+      try {
+        const facts = JSON.parse(obs.facts);
+        if (facts.length > 0) {
+          metadata.push(`Facts: ${facts.join('; ')}`);
+        }
+      } catch (e) {
+        logger.warn('FORMAT', 'Invalid JSON in facts field', { obsId: obs.id });
+      }
+    }
+
+    if (obs.concepts) {
+      try {
+        const concepts = JSON.parse(obs.concepts);
+        if (concepts.length > 0) {
+          metadata.push(`Concepts: ${concepts.join(', ')}`);
+        }
+      } catch (e) {
+        logger.warn('FORMAT', 'Invalid JSON in concepts field', { obsId: obs.id });
+      }
+    }
+
+    if (obs.files_read || obs.files_modified) {
+      const files: string[] = [];
+      if (obs.files_read) {
+        try {
+          files.push(...JSON.parse(obs.files_read));
+        } catch (e) {
+          logger.warn('FORMAT', 'Invalid JSON in files_read field', { obsId: obs.id });
+        }
+      }
+      if (obs.files_modified) {
+        try {
+          files.push(...JSON.parse(obs.files_modified));
+        } catch (e) {
+          logger.warn('FORMAT', 'Invalid JSON in files_modified field', { obsId: obs.id });
+        }
+      }
+      if (files.length > 0) {
+        metadata.push(`Files: ${[...new Set(files)].join(', ')}`);
+      }
+    }
+
+    if (metadata.length > 0) {
+      contentParts.push('---');
+      contentParts.push(metadata.join(' | '));
+    }
+
+    // Add date
+    const date = new Date(obs.created_at_epoch).toLocaleString();
+    contentParts.push('');
+    contentParts.push(`---`);
+    contentParts.push(`Date: ${date}`);
+
+    return contentParts.join('\n');
+  }
+
+  /**
+   * Format session summary as text content with metadata
+   */
+  formatSessionResult(session: SessionSummarySearchResult): string {
+    const title = session.request || `Session ${session.sdk_session_id?.substring(0, 8) || 'unknown'}`;
+
+    // Build content from available fields
+    const contentParts: string[] = [];
+    contentParts.push(`## ${title}`);
+    contentParts.push(`*Source: claude-mem://session/${session.sdk_session_id}*`);
+    contentParts.push('');
+
+    if (session.completed) {
+      contentParts.push(`**Completed:** ${session.completed}`);
+      contentParts.push('');
+    }
+
+    if (session.learned) {
+      contentParts.push(`**Learned:** ${session.learned}`);
+      contentParts.push('');
+    }
+
+    if (session.investigated) {
+      contentParts.push(`**Investigated:** ${session.investigated}`);
+      contentParts.push('');
+    }
+
+    if (session.next_steps) {
+      contentParts.push(`**Next Steps:** ${session.next_steps}`);
+      contentParts.push('');
+    }
+
+    if (session.notes) {
+      contentParts.push(`**Notes:** ${session.notes}`);
+      contentParts.push('');
+    }
+
+    // Add metadata
+    const metadata: string[] = [];
+
+    if (session.files_read || session.files_edited) {
+      const files: string[] = [];
+      if (session.files_read) {
+        try {
+          files.push(...JSON.parse(session.files_read));
+        } catch (e) {
+          logger.warn('FORMAT', 'Invalid JSON in session files_read field', { sessionId: session.sdk_session_id });
+        }
+      }
+      if (session.files_edited) {
+        try {
+          files.push(...JSON.parse(session.files_edited));
+        } catch (e) {
+          logger.warn('FORMAT', 'Invalid JSON in session files_edited field', { sessionId: session.sdk_session_id });
+        }
+      }
+      if (files.length > 0) {
+        metadata.push(`Files: ${[...new Set(files)].join(', ')}`);
+      }
+    }
+
+    const date = new Date(session.created_at_epoch).toLocaleDateString();
+    metadata.push(`Date: ${date}`);
+
+    if (metadata.length > 0) {
+      contentParts.push('---');
+      contentParts.push(metadata.join(' | '));
+    }
+
+    return contentParts.join('\n');
+  }
+
+  /**
+   * Format user prompt as text content with metadata
+   */
+  formatUserPromptResult(prompt: UserPromptSearchResult): string {
+    const contentParts: string[] = [];
+    contentParts.push(`## User Prompt #${prompt.prompt_number}`);
+    contentParts.push(`*Source: claude-mem://user-prompt/${prompt.id}*`);
+    contentParts.push('');
+    contentParts.push(prompt.prompt_text);
+    contentParts.push('');
+    contentParts.push('---');
+
+    const date = new Date(prompt.created_at_epoch).toLocaleString();
+    contentParts.push(`Date: ${date}`);
+
+    return contentParts.join('\n');
+  }
+}
@@ -0,0 +1,155 @@
+# Worker Service Architecture
+
+## Overview
+
+The Worker Service is an Express HTTP server that handles all claude-mem operations. It runs on port 37777 (configurable via `CLAUDE_MEM_WORKER_PORT`) and is managed by PM2.
+
+## Request Flow
+
+```
+Hook (plugin/scripts/*-hook.js)
+  → HTTP Request to Worker (localhost:37777)
+    → Route Handler (http/routes/*.ts)
+      → MCP Server Tool (for search) OR Domain Service (for session/data)
+        → Database (SQLite3 + Chroma vector DB)
+```
+
+## Directory Structure
+
+```
+src/services/worker/
+├── README.md                     # This file
+├── WorkerService.ts              # Slim orchestrator (~150 lines)
+├── http/                         # HTTP layer
+│   ├── middleware.ts             # Shared middleware (logging, CORS, etc.)
+│   └── routes/                   # Route handlers organized by domain
+│       ├── SessionRoutes.ts      # Session lifecycle (init, observations, summarize, complete)
+│       ├── DataRoutes.ts         # Data retrieval (get observations, summaries, prompts, stats)
+│       ├── SearchRoutes.ts       # Search/MCP proxy (all search endpoints)
+│       ├── SettingsRoutes.ts     # Settings, MCP toggle, branch switching
+│       └── ViewerRoutes.ts       # Health check, viewer UI, SSE stream
+└── domain/                       # Business logic (existing services, NO CHANGES in Phase 1)
+    ├── DatabaseManager.ts        # SQLite connection management
+    ├── SessionManager.ts         # Session state tracking
+    ├── SDKAgent.ts               # Claude Agent SDK for observations/summaries
+    ├── SSEBroadcaster.ts         # Server-Sent Events for real-time updates
+    ├── PaginationHelper.ts       # Query pagination utilities
+    ├── SettingsManager.ts        # User settings CRUD
+    └── BranchManager.ts          # Git branch operations
+```
+
+## Route Organization
+
+### ViewerRoutes.ts
+- `GET /health` - Health check endpoint
+- `GET /` - Serve viewer UI (React app)
+- `GET /stream` - SSE stream for real-time updates
+
+### SessionRoutes.ts
+Session lifecycle operations (use domain services directly):
+- `POST /sessions/init` - Initialize new session
+- `POST /sessions/:sessionId/observations` - Add tool usage observations
+- `POST /sessions/:sessionId/summarize` - Trigger session summary
+- `GET /sessions/:sessionId/status` - Get session status
+- `DELETE /sessions/:sessionId` - Delete session
+- `POST /sessions/:sessionId/complete` - Mark session complete
+- `POST /sessions/claude-id/:claudeId/observations` - Add observations by claude_id
+- `POST /sessions/claude-id/:claudeId/summarize` - Summarize by claude_id
+- `POST /sessions/claude-id/:claudeId/complete` - Complete by claude_id
+
+### DataRoutes.ts
+Data retrieval operations (use domain services directly):
+- `GET /observations` - List observations (paginated)
+- `GET /summaries` - List session summaries (paginated)
+- `GET /prompts` - List user prompts (paginated)
+- `GET /observations/:id` - Get observation by ID
+- `GET /sessions/:sessionId` - Get session by ID
+- `GET /prompts/:id` - Get prompt by ID
+- `GET /stats` - Get database statistics
+- `GET /projects` - List all projects
+- `GET /processing` - Get processing status
+- `POST /processing` - Set processing status
+
+### SearchRoutes.ts
+All search operations (proxy to MCP server):
+- `GET /search` - Unified search (observations + sessions + prompts)
+- `GET /timeline` - Unified timeline context
+- `GET /decisions` - Decision-type observations
+- `GET /changes` - Change-related observations
+- `GET /how-it-works` - How-it-works explanations
+- `GET /search/observations` - Search observations
+- `GET /search/sessions` - Search sessions
+- `GET /search/prompts` - Search prompts
+- `GET /search/by-concept` - Find by concept tag
+- `GET /search/by-file` - Find by file path
+- `GET /search/by-type` - Find by observation type
+- `GET /search/recent-context` - Get recent context
+- `GET /search/context-timeline` - Get context timeline
+- `GET /context/preview` - Preview context
+- `GET /context/inject` - Inject context
+- `GET /search/timeline-by-query` - Timeline by search query
+- `GET /search/help` - Search help
+
+### SettingsRoutes.ts
+Settings and configuration (use domain services directly):
+- `GET /settings` - Get user settings
+- `POST /settings` - Update user settings
+- `GET /mcp/status` - Get MCP server status
+- `POST /mcp/toggle` - Toggle MCP server on/off
+- `GET /branch/status` - Get git branch info
+- `POST /branch/switch` - Switch git branch
+- `POST /branch/update` - Pull branch updates
+
+## Current State (Phase 1)
+
+**Phase 1** is a pure code reorganization with ZERO functional changes:
+- Extract route handlers from WorkerService.ts monolith
+- Organize into logical route classes
+- Keep all existing behavior identical
+
+**MCP vs Direct DB Split** (inherited, not changed in Phase 1):
+- Search operations → MCP server (claude-mem-search)
+- Session/data operations → Direct DB access via domain services
+
+## Future Phase 2
+
+Phase 2 will unify the architecture:
+1. Expand MCP server to handle ALL operations (not just search)
+2. Convert all route handlers to proxy through MCP
+3. Move database logic from domain services into MCP tools
+4. Result: Worker becomes pure HTTP → MCP proxy for maximum portability
+
+This separation allows the worker to be deployed anywhere (as a CLI tool, cloud service, etc.) without carrying database dependencies.
+
+## Adding New Endpoints
+
+1. Choose the appropriate route file based on the endpoint's purpose
+2. Add the route handler method to the class
+3. Register the route in the `setupRoutes()` method
+4. Import any needed domain services in the constructor
+5. Follow the existing patterns for error handling and logging
+
+Example:
+```typescript
+// In DataRoutes.ts
+private async handleGetFoo(req: Request, res: Response): Promise<void> {
+  try {
+    const result = await this.dbManager.getFoo();
+    res.json(result);
+  } catch (error) {
+    logger.failure('WORKER', 'Get foo failed', {}, error as Error);
+    res.status(500).json({ error: (error as Error).message });
+  }
+}
+
+// Register in setupRoutes()
+app.get('/foo', this.handleGetFoo.bind(this));
+```
+
+## Key Design Principles
+
+1. **Progressive Disclosure**: Navigate from high-level (WorkerService.ts) to specific routes to implementation details
+2. **Single Responsibility**: Each route class handles one domain area
+3. **Dependency Injection**: Route classes receive only the services they need
+4. **Consistent Error Handling**: All handlers use try/catch with logger.failure()
+5. **Bound Methods**: All route handlers use `.bind(this)` to preserve context
@@ -11,13 +11,14 @@
 import { execSync } from 'child_process';
 import { homedir } from 'os';
 import path from 'path';
-import { existsSync, readFileSync } from 'fs';
 import { DatabaseManager } from './DatabaseManager.js';
 import { SessionManager } from './SessionManager.js';
 import { logger } from '../../utils/logger.js';
-import { silentDebug } from '../../utils/silent-debug.js';
+import { happy_path_error__with_fallback } from '../../utils/silent-debug.js';
 import { parseObservations, parseSummary } from '../../sdk/parser.js';
 import { buildInitPrompt, buildObservationPrompt, buildSummaryPrompt, buildContinuationPrompt } from '../../sdk/prompts.js';
+import { SettingsDefaultsManager } from '../../shared/SettingsDefaultsManager.js';
+import { USER_SETTINGS_PATH } from '../../shared/paths.js';
 import type { ActiveSession, SDKUserMessage, PendingMessage } from '../worker-types.js';

 // Import Agent SDK (assumes it's installed)
@@ -232,8 +233,16 @@ export class SDKAgent {
              sdk_session_id: session.sdkSessionId,
              project: session.project,
              user_prompt: session.userPrompt,
-              last_user_message: message.last_user_message || '',
-              last_assistant_message: message.last_assistant_message || ''
+              last_user_message: happy_path_error__with_fallback(
+                'Missing last_user_message for summary in SDKAgent',
+                { sessionDbId: session.sessionDbId, sdkSessionId: session.sdkSessionId },
+                message.last_user_message || ''
+              ),
+              last_assistant_message: happy_path_error__with_fallback(
+                'Missing last_assistant_message for summary in SDKAgent',
+                { sessionDbId: session.sessionDbId, sdkSessionId: session.sdkSessionId },
+                message.last_assistant_message || ''
+              )
            })
          },
          session_id: session.claudeSessionId,
@@ -267,16 +276,16 @@ export class SDKAgent {
        sessionId: session.sessionDbId,
        obsId,
        type: obs.type,
-        title: obs.title || silentDebug('obs.title is null', { obsId, type: obs.type }, '(untitled)'),
-        filesRead: obs.files_read?.length ?? (silentDebug('obs.files_read is null/undefined', { obsId }), 0),
-        filesModified: obs.files_modified?.length ?? (silentDebug('obs.files_modified is null/undefined', { obsId }), 0),
-        concepts: obs.concepts?.length ?? (silentDebug('obs.concepts is null/undefined', { obsId }), 0)
+        title: obs.title || happy_path_error__with_fallback('obs.title is null', { obsId, type: obs.type }, '(untitled)'),
+        filesRead: obs.files_read?.length ?? (happy_path_error__with_fallback('obs.files_read is null/undefined', { obsId }), 0),
+        filesModified: obs.files_modified?.length ?? (happy_path_error__with_fallback('obs.files_modified is null/undefined', { obsId }), 0),
+        concepts: obs.concepts?.length ?? (happy_path_error__with_fallback('obs.concepts is null/undefined', { obsId }), 0)
      });

      // Sync to Chroma with error logging
      const chromaStart = Date.now();
      const obsType = obs.type;
-      const obsTitle = obs.title || silentDebug('obs.title is null for Chroma sync', { obsId, type: obs.type }, '(untitled)');
+      const obsTitle = obs.title || happy_path_error__with_fallback('obs.title is null for Chroma sync', { obsId, type: obs.type }, '(untitled)');
      this.dbManager.getChromaSync().syncObservation(
        obsId,
        session.claudeSessionId,
@@ -344,14 +353,14 @@ export class SDKAgent {
      logger.info('SDK', 'Summary saved', {
        sessionId: session.sessionDbId,
        summaryId,
-        request: summary.request || silentDebug('summary.request is null', { summaryId }, '(no request)'),
+        request: summary.request || happy_path_error__with_fallback('summary.request is null', { summaryId }, '(no request)'),
        hasCompleted: !!summary.completed,
        hasNextSteps: !!summary.next_steps
      });

      // Sync to Chroma with error logging
      const chromaStart = Date.now();
-      const summaryRequest = summary.request || silentDebug('summary.request is null for Chroma sync', { summaryId }, '(no request)');
+      const summaryRequest = summary.request || happy_path_error__with_fallback('summary.request is null for Chroma sync', { summaryId }, '(no request)');
      this.dbManager.getChromaSync().syncSummary(
        summaryId,
        session.claudeSessionId,
@@ -410,7 +419,8 @@ export class SDKAgent {
   * Find Claude executable (inline, called once per session)
   */
  private findClaudeExecutable(): string {
-    const claudePath = process.env.CLAUDE_CODE_PATH ||
+    const settings = SettingsDefaultsManager.loadFromFile(USER_SETTINGS_PATH);
+    const claudePath = settings.CLAUDE_CODE_PATH ||
      execSync(process.platform === 'win32' ? 'where claude' : 'which claude', { encoding: 'utf8', windowsHide: true })
        .trim().split('\n')[0].trim();

@@ -425,17 +435,8 @@ export class SDKAgent {
   * Get model ID from settings or environment
   */
  private getModelId(): string {
-    try {
-      const settingsPath = path.join(homedir(), '.claude-mem', 'settings.json');
-      if (existsSync(settingsPath)) {
-        const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-        const modelId = settings.env?.CLAUDE_MEM_MODEL;
-        if (modelId) return modelId;
-      }
-    } catch {
-      // Fall through to env var or default
-    }
-
-    return process.env.CLAUDE_MEM_MODEL || 'claude-haiku-4-5';
+    const settingsPath = path.join(homedir(), '.claude-mem', 'settings.json');
+    const settings = SettingsDefaultsManager.loadFromFile(settingsPath);
+    return settings.CLAUDE_MEM_MODEL;
  }
 }
@@ -11,7 +11,6 @@
 import { EventEmitter } from 'events';
 import { DatabaseManager } from './DatabaseManager.js';
 import { logger } from '../../utils/logger.js';
-import { silentDebug } from '../../utils/silent-debug.js';
 import type { ActiveSession, PendingMessage, ObservationData } from '../worker-types.js';

 export class SessionManager {
@@ -43,7 +42,7 @@ export class SessionManager {
      // in the database but the in-memory session still has the stale empty value
      const dbSession = this.dbManager.getSessionById(sessionDbId);
      if (dbSession.project && dbSession.project !== session.project) {
-        silentDebug('[SessionManager] Updating project from database', {
+        logger.debug('SESSION', 'Updating project from database', {
          sessionDbId,
          oldProject: session.project,
          newProject: dbSession.project
@@ -53,7 +52,7 @@ export class SessionManager {

      // Update userPrompt for continuation prompts
      if (currentUserPrompt) {
-        silentDebug('[SessionManager] Updating userPrompt for continuation', {
+        logger.debug('SESSION', 'Updating userPrompt for continuation', {
          sessionDbId,
          promptNumber,
          oldPrompt: session.userPrompt.substring(0, 80),
@@ -62,7 +61,7 @@ export class SessionManager {
        session.userPrompt = currentUserPrompt;
        session.lastPromptNumber = promptNumber || session.lastPromptNumber;
      } else {
-        silentDebug('[SessionManager] No currentUserPrompt provided for existing session', {
+        logger.debug('SESSION', 'No currentUserPrompt provided for existing session', {
          sessionDbId,
          promptNumber,
          usingCachedPrompt: session.userPrompt.substring(0, 80)
@@ -78,13 +77,13 @@ export class SessionManager {
    const userPrompt = currentUserPrompt || dbSession.user_prompt;

    if (!currentUserPrompt) {
-      silentDebug('[SessionManager] No currentUserPrompt provided for new session, using database', {
+      logger.debug('SESSION', 'No currentUserPrompt provided for new session, using database', {
        sessionDbId,
        promptNumber,
        dbPrompt: dbSession.user_prompt.substring(0, 80)
      });
    } else {
-      silentDebug('[SessionManager] Initializing session with fresh userPrompt', {
+      logger.debug('SESSION', 'Initializing session with fresh userPrompt', {
        sessionDbId,
        promptNumber,
        userPrompt: currentUserPrompt.substring(0, 80)
@@ -37,7 +37,7 @@ export class SettingsManager {
      for (const row of rows) {
        const key = row.key as keyof ViewerSettings;
        if (key in settings) {
-          (settings as any)[key] = JSON.parse(row.value);
+          settings[key] = JSON.parse(row.value) as ViewerSettings[typeof key];
        }
      }

@@ -0,0 +1,270 @@
+/**
+ * TimelineService - Handles timeline building, filtering, and formatting
+ * Extracted from mcp-server.ts to follow worker service organization pattern
+ */
+
+import { ObservationSearchResult, SessionSummarySearchResult, UserPromptSearchResult } from '../sqlite/types.js';
+
+/**
+ * Timeline item for unified chronological display
+ */
+export interface TimelineItem {
+  type: 'observation' | 'session' | 'prompt';
+  data: ObservationSearchResult | SessionSummarySearchResult | UserPromptSearchResult;
+  epoch: number;
+}
+
+export interface TimelineData {
+  observations: ObservationSearchResult[];
+  sessions: SessionSummarySearchResult[];
+  prompts: UserPromptSearchResult[];
+}
+
+export class TimelineService {
+  /**
+   * Build timeline items from observations, sessions, and prompts
+   */
+  buildTimeline(data: TimelineData): TimelineItem[] {
+    const items: TimelineItem[] = [
+      ...data.observations.map(obs => ({ type: 'observation' as const, data: obs, epoch: obs.created_at_epoch })),
+      ...data.sessions.map(sess => ({ type: 'session' as const, data: sess, epoch: sess.created_at_epoch })),
+      ...data.prompts.map(prompt => ({ type: 'prompt' as const, data: prompt, epoch: prompt.created_at_epoch }))
+    ];
+    items.sort((a, b) => a.epoch - b.epoch);
+    return items;
+  }
+
+  /**
+   * Filter timeline items to respect depth_before/depth_after window around anchor
+   */
+  filterByDepth(
+    items: TimelineItem[],
+    anchorId: number | string,
+    anchorEpoch: number,
+    depth_before: number,
+    depth_after: number
+  ): TimelineItem[] {
+    if (items.length === 0) return items;
+
+    let anchorIndex = -1;
+    if (typeof anchorId === 'number') {
+      anchorIndex = items.findIndex(item => item.type === 'observation' && (item.data as ObservationSearchResult).id === anchorId);
+    } else if (typeof anchorId === 'string' && anchorId.startsWith('S')) {
+      const sessionNum = parseInt(anchorId.slice(1), 10);
+      anchorIndex = items.findIndex(item => item.type === 'session' && (item.data as SessionSummarySearchResult).id === sessionNum);
+    } else {
+      // Timestamp anchor - find closest item
+      anchorIndex = items.findIndex(item => item.epoch >= anchorEpoch);
+      if (anchorIndex === -1) anchorIndex = items.length - 1;
+    }
+
+    if (anchorIndex === -1) return items;
+
+    const startIndex = Math.max(0, anchorIndex - depth_before);
+    const endIndex = Math.min(items.length, anchorIndex + depth_after + 1);
+    return items.slice(startIndex, endIndex);
+  }
+
+  /**
+   * Format timeline items as markdown with grouped days and tables
+   */
+  formatTimeline(
+    items: TimelineItem[],
+    anchorId: number | string | null,
+    query?: string,
+    depth_before?: number,
+    depth_after?: number
+  ): string {
+    if (items.length === 0) {
+      return query
+        ? `Found observation matching "${query}", but no timeline context available.`
+        : 'No timeline items found';
+    }
+
+    const lines: string[] = [];
+
+    // Header
+    if (query && anchorId) {
+      const anchorObs = items.find(item => item.type === 'observation' && (item.data as ObservationSearchResult).id === anchorId);
+      const anchorTitle = anchorObs ? ((anchorObs.data as ObservationSearchResult).title || 'Untitled') : 'Unknown';
+      lines.push(`# Timeline for query: "${query}"`);
+      lines.push(`**Anchor:** Observation #${anchorId} - ${anchorTitle}`);
+    } else if (anchorId) {
+      lines.push(`# Timeline around anchor: ${anchorId}`);
+    } else {
+      lines.push(`# Timeline`);
+    }
+
+    if (depth_before !== undefined && depth_after !== undefined) {
+      lines.push(`**Window:** ${depth_before} records before → ${depth_after} records after | **Items:** ${items.length}`);
+    } else {
+      lines.push(`**Items:** ${items.length}`);
+    }
+    lines.push('');
+
+    // Legend
+    lines.push(`**Legend:** 🎯 session-request | 🔴 bugfix | 🟣 feature | 🔄 refactor | ✅ change | 🔵 discovery | 🧠 decision`);
+    lines.push('');
+
+    // Group by day
+    const dayMap = new Map<string, TimelineItem[]>();
+    for (const item of items) {
+      const day = this.formatDate(item.epoch);
+      if (!dayMap.has(day)) {
+        dayMap.set(day, []);
+      }
+      dayMap.get(day)!.push(item);
+    }
+
+    // Sort days chronologically
+    const sortedDays = Array.from(dayMap.entries()).sort((a, b) => {
+      const aDate = new Date(a[0]).getTime();
+      const bDate = new Date(b[0]).getTime();
+      return aDate - bDate;
+    });
+
+    // Render each day
+    for (const [day, dayItems] of sortedDays) {
+      lines.push(`### ${day}`);
+      lines.push('');
+
+      let currentFile: string | null = null;
+      let lastTime = '';
+      let tableOpen = false;
+
+      for (const item of dayItems) {
+        const isAnchor = (
+          (typeof anchorId === 'number' && item.type === 'observation' && (item.data as ObservationSearchResult).id === anchorId) ||
+          (typeof anchorId === 'string' && anchorId.startsWith('S') && item.type === 'session' && `S${(item.data as SessionSummarySearchResult).id}` === anchorId)
+        );
+
+        if (item.type === 'session') {
+          if (tableOpen) {
+            lines.push('');
+            tableOpen = false;
+            currentFile = null;
+            lastTime = '';
+          }
+
+          const sess = item.data as SessionSummarySearchResult;
+          const title = sess.request || 'Session summary';
+          const link = `claude-mem://session-summary/${sess.id}`;
+          const marker = isAnchor ? ' ← **ANCHOR**' : '';
+
+          lines.push(`**🎯 #S${sess.id}** ${title} (${this.formatDateTime(item.epoch)}) [→](${link})${marker}`);
+          lines.push('');
+        } else if (item.type === 'prompt') {
+          if (tableOpen) {
+            lines.push('');
+            tableOpen = false;
+            currentFile = null;
+            lastTime = '';
+          }
+
+          const prompt = item.data as UserPromptSearchResult;
+          const truncated = prompt.prompt_text.length > 100 ? prompt.prompt_text.substring(0, 100) + '...' : prompt.prompt_text;
+
+          lines.push(`**💬 User Prompt #${prompt.prompt_number}** (${this.formatDateTime(item.epoch)})`);
+          lines.push(`> ${truncated}`);
+          lines.push('');
+        } else if (item.type === 'observation') {
+          const obs = item.data as ObservationSearchResult;
+          const file = 'General';
+
+          if (file !== currentFile) {
+            if (tableOpen) {
+              lines.push('');
+            }
+
+            lines.push(`**${file}**`);
+            lines.push(`| ID | Time | T | Title | Tokens |`);
+            lines.push(`|----|------|---|-------|--------|`);
+
+            currentFile = file;
+            tableOpen = true;
+            lastTime = '';
+          }
+
+          const icon = this.getTypeIcon(obs.type);
+          const time = this.formatTime(item.epoch);
+          const title = obs.title || 'Untitled';
+          const tokens = this.estimateTokens(obs.narrative);
+
+          const showTime = time !== lastTime;
+          const timeDisplay = showTime ? time : '″';
+          lastTime = time;
+
+          const anchorMarker = isAnchor ? ' ← **ANCHOR**' : '';
+          lines.push(`| #${obs.id} | ${timeDisplay} | ${icon} | ${title}${anchorMarker} | ~${tokens} |`);
+        }
+      }
+
+      if (tableOpen) {
+        lines.push('');
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Get icon for observation type
+   */
+  private getTypeIcon(type: string): string {
+    switch (type) {
+      case 'bugfix': return '🔴';
+      case 'feature': return '🟣';
+      case 'refactor': return '🔄';
+      case 'change': return '✅';
+      case 'discovery': return '🔵';
+      case 'decision': return '🧠';
+      default: return '•';
+    }
+  }
+
+  /**
+   * Format date for grouping (e.g., "Dec 7, 2025")
+   */
+  private formatDate(epochMs: number): string {
+    const date = new Date(epochMs);
+    return date.toLocaleString('en-US', {
+      month: 'short',
+      day: 'numeric',
+      year: 'numeric'
+    });
+  }
+
+  /**
+   * Format time (e.g., "6:30 PM")
+   */
+  private formatTime(epochMs: number): string {
+    const date = new Date(epochMs);
+    return date.toLocaleString('en-US', {
+      hour: 'numeric',
+      minute: '2-digit',
+      hour12: true
+    });
+  }
+
+  /**
+   * Format date and time (e.g., "Dec 7, 6:30 PM")
+   */
+  private formatDateTime(epochMs: number): string {
+    const date = new Date(epochMs);
+    return date.toLocaleString('en-US', {
+      month: 'short',
+      day: 'numeric',
+      hour: 'numeric',
+      minute: '2-digit',
+      hour12: true
+    });
+  }
+
+  /**
+   * Estimate tokens from text length (~4 chars per token)
+   */
+  private estimateTokens(text: string | null): number {
+    if (!text) return 0;
+    return Math.ceil(text.length / 4);
+  }
+}
@@ -0,0 +1,96 @@
+/**
+ * Session Event Broadcaster
+ *
+ * Provides semantic broadcast methods for session lifecycle events.
+ * Consolidates SSE broadcasting and processing status updates.
+ */
+
+import { SSEBroadcaster } from '../SSEBroadcaster.js';
+import type { WorkerService } from '../../worker-service.js';
+
+export class SessionEventBroadcaster {
+  constructor(
+    private sseBroadcaster: SSEBroadcaster,
+    private workerService: WorkerService
+  ) {}
+
+  /**
+   * Broadcast new user prompt arrival
+   * Starts activity indicator to show work is beginning
+   */
+  broadcastNewPrompt(prompt: {
+    id: number;
+    claude_session_id: string;
+    project: string;
+    prompt_number: number;
+    prompt_text: string;
+    created_at_epoch: number;
+  }): void {
+    // Broadcast prompt details
+    this.sseBroadcaster.broadcast({
+      type: 'new_prompt',
+      prompt
+    });
+
+    // Start activity indicator (work is about to begin)
+    this.sseBroadcaster.broadcast({
+      type: 'processing_status',
+      isProcessing: true
+    });
+
+    // Update processing status based on queue depth
+    this.workerService.broadcastProcessingStatus();
+  }
+
+  /**
+   * Broadcast session initialization
+   */
+  broadcastSessionStarted(sessionDbId: number, project: string): void {
+    this.sseBroadcaster.broadcast({
+      type: 'session_started',
+      sessionDbId,
+      project
+    });
+
+    // Update processing status
+    this.workerService.broadcastProcessingStatus();
+  }
+
+  /**
+   * Broadcast observation queued
+   * Updates processing status to reflect new queue depth
+   */
+  broadcastObservationQueued(sessionDbId: number): void {
+    this.sseBroadcaster.broadcast({
+      type: 'observation_queued',
+      sessionDbId
+    });
+
+    // Update processing status (queue depth changed)
+    this.workerService.broadcastProcessingStatus();
+  }
+
+  /**
+   * Broadcast session completion
+   * Updates processing status to reflect session removal
+   */
+  broadcastSessionCompleted(sessionDbId: number): void {
+    this.sseBroadcaster.broadcast({
+      type: 'session_completed',
+      timestamp: Date.now(),
+      sessionDbId
+    });
+
+    // Update processing status (session removed from queue)
+    this.workerService.broadcastProcessingStatus();
+  }
+
+  /**
+   * Broadcast summarize request queued
+   * Updates processing status to reflect new queue depth
+   */
+  broadcastSummarizeQueued(): void {
+    // Update processing status (queue depth changed)
+    this.workerService.broadcastProcessingStatus();
+  }
+}
@@ -0,0 +1,82 @@
+/**
+ * BaseRouteHandler
+ *
+ * Base class for all route handlers providing:
+ * - Automatic try-catch wrapping with error logging
+ * - Integer parameter validation
+ * - Required body parameter validation
+ * - Standard HTTP response helpers
+ * - Centralized error handling
+ */
+
+import { Request, Response } from 'express';
+import { logger } from '../../../utils/logger.js';
+
+export abstract class BaseRouteHandler {
+  /**
+   * Wrap handler with automatic try-catch and error logging
+   */
+  protected wrapHandler(
+    handler: (req: Request, res: Response) => void | Promise<void>
+  ): (req: Request, res: Response) => void {
+    return (req: Request, res: Response): void => {
+      try {
+        const result = handler(req, res);
+        if (result instanceof Promise) {
+          result.catch(error => this.handleError(res, error as Error));
+        }
+      } catch (error) {
+        this.handleError(res, error as Error);
+      }
+    };
+  }
+
+  /**
+   * Parse and validate integer parameter
+   * Returns the integer value or sends 400 error response
+   */
+  protected parseIntParam(req: Request, res: Response, paramName: string): number | null {
+    const value = parseInt(req.params[paramName], 10);
+    if (isNaN(value)) {
+      this.badRequest(res, `Invalid ${paramName}`);
+      return null;
+    }
+    return value;
+  }
+
+  /**
+   * Validate required body parameters
+   * Returns true if all required params present, sends 400 error otherwise
+   */
+  protected validateRequired(req: Request, res: Response, params: string[]): boolean {
+    for (const param of params) {
+      if (req.body[param] === undefined || req.body[param] === null) {
+        this.badRequest(res, `Missing ${param}`);
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Send 400 Bad Request response
+   */
+  protected badRequest(res: Response, message: string): void {
+    res.status(400).json({ error: message });
+  }
+
+  /**
+   * Send 404 Not Found response
+   */
+  protected notFound(res: Response, message: string): void {
+    res.status(404).json({ error: message });
+  }
+
+  /**
+   * Centralized error logging and response
+   */
+  protected handleError(res: Response, error: Error, context?: string): void {
+    logger.failure('WORKER', context || 'Request failed', {}, error);
+    res.status(500).json({ error: error.message });
+  }
+}
@@ -0,0 +1,89 @@
+/**
+ * HTTP Middleware for Worker Service
+ *
+ * Extracted from WorkerService.ts for better organization.
+ * Handles request/response logging, CORS, JSON parsing, and static file serving.
+ */
+
+import express, { Request, Response, NextFunction, RequestHandler } from 'express';
+import cors from 'cors';
+import path from 'path';
+import { getPackageRoot } from '../../../shared/paths.js';
+import { logger } from '../../../utils/logger.js';
+
+/**
+ * Create all middleware for the worker service
+ * @param summarizeRequestBody - Function to summarize request bodies for logging
+ * @returns Array of middleware functions
+ */
+export function createMiddleware(
+  summarizeRequestBody: (method: string, path: string, body: any) => string
+): RequestHandler[] {
+  const middlewares: RequestHandler[] = [];
+
+  // JSON parsing with 50mb limit
+  middlewares.push(express.json({ limit: '50mb' }));
+
+  // CORS
+  middlewares.push(cors());
+
+  // HTTP request/response logging
+  middlewares.push((req: Request, res: Response, next: NextFunction) => {
+    // Skip logging for static assets and health checks
+    if (req.path.startsWith('/health') || req.path === '/' || req.path.includes('.')) {
+      return next();
+    }
+
+    const start = Date.now();
+    const requestId = `${req.method}-${Date.now()}`;
+
+    // Log incoming request with body summary
+    const bodySummary = summarizeRequestBody(req.method, req.path, req.body);
+    logger.info('HTTP', `→ ${req.method} ${req.path}`, { requestId }, bodySummary);
+
+    // Capture response
+    const originalSend = res.send.bind(res);
+    res.send = function(body: any) {
+      const duration = Date.now() - start;
+      logger.info('HTTP', `← ${res.statusCode} ${req.path}`, { requestId, duration: `${duration}ms` });
+      return originalSend(body);
+    };
+
+    next();
+  });
+
+  // Serve static files for web UI (viewer-bundle.js, logos, fonts, etc.)
+  const packageRoot = getPackageRoot();
+  const uiDir = path.join(packageRoot, 'plugin', 'ui');
+  middlewares.push(express.static(uiDir));
+
+  return middlewares;
+}
+
+/**
+ * Summarize request body for logging
+ * Used to avoid logging sensitive data or large payloads
+ */
+export function summarizeRequestBody(method: string, path: string, body: any): string {
+  if (!body || Object.keys(body).length === 0) return '';
+
+  // Session init
+  if (path.includes('/init')) {
+    return '';
+  }
+
+  // Observations
+  if (path.includes('/observations')) {
+    const toolName = body.tool_name || '?';
+    const toolInput = body.tool_input;
+    const toolSummary = logger.formatTool(toolName, toolInput);
+    return `tool=${toolSummary}`;
+  }
+
+  // Summarize request
+  if (path.includes('/summarize')) {
+    return 'requesting summary';
+  }
+
+  return '';
+}
--- a/Show More
+++ b/Show More