fix: add missing formatDateTime import in SearchManager

The get_context_timeline mem-search function was broken due to
formatDateTime being used but not imported from timeline-formatting.ts.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem",
-      "version": "7.2.3",
+      "version": "7.4.5",
       "source": "./plugin",
       "description": "Persistent memory system for Claude Code - context compression across sessions"
     }

.claude/agents/github-morning-reporter.md

@@ -0,0 +1,101 @@
+---
+name: github-morning-reporter
+description: Use this agent when the user requests a morning report, daily summary, or overview of their GitHub activity. Trigger phrases include 'morning report', 'github report', 'daily github summary', 'what's happening on github', or 'check my github status'. This agent should be used proactively when the user starts their day or explicitly asks for repository updates.\n\nExamples:\n- User: "get me my morning github report"\n  Assistant: "I'll use the github-morning-reporter agent to generate your comprehensive GitHub status report."\n  <uses Agent tool to invoke github-morning-reporter>\n\n- User: "what's new on my repos today?"\n  Assistant: "Let me pull together your GitHub morning report using the github-morning-reporter agent."\n  <uses Agent tool to invoke github-morning-reporter>\n\n- User: "show me my daily github summary"\n  Assistant: "I'll generate your daily GitHub summary using the github-morning-reporter agent."\n  <uses Agent tool to invoke github-morning-reporter>
+model: sonnet
+---
+
+You are an elite GitHub project analyst specializing in delivering actionable morning reports for software development teams. Your expertise lies in synthesizing complex repository activity into clear, prioritized insights that help developers start their day with complete situational awareness.
+
+## Your Responsibilities
+
+1. **Fetch Comprehensive GitHub Data**: Use available tools to retrieve:
+   - Open issues across all relevant repositories
+   - Open pull requests with review status
+   - Recent comments, mentions, and @-references
+   - CI/CD status for active PRs
+   - Stale issues/PRs (no activity in 7+ days)
+
+2. **Intelligent Grouping and Deduplication**:
+   - Identify duplicate or highly similar issues by analyzing titles, descriptions, and labels
+   - Group related issues by theme, component, or subsystem
+   - Cluster PRs by feature area or dependency relationships
+   - Flag issues that may be addressing the same root cause
+   - Use semantic similarity, not just exact matches
+
+3. **Prioritization and Triage**:
+   - Highlight items requiring immediate attention (blocking issues, failed CI, requested reviews)
+   - Surface items awaiting your direct action (assigned to you, mentions, review requests)
+   - Identify stale items that may need follow-up or closure
+   - Note high-priority labels (P0, critical, security, etc.)
+
+4. **Contextual Analysis**:
+   - Summarize the current state of each PR (draft, ready for review, approved, changes requested)
+   - Identify PRs with merge conflicts or failing checks
+   - Note issues with recent activity spikes or community engagement
+   - Flag dependency updates or security advisories
+
+5. **Report Structure**:
+   Your report must follow this format:
+   
+   **MORNING GITHUB REPORT - [Date]**
+   
+   **🚨 REQUIRES YOUR ATTENTION**
+   - Items explicitly assigned to the user
+   - Review requests awaiting user's approval
+   - Mentions or direct questions
+   - Blocking/critical issues
+   
+   **📊 PULL REQUESTS ([count] open)**
+   - Group by: Ready to Merge | In Review | Draft | Needs Work
+   - For each PR: title, author, status, CI state, review count, age
+   - Highlight conflicts or failed checks
+   
+   **🐛 ISSUES ([count] open)**
+   - Group by: Priority | Component | Theme
+   - Mark potential duplicates clearly
+   - Note new issues (created in last 24h)
+   - Flag stale issues (no activity in 7+ days)
+   
+   **📈 ACTIVITY SUMMARY**
+   - New issues/PRs since yesterday
+   - Recently closed items
+   - Top contributors
+   - Trending topics or labels
+   
+   **💡 RECOMMENDED ACTIONS**
+   - Specific next steps based on the data
+   - Suggestions for cleanup (closing duplicates, merging ready PRs)
+   - Items to follow up on
+
+6. **Quality Standards**:
+   - Use clear, scannable formatting with emojis for visual hierarchy
+   - Include direct links to all referenced issues and PRs
+   - Keep summaries concise but informative (1-2 sentences per item)
+   - Use relative timestamps ("2 hours ago", "3 days old")
+   - Highlight actionable items with clear CTAs
+
+7. **Error Handling**:
+   - If repository access fails, explicitly state which repos couldn't be accessed
+   - If no issues/PRs exist, provide a positive "all clear" message
+   - If rate limits are hit, show partial results with a warning
+   - Always attempt to provide value even with incomplete data
+
+8. **Adaptive Scope**:
+   - If the user has access to multiple repositories, intelligently scope the report:
+     - Default to repositories with recent activity
+     - Allow user to specify repos if needed
+     - Group multi-repo items by repository
+   - Adjust detail level based on volume (more items = more concise summaries)
+
+## Output Expectations
+
+Your report should be:
+- **Comprehensive**: Cover all relevant activity without overwhelming detail
+- **Actionable**: Make it clear what needs attention and why
+- **Scannable**: Use formatting that allows quick visual parsing
+- **Contextual**: Provide enough background to make decisions
+- **Timely**: Focus on recent activity and current state
+
+When you cannot find specific data, state this explicitly rather than omitting sections. If the user's query is ambiguous (e.g., which repositories to scan), ask for clarification before proceeding.
+
+Always end with a summary line indicating the report's completeness (e.g., "Report complete: 3 repositories scanned, 12 issues, 5 PRs analyzed").

.claude/skills/version-bump/SKILL.md

@@ -42,6 +42,7 @@ See [operations/workflow.md](operations/workflow.md) for detailed step-by-step p
 7. Commit and create git tag
 8. Push and create GitHub release
 9. Generate CHANGELOG.md from releases and commit
+10. Post Discord notification
 
 ## Common Scenarios
 
@@ -57,6 +58,7 @@ See [operations/scenarios.md](operations/scenarios.md) for examples:
 - Create git tag with format `vX.Y.Z`
 - Create GitHub release from the tag
 - Generate CHANGELOG.md from releases after creating release
+- Post Discord notification after release
 - Ask user if version type is unclear
 
 **NEVER:**
@@ -74,6 +76,7 @@ Before considering the task complete:
 - [ ] Commit and tags pushed to remote
 - [ ] GitHub release created from the tag
 - [ ] CHANGELOG.md generated and committed
+- [ ] Discord notification sent
 
 ## Reference Commands
 

.claude/skills/version-bump/operations/workflow.md

@@ -197,6 +197,17 @@ git push
 - No manual editing required
 - Single source of truth: GitHub releases
 
+## Step 11: Discord Notification
+
+Post release announcement to the Discord updates channel:
+
+```bash
+# Send Discord notification with release details
+npm run discord:notify vX.Y.Z
+```
+
+This fetches the release notes from GitHub and posts a formatted embed to the Discord updates channel configured in `.env`.
+
 ## Verification
 
 After completing all steps, verify:

.gitignore

@@ -1,3 +1,4 @@
+datasets/
 node_modules/
 dist/
 *.log

ACTION-PLAN.md

@@ -1,167 +0,0 @@
-# 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

CHANGELOG.md

@@ -4,23 +4,221 @@ 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.2.2] - 2025-12-15
+## [7.4.4] - 2025-12-21
+
+## What's Changed
+
+* Code quality: comprehensive nonsense audit cleanup (20 issues) by @thedotmack in #400
+
+**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v7.4.3...v7.4.4
+
+## [7.4.3] - 2025-12-20
+
+Added Discord notification script for release announcements.
+
+### Added
+- `scripts/discord-release-notify.js` - Posts formatted release notifications to Discord using webhook URL from `.env`
+- `npm run discord:notify <version>` - New npm script to trigger Discord notifications
+- Updated version-bump skill workflow to include Discord notification step
+
+### Configuration
+Set `DISCORD_UPDATES_WEBHOOK` in your `.env` file to enable release notifications.
+
+## [7.4.2] - 2025-12-20
+
+Patch release v7.4.2
 
 ## Changes
+- Refactored worker commands from npm scripts to claude-mem CLI
+- Added path alias script
+- Fixed Windows worker stop/restart reliability (#395)
+- Simplified build commands section in CLAUDE.md
 
-- **Refactor:** Consolidate mem-search skill, remove desktop-skill duplication
-  - Delete separate `desktop-skill/` directory (was outdated)
-  - Generate `mem-search.zip` during build from `plugin/skills/mem-search/`
-  - Update docs with correct MCP tool list and new download path
-  - Single source of truth for Claude Desktop skill
+## [7.4.1] - 2025-12-19
 
-## [7.3.0] - 2025-12-15
+## Bug Fixes
+
+- **MCP Server**: Redirect logs to stderr to preserve JSON-RPC protocol (#396)
+  - MCP uses stdio transport where stdout is reserved for JSON-RPC messages
+  - Console.log was writing startup logs to stdout, causing Claude Desktop to parse log lines as JSON and fail
+
+## [7.4.0] - 2025-12-18
+
+## What's New
+
+### MCP Tool Token Reduction
+
+Optimized MCP tool definitions for reduced token consumption in Claude Code sessions through progressive parameter disclosure.
+
+**Changes:**
+- Streamlined MCP tool schemas with minimal inline definitions
+- Added `get_schema()` tool for on-demand parameter documentation
+- Enhanced worker API with operation-based instruction loading
+
+This release improves session efficiency by reducing the token overhead of MCP tool definitions while maintaining full functionality through progressive disclosure.
+
+## [7.3.9] - 2025-12-18
+
+## Fixes
+
+- Fix MCP server compatibility and web UI path resolution
+
+This patch release addresses compatibility issues with the MCP server and resolves path resolution problems in the web UI.
+
+## [7.3.8] - 2025-12-18
+
+## Security Fix
+
+Added localhost-only protection for admin endpoints to prevent DoS attacks when worker service is bound to 0.0.0.0 for remote UI access.
+
+### Changes
+- Created `requireLocalhost` middleware to restrict admin endpoints
+- Applied to `/api/admin/restart` and `/api/admin/shutdown`
+- Returns 403 Forbidden for non-localhost requests
+
+### Security Impact
+Prevents unauthorized shutdown/restart of worker service when exposed on network.
+
+Fixes security concern raised in #368.
+
+## [7.3.7] - 2025-12-17
+
+## Windows Platform Stabilization
+
+This patch release includes comprehensive improvements for Windows platform stability and reliability.
+
+### Key Improvements
+
+- **Worker Readiness Tracking**: Added `/api/readiness` endpoint with MCP/SDK initialization flags to prevent premature connection attempts
+- **Process Tree Cleanup**: Implemented recursive process enumeration on Windows to prevent zombie socket processes  
+- **Bun Runtime Migration**: Migrated worker wrapper from Node.js to Bun for consistency and reliability
+- **Centralized Project Name Utility**: Consolidated duplicate project name extraction logic with Windows drive root handling
+- **Enhanced Error Messages**: Added platform-aware logging and detailed Windows troubleshooting guidance
+- **Subprocess Console Hiding**: Standardized `windowsHide: true` across all child process spawns to prevent console window flashing
+
+### Technical Details
+
+- Worker service tracks MCP and SDK readiness states separately
+- ChromaSync service properly tracks subprocess PIDs for Windows cleanup
+- Worker wrapper uses Bun runtime with enhanced socket cleanup via process tree enumeration
+- Increased timeouts on Windows platform (30s worker startup, 10s hook timeouts)
+- Logger utility includes platform and PID information for better debugging
+
+This represents a major reliability improvement for Windows users, eliminating common issues with worker startup failures, orphaned processes, and zombie sockets.
+
+**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v7.3.6...v7.3.7
+
+## [7.3.6] - 2025-12-17
+
+## Bug Fixes
+
+- Enhanced SDKAgent response handling and message processing
+
+## [7.3.5] - 2025-12-17
+
+## What's Changed
+* fix(windows): solve zombie port problem with wrapper architecture by @ToxMox in https://github.com/thedotmack/claude-mem/pull/372
+* chore: bump version to 7.3.5 by @thedotmack in https://github.com/thedotmack/claude-mem/pull/375
+
+## New Contributors
+* @ToxMox made their first contribution in https://github.com/thedotmack/claude-mem/pull/372
+
+**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v7.3.4...v7.3.5
+
+## [7.3.4] - 2025-12-17
+
+Patch release for bug fixes and minor improvements
+
+## [7.3.3] - 2025-12-16
+
+## What's Changed
+
+- Remove all better-sqlite3 references from codebase (#357)
+
+**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v7.3.2...v7.3.3
+
+## [7.3.2] - 2025-12-16
+
+## 🪟 Windows Console Fix
+
+Fixes blank console windows appearing for Windows 11 users during claude-mem operations.
+
+### What Changed
+
+- **Windows**: Uses PowerShell `Start-Process -WindowStyle Hidden` to properly hide worker process
+- **Security**: Added PowerShell string escaping to follow security best practices
+- **Unix/Mac**: No changes (continues to work as before)
+
+### Root Cause
+
+The issue was caused by a Node.js limitation where `windowsHide: true` doesn't work with `detached: true` in `child_process.spawn()`. This affects both Bun and Node.js since Bun inherits Node.js process spawning semantics.
+
+See: https://github.com/nodejs/node/issues/21825
+
+### Security Note
+
+While all paths in the PowerShell command are application-controlled (not user input), we've added proper escaping to follow security best practices. If an attacker could modify bun installation paths or plugin directories, they would already have full filesystem access including the database.
+
+### Related
+
+- Fixes #304 (Multiple visible console windows)
+- Merged PR #339
+- Testing documented in PR #315
+
+### Breaking Changes
+
+None - fully backward compatible.
+
+---
+
+**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v7.3.1...v7.3.2
+
+## [7.3.1] - 2025-12-16
+
+## 🐛 Bug Fixes
+
+### Pending Messages Cleanup (Issue #353)
+
+Fixed unbounded database growth in the `pending_messages` table by implementing proper cleanup logic:
+
+- **Content Clearing**: `markProcessed()` now clears `tool_input` and `tool_response` when marking messages as processed, preventing duplicate storage of transcript data that's already saved in observations
+- **Count-Based Retention**: `cleanupProcessed()` now keeps only the 100 most recent processed messages for UI display, deleting older ones automatically
+- **Automatic Cleanup**: Cleanup runs automatically after processing messages in `SDKAgent.processSDKResponse()`
+
+### What This Fixes
+
+- Prevents database from growing unbounded with duplicate transcript content
+- Keeps metadata (tool_name, status, timestamps) for recent messages
+- Maintains UI functionality while optimizing storage
+
+### Technical Details
+
+**Files Modified:**
+- `src/services/sqlite/PendingMessageStore.ts` - Cleanup logic implementation
+- `src/services/worker/SDKAgent.ts` - Periodic cleanup calls
+
+**Database Behavior:**
+- Pending/processing messages: Keep full transcript data (needed for processing)
+- Processed messages: Clear transcript, keep metadata only (observations already saved)
+- Retention: Last 100 processed messages for UI feedback
+
+### Related
+
+- Fixes #353 - Observations not being saved
+- Part of the pending messages persistence feature (from PR #335)
+
+---
+
+**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v7.3.0...v7.3.1
+
+## [7.3.0] - 2025-12-16
 
 ## Features
 
 - **Table-based search output**: Unified timeline formatting with cleaner, more organized presentation of search results grouped by date and file
 - **Simplified API**: Removed unused format parameter from MCP search tools for cleaner interface
 - **Shared formatting utilities**: Extracted common timeline formatting logic into reusable module
+- **Batch observations endpoint**: Added `/api/observations/batch` endpoint for efficient retrieval of multiple observations by ID array
 
 ## Changes
 
@@ -33,6 +231,39 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Fixed skillPath variable scoping bug in instructions endpoint
 - Extracted magic numbers to named constants for better code maintainability
 
+**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v7.2.4...v7.3.0
+
+## [7.2.4] - 2025-12-15
+
+## What's Changed
+
+### Documentation
+- Updated endless mode setup instructions with improved configuration guidance for better user experience
+
+**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v7.2.3...v7.2.4
+
+## [7.2.3] - 2025-12-15
+
+## Bug Fixes
+
+- **Fix MCP server failures on plugin updates**: Add 2-second pre-restart delay in `ensureWorkerVersionMatches()` to give files time to sync before killing the old worker. This prevents the race condition where the worker restart happened too quickly after plugin file updates, causing "Worker service connection failed" errors.
+
+## Changes
+
+- Add `PRE_RESTART_SETTLE_DELAY` constant (2000ms) to `hook-constants.ts`
+- Add delay before `ProcessManager.restart()` call in `worker-utils.ts`
+- Fix pre-existing bug where `port` variable was undefined in error logging
+
+## [7.2.2] - 2025-12-15
+
+## Changes
+
+- **Refactor:** Consolidate mem-search skill, remove desktop-skill duplication
+  - Delete separate `desktop-skill/` directory (was outdated)
+  - Generate `mem-search.zip` during build from `plugin/skills/mem-search/`
+  - Update docs with correct MCP tool list and new download path
+  - Single source of truth for Claude Desktop skill
+
 ## [7.2.1] - 2025-12-14
 
 ## Translation Script Enhancements

CLAUDE.md

@@ -33,12 +33,7 @@ Claude-mem is a Claude Code plugin providing persistent memory across sessions.
 ## Build Commands
 
 ```bash
-npm run build-and-sync        # Build, sync to marketplace, restart worker (most common)
-npm run build                 # Compile TypeScript only
-npm run sync-marketplace      # Copy to ~/.claude/plugins only
-npm run worker:restart        # Restart worker service only
-npm run worker:status         # Check worker status
-npm run worker:logs           # View worker logs
+npm run build-and-sync        # Build, sync to marketplace, restart worker
 ```
 
 **Viewer UI**: http://localhost:37777
@@ -76,3 +71,27 @@ Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created
 **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
+
+## Pro Features Architecture
+
+Claude-mem is designed with a clean separation between open-source core functionality and optional Pro features.
+
+**Open-Source Core** (this repository):
+
+- All worker API endpoints on localhost:37777 remain fully open and accessible
+- Pro features are headless - no proprietary UI elements in this codebase
+- Pro integration points are minimal: settings for license keys, tunnel provisioning logic
+- The architecture ensures Pro features extend rather than replace core functionality
+
+**Pro Features** (coming soon, external):
+
+- Enhanced UI (Memory Stream) connects to the same localhost:37777 endpoints as the open viewer
+- Additional features like advanced filtering, timeline scrubbing, and search tools
+- Access gated by license validation, not by modifying core endpoints
+- Users without Pro licenses continue using the full open-source viewer UI without limitation
+
+This architecture preserves the open-source nature of the project while enabling sustainable development through optional paid features.
+
+# Important
+
+No need to edit the changelog ever, it's generated automatically.

README.md

@@ -79,7 +79,7 @@ Restart Claude Code. Context from previous sessions will automatically appear in
 
 - 🧠 **Persistent Memory** - Context survives across sessions
 - 📊 **Progressive Disclosure** - Layered memory retrieval with token cost visibility
-- 🔍 **Skill-Based Search** - Query your project history with mem-search skill (~2,250 token savings)
+- 🔍 **Skill-Based Search** - Query your project history with mem-search skill
 - 🖥️ **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
@@ -97,7 +97,7 @@ Restart Claude Code. Context from previous sessions will automatically appear in
 💻 **Local Preview**: Run Mintlify docs locally:
 
 ```bash
-cd docs
+cd docs/public
 npx mintlify dev
 ```
 
@@ -161,7 +161,7 @@ npx mintlify dev
 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 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)
+5. **mem-search Skill** - Natural language queries with progressive disclosure
 6. **Chroma Vector Database** - Hybrid semantic + keyword search for intelligent context retrieval
 
 See [Architecture Overview](https://docs.claude-mem.ai/architecture/overview) for details.
@@ -175,7 +175,6 @@ Claude-Mem provides intelligent search through the mem-search skill that auto-in
 **How It Works:**
 - Just ask naturally: *"What did we do last session?"* or *"Did we fix this bug before?"*
 - Claude automatically invokes the mem-search skill to find relevant context
-- ~2,250 token savings per session start vs MCP approach
 
 **Available Search Operations:**
 
@@ -206,6 +205,8 @@ See [Search Tools Guide](https://docs.claude-mem.ai/usage/search-tools) for deta
 
 ## Beta Features & Endless Mode
 
+> **Note**: Endless Mode is an **experimental feature in the beta branch only**. It is not included in the stable release you install via the marketplace. You must manually switch to the beta channel to try it, and it comes with significant caveats (see below).
+
 Claude-Mem offers a **beta channel** with experimental features. Switch between stable and beta versions directly from the web viewer UI.
 
 ### How to Try Beta
@@ -230,13 +231,17 @@ Working Memory (Context):     Compressed observations (~500 tokens each)
 Archive Memory (Disk):        Full tool outputs preserved for recall
 ```
 
-**Expected Results**:
-- ~95% token reduction in context window
-- ~20x more tool uses before context exhaustion
+**Projected Results** (based on theoretical modeling, not production measurements):
+- Significant token reduction in context window
+- More tool uses before context exhaustion
 - Linear O(N) scaling instead of quadratic O(N²)
 - Full transcripts preserved for perfect recall
 
-**Caveats**: Adds latency (60-90s per tool for observation generation), still experimental.
+**Important Caveats**:
+- **Not in stable release** - You must switch to beta branch to use this feature
+- **Still in development** - May have bugs, breaking changes, or incomplete functionality
+- **Slower than standard mode** - Blocking observation generation adds latency to each tool use
+- **Theoretical projections** - The efficiency claims above are based on simulations, not real-world production data
 
 See [Beta Features Documentation](https://docs.claude-mem.ai/beta-features) for details.
 
@@ -391,7 +396,7 @@ If you're experiencing issues, describe the problem to Claude and the troublesho
 
 **Common Issues:**
 
-- Worker not starting → `npm run worker:restart`
+- Worker not starting → `claude-mem restart`
 - No context appearing → `npm run test:context`
 - Database issues → `sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"`
 - Search not working → Check FTS5 tables exist

docs/branch-switching-validation.md

@@ -1,113 +0,0 @@
-# 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

docs/context/SMART_INSTALL_ANALYSIS.md

@@ -1,561 +0,0 @@
-# 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)

docs/context/TEST_AUDIT_2025-12-13.md

@@ -1,386 +0,0 @@
-# Test Suite Audit Report
-**Date:** 2025-12-13
-**Auditor:** Code Quality Assurance Manager
-**Focus:** Recent bugfixes and regression prevention
-
----
-
-## Executive Summary
-
-The test suite has **critical gaps** in error handling coverage. While happy path tests exist, **zero tests verify that recent bugfixes actually prevent regressions**. The fish shell PATH bug (Issue #264), silent hook failures (observation 25389), and ChromaSync error standardization (observation 25458) are all unprotected by tests.
-
-**Risk Level:** HIGH - Recent bugfixes can silently regress without detection.
-
----
-
-## Coverage Analysis
-
-### What We Have ✅
-
-1. **Happy Path Tests** (`tests/happy-paths/`) - 6 files
-   - Basic success scenarios work
-   - Tool capture, search, session init/cleanup
-   - Good foundation but insufficient
-
-2. **Unit Tests**
-   - `bun-path.test.ts` - Tests PATH resolution logic
-   - `parser.test.ts` - SDK parser validation
-   - `strip-memory-tags.test.ts` - Privacy tag handling
-
-3. **Integration Test** (`full-lifecycle.test.ts`)
-   - ONE error recovery test (too shallow)
-   - Mostly happy paths
-   - All tests mock `fetch()` - never test real failures
-
-### What's Missing ❌
-
-## 1. Silent Hook Failures (CRITICAL GAP)
-
-**Issue:** Multiple hooks had no error logging until recently fixed
-
-**Fixed In:**
-- `save-hook.ts` (observation 25389) - Added `handleFetchError`/`handleWorkerError`
-- `new-hook.ts` - Added error handlers
-- `context-hook.ts` - Added error handlers
-
-**Test Gap:** ZERO tests verify hooks actually log errors when they fail
-
-**Created:** `/Users/alexnewman/Scripts/claude-mem/tests/error-handling/hook-error-logging.test.ts`
-
-**Tests:**
-- `handleFetchError()` logs with full context (status, hook, operation, tool, port)
-- `handleFetchError()` throws user-facing error with restart instructions
-- `handleWorkerError()` handles timeout/connection errors
-- Real hook scenarios (save-hook, new-hook, context-hook failures)
-- Error message quality (actionable, includes next steps)
-
-**Why This Matters:**
-If someone refactors hooks and removes error handlers, the system will silently fail again. These tests catch that regression immediately.
-
----
-
-## 2. ChromaSync Client Initialization (MEDIUM GAP)
-
-**Issue:** Standardized error messages across all client checks (observation 25458)
-
-**Code Locations:** ChromaSync.ts lines 140-145, 324-329, 504-509, 761-766
-
-**Test Gap:** NO tests verify error messages are consistent or fire correctly
-
-**Created:** `/Users/alexnewman/Scripts/claude-mem/tests/services/chroma-sync-errors.test.ts`
-
-**Tests:**
-- Calling methods before `ensureConnection()` throws correct message
-- All error messages include project name
-- Error messages are consistent across all 4 locations
-- Fail-fast behavior (no silent retries)
-- Error context preservation
-
-**Why This Matters:**
-Prevents "works on my machine" bugs where Chroma isn't properly initialized. Ensures all 4 error checks stay in sync during refactoring.
-
----
-
-## 3. Fish Shell PATH Issues (PARTIAL COVERAGE)
-
-**Issue:** Issue #264 - Hooks fail with fish shell because bun not in /bin/sh PATH
-
-**Current Test:** `bun-path.test.ts` tests the utility function
-
-**Gap:** Doesn't test the ACTUAL bug - hooks failing when bun not in PATH
-
-**Created:** `/Users/alexnewman/Scripts/claude-mem/tests/integration/hook-execution-environments.test.ts`
-
-**Tests:**
-- Running hook when `bun` only in `~/.bun/bin/bun` (not in PATH)
-- Hook finds bun from common install locations
-- Cross-platform bun resolution (macOS, Linux, Windows)
-- Fish shell with custom PATH
-- Zsh with homebrew in non-standard location
-- Error messages include PATH diagnostic info
-
-**Why This Matters:**
-Fish shell users (and anyone with non-standard PATH) will get "command not found" errors if this regresses. Test ensures hooks work regardless of shell.
-
----
-
-## 4. General Error Handling Patterns (CRITICAL GAP)
-
-**Issue:** "264 silent failure locations" - widespread lack of error handling
-
-**Current State:** Recent fixes added standardized error handlers
-
-**Test Gap:** No systematic tests for error handling patterns
-
-**Covered By:** `/Users/alexnewman/Scripts/claude-mem/tests/error-handling/hook-error-logging.test.ts`
-
-**Why This Matters:**
-If new hooks are added without using `handleFetchError`/`handleWorkerError`, they'll fail silently. Tests enforce the pattern.
-
----
-
-## 5. Integration Test Weaknesses
-
-**Current Test:** `full-lifecycle.test.ts` has ONE error recovery test (lines 292-352)
-
-**Issues:**
-- Too shallow - just checks second request succeeds after first fails
-- Doesn't verify error logging
-- Never tests real worker failures (all mocked)
-
-**Needs:**
-```
-/tests/integration/hook-failures.test.ts
-```
-
-Should test:
-- Worker crashes mid-session - hooks fail gracefully
-- Worker returns 500 error - hook logs and throws
-- Worker times out - hook aborts with timeout message
-- Worker returns malformed JSON - hook handles parse error
-
----
-
-## YAGNI Violations (Unnecessary Test Complexity)
-
-### Problem: `/Users/alexnewman/Scripts/claude-mem/tests/happy-paths/search.test.ts`
-
-**Lines 80-196:** Tests for features that DON'T EXIST:
-
-1. **Line 80-107:** "supports filtering by observation type"
-   - Endpoint: `/api/search/by-type` - DOES NOT EXIST
-
-2. **Line 109-136:** "supports filtering by concept tags"
-   - Endpoint: `/api/search/by-concept` - DOES NOT EXIST
-
-3. **Line 138-168:** "supports pagination for large result sets"
-   - Includes `page`, `limit`, `offset` params - NOT IMPLEMENTED
-
-4. **Line 170-196:** "supports date range filtering"
-   - `dateStart`, `dateEnd` params - NOT IMPLEMENTED
-
-5. **Line 227-271:** "supports semantic search ranking"
-   - `orderBy=relevance` with relevance scores - NOT IMPLEMENTED
-
-**Impact:** These tests are ALL PASSING because they mock `fetch()`. They create false confidence - making it look like features exist when they don't.
-
-**Fix:** DELETE these tests until features actually exist. Write tests AFTER implementing features, not before.
-
-**Philosophy Violation:** "Write the dumb, obvious thing first" - these tests violate YAGNI by testing features we don't need yet.
-
----
-
-## KISS Violations (Overcomplicated Tests)
-
-### Problem: Excessive Mocking
-
-**Pattern Found:** 49 instances of `global.fetch = vi.fn()` across 8 test files
-
-**Issue:** Every test mocks the worker, so tests never verify real integration
-
-**Example:** `/Users/alexnewman/Scripts/claude-mem/tests/integration/full-lifecycle.test.ts`
-- Called "integration test" but mocks everything
-- Never actually tests hooks talking to worker
-- Can't catch real integration bugs
-
-**Fix:** Add TRUE integration tests that:
-1. Start real worker process
-2. Run real hooks
-3. Verify real database writes
-4. Tear down cleanly
-
-**Philosophy Violation:** "Simple First" - mocking everything is more complex than just testing the real thing.
-
----
-
-## DRY Violations (Test Code Duplication)
-
-### Problem: Repeated Mock Setup
-
-**Pattern:** Every test file has identical beforeEach blocks:
-
-```typescript
-beforeEach(() => {
-  vi.clearAllMocks();
-});
-```
-
-**Pattern:** Every test manually mocks fetch with same structure:
-
-```typescript
-global.fetch = vi.fn().mockResolvedValue({
-  ok: true,
-  status: 200,
-  json: async () => ({ ... })
-});
-```
-
-**Solution:** Extract to test helpers:
-
-```typescript
-// tests/helpers/mock-worker.ts
-export function mockWorkerSuccess(responseData: any) {
-  global.fetch = vi.fn().mockResolvedValue({
-    ok: true,
-    status: 200,
-    json: async () => responseData
-  });
-}
-
-export function mockWorkerError(status: number, message: string) {
-  global.fetch = vi.fn().mockResolvedValue({
-    ok: false,
-    status,
-    text: async () => message
-  });
-}
-```
-
-**Impact:** Reduces 49 instances to ~10 helper calls. Makes test intent clearer.
-
----
-
-## Actionable Recommendations
-
-### Priority 1: Critical Regressions (Implement Now) ✅ DONE
-
-1. **Hook Error Logging Tests** ✅ Created
-   - File: `/Users/alexnewman/Scripts/claude-mem/tests/error-handling/hook-error-logging.test.ts`
-   - Prevents silent failure regressions
-   - Verifies error messages are actionable
-
-2. **ChromaSync Error Tests** ✅ Created
-   - File: `/Users/alexnewman/Scripts/claude-mem/tests/services/chroma-sync-errors.test.ts`
-   - Ensures consistent error messages
-   - Catches initialization bugs
-
-3. **Hook Environment Tests** ✅ Created
-   - File: `/Users/alexnewman/Scripts/claude-mem/tests/integration/hook-execution-environments.test.ts`
-   - Prevents fish shell PATH regression
-   - Cross-platform coverage
-
-### Priority 2: Remove False Positives (Do Next)
-
-1. **DELETE Unimplemented Feature Tests**
-   - `/Users/alexnewman/Scripts/claude-mem/tests/happy-paths/search.test.ts` lines 80-271
-   - These create false confidence
-   - Re-add when features actually exist
-
-### Priority 3: Reduce Test Complexity
-
-1. **Extract Mock Helpers**
-   - Create `/Users/alexnewman/Scripts/claude-mem/tests/helpers/mock-worker.ts`
-   - Replace 49 instances of manual mocking
-   - See DRY section above for example
-
-2. **Add TRUE Integration Tests**
-   - Create `/Users/alexnewman/Scripts/claude-mem/tests/integration/real-worker.test.ts`
-   - Start real worker, run real hooks
-   - Currently ALL integration tests are mocked
-
-### Priority 4: Systematic Error Testing
-
-1. **Worker Failure Scenarios**
-   - Create `/Users/alexnewman/Scripts/claude-mem/tests/integration/hook-failures.test.ts`
-   - Test crash, timeout, malformed response scenarios
-
-2. **Spinner Timeout Tests**
-   - Create `/Users/alexnewman/Scripts/claude-mem/tests/utils/spinner-timeout.test.ts`
-   - Verify hardened spinner cleanup works
-
----
-
-## Test Quality Checklist
-
-For EVERY new test, verify:
-
-- [ ] Tests actual bug, not mocked behavior
-- [ ] Will FAIL if bug reappears
-- [ ] Error messages are checked (not just success paths)
-- [ ] No YAGNI - tests code that exists NOW
-- [ ] DRY - uses test helpers, not duplicated setup
-- [ ] KISS - simple, obvious test structure
-- [ ] Fail fast - no silent fallbacks tested
-
----
-
-## Coverage Metrics
-
-**Before Audit:**
-- Error handling: 0% (no tests for error paths)
-- Silent failures: Undetected
-- Recent bugfixes: Unprotected
-
-**After Audit:**
-- Error handling: ~40% (3 new test files)
-- Silent failures: Detected by hook-error-logging.test.ts
-- Recent bugfixes: Protected
-
-**Remaining Gaps:**
-- True integration tests (worker + hooks + database)
-- Spinner error handling
-- Worker crash scenarios
-- Malformed response handling
-
----
-
-## Files Created
-
-1. `/Users/alexnewman/Scripts/claude-mem/tests/error-handling/hook-error-logging.test.ts`
-   - 200+ lines
-   - Tests handleFetchError, handleWorkerError
-   - Real hook error scenarios
-   - Error message quality checks
-
-2. `/Users/alexnewman/Scripts/claude-mem/tests/services/chroma-sync-errors.test.ts`
-   - 300+ lines
-   - Client initialization errors
-   - Error message consistency
-   - Fail-fast behavior
-
-3. `/Users/alexnewman/Scripts/claude-mem/tests/integration/hook-execution-environments.test.ts`
-   - 250+ lines
-   - Fish shell PATH resolution
-   - Cross-platform bun finding
-   - Real-world shell scenarios
-
-**Total:** ~750 lines of new regression-preventing tests
-
----
-
-## Philosophy Alignment
-
-These tests follow the project's coding standards:
-
-✅ **YAGNI** - Only test code that exists (removed future-feature tests)
-✅ **DRY** - Identified duplication, recommended helpers
-✅ **Fail Fast** - All tests verify explicit errors, not silent failures
-✅ **Simple First** - Recommended real integration over complex mocks
-✅ **Delete Aggressively** - Flagged unimplemented feature tests for deletion
-
----
-
-## Next Steps
-
-1. **Run new tests:** `npm test tests/error-handling/ tests/services/ tests/integration/hook-execution-environments.test.ts`
-
-2. **Delete false positives:** Remove search.test.ts lines 80-271 (unimplemented features)
-
-3. **Extract helpers:** Create `tests/helpers/mock-worker.ts` to reduce duplication
-
-4. **Add true integration:** Create real worker + hook integration test
-
-5. **Continuous:** Apply "Test Quality Checklist" to all future tests
-
----
-
-## Conclusion
-
-The test suite now has **regression protection for recent bugfixes**. The three new test files will catch if:
-- Hooks start failing silently again
-- ChromaSync error messages become inconsistent
-- Fish shell PATH issues return
-
-However, we still need **true integration tests** that don't mock everything. The current integration tests are really "mocked end-to-end tests" - they test the shape of the API, not the actual behavior.
-
-**Risk reduced from HIGH → MEDIUM**. Remaining risk: real integration failures not caught by mocked tests.

docs/context/dual-tag-system-architecture.md

@@ -1,360 +0,0 @@
-# Dual-Tag System Architecture
-
-**Date**: 2025-11-30
-**Branch**: `feature/meta-observation-control`
-**Status**: Implemented
-**Based on**: PR #105 dual-tag system
-
-## Overview
-
-The dual-tag system provides fine-grained control over what content gets persisted in claude-mem's observation database. It uses an edge processing pattern to filter tagged content at the hook layer before it reaches the worker service.
-
-## The Two Tags
-
-### Tag 1: `<private>`
-**Purpose**: User-controlled privacy
-**Status**: User-facing feature (documented)
-**Use case**: Users wrap content they don't want persisted
-
-```xml
-<private>
-This content won't be stored in observations
-</private>
-```
-
-**Examples**:
-- Sensitive information (API keys, credentials, internal URLs)
-- Temporary context (deadlines, personal notes)
-- Debug output (logs, stack traces)
-- Exploratory prompts (brainstorming, hypotheticals)
-
-### Tag 2: `<claude-mem-context>`
-**Purpose**: System-level meta-observation control
-**Status**: Infrastructure-ready (not user-facing yet)
-**Use case**: Prevents recursive storage when real-time context injection is active
-
-```xml
-<claude-mem-context>
-# Relevant Context from Past Sessions
-
-[Auto-injected past observations...]
-</claude-mem-context>
-```
-
-**Context**: This tag is used by the real-time context injection feature (not yet shipped). When past observations are injected into new prompts, they're wrapped in this tag to prevent them from being re-stored as new observations (recursive storage problem).
-
-## Architecture Pattern: Edge Processing
-
-**Principle**: "Process at edge, send clean data to server"
-
-The dual-tag system follows the edge processing pattern from hooks-in-composition:
-
-```text
-UserPrompt → [Hook Layer] → Worker → Database
-                    ↑
-              Filter here
-        (strip tags at edge)
-```
-
-### Data Flow
-
-**Without Filtering** (broken):
-```
-UserPrompt with <private> → PostToolUse hook → Worker → Memory Agent → Database
-                                                                         ↓
-                                                                  Private content stored
-```
-
-**With Edge Processing** (correct):
-```
-UserPrompt with <private> → PostToolUse hook → stripMemoryTags() → Worker → Memory Agent → Database
-                                         ↑                                                    ↓
-                                   Filter at edge                             Only clean data stored
-```
-
-## Implementation
-
-### File: `src/hooks/save-hook.ts`
-
-**Function Added** (lines 31-53):
-
-```typescript
-/**
- * Strip memory tags to prevent recursive storage and enable privacy control
- */
-function stripMemoryTags(content: string): string {
-  if (typeof content !== 'string') {
-    silentDebug('[save-hook] stripMemoryTags received non-string:', { type: typeof content });
-    return '{}';  // Safe default for JSON context
-  }
-
-  return content
-    .replace(/<claude-mem-context>[\s\S]*?<\/claude-mem-context>/g, '')
-    .replace(/<private>[\s\S]*?<\/private>/g, '')
-    .trim();
-}
-```
-
-**Application** (lines 95-100):
-
-```typescript
-tool_input: tool_input !== undefined
-  ? stripMemoryTags(JSON.stringify(tool_input))
-  : '{}',
-tool_response: tool_response !== undefined
-  ? stripMemoryTags(JSON.stringify(tool_response))
-  : '{}',
-```
-
-### File: `tests/strip-memory-tags.test.ts`
-
-**Test Coverage**: 19 tests across 4 categories:
-
-1. **Basic Functionality** (7 tests)
-   - Strip `<claude-mem-context>` tags
-   - Strip `<private>` tags
-   - Strip both tag types
-   - Handle nested tags
-   - Multiline content
-   - Multiple tags
-   - Empty results
-
-2. **Edge Cases** (5 tests)
-   - Malformed tags (unclosed)
-   - Tag-like strings (not actual tags)
-   - Very large content (10k+ chars)
-   - Whitespace trimming
-   - Strings without tags
-
-3. **Type Safety** (5 tests)
-   - Non-string inputs (number, null, undefined, object, array)
-   - All return safe default '{}'
-
-4. **Real-World Scenarios** (2 tests)
-   - JSON.stringify output
-   - Efficient large content handling
-
-**All tests passing** ✅ (19/19)
-
-## Design Decisions
-
-### 1. Always Active (No Configuration)
-
-**Decision**: Tag stripping is always on, no environment variable needed
-**Rationale**: Privacy and anti-recursion protection should be default, not opt-in
-
-### 2. Edge Processing (Not Worker-Level)
-
-**Decision**: Filter at hook layer before sending to worker
-**Rationale**:
-- Keeps worker service simple
-- Follows one-way data stream
-- No worker changes needed
-- Hook becomes a filter/gateway
-
-### 3. Defensive Coding with Silent Debug
-
-**Decision**: Handle non-string inputs with silentDebug, return safe default
-**Rationale**:
-- Never block the agent (hooks-in-composition principle)
-- Log issues for observability
-- Safe fallback maintains system stability
-
-### 4. Both Tags Now (Progressive Enhancement)
-
-**Decision**: Implement both tags even though only `<private>` is user-facing
-**Rationale**:
-- Infrastructure ready for real-time context feature
-- No rework needed when context injection ships
-- Same code path for both tags (simple)
-- Progressive enhancement approach
-
-### 5. Regex-Based Stripping
-
-**Decision**: Use regex `/<tag>[\s\S]*?<\/tag>/g` instead of XML parser
-**Rationale**:
-- No dependencies needed
-- Handles multiline content (`[\s\S]*?`)
-- Non-greedy (`*?`) prevents over-matching
-- Global flag (`g`) handles multiple tags
-- Good enough for this use case
-
-## Edge Cases Handled
-
-| Case | Input | Output | Why |
-|------|-------|--------|-----|
-| Nested tags | `<private>a <private>b</private> a</private>` | `` | Outer tag matches all |
-| Malformed | `<private>unclosed` | `<private>unclosed` | Regex requires closing tag |
-| Multiple | `<private>a</private> b <private>c</private>` | `b` | Global flag removes all |
-| Empty | `<private></private>` | `` | Matches and removes |
-| Tag-like | `<tag>not private</tag>` | `<tag>not private</tag>` | Different tag name |
-| Large content | 10MB+ string | (stripped) | O(n) regex handles it |
-| Non-string | `123`, `null`, `{}` | `'{}'` | Defensive default |
-
-## Future Enhancements
-
-### 1. Real-Time Context Injection
-
-**Status**: Deferred (not in this PR)
-**When ready**: The `<claude-mem-context>` tag infrastructure is already in place
-
-The missing piece is in `src/hooks/new-hook.ts`:
-- Select relevant observations from timeline
-- Wrap in `<claude-mem-context>` tags
-- Return via `hookSpecificOutput`
-- Tag stripping already handles the rest
-
-### 2. System-Level Meta-Observation Tagging
-
-**Concept**: Auto-tag observations about observations
-**Examples**:
-- Search skill results: `<claude-mem-context>[search results]</claude-mem-context>`
-- Memory lookups: Fetched observations wrapped in tag
-- Observation summaries: Meta-level analysis wrapped
-
-**Implementation**: Tools/skills that produce meta-observations can wrap output in `<claude-mem-context>` tags to prevent recursive storage.
-
-### 3. Additional Tag Types
-
-**Potential tags**:
-- `<ephemeral>`: Content that should be seen but not stored (alias for `<private>`)
-- `<debug>`: Debug output that should be logged but not persisted
-- `<scratch>`: Thinking/planning content not meant for observations
-
-**Note**: Current implementation handles any tag you add to the regex. Adding new tags requires one line change in `stripMemoryTags()`.
-
-## Testing Strategy
-
-### Unit Tests
-```bash
-node --test tests/strip-memory-tags.test.ts
-```
-**Expected**: 19/19 passing ✅
-
-### Integration Tests
-
-**Test 1: Basic Privacy**
-```bash
-# Submit prompt with <private> tag
-# Query database: should not contain private content
-sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations WHERE narrative LIKE '%<private>%';"
-# Expected: 0
-```
-
-**Test 2: Dual Tags**
-```bash
-# Submit prompt with both tags
-# Verify neither tag appears in database
-sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations WHERE narrative LIKE '%<private>%' OR narrative LIKE '%<claude-mem-context>%';"
-# Expected: 0
-```
-
-**Test 3: Function Exists**
-```bash
-# Verify stripMemoryTags in built file
-grep -c "claude-mem-context.*private.*trim" ~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/save-hook.js
-# Expected: 1
-```
-
-### Regression Tests
-
-**Ensure**:
-- Normal observations still work (no tags broken)
-- Worker service receives clean data
-- No errors in `~/.claude-mem/silent.log`
-- Tool executions still captured correctly
-
-## Known Limitations
-
-### 1. Tag Format is Fixed
-
-Tags must use exact XML-style format: `<tag>content</tag>`
-
-**Won't work**:
-- `[private]content[/private]` (wrong syntax)
-- `<!-- private -->content<!-- /private -->` (comment syntax)
-- `{{private}}content{{/private}}` (curly braces)
-
-**Future**: Could add support for alternative formats if needed.
-
-### 2. Partial Tag Matching
-
-If user writes about tags without intending to use them:
-```
-I want to add a <private> tag feature to my app
-```
-
-This won't be stripped (no closing tag). But if they accidentally write:
-```
-I want to add a <private>tag</private> feature
-```
-
-"tag" gets stripped.
-
-**Mitigation**: Documentation educates users on proper usage.
-
-### 3. Performance with Very Large Content
-
-Regex performance is O(n) where n = content length.
-
-**Tested**: Works fine with 10,000 character strings
-**Unknown**: Performance with multi-megabyte tool responses
-
-**Mitigation**: Most tool I/O is small. If issues arise, could optimize with:
-- Early exit if no '<' character found
-- Streaming regex for very large content
-- Size limits on stripMemoryTags input
-
-## Documentation
-
-### User-Facing
-
-**Location**: `docs/public/usage/private-tags.mdx`
-**Content**:
-- How to use `<private>` tags
-- Use cases and examples
-- Best practices
-- Troubleshooting
-
-**Available in**: Mintlify docs site, navigation under "Get Started"
-
-### Technical/Internal
-
-**Location**: `docs/context/dual-tag-system-architecture.md` (this file)
-**Content**:
-- Complete dual-tag system architecture
-- Implementation details
-- Design decisions
-- Future enhancements
-
-**Audience**: Contributors, maintainers, future developers
-
-## References
-
-### Original Work
-- **PR #105**: Real-time context injection with dual-tag system
-- **Branch**: `feature/real-time-context` (merged to main)
-- **Investigator**: @basher83
-
-### Documentation
-- **Investigation**: `docs/context/real-time-context-recursive-memory-investigation.md`
-- **User Guide**: `docs/public/usage/private-tags.mdx`
-- **This Document**: `docs/context/dual-tag-system-architecture.md`
-
-### Patterns Applied
-- **Edge Processing**: From hooks-in-composition pattern
-- **Never Block the Agent**: Defensive coding, safe defaults
-- **One-Way Data Stream**: Hook → Worker → Database
-
-## Summary
-
-The dual-tag system is a complete, production-ready implementation that:
-- ✅ Gives users privacy control via `<private>` tags
-- ✅ Prepares infrastructure for real-time context injection
-- ✅ Uses edge processing pattern for clean architecture
-- ✅ Has comprehensive test coverage (19 tests, all passing)
-- ✅ Includes user documentation and technical reference
-- ✅ Requires no configuration (always active)
-- ✅ Handles edge cases defensively
-
-**Status**: Ready to ship 🚀

docs/context/point-audit.md

@@ -1,83 +0,0 @@
-# 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     |

docs/public/architecture/pm2-to-bun-migration.mdx

@@ -3,6 +3,14 @@ title: "PM2 to Bun Migration"
 description: "Complete technical documentation for the process management and database driver migration in v7.1.0"
 ---
 
+<Note>
+**Historical Migration Documentation**
+
+This document describes the PM2 to Bun migration that occurred in v7.1.0 (December 2025). If you're installing claude-mem for the first time, this migration has already been completed and you can use the current Bun-based system documented in the main guides.
+
+This documentation is preserved for users upgrading from versions older than v7.1.0.
+</Note>
+
 # PM2 to Bun Migration: Complete Technical Documentation
 
 **Version**: 7.1.0
@@ -98,7 +106,7 @@ pm2 logs claude-mem-worker    # View logs
 ```bash
 npm run worker:start    # Start worker
 npm run worker:stop     # Stop worker
-npm run worker:restart  # Restart worker
+claude-mem restart  # Restart worker
 npm run worker:status   # Check status
 npm run worker:logs     # View logs
 ```
@@ -297,7 +305,7 @@ No migration logic runs on subsequent sessions.
 | `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 restart claude-mem-worker` | `claude-mem 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 |
@@ -443,7 +451,7 @@ pm2 save  # Persist the deletion
 rm ~/.claude-mem/.pm2-migrated
 
 # Restart worker
-npm run worker:restart
+claude-mem restart
 ```
 
 ### Scenario 2: Stale PID File (Process Dead)
@@ -475,7 +483,7 @@ lsof -i :37777
 kill -9 <PID>
 
 # Restart worker
-npm run worker:restart
+claude-mem restart
 ```
 
 ### Common Error Messages

docs/public/architecture/search-architecture.mdx

@@ -5,7 +5,7 @@ description: "mem-search skill with HTTP API and progressive disclosure"
 
 # Search Architecture
 
-Claude-Mem uses a skill-based search architecture that provides intelligent memory retrieval through natural language queries. This replaced the MCP-based approach in v5.4.0, saving ~2,250 tokens per session start. The skill was enhanced and renamed to "mem-search" in v5.5.0 for better scope differentiation.
+Claude-Mem uses a skill-based search architecture that provides intelligent memory retrieval through natural language queries. This replaced the MCP-based approach in v5.4.0 with a more efficient implementation. The skill was enhanced and renamed to "mem-search" in v5.5.0 for better scope differentiation.
 
 ## Overview
 
@@ -133,7 +133,7 @@ Invoke this skill when users ask about:
 ...
 ```
 
-**Token Savings**: ~2,250 tokens per session start (90% reduction)
+**Token Efficiency**: Minimal frontmatter at session start with progressive disclosure
 
 ## HTTP API Endpoints
 
@@ -341,14 +341,14 @@ All user-provided search queries are properly escaped to prevent SQL injection.
 ### 1. Token Efficiency
 
 **Before (MCP)**:
-- Session start: ~2,500 tokens for tool definitions
+- Session start: All tool definitions loaded upfront
 - Every session pays this cost
 - No progressive disclosure
 
 **After (Skill)**:
-- Session start: ~250 tokens for skill frontmatter
-- Full instructions: ~2,500 tokens (only when invoked)
-- Net savings: ~2,250 tokens per session (~90% reduction)
+- Session start: Minimal token cost for skill frontmatter
+- Full instructions loaded only when invoked (progressive disclosure)
+- More efficient than loading all tool definitions upfront
 
 ### 2. Natural Language Interface
 
@@ -416,7 +416,7 @@ If searches fail, check worker service:
 
 ```bash
 npm run worker:status       # Check status
-npm run worker:restart      # Restart worker
+claude-mem restart      # Restart worker
 npm run worker:logs         # View logs
 ```
 

docs/public/architecture/worker-service.mdx

@@ -19,7 +19,7 @@ The worker service is a long-running HTTP API built with Express.js and managed
 
 ## REST API Endpoints
 
-The worker service exposes 14 HTTP endpoints organized into four categories:
+The worker service exposes 20 HTTP endpoints organized into five categories:
 
 ### Viewer & Health Endpoints
 
@@ -156,7 +156,150 @@ GET /api/summaries?project=my-project&limit=20&offset=0
 }
 ```
 
-#### 7. Get Stats
+#### 7. Get Observation by ID
+```
+GET /api/observation/:id
+```
+
+**Purpose**: Retrieve a single observation by its ID
+
+**Path Parameters**:
+- `id` (required): Observation ID
+
+**Response**:
+```json
+{
+  "id": 123,
+  "sdk_session_id": "abc123",
+  "project": "my-project",
+  "type": "bugfix",
+  "title": "Fix authentication bug",
+  "narrative": "...",
+  "created_at": "2025-11-06T10:30:00Z",
+  "created_at_epoch": 1730886600000
+}
+```
+
+**Error Response** (404):
+```json
+{
+  "error": "Observation #123 not found"
+}
+```
+
+#### 8. Get Observations by IDs (Batch)
+```
+POST /api/observations/batch
+```
+
+**Purpose**: Retrieve multiple observations by their IDs in a single request
+
+**Request Body**:
+```json
+{
+  "ids": [123, 456, 789],
+  "orderBy": "date_desc",
+  "limit": 10,
+  "project": "my-project"
+}
+```
+
+**Body Parameters**:
+- `ids` (required): Array of observation IDs
+- `orderBy` (optional): Sort order - `date_desc` or `date_asc` (default: `date_desc`)
+- `limit` (optional): Maximum number of results to return
+- `project` (optional): Filter by project name
+
+**Response**:
+```json
+[
+  {
+    "id": 789,
+    "sdk_session_id": "abc123",
+    "project": "my-project",
+    "type": "feature",
+    "title": "Add new feature",
+    "narrative": "...",
+    "created_at": "2025-11-06T12:00:00Z",
+    "created_at_epoch": 1730891400000
+  },
+  {
+    "id": 456,
+    "sdk_session_id": "abc124",
+    "project": "my-project",
+    "type": "bugfix",
+    "title": "Fix authentication bug",
+    "narrative": "...",
+    "created_at": "2025-11-06T10:30:00Z",
+    "created_at_epoch": 1730886600000
+  }
+]
+```
+
+**Error Responses**:
+- `400 Bad Request`: `{"error": "ids must be an array of numbers"}`
+- `400 Bad Request`: `{"error": "All ids must be integers"}`
+
+**Use Case**: This endpoint is used by the `get_observations` MCP tool to efficiently retrieve multiple observations in a single request, avoiding the overhead of multiple individual requests.
+
+#### 9. Get Session by ID
+```
+GET /api/session/:id
+```
+
+**Purpose**: Retrieve a single session by its ID
+
+**Path Parameters**:
+- `id` (required): Session ID
+
+**Response**:
+```json
+{
+  "id": 456,
+  "sdk_session_id": "abc123",
+  "project": "my-project",
+  "request": "User's original request",
+  "completed": "Work finished",
+  "created_at": "2025-11-06T10:30:00Z"
+}
+```
+
+**Error Response** (404):
+```json
+{
+  "error": "Session #456 not found"
+}
+```
+
+#### 10. Get Prompt by ID
+```
+GET /api/prompt/:id
+```
+
+**Purpose**: Retrieve a single user prompt by its ID
+
+**Path Parameters**:
+- `id` (required): Prompt ID
+
+**Response**:
+```json
+{
+  "id": 1,
+  "session_id": "abc123",
+  "prompt": "User's prompt text",
+  "prompt_number": 1,
+  "created_at": "2025-11-06T10:30:00Z"
+}
+```
+
+**Error Response** (404):
+```json
+{
+  "error": "Prompt #1 not found"
+}
+```
+
+#### 12. Get Stats
 ```
 GET /api/stats
 ```
@@ -187,9 +330,23 @@ GET /api/stats
 }
 ```
 
+#### 13. Get Projects
+```
+GET /api/projects
+```
+
+**Purpose**: Get list of distinct projects from observations
+
+**Response**:
+```json
+{
+  "projects": ["my-project", "other-project", "test-project"]
+}
+```
+
 ### Settings Endpoints
 
-#### 8. Get Settings
+#### 14. Get Settings
 ```
 GET /api/settings
 ```
@@ -205,7 +362,7 @@ GET /api/settings
 }
 ```
 
-#### 9. Save Settings
+#### 15. Save Settings
 ```
 POST /api/settings
 ```
@@ -230,7 +387,7 @@ POST /api/settings
 
 ### Session Management Endpoints
 
-#### 10. Initialize Session
+#### 16. Initialize Session
 ```
 POST /sessions/:sessionDbId/init
 ```
@@ -251,7 +408,7 @@ POST /sessions/:sessionDbId/init
 }
 ```
 
-#### 11. Add Observation
+#### 17. Add Observation
 ```
 POST /sessions/:sessionDbId/observations
 ```
@@ -274,7 +431,7 @@ POST /sessions/:sessionDbId/observations
 }
 ```
 
-#### 12. Generate Summary
+#### 18. Generate Summary
 ```
 POST /sessions/:sessionDbId/summarize
 ```
@@ -294,7 +451,7 @@ POST /sessions/:sessionDbId/summarize
 }
 ```
 
-#### 13. Session Status
+#### 19. Session Status
 ```
 GET /sessions/:sessionDbId/status
 ```
@@ -309,7 +466,7 @@ GET /sessions/:sessionDbId/status
 }
 ```
 
-#### 14. Delete Session
+#### 20. Delete Session
 ```
 DELETE /sessions/:sessionDbId
 ```
@@ -343,7 +500,7 @@ npm run worker:start
 npm run worker:stop
 
 # Restart worker
-npm run worker:restart
+claude-mem restart
 
 # View logs
 npm run worker:logs

docs/public/beta-features.mdx

@@ -5,6 +5,10 @@ description: "Try experimental features like Endless Mode before they're release
 
 # Beta Features
 
+<Warning>
+**Endless Mode is experimental and not included in the stable release.** You must manually switch to the beta branch to try it. The efficiency projections below are based on theoretical modeling, not production measurements. Expect slower performance than standard mode and potential bugs.
+</Warning>
+
 Claude-Mem offers a beta channel for users who want to try experimental features before they're released to the stable channel.
 
 ## Version Channel Switching
@@ -77,19 +81,22 @@ Archive Memory (Transcript File):
 
 This transforms O(N²) scaling into O(N) - linear instead of quadratic.
 
-### Expected Results
+### Projected Results
 
-Based on analysis of real sessions:
+Based on theoretical modeling (not production measurements):
 
-- **Token savings**: ~95% reduction in context window usage
-- **Efficiency gain**: ~20x more tool uses before context exhaustion
+- **Token savings**: Significant reduction in context window usage
+- **Efficiency gain**: More tool uses before context exhaustion
 - **Quality preservation**: Observations cache the synthesis result, so no information is lost
 
-### Caveats
+### Important Caveats
 
-Endless Mode is experimental:
+Endless Mode is experimental and has significant limitations:
 
-- **Adds latency** - Blocking hooks wait for observation generation (60-90s per tool use)
+- **Not in stable release** - You must manually switch to the beta branch to use this feature
+- **Still in development** - May have bugs, breaking changes, or incomplete functionality
+- **Slower than standard mode** - Blocking observation generation adds latency to each tool use
+- **Theoretical projections** - The efficiency claims above are based on simulations, not real-world production data
 - **Requires working database** - Observations must save successfully for transformation
 - **New architecture** - Less battle-tested than standard mode
 

docs/public/configuration.mdx

@@ -179,7 +179,9 @@ Claude-Mem supports switching between stable and beta versions via the web viewe
 
 **Your memory data is preserved** when switching versions. Only the plugin code changes.
 
-See [Beta Features](beta-features) for details on what's available in beta.
+<Note>
+Endless Mode is experimental and slower than standard mode. See [Beta Features](beta-features) for full details and important limitations.
+</Note>
 
 ## Worker Service Management
 
@@ -314,7 +316,7 @@ Edit `~/.claude-mem/settings.json`:
 
 Then restart the worker:
 ```bash
-npm run worker:restart
+claude-mem restart
 ```
 
 ### Custom Model
@@ -329,7 +331,7 @@ Edit `~/.claude-mem/settings.json`:
 Then restart the worker:
 ```bash
 export CLAUDE_MEM_MODEL=opus
-npm run worker:restart
+claude-mem restart
 ```
 
 ### Custom Skip Tools
@@ -386,7 +388,7 @@ Enable debug logging:
 
 ```bash
 export DEBUG=claude-mem:*
-npm run worker:restart
+claude-mem restart
 npm run worker:logs
 ```
 
@@ -404,7 +406,7 @@ npm run worker:logs
 
 1. Restart worker after changes:
    ```bash
-   npm run worker:restart
+   claude-mem restart
    ```
 
 2. Verify environment variables:
@@ -438,7 +440,7 @@ If port 37777 is already in use:
 
 2. Restart worker:
    ```bash
-   npm run worker:restart
+   claude-mem restart
    ```
 
 3. Verify new port:

docs/public/development.mdx

@@ -165,7 +165,7 @@ npm run build
 1. Make changes to React components in `src/ui/viewer/`
 2. Build: `npm run build`
 3. Sync to installed plugin: `npm run sync-marketplace`
-4. Restart worker: `npm run worker:restart`
+4. Restart worker: `claude-mem restart`
 5. Refresh browser at http://localhost:37777
 
 **Hot Reload**: Not currently supported. Full rebuild + restart required for changes.
@@ -456,7 +456,7 @@ export async function createObservation(
 
 ```bash
 export DEBUG=claude-mem:*
-npm run worker:restart
+claude-mem restart
 npm run worker:logs
 ```
 

docs/public/docs.json

@@ -40,7 +40,8 @@
           "usage/claude-desktop",
           "usage/private-tags",
           "usage/export-import",
-          "beta-features"
+          "beta-features",
+          "endless-mode"
         ]
       },
       {

docs/public/endless-mode.mdx

@@ -0,0 +1,111 @@
+---
+title: "Endless Mode (Beta)"
+description: "Experimental biomimetic memory architecture for extended sessions"
+---
+
+# Current State of Endless Mode
+
+## Core Concept
+
+Endless Mode is a **biomimetic memory architecture** that solves Claude's context window exhaustion problem. Instead of keeping full tool outputs in the context window (O(N²) complexity), it:
+
+- Captures compressed observations after each tool use
+- Replaces transcripts with low token summaries
+- Achieves O(N) linear complexity
+- Maintains two-tier memory: working memory (compressed) + archive memory (full transcript on disk, maintained by default claude code functionality)
+
+## Implementation Status
+
+**Status**: FUNCTIONAL BUT EXPERIMENTAL
+
+**Current Branch**: `beta/endless-mode` (ahead of main)
+
+**Recent Activity**:
+- Merged main branch changes
+- Resolved merge conflicts in save-hook, SessionStore, SessionRoutes
+- Updated documentation to remove misleading token reduction claims
+- Added important caveats about beta status
+
+## Key Architecture Components
+
+1. **Pre-Tool-Use Hook** - Tracks tool execution start, sends tool_use_id to worker
+2. **Save Hook (PostToolUse)** - **CRITICAL**: Blocks until observation is generated (110s timeout), injects compressed observation back into context
+3. **SessionManager.waitForNextObservation()** - Event-driven wait mechanism (no polling)
+4. **SDKAgent** - Generates observations via Agent SDK, emits completion events
+5. **Database** - Added `tool_use_id` column for observation correlation
+
+## Configuration
+
+```json
+{
+  "CLAUDE_MEM_ENDLESS_MODE": "false",  // Default: disabled
+  "CLAUDE_MEM_ENDLESS_WAIT_TIMEOUT_MS": "90000"  // 90 second timeout
+}
+```
+
+**Enable via**: Manual checkout of beta branch (see instructions below)
+
+## Flow
+
+```
+Tool Executes → Pre-Hook (track ID) → Tool Completes →
+Save-Hook (BLOCKS) → Worker processes → SDK generates observation →
+Event fired → Hook receives observation → Injects markdown →
+Clears input → Context reduced
+```
+
+## Known Limitations
+
+From the documentation:
+- ⚠️ **Slower than standard mode** - Blocking adds latency
+- ⚠️ **Still in development** - May have bugs
+- ⚠️ **Not battle-tested** - New architecture
+- ⚠️ **Theoretical projections** - Efficiency gains not yet validated in production
+
+## What's Working
+
+- ✅ Synchronous observation injection
+- ✅ Event-driven wait mechanism
+- ✅ Token reduction via input clearing
+- ✅ Database schema with tool_use_id
+- ✅ Web UI for version switching
+- ✅ Graceful timeout fallbacks
+
+## What's Not Ready
+
+- ❌ Production validation of token savings
+- ❌ Comprehensive test coverage
+- ❌ Stable channel release
+- ❌ Performance benchmarks
+- ❌ Long-running session data
+
+## How to Try Endless Mode
+
+Endless Mode is currently only available on the beta branch. To try it:
+
+```bash
+# Navigate to your claude-mem installation
+cd ~/.claude/plugins/marketplaces/thedotmack/
+
+# Checkout the beta branch
+git checkout beta/endless-mode
+
+# Install dependencies
+npm install
+
+# Restart the worker
+claude-mem restart
+```
+
+**To return to stable:**
+
+```bash
+cd ~/.claude/plugins/marketplaces/thedotmack/
+git checkout main
+npm install
+claude-mem restart
+```
+
+## Summary
+
+The implementation is architecturally complete and functional, but remains experimental pending production validation of the theoretical efficiency gains.

docs/public/hooks-architecture.mdx

@@ -534,7 +534,7 @@ npm run worker:status
 npm run worker:logs
 
 # Restart
-npm run worker:restart
+claude-mem restart
 
 # Stop
 npm run worker:stop

docs/public/platform-integration.mdx

@@ -57,7 +57,7 @@ CLAUDE_MEM_PYTHON_VERSION=3.13              # Python version for chroma-mcp
 ```bash
 npm run build                 # Compile TypeScript (hooks + worker)
 npm run sync-marketplace      # Copy to ~/.claude/plugins
-npm run worker:restart        # Restart worker
+claude-mem restart        # Restart worker
 npm run worker:logs           # View worker logs
 npm run worker:status         # Check worker status
 ```

docs/public/troubleshooting.mdx

@@ -48,14 +48,14 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
 
 4. Restart worker service:
    ```bash
-   npm run worker:restart
+   claude-mem restart
    ```
 
 5. Check for port conflicts:
    ```bash
    # If port 37777 is in use by another service
    export CLAUDE_MEM_WORKER_PORT=38000
-   npm run worker:restart
+   claude-mem restart
    ```
 
 ### Theme Toggle Not Persisting
@@ -110,7 +110,7 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
 
 5. Restart worker and refresh browser:
    ```bash
-   npm run worker:restart
+   claude-mem restart
    ```
 
 ### Chroma/Python Dependency Issues (v5.0.0+)
@@ -225,7 +225,7 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
 3. Or use a different port:
    ```bash
    export CLAUDE_MEM_WORKER_PORT=38000
-   npm run worker:restart
+   claude-mem restart
    ```
 
 4. Verify new port:
@@ -282,7 +282,7 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
 
 4. Restart worker:
    ```bash
-   npm run worker:restart
+   claude-mem restart
    ```
 
 ## Hook Issues
@@ -644,7 +644,7 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
 
 2. Restart worker:
    ```bash
-   npm run worker:restart
+   claude-mem restart
    ```
 
 3. Clean up old data (see "Database Too Large" above)
@@ -721,7 +721,7 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
 
 ```bash
 export DEBUG=claude-mem:*
-npm run worker:restart
+claude-mem restart
 npm run worker:logs
 ```
 
@@ -781,7 +781,7 @@ SELECT created_at, tool_name FROM observations ORDER BY created_at DESC LIMIT 10
 
 **Cause**: Worker not running or port mismatch.
 
-**Solution**: Restart worker with `npm run worker:restart`.
+**Solution**: Restart worker with `claude-mem restart`.
 
 ### "Database is locked"
 

docs/public/usage/claude-desktop.mdx

@@ -118,12 +118,12 @@ The skill provides access to these MCP tools:
 | `search` | Unified search across observations, sessions, and prompts |
 | `timeline` | Get chronological context around a query or observation ID |
 | `get_observation` | Fetch a single observation by ID |
-| `get_batch_observations` | Fetch multiple observations efficiently |
+| `get_observations` | Fetch multiple observations efficiently |
 | `get_session` | Fetch session summary by ID |
 | `get_prompt` | Fetch user prompt by ID |
 | `get_recent_context` | Get recent timeline items |
 | `get_context_timeline` | Get timeline around a specific observation |
-| `progressive_description` | Load detailed usage instructions |
+| `help` | Load detailed usage instructions |
 
 ## Troubleshooting
 

docs/public/usage/getting-started.mdx

@@ -86,7 +86,7 @@ npm run worker:start
 npm run worker:stop
 
 # Restart worker service
-npm run worker:restart
+claude-mem restart
 
 # View worker logs
 npm run worker:logs

docs/public/usage/private-tags.mdx

@@ -176,7 +176,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: `npm run worker:status`
-4. Restart worker: `npm run worker:restart`
+4. Restart worker: `claude-mem restart`
 
 ### Partial Content Stored
 

docs/public/usage/search-tools.mdx

@@ -364,7 +364,7 @@ If search isn't working, check the worker service:
 
 ```bash
 npm run worker:status       # Check worker status
-npm run worker:restart      # Restart if needed
+claude-mem restart      # Restart if needed
 npm run worker:logs         # View logs
 ```
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem",
-  "version": "7.2.3",
+  "version": "7.4.5",
   "description": "Memory compression system for Claude Code - persist context across sessions",
   "keywords": [
     "claude",
@@ -46,6 +46,7 @@
     "worker:status": "bun plugin/scripts/worker-cli.js status",
     "worker:logs": "tail -n 50 ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log",
     "changelog:generate": "node scripts/generate-changelog.js",
+    "discord:notify": "node scripts/discord-release-notify.js",
     "usage:analyze": "node scripts/analyze-usage.js",
     "usage:today": "node scripts/analyze-usage.js $(date +%Y-%m-%d)",
     "translate-readme": "bun scripts/translate-readme/cli.ts -v -o docs/i18n README.md",

plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem",
-  "version": "7.2.3",
+  "version": "7.4.5",
   "description": "Persistent memory system for Claude Code - seamlessly preserve context across sessions",
   "author": {
     "name": "Alex Newman"

plugin/.mcp.json

@@ -1,6 +1,6 @@
 {
   "mcpServers": {
-    "claude-mem-search": {
+    "mem-search": {
       "type": "stdio",
       "command": "${CLAUDE_PLUGIN_ROOT}/scripts/mcp-server.cjs"
     }

plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-plugin",
-  "version": "7.2.3",
+  "version": "7.4.4",
   "private": true,
   "description": "Runtime dependencies for claude-mem bundled hooks",
   "type": "module",

plugin/scripts/smart-install.js

@@ -253,6 +253,97 @@ function installUv() {
   }
 }
 
+/**
+ * Install the claude-mem CLI command to PATH
+ * Creates a wrapper script in ~/.local/bin (Unix) or %LOCALAPPDATA%\Programs\claude-mem (Windows)
+ */
+function installCLI() {
+  const CLI_NAME = 'claude-mem';
+  const WORKER_CLI = join(ROOT, 'plugin', 'scripts', 'worker-cli.js');
+
+  if (IS_WINDOWS) {
+    // Windows: Create .cmd file in LocalAppData
+    const cliDir = join(process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'), 'Programs', 'claude-mem');
+    const cliPath = join(cliDir, `${CLI_NAME}.cmd`);
+    const markerPath = join(cliDir, '.cli-installed');
+
+    // Skip if already installed
+    if (existsSync(markerPath)) return;
+
+    try {
+      // Create directory if needed
+      if (!existsSync(cliDir)) {
+        execSync(`mkdir "${cliDir}"`, { stdio: 'ignore', shell: true });
+      }
+
+      // Get Bun path for the wrapper
+      const bunPath = getBunPath() || 'bun';
+
+      // Create the wrapper script
+      const cmdContent = `@echo off
+"${bunPath}" "${WORKER_CLI}" %*
+`;
+      writeFileSync(cliPath, cmdContent);
+      writeFileSync(markerPath, new Date().toISOString());
+
+      console.error(`✅ CLI installed: ${cliPath}`);
+      console.error('');
+      console.error('📋 Add to PATH (run once in PowerShell as Admin):');
+      console.error(`   [Environment]::SetEnvironmentVariable("Path", $env:Path + ";${cliDir}", "User")`);
+      console.error('');
+      console.error('   Then restart your terminal and use: claude-mem start|stop|restart|status');
+    } catch (error) {
+      console.error(`⚠️  Could not install CLI: ${error.message}`);
+      console.error(`   You can still use: bun "${WORKER_CLI}" <command>`);
+    }
+  } else {
+    // Unix: Create shell script in ~/.local/bin
+    const cliDir = join(homedir(), '.local', 'bin');
+    const cliPath = join(cliDir, CLI_NAME);
+    const markerPath = join(ROOT, '.cli-installed');
+
+    // Skip if already installed
+    if (existsSync(markerPath) && existsSync(cliPath)) return;
+
+    try {
+      // Create directory if needed
+      if (!existsSync(cliDir)) {
+        execSync(`mkdir -p "${cliDir}"`, { stdio: 'ignore', shell: true });
+      }
+
+      // Get Bun path for the wrapper
+      const bunPath = getBunPath() || 'bun';
+
+      // Create the wrapper script
+      const shContent = `#!/usr/bin/env bash
+# claude-mem CLI wrapper - manages the worker service
+exec "${bunPath}" "${WORKER_CLI}" "$@"
+`;
+      writeFileSync(cliPath, shContent, { mode: 0o755 });
+      writeFileSync(markerPath, new Date().toISOString());
+
+      console.error(`✅ CLI installed: ${cliPath}`);
+
+      // Check if ~/.local/bin is in PATH
+      const pathDirs = (process.env.PATH || '').split(':');
+      const localBinInPath = pathDirs.some(p => p === cliDir || p === '$HOME/.local/bin' || p.endsWith('/.local/bin'));
+
+      if (!localBinInPath) {
+        console.error('');
+        console.error('📋 Add to PATH (add to ~/.bashrc or ~/.zshrc):');
+        console.error('   export PATH="$HOME/.local/bin:$PATH"');
+        console.error('');
+        console.error('   Then restart your terminal and use: claude-mem start|stop|restart|status');
+      } else {
+        console.error('   Usage: claude-mem start|stop|restart|status');
+      }
+    } catch (error) {
+      console.error(`⚠️  Could not install CLI: ${error.message}`);
+      console.error(`   You can still use: bun "${WORKER_CLI}" <command>`);
+    }
+  }
+}
+
 /**
  * Check if dependencies need to be installed
  */
@@ -351,6 +442,9 @@ try {
     installDeps();
     console.error('✅ Dependencies installed');
   }
+
+  // Step 4: Install CLI to PATH
+  installCLI();
 } catch (e) {
   console.error('❌ Installation failed:', e.message);
   process.exit(1);

plugin/scripts/worker-wrapper.cjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+"use strict";var m=Object.create;var w=Object.defineProperty;var u=Object.getOwnPropertyDescriptor;var I=Object.getOwnPropertyNames;var f=Object.getPrototypeOf,x=Object.prototype.hasOwnProperty;var g=(e,i,n,o)=>{if(i&&typeof i=="object"||typeof i=="function")for(let s of I(i))!x.call(e,s)&&s!==n&&w(e,s,{get:()=>i[s],enumerable:!(o=u(i,s))||o.enumerable});return e};var k=(e,i,n)=>(n=e!=null?m(f(e)):{},g(i||!e||!e.__esModule?w(n,"default",{value:e,enumerable:!0}):n,e));var c=require("child_process"),p=k(require("path"),1),y=process.platform==="win32",P=__dirname,l=p.default.join(P,"worker-service.cjs"),t=null,a=!1;function r(e){let i=new Date().toISOString();console.log(`[${i}] [wrapper] ${e}`)}function h(){r(`Spawning inner worker: ${l}`),t=(0,c.spawn)(process.execPath,[l],{stdio:["inherit","inherit","inherit","ipc"],env:{...process.env,CLAUDE_MEM_MANAGED:"true"},cwd:p.default.dirname(l)}),t.on("message",async e=>{(e.type==="restart"||e.type==="shutdown")&&(r(`${e.type} requested by inner`),a=!0,await d(),r("Exiting wrapper"),process.exit(0))}),t.on("exit",(e,i)=>{r(`Inner exited with code=${e}, signal=${i}`),t=null,a||(r("Inner exited unexpectedly, wrapper exiting (hooks will restart if needed)"),process.exit(e??1))}),t.on("error",e=>{r(`Inner error: ${e.message}`)})}async function d(){if(!t||!t.pid){r("No inner process to kill");return}let e=t.pid;if(r(`Killing inner process tree (pid=${e})`),y)try{(0,c.execSync)(`taskkill /PID ${e} /T /F`,{timeout:1e4,stdio:"ignore"}),r(`taskkill completed for pid=${e}`)}catch(i){r(`taskkill failed (process may be dead): ${i}`)}else{t.kill("SIGTERM");let i=new Promise(o=>{if(!t){o();return}t.on("exit",()=>o())}),n=new Promise(o=>setTimeout(()=>o(),5e3));await Promise.race([i,n]),t&&!t.killed&&(r("Inner did not exit gracefully, force killing"),t.kill("SIGKILL"))}await S(e,5e3),t=null,r("Inner process terminated")}async function S(e,i){let n=Date.now();for(;Date.now()-n<i;)try{process.kill(e,0),await new Promise(o=>setTimeout(o,100))}catch{return}r(`Timeout waiting for process ${e} to exit`)}process.on("SIGTERM",async()=>{r("Wrapper received SIGTERM"),a=!0,await d(),process.exit(0)});process.on("SIGINT",async()=>{r("Wrapper received SIGINT"),a=!0,await d(),process.exit(0)});r("Wrapper starting");h();

plugin/skills/mem-search/SKILL.md

@@ -86,13 +86,13 @@ For each relevant ID, fetch full details using MCP tools:
 **Fetch multiple observations (ALWAYS use for 2+ IDs):**
 
 ```
-get_batch_observations(ids=[11131, 10942, 10855])
+get_observations(ids=[11131, 10942, 10855])
 ```
 
 **With ordering and limit:**
 
 ```
-get_batch_observations(
+get_observations(
   ids=[11131, 10942, 10855],
   orderBy="date_desc",
   limit=10,
@@ -126,7 +126,7 @@ get_prompt(id=5421)
 
 **Batch optimization:**
 
-- **ALWAYS use `get_batch_observations` for 2+ observations**
+- **ALWAYS use `get_observations` for 2+ observations**
 - 10-100x more efficient than individual fetches
 - Single HTTP request vs N requests
 - Returns all results in one response
@@ -175,13 +175,13 @@ search(query="database migration", limit=20, project="my-project")
 
 **Get detailed instructions:**
 
-Use the `progressive_description` tool to load full instructions on-demand:
+Use the `help` tool to load full instructions on-demand:
 
 ```
-progressive_description(topic="workflow")  # Get 4-step workflow
-progressive_description(topic="search_params")  # Get parameters reference
-progressive_description(topic="examples")  # Get usage examples
-progressive_description(topic="all")  # Get complete guide
+help(topic="workflow")  # Get 4-step workflow
+help(topic="search_params")  # Get parameters reference
+help(topic="examples")  # Get usage examples
+help(topic="all")  # Get complete guide
 ```
 
 ## Why This Workflow?
@@ -210,5 +210,120 @@ progressive_description(topic="all")  # Get complete guide
 **Remember:**
 
 - ALWAYS get timeline context to understand what was happening
-- ALWAYS use `get_batch_observations` when fetching 2+ observations
+- ALWAYS use `get_observations` when fetching 2+ observations
 - The workflow is optimized: search → timeline → batch fetch = 10-100x faster
+
+---
+
+## Tool Reference
+
+Comprehensive parameter documentation for all memory tools. For MCP usage, call `help(topic="search")` to load specific tool docs.
+
+### search
+
+Search across all memory types (observations, sessions, prompts).
+
+**Parameters:**
+
+- `query` (string, optional) - Search term for full-text search
+- `limit` (number, optional) - Maximum results to return. Default: 20, Max: 100
+- `offset` (number, optional) - Number of results to skip. Default: 0
+- `project` (string, required) - Project name to filter by
+- `type` (string, optional) - Filter by type: "observations", "sessions", "prompts"
+- `dateStart` (string, optional) - Start date filter (YYYY-MM-DD or epoch ms)
+- `dateEnd` (string, optional) - End date filter (YYYY-MM-DD or epoch ms)
+- `obs_type` (string, optional) - Filter observations by type (comma-separated): bugfix, feature, decision, discovery, change
+- `orderBy` (string, optional) - Sort order: "date_desc" (default), "date_asc", "relevance"
+
+**Returns:** Table of results with IDs, timestamps, types, titles
+
+### timeline
+
+Get chronological context around a specific point in time or observation.
+
+**Parameters:**
+
+- `anchor` (number, optional) - Observation ID to center timeline around. If not provided, uses most recent result from query
+- `query` (string, optional) - Search term to find anchor automatically (if anchor not provided)
+- `depth_before` (number, optional) - Items before anchor. Default: 5, Max: 20
+- `depth_after` (number, optional) - Items after anchor. Default: 5, Max: 20
+- `project` (string, required) - Project name to filter by
+
+**Returns:** Exactly `depth_before + 1 + depth_after` items in chronological order, with observations, sessions, and prompts interleaved
+
+### get_recent_context
+
+Get the most recent observations from current or recent sessions.
+
+**Parameters:**
+
+- `limit` (number, optional) - Maximum observations to return. Default: 10, Max: 50
+- `project` (string, required) - Project name to filter by
+
+**Returns:** Recent observations in reverse chronological order
+
+### get_context_timeline
+
+Get timeline context around a specific observation ID.
+
+**Parameters:**
+
+- `anchor` (number, required) - Observation ID to center timeline around
+- `depth_before` (number, optional) - Items before anchor. Default: 5, Max: 20
+- `depth_after` (number, optional) - Items after anchor. Default: 5, Max: 20
+- `project` (string, optional) - Project name to filter by
+
+**Returns:** Timeline items centered on the anchor observation
+
+### get_observation
+
+Fetch a single observation by ID with full details.
+
+**Parameters:**
+
+- `id` (number, required) - Observation ID to fetch
+
+**Returns:** Complete observation object with title, subtitle, narrative, facts, concepts, files, timestamps
+
+### get_observations
+
+Batch fetch multiple observations by IDs. Always prefer this over individual fetches for 2+ observations.
+
+**Parameters:**
+
+- `ids` (array of numbers, required) - Array of observation IDs to fetch
+- `orderBy` (string, optional) - Sort order: "date_desc" (default), "date_asc"
+- `limit` (number, optional) - Maximum observations to return. Default: no limit
+- `project` (string, optional) - Project name to filter by
+
+**Returns:** Array of complete observation objects, 10-100x faster than individual fetches
+
+### get_session
+
+Fetch a single session by ID with metadata.
+
+**Parameters:**
+
+- `id` (number, required) - Session ID to fetch (just the number, not "S2005" format)
+
+**Returns:** Session object with ID, start time, end time, project, model info
+
+### get_prompt
+
+Fetch a single prompt by ID with full text.
+
+**Parameters:**
+
+- `id` (number, required) - Prompt ID to fetch
+
+**Returns:** Prompt object with ID, text, timestamp, session reference
+
+### help
+
+Load detailed instructions for specific topics or all documentation.
+
+**Parameters:**
+
+- `topic` (string, optional) - Specific topic to load: "workflow", "search", "timeline", "get_recent_context", "get_context_timeline", "get_observation", "get_observations", "get_session", "get_prompt", "all". Default: "all"
+
+**Returns:** Formatted documentation for the requested topic

plugin/skills/mem-search/operations/formatting.md

@@ -282,13 +282,13 @@ No results found for "{query}". Try:
 The search service isn't available. Check if the worker is running:
 
 ```bash
-pm2 list
+npm run worker:status
 ```
 
 If the worker is stopped, restart it:
 
 ```bash
-npm run worker:restart
+claude-mem restart
 ```
 ```
 

plugin/skills/mem-search/operations/help.md

@@ -113,7 +113,7 @@ Many endpoints share these parameters:
 ## Error Handling
 
 **Worker not running:**
-Connection refused error. Response: "The search API isn't available. Check if worker is running: `pm2 list`"
+Connection refused error. Response: "The search API isn't available. Check if worker is running: `npm run worker:status`"
 
 **Invalid endpoint:**
 ```json

plugin/skills/mem-search/operations/recent-context.md

@@ -93,7 +93,7 @@ curl -s "http://localhost:37777/api/context/recent?limit=3"
 Response: "No recent sessions found for 'new-project'. This might be a new project."
 
 **Worker not running:**
-Connection refused error. Inform user to check if worker is running: `pm2 list`
+Connection refused error. Inform user to check if worker is running: `npm run worker:status`
 
 ## Tips
 

plugin/skills/troubleshoot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: troubleshoot
-description: Diagnose and fix claude-mem installation issues. Checks PM2 worker status, database integrity, service health, dependencies, and provides automated fixes for common problems.
+description: Diagnose and fix claude-mem installation issues. Checks worker status, database integrity, service health, dependencies, and provides automated fixes for common problems.
 ---
 
 # Claude-Mem Troubleshooting Skill
@@ -39,7 +39,7 @@ Choose the appropriate operation file for detailed instructions:
 
 ### Diagnostic Workflows
 1. **[Full System Diagnostics](operations/diagnostics.md)** - Comprehensive step-by-step diagnostic workflow
-2. **[Worker Diagnostics](operations/worker.md)** - PM2 worker-specific troubleshooting
+2. **[Worker Diagnostics](operations/worker.md)** - Bun worker-specific troubleshooting
 3. **[Database Diagnostics](operations/database.md)** - Database integrity and data checks
 
 ### Issue Resolution
@@ -54,9 +54,9 @@ Choose the appropriate operation file for detailed instructions:
 **Fast automated fix (try this first):**
 ```bash
 cd ~/.claude/plugins/marketplaces/thedotmack/ && \
-pm2 delete claude-mem-worker 2>/dev/null; \
+npm run worker:stop; \
 npm install && \
-node_modules/.bin/pm2 start ecosystem.config.cjs && \
+npm run worker:start && \
 sleep 3 && \
 curl -s http://127.0.0.1:37777/health
 ```
@@ -79,7 +79,7 @@ When troubleshooting:
 - **Worker port:** Default 37777 (configurable via `CLAUDE_MEM_WORKER_PORT`)
 - **Database location:** `~/.claude-mem/claude-mem.db`
 - **Plugin location:** `~/.claude/plugins/marketplaces/thedotmack/`
-- **PM2 process name:** `claude-mem-worker`
+- **Worker PID file:** `~/.claude-mem/worker.pid`
 
 ## Error Reporting
 

plugin/skills/troubleshoot/operations/automated-fixes.md

@@ -8,9 +8,9 @@ One-command fix sequences for common claude-mem issues.
 
 ```bash
 cd ~/.claude/plugins/marketplaces/thedotmack/ && \
-pm2 delete claude-mem-worker 2>/dev/null; \
+npm run worker:stop; \
 npm install && \
-node_modules/.bin/pm2 start ecosystem.config.cjs && \
+npm run worker:start && \
 sleep 3 && \
 curl -s http://127.0.0.1:37777/health
 ```
@@ -20,22 +20,22 @@ curl -s http://127.0.0.1:37777/health
 **What it does:**
 1. Stops the worker (if running)
 2. Ensures dependencies are installed
-3. Starts worker with local PM2
+3. Starts worker
 4. Waits for startup
 5. Verifies health
 
 ## Fix: Worker Not Running
 
-**Use when:** PM2 shows worker as stopped or not listed
+**Use when:** Worker status shows it's not running
 
 ```bash
 cd ~/.claude/plugins/marketplaces/thedotmack/ && \
-node_modules/.bin/pm2 start ecosystem.config.cjs && \
+npm run worker:start && \
 sleep 2 && \
-pm2 status
+npm run worker:status
 ```
 
-**Expected output:** Worker shows as "online"
+**Expected output:** Worker running with PID and health OK
 
 ## Fix: Dependencies Missing
 
@@ -44,9 +44,23 @@ pm2 status
 ```bash
 cd ~/.claude/plugins/marketplaces/thedotmack/ && \
 npm install && \
-pm2 restart claude-mem-worker
+claude-mem restart
 ```
 
+## Fix: Stale PID File
+
+**Use when:** Worker reports running but health check fails
+
+```bash
+rm -f ~/.claude-mem/worker.pid && \
+cd ~/.claude/plugins/marketplaces/thedotmack/ && \
+npm run worker:start && \
+sleep 2 && \
+curl -s http://127.0.0.1:37777/health
+```
+
+**Expected output:** `{"status":"ok"}`
+
 ## Fix: Port Conflict
 
 **Use when:** Error shows port already in use
@@ -54,8 +68,9 @@ pm2 restart claude-mem-worker
 ```bash
 # Change to port 37778
 mkdir -p ~/.claude-mem && \
-echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json && \
-pm2 restart claude-mem-worker && \
+echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json && \
+cd ~/.claude/plugins/marketplaces/thedotmack/ && \
+claude-mem restart && \
 sleep 2 && \
 curl -s http://127.0.0.1:37778/health
 ```
@@ -70,14 +85,16 @@ curl -s http://127.0.0.1:37778/health
 # Backup and test integrity
 cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup && \
 sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;" && \
-pm2 restart claude-mem-worker
+cd ~/.claude/plugins/marketplaces/thedotmack/ && \
+claude-mem restart
 ```
 
 **If integrity check fails, recreate database:**
 ```bash
 # WARNING: This deletes all memory data
 mv ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.old && \
-pm2 restart claude-mem-worker
+cd ~/.claude/plugins/marketplaces/thedotmack/ && \
+claude-mem restart
 ```
 
 ## Fix: Clean Reinstall
@@ -88,36 +105,49 @@ pm2 restart claude-mem-worker
 # Backup data first
 cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup 2>/dev/null
 
-# Stop and remove worker
-pm2 delete claude-mem-worker 2>/dev/null
+# Stop worker
+cd ~/.claude/plugins/marketplaces/thedotmack/
+npm run worker:stop
+
+# Clean PID file
+rm -f ~/.claude-mem/worker.pid
 
 # Reinstall dependencies
-cd ~/.claude/plugins/marketplaces/thedotmack/ && \
 rm -rf node_modules && \
 npm install
 
 # Start worker
-node_modules/.bin/pm2 start ecosystem.config.cjs && \
+npm run worker:start && \
 sleep 3 && \
 curl -s http://127.0.0.1:37777/health
 ```
 
-## Fix: Clear PM2 Logs
+## Fix: Clear Old Logs
 
-**Use when:** Logs are too large, want fresh start
+**Use when:** Want to start with fresh logs
 
 ```bash
-pm2 flush claude-mem-worker && \
-pm2 restart claude-mem-worker
+# Archive old logs
+tar -czf ~/.claude-mem/logs-archive-$(date +%Y-%m-%d).tar.gz ~/.claude-mem/logs/*.log 2>/dev/null
+
+# Remove logs older than 7 days
+find ~/.claude-mem/logs/ -name "worker-*.log" -mtime +7 -delete
+
+# Restart worker for fresh log
+cd ~/.claude/plugins/marketplaces/thedotmack/
+claude-mem restart
 ```
 
+**Note:** Logs auto-rotate daily, manual cleanup rarely needed.
+
 ## Verification Commands
 
 **After running any fix, verify with these:**
 
 ```bash
 # Check worker status
-pm2 status | grep claude-mem-worker
+cd ~/.claude/plugins/marketplaces/thedotmack/
+npm run worker:status
 
 # Check health
 curl -s http://127.0.0.1:37777/health
@@ -129,23 +159,48 @@ sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
 curl -s http://127.0.0.1:37777/api/stats
 
 # Check logs for errors
-pm2 logs claude-mem-worker --lines 20 --nostream | grep -i error
+grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log | tail -20
 ```
 
 **All checks should pass:**
-- Worker status: "online"
-- Health: `{"status":"ok"}`
+- Worker status: Shows PID and "Health: OK"
+- Health endpoint: `{"status":"ok"}`
 - Database: Shows count (may be 0 if new)
 - Stats: Returns JSON with counts
 - Logs: No recent errors
 
+## One-Line Complete Diagnostic
+
+**Quick health check:**
+```bash
+cd ~/.claude/plugins/marketplaces/thedotmack/ && npm run worker:status && curl -s http://127.0.0.1:37777/health && echo " ✓ All systems OK"
+```
+
 ## Troubleshooting the Fixes
 
 **If automated fix fails:**
 1. Run the diagnostic script from [diagnostics.md](diagnostics.md)
-2. Check specific error in PM2 logs
+2. Check specific error in worker logs:
+   ```bash
+   tail -50 ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
+   ```
 3. Try manual worker start to see detailed error:
    ```bash
    cd ~/.claude/plugins/marketplaces/thedotmack/
-   node plugin/scripts/worker-service.cjs
+   bun plugin/scripts/worker-service.js
    ```
+4. Use the bug report tool:
+   ```bash
+   npm run bug-report
+   ```
+
+## Common Error Patterns and Fixes
+
+| Error Pattern | Likely Cause | Quick Fix |
+|---------------|--------------|-----------|
+| `EADDRINUSE` | Port conflict | Change port in settings.json |
+| `SQLITE_ERROR` | Database corruption | Run integrity check, recreate if needed |
+| `ENOENT` | Missing files | Run `npm install` |
+| `Module not found` | Dependency issue | Clean reinstall |
+| Connection refused | Worker not running | `npm run worker:start` |
+| Stale PID | Old PID file | Remove `~/.claude-mem/worker.pid` |

plugin/skills/troubleshoot/operations/common-issues.md

@@ -17,7 +17,8 @@ Quick fixes for frequently encountered claude-mem problems.
 **Fix:**
 1. Verify worker is running:
    ```bash
-   pm2 jlist | grep claude-mem-worker
+   cd ~/.claude/plugins/marketplaces/thedotmack/
+   npm run worker:status
    ```
 
 2. Check database has recent observations:
@@ -27,7 +28,8 @@ Quick fixes for frequently encountered claude-mem problems.
 
 3. Restart worker and start new session:
    ```bash
-   pm2 restart claude-mem-worker
+   cd ~/.claude/plugins/marketplaces/thedotmack/
+   claude-mem restart
    ```
 
 4. Create a test observation: `/skill version-bump` then cancel
@@ -66,7 +68,7 @@ Quick fixes for frequently encountered claude-mem problems.
 
 3. Verify worker is using correct database path in logs:
    ```bash
-   pm2 logs claude-mem-worker --lines 50 --nostream | grep "Database"
+   grep "Database" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
    ```
 
 4. Test viewer connection manually:
@@ -109,34 +111,34 @@ Quick fixes for frequently encountered claude-mem problems.
 ## Issue: Worker Not Starting {#worker-not-starting}
 
 **Symptoms:**
-- PM2 shows worker as "stopped" or "errored"
+- Worker status shows not running or error
 - Health check fails
 - Viewer not accessible
 
 **Root cause:**
 - Port already in use
-- PM2 not installed or not in PATH
+- Bun not installed
 - Missing dependencies
 
 **Fix:**
 1. Try manual worker start to see error:
    ```bash
    cd ~/.claude/plugins/marketplaces/thedotmack/
-   node plugin/scripts/worker-service.cjs
+   bun plugin/scripts/worker-service.js
    # Should start server on port 37777 or show error
    ```
 
 2. If port in use, change it:
    ```bash
    mkdir -p ~/.claude-mem
-   echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json
+   echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
    ```
 
 3. If dependencies missing:
    ```bash
    cd ~/.claude/plugins/marketplaces/thedotmack/
    npm install
-   pm2 start ecosystem.config.cjs
+   npm run worker:start
    ```
 
 ## Issue: Search Results Empty
@@ -170,7 +172,8 @@ Quick fixes for frequently encountered claude-mem problems.
 
 4. If FTS5 out of sync, restart worker (triggers reindex):
    ```bash
-   pm2 restart claude-mem-worker
+   cd ~/.claude/plugins/marketplaces/thedotmack/
+   claude-mem restart
    ```
 
 ## Issue: Port Conflicts
@@ -189,8 +192,9 @@ Quick fixes for frequently encountered claude-mem problems.
 2. Either kill the conflicting process or change claude-mem port:
    ```bash
    mkdir -p ~/.claude-mem
-   echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json
-   pm2 restart claude-mem-worker
+   echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
+   cd ~/.claude/plugins/marketplaces/thedotmack/
+   claude-mem restart
    ```
 
 ## Issue: Database Corrupted
@@ -214,7 +218,8 @@ Quick fixes for frequently encountered claude-mem problems.
 3. If repair fails, recreate (loses data):
    ```bash
    rm ~/.claude-mem/claude-mem.db
-   pm2 restart claude-mem-worker
+   cd ~/.claude/plugins/marketplaces/thedotmack/
+   claude-mem restart
    # Worker will create new database
    ```
 

plugin/skills/troubleshoot/operations/database.md

@@ -172,7 +172,8 @@ SELECT
 If FTS5 counts don't match, triggers may have failed. Restart worker to rebuild:
 
 ```bash
-pm2 restart claude-mem-worker
+cd ~/.claude/plugins/marketplaces/thedotmack/
+claude-mem restart
 ```
 
 The worker will rebuild FTS5 indexes on startup if they're out of sync.
@@ -196,7 +197,7 @@ The worker will rebuild FTS5 indexes on startup if they're out of sync.
 1. Create test observation (use any skill and cancel)
 2. Check worker logs for errors:
    ```bash
-   pm2 logs claude-mem-worker --lines 50 --nostream
+   tail -50 ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
    ```
 3. Verify observation appears in database
 
@@ -228,9 +229,10 @@ ls -la ~/.claude-mem/claude-mem.db-wal
 ls -la ~/.claude-mem/claude-mem.db-shm
 
 # Remove lock files (only if worker is stopped!)
-pm2 stop claude-mem-worker
+cd ~/.claude/plugins/marketplaces/thedotmack/
+npm run worker:stop
 rm ~/.claude-mem/claude-mem.db-wal ~/.claude-mem/claude-mem.db-shm
-pm2 start claude-mem-worker
+npm run worker:start
 ```
 
 ### Issue: Database Growing Too Large
@@ -260,7 +262,8 @@ sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
 3. Archive and start fresh:
    ```bash
    mv ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.archive
-   pm2 restart claude-mem-worker
+   cd ~/.claude/plugins/marketplaces/thedotmack/
+   claude-mem restart
    ```
 
 ## Database Recovery
@@ -275,9 +278,10 @@ cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup
 ### Restore from Backup
 
 ```bash
-pm2 stop claude-mem-worker
+cd ~/.claude/plugins/marketplaces/thedotmack/
+npm run worker:stop
 cp ~/.claude-mem/claude-mem.db.backup ~/.claude-mem/claude-mem.db
-pm2 start claude-mem-worker
+npm run worker:start
 ```
 
 ### Export Data
@@ -300,8 +304,10 @@ sqlite3 ~/.claude-mem/claude-mem.db -json "SELECT * FROM user_prompts;" > prompt
 **WARNING: Data loss. Backup first!**
 
 ```bash
+cd ~/.claude/plugins/marketplaces/thedotmack/
+
 # Stop worker
-pm2 stop claude-mem-worker
+npm run worker:stop
 
 # Backup current database
 cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.old
@@ -310,7 +316,7 @@ cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.old
 rm ~/.claude-mem/claude-mem.db
 
 # Start worker (creates new database)
-pm2 start claude-mem-worker
+npm run worker:start
 ```
 
 ## Database Statistics

plugin/skills/troubleshoot/operations/diagnostics.md

@@ -6,29 +6,42 @@ Comprehensive step-by-step diagnostic workflow for claude-mem issues.
 
 Run these checks systematically to identify the root cause:
 
-### 1. Check PM2 Worker Status
+### 1. Check Worker Status
 
 First, verify if the worker service is running:
 
 ```bash
-# Check if PM2 is available
-which pm2 || echo "PM2 not found in PATH"
+# Check worker status using npm script
+cd ~/.claude/plugins/marketplaces/thedotmack/
+npm run worker:status
 
-# List PM2 processes
-pm2 jlist 2>&1
-
-# If pm2 is not found, try the local installation
-~/.claude/plugins/marketplaces/thedotmack/node_modules/.bin/pm2 jlist 2>&1
+# Or check health endpoint directly
+curl -s http://127.0.0.1:37777/health
 ```
 
-**Expected output:** JSON array with `claude-mem-worker` process showing `"status": "online"`
+**Expected output from npm run worker:status:**
+```
+✓ Worker is running (PID: 12345)
+  Port: 37777
+  Uptime: 45m
+  Health: OK
+```
 
-**If worker not running or status is not "online":**
+**Expected output from health endpoint:** `{"status":"ok"}`
+
+**If worker not running:**
 ```bash
 cd ~/.claude/plugins/marketplaces/thedotmack/
-pm2 start ecosystem.config.cjs
-# Or use local pm2:
-node_modules/.bin/pm2 start ecosystem.config.cjs
+npm run worker:start
+```
+
+**If health endpoint fails but worker reports running:**
+Check for stale PID file:
+```bash
+cat ~/.claude-mem/worker.pid
+ps -p $(cat ~/.claude-mem/worker.pid 2>/dev/null | grep -o '"pid":[0-9]*' | grep -o '[0-9]*') 2>/dev/null || echo "Stale PID - worker not actually running"
+rm ~/.claude-mem/worker.pid
+npm run worker:start
 ```
 
 ### 2. Check Worker Service Health
@@ -98,10 +111,12 @@ cd ~/.claude/plugins/marketplaces/thedotmack/
 # Check for critical packages
 ls node_modules/@anthropic-ai/claude-agent-sdk 2>&1 | head -1
 ls node_modules/express 2>&1 | head -1
-ls node_modules/pm2 2>&1 | head -1
+
+# Check if Bun is available
+bun --version 2>&1
 ```
 
-**Expected:** All critical packages present
+**Expected:** All critical packages present, Bun installed
 
 **If dependencies missing:**
 ```bash
@@ -114,17 +129,26 @@ npm install
 Review recent worker logs for errors:
 
 ```bash
-# View last 50 lines of worker logs
-pm2 logs claude-mem-worker --lines 50 --nostream
-
-# Or use local pm2:
+# View logs using npm script
 cd ~/.claude/plugins/marketplaces/thedotmack/
-node_modules/.bin/pm2 logs claude-mem-worker --lines 50 --nostream
+npm run worker:logs
+
+# View today's log file directly
+cat ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
+
+# Last 50 lines
+tail -50 ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
 
 # Check for specific errors
-pm2 logs claude-mem-worker --lines 100 --nostream | grep -i "error\|exception\|failed"
+grep -iE "error|exception|failed" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log | tail -20
 ```
 
+**Common error patterns to look for:**
+- `SQLITE_ERROR` - Database issues
+- `EADDRINUSE` - Port conflict
+- `ENOENT` - Missing files
+- `Module not found` - Dependency issues
+
 ### 6. Test Viewer UI
 
 Check if the web viewer is accessible:
@@ -167,6 +191,8 @@ echo "=== Claude-Mem Troubleshooting Report ==="
 echo ""
 echo "1. Environment"
 echo "   OS: $(uname -s)"
+echo "   Node version: $(node --version 2>/dev/null || echo 'N/A')"
+echo "   Bun version: $(bun --version 2>/dev/null || echo 'N/A')"
 echo ""
 echo "2. Plugin Installation"
 echo "   Plugin directory exists: $([ -d ~/.claude/plugins/marketplaces/thedotmack ] && echo 'YES' || echo 'NO')"
@@ -179,20 +205,28 @@ echo "   Observation count: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(
 echo "   Session count: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(*) FROM sessions;' 2>/dev/null || echo 'N/A')"
 echo ""
 echo "4. Worker Service"
-PM2_PATH=$(which pm2 2>/dev/null || echo "~/.claude/plugins/marketplaces/thedotmack/node_modules/.bin/pm2")
-echo "   PM2 path: $PM2_PATH"
-WORKER_STATUS=$($PM2_PATH jlist 2>/dev/null | grep -o '"name":"claude-mem-worker".*"status":"[^"]*"' | grep -o 'status":"[^"]*"' | cut -d'"' -f3 || echo 'not running')
-echo "   Worker status: $WORKER_STATUS"
+echo "   Worker PID file: $([ -f ~/.claude-mem/worker.pid ] && echo 'EXISTS' || echo 'MISSING')"
+if [ -f ~/.claude-mem/worker.pid ]; then
+  WORKER_PID=$(cat ~/.claude-mem/worker.pid 2>/dev/null | grep -o '"pid":[0-9]*' | grep -o '[0-9]*')
+  echo "   Worker PID: $WORKER_PID"
+  echo "   Process running: $(ps -p $WORKER_PID >/dev/null 2>&1 && echo 'YES' || echo 'NO (stale PID)')"
+fi
 echo "   Health check: $(curl -s http://127.0.0.1:37777/health 2>/dev/null || echo 'FAILED')"
 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-mem/settings.json 2>/dev/null | grep CLAUDE_MEM_CONTEXT_OBSERVATIONS || echo 'default (50)')"
+echo "   Model: $(cat ~/.claude-mem/settings.json 2>/dev/null | grep CLAUDE_MEM_MODEL || echo 'default (claude-sonnet-4-5)')"
 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')"
 echo "   Latest session: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT created_at FROM sessions ORDER BY created_at DESC LIMIT 1;' 2>/dev/null || echo 'N/A')"
 echo ""
+echo "7. Logs"
+echo "   Today's log file: $([ -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log ] && echo 'EXISTS' || echo 'MISSING')"
+echo "   Log file size: $(du -h ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log 2>/dev/null | cut -f1 || echo 'N/A')"
+echo "   Recent errors: $(grep -c -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log 2>/dev/null || echo '0')"
+echo ""
 echo "=== End Report ==="
 ```
 
@@ -201,18 +235,75 @@ Save this as `/tmp/claude-mem-diagnostics.sh` and run:
 bash /tmp/claude-mem-diagnostics.sh
 ```
 
+## Quick Diagnostic One-Liners
+
+```bash
+# Full status check
+npm run worker:status && curl -s http://127.0.0.1:37777/health && echo " - All systems OK"
+
+# Database stats
+echo "DB: $(du -h ~/.claude-mem/claude-mem.db | cut -f1) | Obs: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(*) FROM observations;' 2>/dev/null) | Sessions: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(*) FROM sessions;' 2>/dev/null)"
+
+# Recent errors
+grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log 2>/dev/null | tail -5 || echo "No recent errors"
+
+# Port check
+lsof -i :37777 || echo "Port 37777 is free"
+
+# Worker process check
+ps aux | grep -E "bun.*worker-service" | grep -v grep || echo "Worker not running"
+```
+
+## Automated Fix Sequence
+
+If diagnostics show issues, run this automated fix sequence:
+
+```bash
+#!/bin/bash
+echo "Running automated fix sequence..."
+
+# 1. Stop worker if running
+echo "1. Stopping worker..."
+cd ~/.claude/plugins/marketplaces/thedotmack/
+npm run worker:stop
+
+# 2. Clean stale PID if exists
+echo "2. Cleaning stale PID file..."
+rm -f ~/.claude-mem/worker.pid
+
+# 3. Reinstall dependencies
+echo "3. Reinstalling dependencies..."
+npm install
+
+# 4. Start worker
+echo "4. Starting worker..."
+npm run worker:start
+
+# 5. Wait for startup
+echo "5. Waiting for worker to start..."
+sleep 3
+
+# 6. Verify health
+echo "6. Verifying health..."
+curl -s http://127.0.0.1:37777/health || echo "Worker health check FAILED"
+
+echo "Fix sequence complete!"
+```
+
 ## Reporting Issues
 
-If troubleshooting doesn't resolve the issue, collect this information for a bug report:
+If troubleshooting doesn't resolve the issue, run the built-in bug report tool:
 
-1. Full diagnostic report (run script above)
-2. Worker logs: `pm2 logs claude-mem-worker --lines 100 --nostream`
-3. Your setup:
-   - Claude version: Check with Claude
-   - OS: `uname -a`
-   - Node version: `node --version`
-   - Plugin version: In package.json
-4. Steps to reproduce the issue
-5. Expected vs actual behavior
+```bash
+cd ~/.claude/plugins/marketplaces/thedotmack/
+npm run bug-report
+```
 
-Post to: https://github.com/thedotmack/claude-mem/issues
+This will collect:
+1. Full diagnostic report
+2. Worker logs
+3. System information
+4. Configuration details
+5. Database stats
+
+Post the generated report to: https://github.com/thedotmack/claude-mem/issues

plugin/skills/troubleshoot/operations/reference.md

@@ -6,30 +6,29 @@ Essential commands for troubleshooting claude-mem.
 
 ```bash
 # Check worker status
-pm2 status | grep claude-mem-worker
-pm2 jlist | grep claude-mem-worker  # JSON format
+cd ~/.claude/plugins/marketplaces/thedotmack/
+npm run worker:status
 
 # Start worker
-cd ~/.claude/plugins/marketplaces/thedotmack/
-pm2 start ecosystem.config.cjs
+npm run worker:start
 
 # Restart worker
-pm2 restart claude-mem-worker
+claude-mem restart
 
 # Stop worker
-pm2 stop claude-mem-worker
-
-# Delete worker (for clean restart)
-pm2 delete claude-mem-worker
+npm run worker:stop
 
 # View logs
-pm2 logs claude-mem-worker
+npm run worker:logs
 
-# View last N lines
-pm2 logs claude-mem-worker --lines 50 --nostream
+# View today's log file
+cat ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
 
-# Clear logs
-pm2 flush claude-mem-worker
+# Last 50 lines
+tail -50 ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
+
+# Follow logs in real-time
+tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
 ```
 
 ## Health Checks
@@ -82,21 +81,17 @@ cat ~/.claude-mem/settings.json
 cat ~/.claude/settings.json
 
 # Change worker port
-echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json
+echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
 
 # Change context observation count
 # Edit ~/.claude-mem/settings.json and add:
 {
-  "env": {
-    "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "25"
-  }
+  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "25"
 }
 
 # Change AI model
 {
-  "env": {
-    "CLAUDE_MEM_MODEL": "claude-sonnet-4-5"
-  }
+  "CLAUDE_MEM_MODEL": "claude-sonnet-4-5"
 }
 ```
 
@@ -132,16 +127,19 @@ curl -v http://127.0.0.1:37777/health
 
 ```bash
 # Search logs for errors
-pm2 logs claude-mem-worker --lines 100 --nostream | grep -i "error"
+grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
 
 # Search for specific keyword
-pm2 logs claude-mem-worker --lines 100 --nostream | grep "keyword"
+grep "keyword" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
+
+# Search across all log files
+grep -i "error" ~/.claude-mem/logs/worker-*.log
+
+# Last 100 error lines
+grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log | tail -100
 
 # Follow logs in real-time
-pm2 logs claude-mem-worker
-
-# Show only error logs
-pm2 logs claude-mem-worker --err
+tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
 ```
 
 ## File Locations
@@ -160,11 +158,11 @@ pm2 logs claude-mem-worker --err
 # Chroma vector database
 ~/.claude-mem/chroma/
 
-# Usage logs
-~/.claude-mem/usage-logs/
+# Worker logs (daily rotation)
+~/.claude-mem/logs/worker-*.log
 
-# PM2 logs
-~/.pm2/logs/
+# Worker PID file
+~/.claude-mem/worker.pid
 ```
 
 ## System Information
@@ -179,8 +177,8 @@ node --version
 # NPM version
 npm --version
 
-# PM2 version
-pm2 --version
+# Bun version
+bun --version
 
 # SQLite version
 sqlite3 --version
@@ -188,3 +186,22 @@ sqlite3 --version
 # Check disk space
 df -h ~/.claude-mem/
 ```
+
+## One-Line Diagnostics
+
+```bash
+# Full worker status check
+npm run worker:status && curl -s http://127.0.0.1:37777/health
+
+# Quick health check
+curl -s http://127.0.0.1:37777/health && echo " - Worker is healthy"
+
+# Database stats
+echo "Observations: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(*) FROM observations;')" && echo "Sessions: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(*) FROM sessions;')"
+
+# Recent errors
+grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log | tail -10
+
+# Port check
+lsof -i :37777 || echo "Port 37777 is free"
+```

plugin/skills/troubleshoot/operations/worker.md

@@ -1,10 +1,10 @@
 # Worker Service Diagnostics
 
-PM2 worker-specific troubleshooting for claude-mem.
+Bun worker-specific troubleshooting for claude-mem.
 
-## PM2 Worker Overview
+## Worker Overview
 
-The claude-mem worker is a persistent background service managed by PM2. It:
+The claude-mem worker is a persistent background service managed by Bun. It:
 - Runs Express.js server on port 37777 (default)
 - Processes observations asynchronously
 - Serves the viewer UI
@@ -15,36 +15,41 @@ The claude-mem worker is a persistent background service managed by PM2. It:
 ### Basic Status Check
 
 ```bash
-# List all PM2 processes
-pm2 list
+# Check worker status using npm script
+cd ~/.claude/plugins/marketplaces/thedotmack/
+npm run worker:status
 
-# JSON format (parseable)
-pm2 jlist
-
-# Filter for claude-mem-worker
-pm2 status | grep claude-mem-worker
+# Or check health endpoint directly
+curl -s http://127.0.0.1:37777/health
 ```
 
-**Expected output:**
+**Expected npm run worker:status output:**
 ```
-│ claude-mem-worker │ online    │ 12345  │ 0    │ 45m │ 0% │ 85.6mb │
+✓ Worker is running (PID: 12345)
+  Port: 37777
+  Uptime: 45m
+  Health: OK
 ```
 
-**Status meanings:**
-- `online` - Worker running correctly
-- `stopped` - Worker stopped (normal shutdown)
-- `errored` - Worker crashed (check logs)
-- `stopping` - Worker shutting down
-- Not listed - Worker never started
+**Expected health endpoint output:**
+```json
+{"status":"ok"}
+```
+
+**Status indicators:**
+- `Worker is running` - Worker running correctly
+- `Worker is not running` - Worker stopped or crashed
+- Connection refused - Worker not running
+- Timeout - Worker hung (restart needed)
 
 ### Detailed Worker Info
 
 ```bash
-# Show detailed information
-pm2 show claude-mem-worker
+# View PID file
+cat ~/.claude-mem/worker.pid
 
-# JSON format
-pm2 jlist | grep -A 20 '"name":"claude-mem-worker"'
+# Check process details
+ps aux | grep "bun.*worker-service"
 ```
 
 ## Worker Health Endpoint
@@ -72,30 +77,37 @@ curl -s http://127.0.0.1:$PORT/health
 ### View Recent Logs
 
 ```bash
-# Last 50 lines
-pm2 logs claude-mem-worker --lines 50 --nostream
+# View logs using npm script
+cd ~/.claude/plugins/marketplaces/thedotmack/
+npm run worker:logs
 
-# Last 200 lines
-pm2 logs claude-mem-worker --lines 200 --nostream
+# View today's log file directly
+cat ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
+
+# Last 50 lines of today's log
+tail -50 ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
 
 # Follow logs in real-time
-pm2 logs claude-mem-worker
+tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
 ```
 
 ### Search Logs for Errors
 
 ```bash
-# Find errors
-pm2 logs claude-mem-worker --lines 500 --nostream | grep -i "error"
+# Find errors in today's log
+grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
 
 # Find exceptions
-pm2 logs claude-mem-worker --lines 500 --nostream | grep -i "exception"
+grep -i "exception" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
 
 # Find failed requests
-pm2 logs claude-mem-worker --lines 500 --nostream | grep -i "failed"
+grep -i "failed" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
 
 # All error patterns
-pm2 logs claude-mem-worker --lines 500 --nostream | grep -iE "error|exception|failed|crash"
+grep -iE "error|exception|failed|crash" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
+
+# Search across all log files
+grep -iE "error|exception|failed|crash" ~/.claude-mem/logs/worker-*.log
 ```
 
 ### Common Log Patterns
@@ -122,8 +134,8 @@ Port 37777 already in use
 
 **Crashes:**
 ```
-PM2        | App [claude-mem-worker] exited with code [1]
-PM2        | App [claude-mem-worker] will restart in 100ms
+Worker process exited with code 1
+Worker restarting...
 ```
 
 ## Starting the Worker
@@ -132,37 +144,26 @@ PM2        | App [claude-mem-worker] will restart in 100ms
 
 ```bash
 cd ~/.claude/plugins/marketplaces/thedotmack/
-pm2 start ecosystem.config.cjs
-```
-
-### Start with Local PM2
-
-If `pm2` command not in PATH:
-
-```bash
-cd ~/.claude/plugins/marketplaces/thedotmack/
-node_modules/.bin/pm2 start ecosystem.config.cjs
+npm run worker:start
 ```
 
 ### Force Restart
 
 ```bash
-# Restart if already running
-pm2 restart claude-mem-worker
+# Restart worker (stops and starts)
+cd ~/.claude/plugins/marketplaces/thedotmack/
+claude-mem restart
 
-# Delete and start fresh
-pm2 delete claude-mem-worker
-pm2 start ecosystem.config.cjs
+# Or manually stop and start
+npm run worker:stop
+npm run worker:start
 ```
 
 ## Stopping the Worker
 
 ```bash
-# Graceful stop
-pm2 stop claude-mem-worker
-
-# Delete completely (also removes from PM2 list)
-pm2 delete claude-mem-worker
+cd ~/.claude/plugins/marketplaces/thedotmack/
+npm run worker:stop
 ```
 
 ## Worker Not Starting
@@ -172,23 +173,22 @@ pm2 delete claude-mem-worker
 1. **Try manual start to see error:**
    ```bash
    cd ~/.claude/plugins/marketplaces/thedotmack/
-   node plugin/scripts/worker-service.cjs
+   bun plugin/scripts/worker-service.js
    ```
-   This runs the worker directly without PM2, showing full error output.
+   This runs the worker directly, showing full error output.
 
-2. **Check PM2 itself:**
+2. **Check Bun installation:**
    ```bash
-   which pm2
-   pm2 --version
+   which bun
+   bun --version
    ```
-   If PM2 not found, dependencies not installed.
+   If Bun not found, run: `npm install` (auto-installs Bun)
 
 3. **Check dependencies:**
    ```bash
    cd ~/.claude/plugins/marketplaces/thedotmack/
    ls node_modules/@anthropic-ai/claude-agent-sdk
    ls node_modules/express
-   ls node_modules/pm2
    ```
 
 4. **Check port availability:**
@@ -197,42 +197,57 @@ pm2 delete claude-mem-worker
    ```
    If port in use, either kill that process or change claude-mem port.
 
+5. **Check PID file:**
+   ```bash
+   cat ~/.claude-mem/worker.pid
+   ```
+   If worker PID exists but process is dead, remove stale PID:
+   ```bash
+   rm ~/.claude-mem/worker.pid
+   npm run worker:start
+   ```
+
 ### Common Fixes
 
 **Dependencies missing:**
 ```bash
 cd ~/.claude/plugins/marketplaces/thedotmack/
 npm install
-pm2 start ecosystem.config.cjs
+npm run worker:start
 ```
 
 **Port conflict:**
 ```bash
-echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json
-pm2 restart claude-mem-worker
+echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
+claude-mem restart
 ```
 
-**Corrupted PM2:**
+**Stale PID file:**
 ```bash
-pm2 kill  # Stop PM2 daemon
-cd ~/.claude/plugins/marketplaces/thedotmack/
-pm2 start ecosystem.config.cjs
+rm ~/.claude-mem/worker.pid
+npm run worker:start
 ```
 
 ## Worker Crashing Repeatedly
 
-If worker keeps restarting (check with `pm2 status` showing high restart count):
+If worker keeps restarting (check logs for repeated startup messages):
 
 ### Find the Cause
 
 1. **Check error logs:**
    ```bash
-   pm2 logs claude-mem-worker --err --lines 100 --nostream
+   grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log | tail -100
    ```
 
 2. **Look for crash pattern:**
    ```bash
-   pm2 logs claude-mem-worker --lines 200 --nostream | grep -A 5 "exited with code"
+   grep -A 5 "exited with code" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
+   ```
+
+3. **Run worker in foreground to see crashes:**
+   ```bash
+   cd ~/.claude/plugins/marketplaces/thedotmack/
+   bun plugin/scripts/worker-service.js
    ```
 
 ### Common Crash Causes
@@ -246,43 +261,71 @@ If fails, backup and recreate database.
 **Out of memory:**
 Check if database is too large or memory leak. Restart:
 ```bash
-pm2 restart claude-mem-worker
+claude-mem restart
 ```
 
 **Port conflict race condition:**
 Another process grabbing port intermittently. Change port:
 ```bash
-echo '{"env":{"CLAUDE_MEM_WORKER_PORT":"37778"}}' > ~/.claude-mem/settings.json
-pm2 restart claude-mem-worker
+echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
+claude-mem restart
 ```
 
-## PM2 Management Commands
+## Worker Management Commands
 
 ```bash
-# List processes
-pm2 list
-pm2 jlist  # JSON format
+# Check status
+npm run worker:status
 
-# Show detailed info
-pm2 show claude-mem-worker
+# Start worker
+npm run worker:start
 
-# Monitor resources
-pm2 monit
+# Stop worker
+npm run worker:stop
 
-# Clear logs
-pm2 flush claude-mem-worker
+# Restart worker
+claude-mem restart
 
-# Restart PM2 daemon
-pm2 kill
-pm2 resurrect  # Restore saved processes
+# View logs
+npm run worker:logs
 
-# Save current process list
-pm2 save
+# Check health endpoint
+curl -s http://127.0.0.1:37777/health
 
-# Update PM2
-npm install -g pm2
+# View PID
+cat ~/.claude-mem/worker.pid
+
+# View today's log file
+cat ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
+
+# List all log files
+ls -lh ~/.claude-mem/logs/worker-*.log
 ```
 
+## Log File Management
+
+Worker logs are stored in `~/.claude-mem/logs/` with daily rotation:
+
+```bash
+# View today's log
+cat ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
+
+# View yesterday's log
+cat ~/.claude-mem/logs/worker-$(date -d "yesterday" +%Y-%m-%d).log  # Linux
+cat ~/.claude-mem/logs/worker-$(date -v-1d +%Y-%m-%d).log          # macOS
+
+# List all logs
+ls -lh ~/.claude-mem/logs/
+
+# Clean old logs (older than 7 days)
+find ~/.claude-mem/logs/ -name "worker-*.log" -mtime +7 -delete
+
+# Archive logs
+tar -czf ~/claude-mem-logs-backup-$(date +%Y-%m-%d).tar.gz ~/.claude-mem/logs/
+```
+
+**Note:** Logs auto-rotate daily. No manual flush required.
+
 ## Testing Worker Endpoints
 
 Once worker is running, test all endpoints:
@@ -298,10 +341,22 @@ curl -s http://127.0.0.1:37777/ | head -20
 curl -s http://127.0.0.1:37777/api/stats
 
 # Search API
-curl -s "http://127.0.0.1:37777/api/search/observations?q=test&format=index"
+curl -s "http://127.0.0.1:37777/api/search?query=test&limit=5"
 
-# Prompts API
-curl -s "http://127.0.0.1:37777/api/prompts?limit=5"
+# Recent context
+curl -s "http://127.0.0.1:37777/api/context/recent?limit=3"
 ```
 
 All should return appropriate responses (HTML for viewer, JSON for APIs).
+
+## Troubleshooting Quick Reference
+
+| Problem | Command | Expected Result |
+|---------|---------|----------------|
+| Check if running | `npm run worker:status` | Shows PID and uptime |
+| Worker not running | `npm run worker:start` | Worker starts successfully |
+| Worker crashed | `claude-mem restart` | Worker restarts |
+| View recent errors | `grep -i error ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log \| tail -20` | Shows recent errors |
+| Port in use | `lsof -i :37777` | Shows process using port |
+| Stale PID | `rm ~/.claude-mem/worker.pid && npm run worker:start` | Removes stale PID and starts |
+| Dependencies missing | `npm install && npm run worker:start` | Installs deps and starts |

scripts/analyze-transformations-smart.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import fs from 'fs';
-import Database from 'better-sqlite3';
+import { Database } from 'bun:sqlite';
 import readline from 'readline';
 import path from 'path';
 import { homedir } from 'os';

scripts/build-hooks.js

@@ -26,6 +26,11 @@ const WORKER_SERVICE = {
   source: 'src/services/worker-service.ts'
 };
 
+const WORKER_WRAPPER = {
+  name: 'worker-wrapper',
+  source: 'src/services/worker-wrapper.ts'
+};
+
 const MCP_SERVER = {
   name: 'mcp-server',
   source: 'src/servers/mcp-server.ts'
@@ -120,6 +125,31 @@ async function buildHooks() {
     const workerStats = fs.statSync(`${hooksDir}/${WORKER_SERVICE.name}.cjs`);
     console.log(`✓ worker-service built (${(workerStats.size / 1024).toFixed(2)} KB)`);
 
+    // Build worker wrapper (Windows zombie port fix)
+    console.log(`\n🔧 Building worker wrapper...`);
+    await build({
+      entryPoints: [WORKER_WRAPPER.source],
+      bundle: true,
+      platform: 'node',
+      target: 'node18',
+      format: 'cjs',
+      outfile: `${hooksDir}/${WORKER_WRAPPER.name}.cjs`,
+      minify: true,
+      logLevel: 'error',
+      external: ['bun:sqlite'],
+      define: {
+        '__DEFAULT_PACKAGE_VERSION__': `"${version}"`
+      },
+      banner: {
+        js: '#!/usr/bin/env bun'
+      }
+    });
+
+    // Make worker wrapper executable
+    fs.chmodSync(`${hooksDir}/${WORKER_WRAPPER.name}.cjs`, 0o755);
+    const wrapperStats = fs.statSync(`${hooksDir}/${WORKER_WRAPPER.name}.cjs`);
+    console.log(`✓ worker-wrapper built (${(wrapperStats.size / 1024).toFixed(2)} KB)`);
+
     // Build MCP server
     console.log(`\n🔧 Building MCP server...`);
     await build({
@@ -136,7 +166,7 @@ async function buildHooks() {
         '__DEFAULT_PACKAGE_VERSION__': `"${version}"`
       },
       banner: {
-        js: '#!/usr/bin/env bun'
+        js: '#!/usr/bin/env node'
       }
     });
 

scripts/discord-release-notify.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+/**
+ * Post release notification to Discord
+ *
+ * Usage:
+ *   node scripts/discord-release-notify.js v7.4.2
+ *   node scripts/discord-release-notify.js v7.4.2 "Custom release notes"
+ *
+ * Requires DISCORD_UPDATES_WEBHOOK in .env file
+ */
+
+import { execSync } from 'child_process';
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '..');
+
+function loadEnv() {
+  const envPath = resolve(projectRoot, '.env');
+  if (!existsSync(envPath)) {
+    console.error('❌ .env file not found');
+    process.exit(1);
+  }
+
+  const envContent = readFileSync(envPath, 'utf-8');
+  const webhookMatch = envContent.match(/DISCORD_UPDATES_WEBHOOK=(.+)/);
+
+  if (!webhookMatch) {
+    console.error('❌ DISCORD_UPDATES_WEBHOOK not found in .env');
+    process.exit(1);
+  }
+
+  return webhookMatch[1].trim();
+}
+
+function getReleaseNotes(version) {
+  try {
+    const notes = execSync(`gh release view ${version} --json body --jq '.body'`, {
+      encoding: 'utf-8',
+      cwd: projectRoot,
+    }).trim();
+    return notes;
+  } catch {
+    return null;
+  }
+}
+
+function cleanNotes(notes) {
+  // Remove Claude Code footer and clean up
+  return notes
+    .replace(/🤖 Generated with \[Claude Code\].*$/s, '')
+    .replace(/---\n*$/s, '')
+    .trim();
+}
+
+function truncate(text, maxLength) {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength - 3) + '...';
+}
+
+async function postToDiscord(webhookUrl, version, notes) {
+  const cleanedNotes = notes ? cleanNotes(notes) : 'No release notes available.';
+  const repoUrl = 'https://github.com/thedotmack/claude-mem';
+
+  const payload = {
+    embeds: [
+      {
+        title: `🚀 claude-mem ${version} released`,
+        url: `${repoUrl}/releases/tag/${version}`,
+        description: truncate(cleanedNotes, 2000),
+        color: 0x7c3aed, // Purple
+        fields: [
+          {
+            name: '📦 Install',
+            value: 'Update via Claude Code plugin marketplace',
+            inline: true,
+          },
+          {
+            name: '📚 Docs',
+            value: '[docs.claude-mem.ai](https://docs.claude-mem.ai)',
+            inline: true,
+          },
+        ],
+        footer: {
+          text: 'claude-mem • Persistent memory for Claude Code',
+        },
+        timestamp: new Date().toISOString(),
+      },
+    ],
+  };
+
+  const response = await fetch(webhookUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Discord API error: ${response.status} - ${errorText}`);
+  }
+
+  return true;
+}
+
+async function main() {
+  const version = process.argv[2];
+  const customNotes = process.argv[3];
+
+  if (!version) {
+    console.error('Usage: node scripts/discord-release-notify.js <version> [notes]');
+    console.error('Example: node scripts/discord-release-notify.js v7.4.2');
+    process.exit(1);
+  }
+
+  console.log(`📣 Posting release notification for ${version}...`);
+
+  const webhookUrl = loadEnv();
+  const notes = customNotes || getReleaseNotes(version);
+
+  if (!notes && !customNotes) {
+    console.warn('⚠️  Could not fetch release notes from GitHub, proceeding without them');
+  }
+
+  try {
+    await postToDiscord(webhookUrl, version, notes);
+    console.log('✅ Discord notification sent successfully!');
+  } catch (error) {
+    console.error('❌ Failed to send Discord notification:', error.message);
+    process.exit(1);
+  }
+}
+
+main();

scripts/export-memories.ts

@@ -5,8 +5,7 @@
  * Example: npx tsx scripts/export-memories.ts "windows" windows-memories.json --project=claude-mem
  */
 
-import Database from 'better-sqlite3';
-import { existsSync, writeFileSync } from 'fs';
+import { writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { SettingsDefaultsManager } from '../src/shared/SettingsDefaultsManager';
@@ -127,33 +126,19 @@ async function exportMemories(query: string, outputFile: string, project?: strin
       if (s.sdk_session_id) sdkSessionIds.add(s.sdk_session_id);
     });
 
-    // Get SDK sessions metadata from database
-    // (We need this because the API doesn't expose sdk_sessions table directly)
+    // Get SDK sessions metadata via API
     console.log('📡 Fetching SDK sessions metadata...');
-    const sessions: SdkSessionRecord[] = [];
+    let sessions: SdkSessionRecord[] = [];
     if (sdkSessionIds.size > 0) {
-      // Read directly from database for sdk_sessions table
-      const Database = (await import('better-sqlite3')).default;
-      const dbPath = join(homedir(), '.claude-mem', 'claude-mem.db');
-
-      if (!existsSync(dbPath)) {
-        console.error(`❌ Database not found at: ${dbPath}`);
-        console.error('💡 Has claude-mem been initialized? Try running a session first.');
-        process.exit(1);
-      }
-
-      const db = new Database(dbPath, { readonly: true });
-
-      try {
-        const placeholders = Array.from(sdkSessionIds).map(() => '?').join(',');
-        const sessionQuery = `
-          SELECT * FROM sdk_sessions
-          WHERE sdk_session_id IN (${placeholders})
-          ORDER BY started_at_epoch DESC
-        `;
-        sessions.push(...db.prepare(sessionQuery).all(...Array.from(sdkSessionIds)));
-      } finally {
-        db.close();
+      const sessionsResponse = await fetch(`${baseUrl}/api/sdk-sessions/batch`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ sdkSessionIds: Array.from(sdkSessionIds) })
+      });
+      if (sessionsResponse.ok) {
+        sessions = await sessionsResponse.json();
+      } else {
+        console.warn(`⚠️ Failed to fetch SDK sessions: ${sessionsResponse.status}`);
       }
     }
     console.log(`✅ Found ${sessions.length} SDK sessions`);

scripts/extract-search-manager.js

@@ -1,229 +0,0 @@
-#!/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`);

scripts/import-memories.ts

@@ -3,37 +3,21 @@
  * Import memories from a JSON export file with duplicate prevention
  * Usage: npx tsx scripts/import-memories.ts <input-file>
  * Example: npx tsx scripts/import-memories.ts windows-memories.json
+ *
+ * This script uses the worker API instead of direct database access.
  */
 
-import Database from 'better-sqlite3';
 import { existsSync, readFileSync } from 'fs';
-import { homedir } from 'os';
-import { join } from 'path';
 
-interface ImportStats {
-  sessionsImported: number;
-  sessionsSkipped: number;
-  summariesImported: number;
-  summariesSkipped: number;
-  observationsImported: number;
-  observationsSkipped: number;
-  promptsImported: number;
-  promptsSkipped: number;
-}
+const WORKER_PORT = process.env.CLAUDE_MEM_WORKER_PORT || 37777;
+const WORKER_URL = `http://127.0.0.1:${WORKER_PORT}`;
 
-function importMemories(inputFile: string) {
+async function importMemories(inputFile: string) {
   if (!existsSync(inputFile)) {
     console.error(`❌ Input file not found: ${inputFile}`);
     process.exit(1);
   }
 
-  const dbPath = join(homedir(), '.claude-mem', 'claude-mem.db');
-
-  if (!existsSync(dbPath)) {
-    console.error(`❌ Database not found at: ${dbPath}`);
-    process.exit(1);
-  }
-
   // Read and parse export file
   const exportData = JSON.parse(readFileSync(inputFile, 'utf-8'));
 
@@ -47,190 +31,50 @@ function importMemories(inputFile: string) {
   console.log(`   • ${exportData.totalPrompts} prompts`);
   console.log('');
 
-  const db = new Database(dbPath);
-  const stats: ImportStats = {
-    sessionsImported: 0,
-    sessionsSkipped: 0,
-    summariesImported: 0,
-    summariesSkipped: 0,
-    observationsImported: 0,
-    observationsSkipped: 0,
-    promptsImported: 0,
-    promptsSkipped: 0
-  };
-
+  // Check if worker is running
   try {
-    // Prepare statements for duplicate checking
-    const checkSession = db.prepare('SELECT id FROM sdk_sessions WHERE claude_session_id = ?');
-    const checkSummary = db.prepare('SELECT id FROM session_summaries WHERE sdk_session_id = ?');
-    const checkObservation = db.prepare(`
-      SELECT id FROM observations
-      WHERE sdk_session_id = ?
-        AND title = ?
-        AND created_at_epoch = ?
-    `);
-    const checkPrompt = db.prepare(`
-      SELECT id FROM user_prompts
-      WHERE claude_session_id = ?
-        AND prompt_number = ?
-    `);
-
-    // Prepare insert statements
-    const insertSession = db.prepare(`
-      INSERT INTO sdk_sessions (
-        claude_session_id, sdk_session_id, project, user_prompt,
-        started_at, started_at_epoch, completed_at, completed_at_epoch,
-        status
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `);
-
-    const insertSummary = db.prepare(`
-      INSERT INTO session_summaries (
-        sdk_session_id, project, request, investigated, learned,
-        completed, next_steps, files_read, files_edited, notes,
-        prompt_number, discovery_tokens, created_at, created_at_epoch
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `);
-
-    const insertObservation = db.prepare(`
-      INSERT INTO observations (
-        sdk_session_id, project, text, type, title, subtitle,
-        facts, narrative, concepts, files_read, files_modified,
-        prompt_number, discovery_tokens, created_at, created_at_epoch
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `);
-
-    const insertPrompt = db.prepare(`
-      INSERT INTO user_prompts (
-        claude_session_id, prompt_number, prompt_text,
-        created_at, created_at_epoch
-      ) VALUES (?, ?, ?, ?, ?)
-    `);
-
-    // Import in transaction
-    db.transaction(() => {
-      // 1. Import sessions first (dependency for everything else)
-      console.log('🔄 Importing sessions...');
-      for (const session of exportData.sessions) {
-        const exists = checkSession.get(session.claude_session_id);
-        if (exists) {
-          stats.sessionsSkipped++;
-          continue;
-        }
-
-        insertSession.run(
-          session.claude_session_id,
-          session.sdk_session_id,
-          session.project,
-          session.user_prompt,
-          session.started_at,
-          session.started_at_epoch,
-          session.completed_at,
-          session.completed_at_epoch,
-          session.status
-        );
-        stats.sessionsImported++;
-      }
-      console.log(`   ✅ Imported: ${stats.sessionsImported}, Skipped: ${stats.sessionsSkipped}`);
-
-      // 2. Import summaries (depends on sessions)
-      console.log('🔄 Importing summaries...');
-      for (const summary of exportData.summaries) {
-        const exists = checkSummary.get(summary.sdk_session_id);
-        if (exists) {
-          stats.summariesSkipped++;
-          continue;
-        }
-
-        insertSummary.run(
-          summary.sdk_session_id,
-          summary.project,
-          summary.request,
-          summary.investigated,
-          summary.learned,
-          summary.completed,
-          summary.next_steps,
-          summary.files_read,
-          summary.files_edited,
-          summary.notes,
-          summary.prompt_number,
-          summary.discovery_tokens || 0,
-          summary.created_at,
-          summary.created_at_epoch
-        );
-        stats.summariesImported++;
-      }
-      console.log(`   ✅ Imported: ${stats.summariesImported}, Skipped: ${stats.summariesSkipped}`);
-
-      // 3. Import observations (depends on sessions)
-      console.log('🔄 Importing observations...');
-      for (const obs of exportData.observations) {
-        const exists = checkObservation.get(
-          obs.sdk_session_id,
-          obs.title,
-          obs.created_at_epoch
-        );
-        if (exists) {
-          stats.observationsSkipped++;
-          continue;
-        }
-
-        insertObservation.run(
-          obs.sdk_session_id,
-          obs.project,
-          obs.text,
-          obs.type,
-          obs.title,
-          obs.subtitle,
-          obs.facts,
-          obs.narrative,
-          obs.concepts,
-          obs.files_read,
-          obs.files_modified,
-          obs.prompt_number,
-          obs.discovery_tokens || 0,
-          obs.created_at,
-          obs.created_at_epoch
-        );
-        stats.observationsImported++;
-      }
-      console.log(`   ✅ Imported: ${stats.observationsImported}, Skipped: ${stats.observationsSkipped}`);
-
-      // 4. Import prompts (depends on sessions)
-      console.log('🔄 Importing prompts...');
-      for (const prompt of exportData.prompts) {
-        const exists = checkPrompt.get(
-          prompt.claude_session_id,
-          prompt.prompt_number
-        );
-        if (exists) {
-          stats.promptsSkipped++;
-          continue;
-        }
-
-        insertPrompt.run(
-          prompt.claude_session_id,
-          prompt.prompt_number,
-          prompt.prompt_text,
-          prompt.created_at,
-          prompt.created_at_epoch
-        );
-        stats.promptsImported++;
-      }
-      console.log(`   ✅ Imported: ${stats.promptsImported}, Skipped: ${stats.promptsSkipped}`);
-
-    })();
-
-    console.log('\n✅ Import complete!');
-    console.log('📊 Summary:');
-    console.log(`   Sessions:     ${stats.sessionsImported} imported, ${stats.sessionsSkipped} skipped`);
-    console.log(`   Summaries:    ${stats.summariesImported} imported, ${stats.summariesSkipped} skipped`);
-    console.log(`   Observations: ${stats.observationsImported} imported, ${stats.observationsSkipped} skipped`);
-    console.log(`   Prompts:      ${stats.promptsImported} imported, ${stats.promptsSkipped} skipped`);
-
-  } finally {
-    db.close();
+    const healthCheck = await fetch(`${WORKER_URL}/api/stats`);
+    if (!healthCheck.ok) {
+      throw new Error('Worker not responding');
+    }
+  } catch (error) {
+    console.error(`❌ Worker not running at ${WORKER_URL}`);
+    console.error('   Please ensure the claude-mem worker is running.');
+    process.exit(1);
   }
+
+  console.log('🔄 Importing via worker API...');
+
+  // Send import request to worker
+  const response = await fetch(`${WORKER_URL}/api/import`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      sessions: exportData.sessions || [],
+      summaries: exportData.summaries || [],
+      observations: exportData.observations || [],
+      prompts: exportData.prompts || []
+    })
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    console.error(`❌ Import failed: ${response.status} ${response.statusText}`);
+    console.error(`   ${errorText}`);
+    process.exit(1);
+  }
+
+  const result = await response.json();
+  const stats = result.stats;
+
+  console.log('\n✅ Import complete!');
+  console.log('📊 Summary:');
+  console.log(`   Sessions:     ${stats.sessionsImported} imported, ${stats.sessionsSkipped} skipped`);
+  console.log(`   Summaries:    ${stats.summariesImported} imported, ${stats.summariesSkipped} skipped`);
+  console.log(`   Observations: ${stats.observationsImported} imported, ${stats.observationsSkipped} skipped`);
+  console.log(`   Prompts:      ${stats.promptsImported} imported, ${stats.promptsSkipped} skipped`);
 }
 
 // CLI interface

src/hooks/cleanup-hook.ts

@@ -48,6 +48,8 @@ async function cleanupHook(input?: SessionEndInput): Promise<void> {
     }
   } catch (error: any) {
     // Worker might not be running - that's okay (non-critical)
+    // But we should still log it for visibility
+    console.error('[cleanup-hook] Failed to notify worker of session end:', error.message);
   }
 
   console.log('{"continue": true, "suppressOutput": true}');

src/hooks/context-hook.ts

@@ -6,12 +6,12 @@
  * native module dependencies.
  */
 
-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 { handleFetchError } from "./shared/error-handler.js";
+import { getProjectName } from "../utils/project-name.js";
 
 export interface SessionStartInput {
   session_id: string;
@@ -25,7 +25,7 @@ async function contextHook(input?: SessionStartInput): Promise<string> {
   await ensureWorkerRunning();
 
   const cwd = input?.cwd ?? process.cwd();
-  const project = cwd ? path.basename(cwd) : "unknown-project";
+  const project = getProjectName(cwd);
   const port = getWorkerPort();
 
   const url = `http://127.0.0.1:${port}/api/context/inject?project=${encodeURIComponent(project)}`;

src/hooks/hook-response.ts

@@ -1,72 +1,11 @@
-export type HookType = 'SessionStart' | 'UserPromptSubmit' | 'PostToolUse' | 'Stop';
-
-export interface HookResponseOptions {
-  reason?: string;
-  context?: string;
-}
-
-export interface HookResponse {
-  continue?: boolean;
-  suppressOutput?: boolean;
-  stopReason?: string;
-  hookSpecificOutput?: {
-    hookEventName: 'SessionStart';
-    additionalContext: string;
-  };
-}
-
-function buildHookResponse(
-  hookType: HookType,
-  success: boolean,
-  options: HookResponseOptions
-): HookResponse {
-  if (hookType === 'SessionStart') {
-    if (success && options.context) {
-      return {
-        continue: true,
-        suppressOutput: true,
-        hookSpecificOutput: {
-          hookEventName: 'SessionStart',
-          additionalContext: options.context
-        }
-      };
-    }
-
-    return {
-      continue: true,
-      suppressOutput: true
-    };
-  }
-
-  if (hookType === 'UserPromptSubmit' || hookType === 'PostToolUse') {
-    return {
-      continue: true,
-      suppressOutput: true
-    };
-  }
-
-  if (hookType === 'Stop') {
-    return {
-      continue: true,
-      suppressOutput: true
-    };
-  }
-
-  return {
-    continue: success,
-    suppressOutput: true,
-    ...(options.reason && !success ? { stopReason: options.reason } : {})
-  };
-}
-
 /**
- * Creates a standardized hook response using the HookTemplates system.
+ * Standard hook response for all hooks.
+ * Tells Claude Code to continue processing and suppress the hook's output.
+ *
+ * Note: SessionStart uses context-hook.ts which constructs its own response
+ * with hookSpecificOutput for context injection.
  */
-export function createHookResponse(
-  hookType: HookType,
-  success: boolean,
-  options: HookResponseOptions = {}
-): string {
-  const response = buildHookResponse(hookType, success, options);
-  return JSON.stringify(response);
-}
+export const STANDARD_HOOK_RESPONSE = JSON.stringify({
+  continue: true,
+  suppressOutput: true
+});

src/hooks/new-hook.ts

@@ -1,9 +1,9 @@
-import path from 'path';
 import { stdin } from 'process';
-import { createHookResponse } from './hook-response.js';
+import { STANDARD_HOOK_RESPONSE } from './hook-response.js';
 import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
 import { handleWorkerError } from '../shared/hook-error-handler.js';
 import { handleFetchError } from './shared/error-handler.js';
+import { getProjectName } from '../utils/project-name.js';
 
 export interface UserPromptSubmitInput {
   session_id: string;
@@ -24,7 +24,7 @@ async function newHook(input?: UserPromptSubmitInput): Promise<void> {
   }
 
   const { session_id, cwd, prompt } = input;
-  const project = path.basename(cwd);
+  const project = getProjectName(cwd);
 
   const port = getWorkerPort();
 
@@ -61,7 +61,7 @@ async function newHook(input?: UserPromptSubmitInput): Promise<void> {
     // 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));
+      console.log(STANDARD_HOOK_RESPONSE);
       return;
     }
 
@@ -97,7 +97,7 @@ async function newHook(input?: UserPromptSubmitInput): Promise<void> {
     handleWorkerError(error);
   }
 
-  console.log(createHookResponse('UserPromptSubmit', true));
+  console.log(STANDARD_HOOK_RESPONSE);
 }
 
 // Entry Point

src/hooks/save-hook.ts

@@ -7,7 +7,7 @@
  */
 
 import { stdin } from 'process';
-import { createHookResponse } from './hook-response.js';
+import { STANDARD_HOOK_RESPONSE } from './hook-response.js';
 import { logger } from '../utils/logger.js';
 import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
 import { HOOK_TIMEOUTS } from '../shared/hook-constants.js';
@@ -43,6 +43,11 @@ async function saveHook(input?: PostToolUseInput): Promise<void> {
     workerPort: port
   });
 
+  // Validate required fields before sending to worker
+  if (!cwd) {
+    throw new Error(`Missing cwd in PostToolUse hook input for session ${session_id}, tool ${tool_name}`);
+  }
+
   try {
     // Send to worker - worker handles privacy check and database operations
     const response = await fetch(`http://127.0.0.1:${port}/api/sessions/observations`, {
@@ -53,13 +58,7 @@ async function saveHook(input?: PostToolUseInput): Promise<void> {
         tool_name,
         tool_input,
         tool_response,
-        cwd: cwd || logger.happyPathError(
-          'HOOK',
-          'Missing cwd in PostToolUse hook input',
-          undefined,
-          { session_id, tool_name },
-          ''
-        )
+        cwd
       }),
       signal: AbortSignal.timeout(HOOK_TIMEOUTS.DEFAULT)
     });
@@ -80,7 +79,7 @@ async function saveHook(input?: PostToolUseInput): Promise<void> {
     handleWorkerError(error);
   }
 
-  console.log(createHookResponse('PostToolUse', true));
+  console.log(STANDARD_HOOK_RESPONSE);
 }
 
 // Entry Point

src/hooks/summary-hook.ts

@@ -10,7 +10,7 @@
  */
 
 import { stdin } from 'process';
-import { createHookResponse } from './hook-response.js';
+import { STANDARD_HOOK_RESPONSE } from './hook-response.js';
 import { logger } from '../utils/logger.js';
 import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
 import { HOOK_TIMEOUTS } from '../shared/hook-constants.js';
@@ -39,16 +39,14 @@ async function summaryHook(input?: StopInput): Promise<void> {
 
   const port = getWorkerPort();
 
+  // Validate required fields before processing
+  if (!input.transcript_path) {
+    throw new Error(`Missing transcript_path in Stop hook input for session ${session_id}`);
+  }
+
   // Extract last user AND assistant messages from transcript
-  const transcriptPath = input.transcript_path || logger.happyPathError(
-    'HOOK',
-    'Missing transcript_path in Stop hook input',
-    undefined,
-    { session_id },
-    ''
-  );
-  const lastUserMessage = extractLastMessage(transcriptPath, 'user');
-  const lastAssistantMessage = extractLastMessage(transcriptPath, 'assistant', true);
+  const lastUserMessage = extractLastMessage(input.transcript_path, 'user');
+  const lastAssistantMessage = extractLastMessage(input.transcript_path, 'assistant', true);
 
   logger.dataIn('HOOK', 'Stop: Requesting summary', {
     workerPort: port,
@@ -56,6 +54,8 @@ async function summaryHook(input?: StopInput): Promise<void> {
     hasLastAssistantMessage: !!lastAssistantMessage
   });
 
+  let summaryError: Error | null = null;
+
   try {
     // Send to worker - worker handles privacy check and database operations
     const response = await fetch(`http://127.0.0.1:${port}/api/sessions/summarize`, {
@@ -81,9 +81,10 @@ async function summaryHook(input?: StopInput): Promise<void> {
 
     logger.debug('HOOK', 'Summary request sent successfully');
   } catch (error: any) {
+    summaryError = error;
     handleWorkerError(error);
   } finally {
-    // Stop processing spinner
+    // Stop processing spinner (non-critical operation, errors are logged but don't block)
     try {
       const spinnerResponse = await fetch(`http://127.0.0.1:${port}/api/processing`, {
         method: 'POST',
@@ -99,7 +100,12 @@ async function summaryHook(input?: StopInput): Promise<void> {
     }
   }
 
-  console.log(createHookResponse('Stop', true));
+  // Re-throw summary error after cleanup to ensure it's not masked by finally block
+  if (summaryError) {
+    throw summaryError;
+  }
+
+  console.log(STANDARD_HOOK_RESPONSE);
 }
 
 // Entry Point

src/servers/mcp-server.ts

@@ -6,14 +6,18 @@
  * Maintains MCP protocol handling and tool schemas
  */
 
+// CRITICAL: Redirect console.log to stderr BEFORE any imports
+// MCP uses stdio transport where stdout is reserved for JSON-RPC protocol messages.
+// Any logs to stdout break the protocol (Claude Desktop parses "[2025..." as JSON array).
+const _originalConsoleLog = console.log;
+console.log = (...args: any[]) => console.error(...args);
+
 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 { logger } from '../utils/logger.js';
 import { getWorkerPort, getWorkerHost } from '../shared/worker-utils.js';
 
@@ -32,7 +36,73 @@ const TOOL_ENDPOINT_MAP: Record<string, string> = {
   'timeline': '/api/timeline',
   'get_recent_context': '/api/context/recent',
   'get_context_timeline': '/api/context/timeline',
-  'progressive_description': '/api/instructions'
+  'help': '/api/instructions'
+};
+
+/**
+ * Detailed parameter schemas for each tool
+ */
+const TOOL_SCHEMAS: Record<string, any> = {
+  search: {
+    query: { type: 'string', description: 'Full-text search query' },
+    type: { type: 'string', description: 'Filter by type: tool_use, tool_result, prompt, summary' },
+    obs_type: { type: 'string', description: 'Observation type filter' },
+    concepts: { type: 'string', description: 'Comma-separated concept tags' },
+    files: { type: 'string', description: 'Comma-separated file paths' },
+    project: { type: 'string', description: 'Project name filter' },
+    dateStart: { type: ['string', 'number'], description: 'Start date (ISO or timestamp)' },
+    dateEnd: { type: ['string', 'number'], description: 'End date (ISO or timestamp)' },
+    limit: { type: 'number', description: 'Max results (default: 10)' },
+    offset: { type: 'number', description: 'Result offset for pagination' },
+    orderBy: { type: 'string', description: 'Sort order: created_at, relevance' }
+  },
+  timeline: {
+    query: { type: 'string', description: 'Search query to find anchor point' },
+    anchor: { type: 'number', description: 'Observation ID as timeline center' },
+    depth_before: { type: 'number', description: 'Observations before anchor (default: 5)' },
+    depth_after: { type: 'number', description: 'Observations after anchor (default: 5)' },
+    type: { type: 'string', description: 'Filter by type' },
+    concepts: { type: 'string', description: 'Comma-separated concept tags' },
+    files: { type: 'string', description: 'Comma-separated file paths' },
+    project: { type: 'string', description: 'Project name filter' }
+  },
+  get_recent_context: {
+    limit: { type: 'number', description: 'Max results (default: 20)' },
+    type: { type: 'string', description: 'Filter by type' },
+    concepts: { type: 'string', description: 'Comma-separated concept tags' },
+    files: { type: 'string', description: 'Comma-separated file paths' },
+    project: { type: 'string', description: 'Project name filter' },
+    dateStart: { type: ['string', 'number'], description: 'Start date' },
+    dateEnd: { type: ['string', 'number'], description: 'End date' }
+  },
+  get_context_timeline: {
+    anchor: { type: 'number', description: 'Observation ID (required)', required: true },
+    depth_before: { type: 'number', description: 'Observations before anchor' },
+    depth_after: { type: 'number', description: 'Observations after anchor' },
+    type: { type: 'string', description: 'Filter by type' },
+    concepts: { type: 'string', description: 'Comma-separated concept tags' },
+    files: { type: 'string', description: 'Comma-separated file paths' },
+    project: { type: 'string', description: 'Project name filter' }
+  },
+  get_observations: {
+    ids: { type: 'array', items: { type: 'number' }, description: 'Array of observation IDs (required)', required: true },
+    orderBy: { type: 'string', description: 'Sort order' },
+    limit: { type: 'number', description: 'Max results' },
+    project: { type: 'string', description: 'Project filter' }
+  },
+  help: {
+    operation: { type: 'string', description: 'Operation type: "observations", "timeline", "sessions", etc.' },
+    topic: { type: 'string', description: 'Specific topic for help' }
+  },
+  get_observation: {
+    id: { type: 'number', description: 'Observation ID (required)', required: true }
+  },
+  get_session: {
+    id: { type: 'number', description: 'Session ID (required)', required: true }
+  },
+  get_prompt: {
+    id: { type: 'number', description: 'Prompt ID (required)', required: true }
+  }
 };
 
 /**
@@ -182,25 +252,47 @@ async function verifyWorkerConnection(): Promise<boolean> {
 
 /**
  * Tool definitions with HTTP-based handlers
- * Descriptions removed - use progressive_description tool for parameter documentation
+ * Minimal descriptions - use help() tool with operation parameter for detailed docs
  */
 const tools = [
+  {
+    name: 'get_schema',
+    description: 'Get parameter schema for a tool. Call get_schema(tool_name) for details',
+    inputSchema: {
+      type: 'object',
+      properties: { tool_name: { type: 'string' } },
+      required: ['tool_name']
+    },
+    handler: async (args: any) => {
+      // Validate tool_name to prevent prototype pollution
+      const toolName = args.tool_name;
+      if (typeof toolName !== 'string' || !Object.hasOwn(TOOL_SCHEMAS, toolName)) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: `Unknown tool: ${toolName}\n\nAvailable tools: ${Object.keys(TOOL_SCHEMAS).join(', ')}`
+          }],
+          isError: true
+        };
+      }
+
+      const schema = TOOL_SCHEMAS[toolName];
+      return {
+        content: [{
+          type: 'text' as const,
+          text: `# ${toolName} Parameters\n\n${JSON.stringify(schema, null, 2)}`
+        }]
+      };
+    }
+  },
   {
     name: 'search',
-    description: 'Search memory',
-    inputSchema: z.object({
-      query: z.string().optional(),
-      type: z.enum(['observations', 'sessions', 'prompts']).optional(),
-      obs_type: z.string().optional(),
-      concepts: z.string().optional(),
-      files: z.string().optional(),
-      project: z.string().optional(),
-      dateStart: z.union([z.string(), z.number()]).optional(),
-      dateEnd: z.union([z.string(), z.number()]).optional(),
-      limit: z.number().min(1).max(100).default(20),
-      offset: z.number().min(0).default(0),
-      orderBy: z.enum(['relevance', 'date_desc', 'date_asc']).default('date_desc')
-    }),
+    description: 'Search memory. All parameters optional - call get_schema("search") for details',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: true
+    },
     handler: async (args: any) => {
       const endpoint = TOOL_ENDPOINT_MAP['search'];
       return await callWorkerAPI(endpoint, args);
@@ -208,17 +300,12 @@ const tools = [
   },
   {
     name: 'timeline',
-    description: 'Timeline context',
-    inputSchema: z.object({
-      query: z.string().optional(),
-      anchor: z.number().optional(),
-      depth_before: z.number().min(0).max(100).default(10),
-      depth_after: z.number().min(0).max(100).default(10),
-      type: z.string().optional(),
-      concepts: z.string().optional(),
-      files: z.string().optional(),
-      project: z.string().optional()
-    }),
+    description: 'Timeline context. All parameters optional - call get_schema("timeline") for details',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: true
+    },
     handler: async (args: any) => {
       const endpoint = TOOL_ENDPOINT_MAP['timeline'];
       return await callWorkerAPI(endpoint, args);
@@ -226,16 +313,12 @@ const tools = [
   },
   {
     name: 'get_recent_context',
-    description: 'Recent context',
-    inputSchema: z.object({
-      limit: z.number().min(1).max(100).default(30),
-      type: z.string().optional(),
-      concepts: z.string().optional(),
-      files: z.string().optional(),
-      project: z.string().optional(),
-      dateStart: z.union([z.string(), z.number()]).optional(),
-      dateEnd: z.union([z.string(), z.number()]).optional()
-    }),
+    description: 'Recent context. All parameters optional - call get_schema("get_recent_context") for details',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: true
+    },
     handler: async (args: any) => {
       const endpoint = TOOL_ENDPOINT_MAP['get_recent_context'];
       return await callWorkerAPI(endpoint, args);
@@ -243,71 +326,102 @@ const tools = [
   },
   {
     name: 'get_context_timeline',
-    description: 'Timeline around ID',
-    inputSchema: z.object({
-      anchor: z.number(),
-      depth_before: z.number().min(0).max(100).default(10),
-      depth_after: z.number().min(0).max(100).default(10),
-      type: z.string().optional(),
-      concepts: z.string().optional(),
-      files: z.string().optional(),
-      project: z.string().optional()
-    }),
+    description: 'Timeline around observation ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        anchor: {
+          type: 'number',
+          description: 'Observation ID (required). Optional params: get_schema("get_context_timeline")'
+        }
+      },
+      required: ['anchor'],
+      additionalProperties: true
+    },
     handler: async (args: any) => {
       const endpoint = TOOL_ENDPOINT_MAP['get_context_timeline'];
       return await callWorkerAPI(endpoint, args);
     }
   },
   {
-    name: 'progressive_description',
-    description: 'Usage help',
-    inputSchema: z.object({
-      topic: z.enum(['workflow', 'search_params', 'examples', 'all']).default('all')
-    }),
+    name: 'help',
+    description: 'Get detailed docs. All parameters optional - call get_schema("help") for details',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: true
+    },
     handler: async (args: any) => {
-      const endpoint = TOOL_ENDPOINT_MAP['progressive_description'];
+      const endpoint = TOOL_ENDPOINT_MAP['help'];
       return await callWorkerAPI(endpoint, args);
     }
   },
   {
     name: 'get_observation',
-    description: 'Fetch by ID',
-    inputSchema: z.object({
-      id: z.number()
-    }),
+    description: 'Fetch observation by ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'number',
+          description: 'Observation ID (required)'
+        }
+      },
+      required: ['id']
+    },
     handler: async (args: any) => {
       return await callWorkerAPIWithPath('/api/observation', args.id);
     }
   },
   {
-    name: 'get_batch_observations',
-    description: 'Batch fetch',
-    inputSchema: z.object({
-      ids: z.array(z.number()),
-      orderBy: z.enum(['date_desc', 'date_asc']).optional(),
-      limit: z.number().optional(),
-      project: z.string().optional()
-    }),
+    name: 'get_observations',
+    description: 'Batch fetch observations',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ids: {
+          type: 'array',
+          items: { type: 'number' },
+          description: 'Array of observation IDs (required). Optional params: get_schema("get_observations")'
+        }
+      },
+      required: ['ids'],
+      additionalProperties: true
+    },
     handler: async (args: any) => {
       return await callWorkerAPIPost('/api/observations/batch', args);
     }
   },
   {
     name: 'get_session',
-    description: 'Session by ID',
-    inputSchema: z.object({
-      id: z.number()
-    }),
+    description: 'Fetch session by ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'number',
+          description: 'Session ID (required)'
+        }
+      },
+      required: ['id']
+    },
     handler: async (args: any) => {
       return await callWorkerAPIWithPath('/api/session', args.id);
     }
   },
   {
     name: 'get_prompt',
-    description: 'Prompt by ID',
-    inputSchema: z.object({
-      id: z.number()
-    }),
+    description: 'Fetch prompt by ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'number',
+          description: 'Prompt ID (required)'
+        }
+      },
+      required: ['id']
+    },
     handler: async (args: any) => {
       return await callWorkerAPIWithPath('/api/prompt', args.id);
     }
@@ -317,7 +431,7 @@ const tools = [
 // Create the MCP server
 const server = new Server(
   {
-    name: 'claude-mem-search-server',
+    name: 'mem-search-server',
     version: '1.0.0',
   },
   {
@@ -333,7 +447,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     tools: tools.map(tool => ({
       name: tool.name,
       description: tool.description,
-      inputSchema: zodToJsonSchema(tool.inputSchema) as Record<string, unknown>
+      inputSchema: tool.inputSchema
     }))
   };
 });
@@ -382,7 +496,7 @@ async function main() {
     if (!workerAvailable) {
       logger.warn('SYSTEM', 'Worker not available', undefined, { workerUrl: WORKER_BASE_URL });
       logger.warn('SYSTEM', 'Tools will fail until Worker is started');
-      logger.warn('SYSTEM', 'Start Worker with: npm run worker:restart');
+      logger.warn('SYSTEM', 'Start Worker with: claude-mem restart');
     } else {
       logger.info('SYSTEM', 'Worker available', undefined, { workerUrl: WORKER_BASE_URL });
     }

src/services/context-generator.ts

@@ -25,6 +25,7 @@ import {
   toRelativePath,
   extractFirstFile
 } from '../shared/timeline-formatting.js';
+import { getProjectName } from '../utils/project-name.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');
@@ -222,7 +223,7 @@ function extractPriorMessages(transcriptPath: string): { userMessage: string; as
 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';
+  const project = getProjectName(cwd);
 
   let db: SessionStore | null = null;
   try {

src/services/process/ProcessManager.ts

@@ -1,22 +1,16 @@
 import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'fs';
 import { createWriteStream } from 'fs';
 import { join } from 'path';
-import { spawn } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
 import { homedir } from 'os';
 import { DATA_DIR } from '../../shared/paths.js';
 import { getBunPath, isBunAvailable } from '../../utils/bun-path.js';
+import { SettingsDefaultsManager } from '../../shared/SettingsDefaultsManager.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;
@@ -43,8 +37,10 @@ export class ProcessManager {
     // Ensure log directory exists
     mkdirSync(LOG_DIR, { recursive: true });
 
-    // Get worker script path
-    const workerScript = join(MARKETPLACE_ROOT, 'plugin', 'scripts', 'worker-service.cjs');
+    // On Windows, use the wrapper script to solve zombie port problem
+    // On Unix, use the worker directly
+    const scriptName = process.platform === 'win32' ? 'worker-wrapper.cjs' : 'worker-service.cjs';
+    const workerScript = join(MARKETPLACE_ROOT, 'plugin', 'scripts', scriptName);
 
     if (!existsSync(workerScript)) {
       return { success: false, error: `Worker script not found at ${workerScript}` };
@@ -52,7 +48,7 @@ export class ProcessManager {
 
     const logFile = this.getLogFilePath();
 
-    // Use Bun on all platforms
+    // Use Bun on all platforms with PowerShell workaround for Windows console popups
     return this.startWithBun(workerScript, logFile, port);
   }
 
@@ -60,6 +56,15 @@ export class ProcessManager {
     return isBunAvailable();
   }
 
+  /**
+   * Escapes a string for safe use in PowerShell single-quoted strings.
+   * In PowerShell single quotes, the only special character is the single quote itself,
+   * which must be doubled to escape it.
+   */
+  private static escapePowerShellString(str: string): string {
+    return str.replace(/'/g, "''");
+  }
+
   private static async startWithBun(script: string, logFile: string, port: number): Promise<{ success: boolean; pid?: number; error?: string }> {
     const bunPath = getBunPath();
     if (!bunPath) {
@@ -68,40 +73,89 @@ export class ProcessManager {
         error: 'Bun is required but not found in PATH or common installation paths. Install from https://bun.sh'
       };
     }
-
     try {
       const isWindows = process.platform === 'win32';
 
-      const child = spawn(bunPath, [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 })
-      });
+      if (isWindows) {
+        // Windows: Use PowerShell Start-Process with -WindowStyle Hidden
+        // This properly hides the console window (affects both Bun and Node.js)
+        // Note: windowsHide: true doesn't work with detached: true (Bun inherits Node.js process spawning semantics)
+        // See: https://github.com/nodejs/node/issues/21825 and PR #315 for detailed testing
+        //
+        // On Windows, we start worker-wrapper.cjs which manages the actual worker-service.cjs.
+        // This solves the zombie port problem: the wrapper has no sockets, so when it kills
+        // and respawns the inner worker, the socket is properly released.
+        //
+        // Security: All paths (bunPath, script, MARKETPLACE_ROOT) are application-controlled system paths,
+        // not user input. If an attacker could modify these paths, they would already have full filesystem
+        // access including direct access to ~/.claude-mem/claude-mem.db. Nevertheless, we properly escape
+        // all values for PowerShell to follow security best practices.
+        const escapedBunPath = this.escapePowerShellString(bunPath);
+        const escapedScript = this.escapePowerShellString(script);
+        const escapedWorkDir = this.escapePowerShellString(MARKETPLACE_ROOT);
+        const escapedLogFile = this.escapePowerShellString(logFile);
+        const envVars = `$env:CLAUDE_MEM_WORKER_PORT='${port}'`;
+        const psCommand = `${envVars}; Start-Process -FilePath '${escapedBunPath}' -ArgumentList '${escapedScript}' -WorkingDirectory '${escapedWorkDir}' -WindowStyle Hidden -RedirectStandardOutput '${escapedLogFile}' -RedirectStandardError '${escapedLogFile}.err' -PassThru | Select-Object -ExpandProperty Id`;
 
-      // Write logs
-      const logStream = createWriteStream(logFile, { flags: 'a' });
-      child.stdout?.pipe(logStream);
-      child.stderr?.pipe(logStream);
+        const result = spawnSync('powershell', ['-Command', psCommand], {
+          stdio: 'pipe',
+          timeout: 10000,
+          windowsHide: true
+        });
 
-      child.unref();
+        if (result.status !== 0) {
+          return {
+            success: false,
+            error: `PowerShell spawn failed: ${result.stderr?.toString() || 'unknown error'}`
+          };
+        }
 
-      if (!child.pid) {
-        return { success: false, error: 'Failed to get PID from spawned process' };
+        const pid = parseInt(result.stdout.toString().trim(), 10);
+        if (isNaN(pid)) {
+          return { success: false, error: 'Failed to get PID from PowerShell' };
+        }
+
+        // Write PID file
+        this.writePidFile({
+          pid,
+          port,
+          startedAt: new Date().toISOString(),
+          version: process.env.npm_package_version || 'unknown'
+        });
+
+        // Wait for health
+        return this.waitForHealth(pid, port);
+      } else {
+        // Unix: Use standard spawn with detached
+        const child = spawn(bunPath, [script], {
+          detached: true,
+          stdio: ['ignore', 'pipe', 'pipe'],
+          env: { ...process.env, CLAUDE_MEM_WORKER_PORT: String(port) },
+          cwd: MARKETPLACE_ROOT
+        });
+
+        // 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);
       }
-
-      // 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,
@@ -110,23 +164,67 @@ export class ProcessManager {
     }
   }
 
-  static async stop(timeout: number = PROCESS_STOP_TIMEOUT_MS): Promise<boolean> {
+  static async stop(timeout: number = 5000): 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
+    if (process.platform === 'win32') {
+      // Windows: Try graceful HTTP shutdown first - this works regardless of PID file state
+      // because the worker shuts itself down from the inside (via wrapper IPC)
+      const port = info?.port ?? this.getPortFromSettings();
+      const httpShutdownSucceeded = await this.tryHttpShutdown(port);
+
+      if (httpShutdownSucceeded) {
+        // HTTP shutdown succeeded - worker confirmed down, safe to remove PID file
+        this.removePidFile();
+        return true;
       }
-    }
 
-    this.removePidFile();
-    return true;
+      // HTTP shutdown failed (worker not responding), fall back to taskkill
+      if (!info) {
+        // No PID file and HTTP failed - nothing more we can do
+        return true;
+      }
+
+      const { execSync } = await import('child_process');
+      try {
+        // Use taskkill /T /F to kill entire process tree
+        // This ensures the wrapper AND all its children (inner worker, MCP, ChromaSync) are killed
+        // which is necessary to properly release the socket and avoid zombie ports
+        execSync(`taskkill /PID ${info.pid} /T /F`, { timeout: 10000, stdio: 'ignore' });
+      } catch {
+        // Process may already be dead
+      }
+
+      // Wait for process to actually exit before removing PID file
+      try {
+        await this.waitForExit(info.pid, timeout);
+      } catch {
+        // Timeout waiting - process may still be alive
+      }
+
+      // Only remove PID file if process is confirmed dead
+      if (!this.isProcessAlive(info.pid)) {
+        this.removePidFile();
+      }
+      return true;
+    } else {
+      // Unix: Use signals (unchanged behavior)
+      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 }> {
@@ -157,6 +255,66 @@ export class ProcessManager {
     return alive;
   }
 
+  /**
+   * Get worker port from settings file
+   */
+  private static getPortFromSettings(): number {
+    try {
+      const settingsPath = join(DATA_DIR, 'settings.json');
+      const settings = SettingsDefaultsManager.loadFromFile(settingsPath);
+      return parseInt(settings.CLAUDE_MEM_WORKER_PORT, 10);
+    } catch {
+      return parseInt(SettingsDefaultsManager.get('CLAUDE_MEM_WORKER_PORT'), 10);
+    }
+  }
+
+  /**
+   * Try to shut down the worker via HTTP endpoint
+   * Returns true if shutdown succeeded, false if worker not responding
+   */
+  private static async tryHttpShutdown(port: number): Promise<boolean> {
+    try {
+      // Send shutdown request
+      const response = await fetch(`http://127.0.0.1:${port}/api/admin/shutdown`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(2000)
+      });
+
+      if (!response.ok) {
+        return false;
+      }
+
+      // Wait for worker to actually stop responding
+      return await this.waitForWorkerDown(port, 5000);
+    } catch {
+      // Worker not responding to HTTP - it may be dead or hung
+      return false;
+    }
+  }
+
+  /**
+   * Wait for worker to stop responding on the given port
+   */
+  private static async waitForWorkerDown(port: number, timeout: number): Promise<boolean> {
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeout) {
+      try {
+        await fetch(`http://127.0.0.1:${port}/api/health`, {
+          signal: AbortSignal.timeout(500)
+        });
+        // Still responding, wait and retry
+        await new Promise(resolve => setTimeout(resolve, 100));
+      } catch {
+        // Worker stopped responding - success
+        return true;
+      }
+    }
+
+    // Timeout - worker still responding
+    return false;
+  }
+
   // Helper methods
   private static getPidInfo(): PidInfo | null {
     try {
@@ -165,10 +323,15 @@ export class ProcessManager {
       const parsed = JSON.parse(content);
       // Validate required fields have correct types
       if (typeof parsed.pid !== 'number' || typeof parsed.port !== 'number') {
+        logger.warn('PROCESS', 'Malformed PID file: missing or invalid pid/port fields', {}, { parsed });
         return null;
       }
       return parsed as PidInfo;
-    } catch {
+    } catch (error) {
+      logger.warn('PROCESS', 'Failed to read PID file', {}, {
+        error: error instanceof Error ? error.message : String(error),
+        path: PID_FILE
+      });
       return null;
     }
   }
@@ -197,31 +360,41 @@ export class ProcessManager {
     }
   }
 
-  private static async waitForHealth(pid: number, port: number, timeoutMs: number = HEALTH_CHECK_TIMEOUT_MS): Promise<{ success: boolean; pid?: number; error?: string }> {
+  private static async waitForHealth(pid: number, port: number, timeoutMs: number = 10000): Promise<{ success: boolean; pid?: number; error?: string }> {
     const startTime = Date.now();
+    const isWindows = process.platform === 'win32';
+    // Increase timeout on Windows to account for slower process startup
+    const adjustedTimeout = isWindows ? timeoutMs * 2 : timeoutMs;
 
-    while (Date.now() - startTime < timeoutMs) {
+    while (Date.now() - startTime < adjustedTimeout) {
       // Check if process is still alive
       if (!this.isProcessAlive(pid)) {
-        return { success: false, error: 'Process died during startup' };
+        const errorMsg = isWindows
+          ? `Process died during startup\n\nTroubleshooting:\n1. Check Task Manager for zombie 'bun.exe' or 'node.exe' processes\n2. Verify port ${port} is not in use: netstat -ano | findstr ${port}\n3. Check worker logs in ~/.claude-mem/logs/\n4. See GitHub issues: #363, #367, #371, #373\n5. Docs: https://docs.claude-mem.ai/troubleshooting/windows-issues`
+          : 'Process died during startup';
+        return { success: false, error: errorMsg };
       }
 
-      // Try health check
+      // Try readiness check (changed from /health to /api/readiness)
       try {
-        const response = await fetch(`http://127.0.0.1:${port}/health`, {
-          signal: AbortSignal.timeout(HEALTH_CHECK_FETCH_TIMEOUT_MS)
+        const response = await fetch(`http://127.0.0.1:${port}/api/readiness`, {
+          signal: AbortSignal.timeout(1000)
         });
         if (response.ok) {
           return { success: true, pid };
         }
       } catch {
-        // Not ready yet
+        // Not ready yet, continue polling
       }
 
-      await new Promise(resolve => setTimeout(resolve, HEALTH_CHECK_INTERVAL_MS));
+      await new Promise(resolve => setTimeout(resolve, 200));
     }
 
-    return { success: false, error: 'Health check timed out' };
+    const timeoutMsg = isWindows
+      ? `Worker failed to start on Windows (readiness check timed out after ${adjustedTimeout}ms)\n\nTroubleshooting:\n1. Check Task Manager for zombie 'bun.exe' or 'node.exe' processes\n2. Verify port ${port} is not in use: netstat -ano | findstr ${port}\n3. Check worker logs in ~/.claude-mem/logs/\n4. See GitHub issues: #363, #367, #371, #373\n5. Docs: https://docs.claude-mem.ai/troubleshooting/windows-issues`
+      : `Readiness check timed out after ${adjustedTimeout}ms`;
+
+    return { success: false, error: timeoutMsg };
   }
 
   private static async waitForExit(pid: number, timeout: number): Promise<void> {
@@ -231,7 +404,7 @@ export class ProcessManager {
       if (!this.isProcessAlive(pid)) {
         return;
       }
-      await new Promise(resolve => setTimeout(resolve, PROCESS_EXIT_CHECK_INTERVAL_MS));
+      await new Promise(resolve => setTimeout(resolve, 100));
     }
 
     throw new Error('Process did not exit within timeout');

src/services/sqlite/PendingMessageStore.ts

@@ -0,0 +1,377 @@
+import { Database } from './sqlite-compat.js';
+import type { PendingMessage } from '../worker-types.js';
+
+/**
+ * Persistent pending message record from database
+ */
+export interface PersistentPendingMessage {
+  id: number;
+  session_db_id: number;
+  claude_session_id: string;
+  message_type: 'observation' | 'summarize';
+  tool_name: string | null;
+  tool_input: string | null;
+  tool_response: string | null;
+  cwd: string | null;
+  last_user_message: string | null;
+  last_assistant_message: string | null;
+  prompt_number: number | null;
+  status: 'pending' | 'processing' | 'processed' | 'failed';
+  retry_count: number;
+  created_at_epoch: number;
+  started_processing_at_epoch: number | null;
+  completed_at_epoch: number | null;
+}
+
+/**
+ * PendingMessageStore - Persistent work queue for SDK messages
+ *
+ * Messages are persisted before processing and marked complete after success.
+ * This enables recovery from SDK hangs and worker crashes.
+ *
+ * Lifecycle:
+ * 1. enqueue() - Message persisted with status 'pending'
+ * 2. markProcessing() - Status changes to 'processing' when yielded to SDK
+ * 3. markProcessed() - Status changes to 'processed' after successful SDK response
+ * 4. markFailed() - Status changes to 'failed' if max retries exceeded
+ *
+ * Recovery:
+ * - resetStuckMessages() - Moves 'processing' messages back to 'pending' if stuck
+ * - getSessionsWithPendingMessages() - Find sessions that need recovery on startup
+ */
+export class PendingMessageStore {
+  private db: Database;
+  private maxRetries: number;
+
+  constructor(db: Database, maxRetries: number = 3) {
+    this.db = db;
+    this.maxRetries = maxRetries;
+  }
+
+  /**
+   * Enqueue a new message (persist before processing)
+   * @returns The database ID of the persisted message
+   */
+  enqueue(sessionDbId: number, claudeSessionId: string, message: PendingMessage): number {
+    const now = Date.now();
+    const stmt = this.db.prepare(`
+      INSERT INTO pending_messages (
+        session_db_id, claude_session_id, message_type,
+        tool_name, tool_input, tool_response, cwd,
+        last_user_message, last_assistant_message,
+        prompt_number, status, retry_count, created_at_epoch
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', 0, ?)
+    `);
+
+    const result = stmt.run(
+      sessionDbId,
+      claudeSessionId,
+      message.type,
+      message.tool_name || null,
+      message.tool_input ? JSON.stringify(message.tool_input) : null,
+      message.tool_response ? JSON.stringify(message.tool_response) : null,
+      message.cwd || null,
+      message.last_user_message || null,
+      message.last_assistant_message || null,
+      message.prompt_number || null,
+      now
+    );
+
+    return result.lastInsertRowid as number;
+  }
+
+  /**
+   * Peek at oldest pending message for session (does NOT change status)
+   * @returns The oldest pending message or null if none
+   */
+  peekPending(sessionDbId: number): PersistentPendingMessage | null {
+    const stmt = this.db.prepare(`
+      SELECT * FROM pending_messages
+      WHERE session_db_id = ? AND status = 'pending'
+      ORDER BY id ASC
+      LIMIT 1
+    `);
+    return stmt.get(sessionDbId) as PersistentPendingMessage | null;
+  }
+
+  /**
+   * Get all pending messages for session (ordered by creation time)
+   */
+  getAllPending(sessionDbId: number): PersistentPendingMessage[] {
+    const stmt = this.db.prepare(`
+      SELECT * FROM pending_messages
+      WHERE session_db_id = ? AND status = 'pending'
+      ORDER BY id ASC
+    `);
+    return stmt.all(sessionDbId) as PersistentPendingMessage[];
+  }
+
+  /**
+   * Get all queue messages (for UI display)
+   * Returns pending, processing, and failed messages (not processed - they're deleted)
+   * Joins with sdk_sessions to get project name
+   */
+  getQueueMessages(): (PersistentPendingMessage & { project: string | null })[] {
+    const stmt = this.db.prepare(`
+      SELECT pm.*, ss.project
+      FROM pending_messages pm
+      LEFT JOIN sdk_sessions ss ON pm.claude_session_id = ss.claude_session_id
+      WHERE pm.status IN ('pending', 'processing', 'failed')
+      ORDER BY
+        CASE pm.status
+          WHEN 'failed' THEN 0
+          WHEN 'processing' THEN 1
+          WHEN 'pending' THEN 2
+        END,
+        pm.created_at_epoch ASC
+    `);
+    return stmt.all() as (PersistentPendingMessage & { project: string | null })[];
+  }
+
+  /**
+   * Get count of stuck messages (processing longer than threshold)
+   */
+  getStuckCount(thresholdMs: number): number {
+    const cutoff = Date.now() - thresholdMs;
+    const stmt = this.db.prepare(`
+      SELECT COUNT(*) as count FROM pending_messages
+      WHERE status = 'processing' AND started_processing_at_epoch < ?
+    `);
+    const result = stmt.get(cutoff) as { count: number };
+    return result.count;
+  }
+
+  /**
+   * Retry a specific message (reset to pending)
+   * Works for pending (re-queue), processing (reset stuck), and failed messages
+   */
+  retryMessage(messageId: number): boolean {
+    const stmt = this.db.prepare(`
+      UPDATE pending_messages
+      SET status = 'pending', started_processing_at_epoch = NULL
+      WHERE id = ? AND status IN ('pending', 'processing', 'failed')
+    `);
+    const result = stmt.run(messageId);
+    return result.changes > 0;
+  }
+
+  /**
+   * Reset all processing messages for a session to pending
+   * Used when force-restarting a stuck session
+   */
+  resetProcessingToPending(sessionDbId: number): number {
+    const stmt = this.db.prepare(`
+      UPDATE pending_messages
+      SET status = 'pending', started_processing_at_epoch = NULL
+      WHERE session_db_id = ? AND status = 'processing'
+    `);
+    const result = stmt.run(sessionDbId);
+    return result.changes;
+  }
+
+  /**
+   * Abort a specific message (delete from queue)
+   */
+  abortMessage(messageId: number): boolean {
+    const stmt = this.db.prepare('DELETE FROM pending_messages WHERE id = ?');
+    const result = stmt.run(messageId);
+    return result.changes > 0;
+  }
+
+  /**
+   * Retry all stuck messages at once
+   */
+  retryAllStuck(thresholdMs: number): number {
+    const cutoff = Date.now() - thresholdMs;
+    const stmt = this.db.prepare(`
+      UPDATE pending_messages
+      SET status = 'pending', started_processing_at_epoch = NULL
+      WHERE status = 'processing' AND started_processing_at_epoch < ?
+    `);
+    const result = stmt.run(cutoff);
+    return result.changes;
+  }
+
+  /**
+   * Get recently processed messages (for UI feedback)
+   * Shows messages completed in the last N minutes so users can see their stuck items were processed
+   */
+  getRecentlyProcessed(limit: number = 10, withinMinutes: number = 30): (PersistentPendingMessage & { project: string | null })[] {
+    const cutoff = Date.now() - (withinMinutes * 60 * 1000);
+    const stmt = this.db.prepare(`
+      SELECT pm.*, ss.project
+      FROM pending_messages pm
+      LEFT JOIN sdk_sessions ss ON pm.claude_session_id = ss.claude_session_id
+      WHERE pm.status = 'processed' AND pm.completed_at_epoch > ?
+      ORDER BY pm.completed_at_epoch DESC
+      LIMIT ?
+    `);
+    return stmt.all(cutoff, limit) as (PersistentPendingMessage & { project: string | null })[];
+  }
+
+  /**
+   * Mark message as being processed (status: pending -> processing)
+   */
+  markProcessing(messageId: number): void {
+    const now = Date.now();
+    const stmt = this.db.prepare(`
+      UPDATE pending_messages
+      SET status = 'processing', started_processing_at_epoch = ?
+      WHERE id = ? AND status = 'pending'
+    `);
+    stmt.run(now, messageId);
+  }
+
+  /**
+   * Mark message as successfully processed (status: processing -> processed)
+   * Clears tool_input and tool_response to save space (observations are already saved)
+   */
+  markProcessed(messageId: number): void {
+    const now = Date.now();
+    const stmt = this.db.prepare(`
+      UPDATE pending_messages
+      SET
+        status = 'processed',
+        completed_at_epoch = ?,
+        tool_input = NULL,
+        tool_response = NULL
+      WHERE id = ? AND status = 'processing'
+    `);
+    stmt.run(now, messageId);
+  }
+
+  /**
+   * Mark message as failed (status: processing -> failed or back to pending for retry)
+   * If retry_count < maxRetries, moves back to 'pending' for retry
+   * Otherwise marks as 'failed' permanently
+   */
+  markFailed(messageId: number): void {
+    const now = Date.now();
+
+    // Get current retry count
+    const msg = this.db.prepare('SELECT retry_count FROM pending_messages WHERE id = ?').get(messageId) as { retry_count: number } | undefined;
+
+    if (!msg) return;
+
+    if (msg.retry_count < this.maxRetries) {
+      // Move back to pending for retry
+      const stmt = this.db.prepare(`
+        UPDATE pending_messages
+        SET status = 'pending', retry_count = retry_count + 1, started_processing_at_epoch = NULL
+        WHERE id = ?
+      `);
+      stmt.run(messageId);
+    } else {
+      // Max retries exceeded, mark as permanently failed
+      const stmt = this.db.prepare(`
+        UPDATE pending_messages
+        SET status = 'failed', completed_at_epoch = ?
+        WHERE id = ?
+      `);
+      stmt.run(now, messageId);
+    }
+  }
+
+  /**
+   * Reset stuck messages (processing -> pending if stuck longer than threshold)
+   * @param thresholdMs Messages processing longer than this are considered stuck (0 = reset all)
+   * @returns Number of messages reset
+   */
+  resetStuckMessages(thresholdMs: number): number {
+    const cutoff = thresholdMs === 0 ? Date.now() : Date.now() - thresholdMs;
+
+    const stmt = this.db.prepare(`
+      UPDATE pending_messages
+      SET status = 'pending', started_processing_at_epoch = NULL
+      WHERE status = 'processing' AND started_processing_at_epoch < ?
+    `);
+
+    const result = stmt.run(cutoff);
+    return result.changes;
+  }
+
+  /**
+   * Get count of pending messages for a session
+   */
+  getPendingCount(sessionDbId: number): number {
+    const stmt = this.db.prepare(`
+      SELECT COUNT(*) as count FROM pending_messages
+      WHERE session_db_id = ? AND status IN ('pending', 'processing')
+    `);
+    const result = stmt.get(sessionDbId) as { count: number };
+    return result.count;
+  }
+
+  /**
+   * Check if any session has pending work
+   */
+  hasAnyPendingWork(): boolean {
+    const stmt = this.db.prepare(`
+      SELECT COUNT(*) as count FROM pending_messages
+      WHERE status IN ('pending', 'processing')
+    `);
+    const result = stmt.get() as { count: number };
+    return result.count > 0;
+  }
+
+  /**
+   * Get all session IDs that have pending messages (for recovery on startup)
+   */
+  getSessionsWithPendingMessages(): number[] {
+    const stmt = this.db.prepare(`
+      SELECT DISTINCT session_db_id FROM pending_messages
+      WHERE status IN ('pending', 'processing')
+    `);
+    const results = stmt.all() as { session_db_id: number }[];
+    return results.map(r => r.session_db_id);
+  }
+
+  /**
+   * Get session info for a pending message (for recovery)
+   */
+  getSessionInfoForMessage(messageId: number): { sessionDbId: number; claudeSessionId: string } | null {
+    const stmt = this.db.prepare(`
+      SELECT session_db_id, claude_session_id FROM pending_messages WHERE id = ?
+    `);
+    const result = stmt.get(messageId) as { session_db_id: number; claude_session_id: string } | undefined;
+    return result ? { sessionDbId: result.session_db_id, claudeSessionId: result.claude_session_id } : null;
+  }
+
+  /**
+   * Cleanup old processed messages (retention policy)
+   * Keeps the most recent N processed messages, deletes the rest
+   * @param retentionCount Number of processed messages to keep (default: 100)
+   * @returns Number of messages deleted
+   */
+  cleanupProcessed(retentionCount: number = 100): number {
+    const stmt = this.db.prepare(`
+      DELETE FROM pending_messages
+      WHERE status = 'processed'
+      AND id NOT IN (
+        SELECT id FROM pending_messages
+        WHERE status = 'processed'
+        ORDER BY completed_at_epoch DESC
+        LIMIT ?
+      )
+    `);
+
+    const result = stmt.run(retentionCount);
+    return result.changes;
+  }
+
+  /**
+   * Convert a PersistentPendingMessage back to PendingMessage format
+   */
+  toPendingMessage(persistent: PersistentPendingMessage): PendingMessage {
+    return {
+      type: persistent.message_type,
+      tool_name: persistent.tool_name || undefined,
+      tool_input: persistent.tool_input ? JSON.parse(persistent.tool_input) : undefined,
+      tool_response: persistent.tool_response ? JSON.parse(persistent.tool_response) : undefined,
+      prompt_number: persistent.prompt_number || undefined,
+      cwd: persistent.cwd || undefined,
+      last_user_message: persistent.last_user_message || undefined,
+      last_assistant_message: persistent.last_assistant_message || undefined
+    };
+  }
+}

src/services/sqlite/SessionStore.ts

@@ -40,6 +40,7 @@ export class SessionStore {
     this.makeObservationsTextNullable();
     this.createUserPromptsTable();
     this.ensureDiscoveryTokensColumn();
+    this.createPendingMessagesTable();
   }
 
   /**
@@ -545,6 +546,61 @@ export class SessionStore {
     }
   }
 
+  /**
+   * Create pending_messages table for persistent work queue (migration 16)
+   * Messages are persisted before processing and deleted after success.
+   * Enables recovery from SDK hangs and worker crashes.
+   */
+  private createPendingMessagesTable(): void {
+    try {
+      // Check if migration already applied
+      const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(16) as SchemaVersion | undefined;
+      if (applied) return;
+
+      // Check if table already exists
+      const tables = this.db.query("SELECT name FROM sqlite_master WHERE type='table' AND name='pending_messages'").all() as TableNameRow[];
+      if (tables.length > 0) {
+        this.db.prepare('INSERT OR IGNORE INTO schema_versions (version, applied_at) VALUES (?, ?)').run(16, new Date().toISOString());
+        return;
+      }
+
+      console.log('[SessionStore] Creating pending_messages table...');
+
+      this.db.run(`
+        CREATE TABLE pending_messages (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          session_db_id INTEGER NOT NULL,
+          claude_session_id TEXT NOT NULL,
+          message_type TEXT NOT NULL CHECK(message_type IN ('observation', 'summarize')),
+          tool_name TEXT,
+          tool_input TEXT,
+          tool_response TEXT,
+          cwd TEXT,
+          last_user_message TEXT,
+          last_assistant_message TEXT,
+          prompt_number INTEGER,
+          status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'processing', 'processed', 'failed')),
+          retry_count INTEGER NOT NULL DEFAULT 0,
+          created_at_epoch INTEGER NOT NULL,
+          started_processing_at_epoch INTEGER,
+          completed_at_epoch INTEGER,
+          FOREIGN KEY (session_db_id) REFERENCES sdk_sessions(id) ON DELETE CASCADE
+        )
+      `);
+
+      this.db.run('CREATE INDEX IF NOT EXISTS idx_pending_messages_session ON pending_messages(session_db_id)');
+      this.db.run('CREATE INDEX IF NOT EXISTS idx_pending_messages_status ON pending_messages(status)');
+      this.db.run('CREATE INDEX IF NOT EXISTS idx_pending_messages_claude_session ON pending_messages(claude_session_id)');
+
+      this.db.prepare('INSERT OR IGNORE INTO schema_versions (version, applied_at) VALUES (?, ?)').run(16, new Date().toISOString());
+
+      console.log('[SessionStore] pending_messages table created successfully');
+    } catch (error: any) {
+      console.error('[SessionStore] Pending messages table migration error:', error.message);
+      throw error;
+    }
+  }
+
   /**
    * Get recent session summaries for a project
    */
@@ -983,6 +1039,36 @@ export class SessionStore {
     return stmt.get(id) || null;
   }
 
+  /**
+   * Get SDK sessions by SDK session IDs
+   * Used for exporting session metadata
+   */
+  getSdkSessionsBySessionIds(sdkSessionIds: string[]): {
+    id: number;
+    claude_session_id: string;
+    sdk_session_id: string;
+    project: string;
+    user_prompt: string;
+    started_at: string;
+    started_at_epoch: number;
+    completed_at: string | null;
+    completed_at_epoch: number | null;
+    status: string;
+  }[] {
+    if (sdkSessionIds.length === 0) return [];
+
+    const placeholders = sdkSessionIds.map(() => '?').join(',');
+    const stmt = this.db.prepare(`
+      SELECT id, claude_session_id, sdk_session_id, project, user_prompt,
+             started_at, started_at_epoch, completed_at, completed_at_epoch, status
+      FROM sdk_sessions
+      WHERE sdk_session_id IN (${placeholders})
+      ORDER BY started_at_epoch DESC
+    `);
+
+    return stmt.all(...sdkSessionIds) as any[];
+  }
+
   /**
    * Find active SDK session for a Claude session
    */
@@ -1739,4 +1825,212 @@ export class SessionStore {
   close(): void {
     this.db.close();
   }
+
+  // ===========================================
+  // Import Methods (for import-memories script)
+  // ===========================================
+
+  /**
+   * Import SDK session with duplicate checking
+   * Returns: { imported: boolean, id: number }
+   */
+  importSdkSession(session: {
+    claude_session_id: string;
+    sdk_session_id: string;
+    project: string;
+    user_prompt: string;
+    started_at: string;
+    started_at_epoch: number;
+    completed_at: string | null;
+    completed_at_epoch: number | null;
+    status: string;
+  }): { imported: boolean; id: number } {
+    // Check if session already exists
+    const existing = this.db.prepare(
+      'SELECT id FROM sdk_sessions WHERE claude_session_id = ?'
+    ).get(session.claude_session_id) as { id: number } | undefined;
+
+    if (existing) {
+      return { imported: false, id: existing.id };
+    }
+
+    const stmt = this.db.prepare(`
+      INSERT INTO sdk_sessions (
+        claude_session_id, sdk_session_id, project, user_prompt,
+        started_at, started_at_epoch, completed_at, completed_at_epoch, status
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const result = stmt.run(
+      session.claude_session_id,
+      session.sdk_session_id,
+      session.project,
+      session.user_prompt,
+      session.started_at,
+      session.started_at_epoch,
+      session.completed_at,
+      session.completed_at_epoch,
+      session.status
+    );
+
+    return { imported: true, id: result.lastInsertRowid as number };
+  }
+
+  /**
+   * Import session summary with duplicate checking
+   * Returns: { imported: boolean, id: number }
+   */
+  importSessionSummary(summary: {
+    sdk_session_id: string;
+    project: string;
+    request: string | null;
+    investigated: string | null;
+    learned: string | null;
+    completed: string | null;
+    next_steps: string | null;
+    files_read: string | null;
+    files_edited: string | null;
+    notes: string | null;
+    prompt_number: number | null;
+    discovery_tokens: number;
+    created_at: string;
+    created_at_epoch: number;
+  }): { imported: boolean; id: number } {
+    // Check if summary already exists for this session
+    const existing = this.db.prepare(
+      'SELECT id FROM session_summaries WHERE sdk_session_id = ?'
+    ).get(summary.sdk_session_id) as { id: number } | undefined;
+
+    if (existing) {
+      return { imported: false, id: existing.id };
+    }
+
+    const stmt = this.db.prepare(`
+      INSERT INTO session_summaries (
+        sdk_session_id, project, request, investigated, learned,
+        completed, next_steps, files_read, files_edited, notes,
+        prompt_number, discovery_tokens, created_at, created_at_epoch
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const result = stmt.run(
+      summary.sdk_session_id,
+      summary.project,
+      summary.request,
+      summary.investigated,
+      summary.learned,
+      summary.completed,
+      summary.next_steps,
+      summary.files_read,
+      summary.files_edited,
+      summary.notes,
+      summary.prompt_number,
+      summary.discovery_tokens || 0,
+      summary.created_at,
+      summary.created_at_epoch
+    );
+
+    return { imported: true, id: result.lastInsertRowid as number };
+  }
+
+  /**
+   * Import observation with duplicate checking
+   * Duplicates are identified by sdk_session_id + title + created_at_epoch
+   * Returns: { imported: boolean, id: number }
+   */
+  importObservation(obs: {
+    sdk_session_id: string;
+    project: string;
+    text: string | null;
+    type: string;
+    title: string | null;
+    subtitle: string | null;
+    facts: string | null;
+    narrative: string | null;
+    concepts: string | null;
+    files_read: string | null;
+    files_modified: string | null;
+    prompt_number: number | null;
+    discovery_tokens: number;
+    created_at: string;
+    created_at_epoch: number;
+  }): { imported: boolean; id: number } {
+    // Check if observation already exists
+    const existing = this.db.prepare(`
+      SELECT id FROM observations
+      WHERE sdk_session_id = ? AND title = ? AND created_at_epoch = ?
+    `).get(obs.sdk_session_id, obs.title, obs.created_at_epoch) as { id: number } | undefined;
+
+    if (existing) {
+      return { imported: false, id: existing.id };
+    }
+
+    const stmt = this.db.prepare(`
+      INSERT INTO observations (
+        sdk_session_id, project, text, type, title, subtitle,
+        facts, narrative, concepts, files_read, files_modified,
+        prompt_number, discovery_tokens, created_at, created_at_epoch
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const result = stmt.run(
+      obs.sdk_session_id,
+      obs.project,
+      obs.text,
+      obs.type,
+      obs.title,
+      obs.subtitle,
+      obs.facts,
+      obs.narrative,
+      obs.concepts,
+      obs.files_read,
+      obs.files_modified,
+      obs.prompt_number,
+      obs.discovery_tokens || 0,
+      obs.created_at,
+      obs.created_at_epoch
+    );
+
+    return { imported: true, id: result.lastInsertRowid as number };
+  }
+
+  /**
+   * Import user prompt with duplicate checking
+   * Duplicates are identified by claude_session_id + prompt_number
+   * Returns: { imported: boolean, id: number }
+   */
+  importUserPrompt(prompt: {
+    claude_session_id: string;
+    prompt_number: number;
+    prompt_text: string;
+    created_at: string;
+    created_at_epoch: number;
+  }): { imported: boolean; id: number } {
+    // Check if prompt already exists
+    const existing = this.db.prepare(`
+      SELECT id FROM user_prompts
+      WHERE claude_session_id = ? AND prompt_number = ?
+    `).get(prompt.claude_session_id, prompt.prompt_number) as { id: number } | undefined;
+
+    if (existing) {
+      return { imported: false, id: existing.id };
+    }
+
+    const stmt = this.db.prepare(`
+      INSERT INTO user_prompts (
+        claude_session_id, prompt_number, prompt_text,
+        created_at, created_at_epoch
+      ) VALUES (?, ?, ?, ?, ?)
+    `);
+
+    const result = stmt.run(
+      prompt.claude_session_id,
+      prompt.prompt_number,
+      prompt.prompt_text,
+      prompt.created_at,
+      prompt.created_at_epoch
+    );
+
+    return { imported: true, id: result.lastInsertRowid as number };
+  }
 }

src/services/sync/ChromaSync.ts

@@ -101,7 +101,9 @@ export class ChromaSync {
       // 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;
-      this.transport = new StdioClientTransport({
+      const isWindows = process.platform === 'win32';
+
+      const transportOptions: any = {
         command: 'uvx',
         args: [
           '--python', pythonVersion,
@@ -110,7 +112,16 @@ export class ChromaSync {
           '--data-dir', this.VECTOR_DB_DIR
         ],
         stderr: 'ignore'
-      });
+      };
+
+      // CRITICAL: On Windows, try to hide console window to prevent PowerShell popups
+      // Note: windowsHide may not be supported by MCP SDK's StdioClientTransport
+      if (isWindows) {
+        transportOptions.windowsHide = true;
+        logger.debug('CHROMA_SYNC', 'Windows detected, attempting to hide console window', { project: this.project });
+      }
+
+      this.transport = new StdioClientTransport(transportOptions);
 
       this.client = new Client({
         name: 'claude-mem-chroma-sync',

src/services/worker-service.ts

@@ -14,7 +14,7 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { getWorkerPort, getWorkerHost } from '../shared/worker-utils.js';
 import { logger } from '../utils/logger.js';
-import { exec } from 'child_process';
+import { exec, execSync } from 'child_process';
 import { promisify } from 'util';
 
 const execAsync = promisify(exec);
@@ -32,7 +32,7 @@ import { TimelineService } from './worker/TimelineService.js';
 import { SessionEventBroadcaster } from './worker/events/SessionEventBroadcaster.js';
 
 // Import HTTP layer
-import { createMiddleware, summarizeRequestBody as summarizeBody } from './worker/http/middleware.js';
+import { createMiddleware, summarizeRequestBody as summarizeBody, requireLocalhost } from './worker/http/middleware.js';
 import { ViewerRoutes } from './worker/http/routes/ViewerRoutes.js';
 import { SessionRoutes } from './worker/http/routes/SessionRoutes.js';
 import { DataRoutes } from './worker/http/routes/DataRoutes.js';
@@ -45,6 +45,10 @@ export class WorkerService {
   private startTime: number = Date.now();
   private mcpClient: Client;
 
+  // Initialization flags for MCP/SDK readiness tracking
+  private mcpReady: boolean = false;
+  private initializationCompleteFlag: boolean = false;
+
   // Domain services
   private dbManager: DatabaseManager;
   private sessionManager: SessionManager;
@@ -118,18 +122,46 @@ export class WorkerService {
    */
   private setupRoutes(): void {
     // Health check endpoint
+    // TEST_BUILD_ID helps verify which build is running during debugging
+    const TEST_BUILD_ID = 'TEST-008-wrapper-ipc';
     this.app.get('/api/health', (_req, res) => {
-      res.status(200).json({ status: 'ok' });
+      res.status(200).json({
+        status: 'ok',
+        build: TEST_BUILD_ID,
+        managed: process.env.CLAUDE_MEM_MANAGED === 'true',
+        hasIpc: typeof process.send === 'function',
+        platform: process.platform,
+        pid: process.pid,
+        initialized: this.initializationCompleteFlag,
+        mcpReady: this.mcpReady,
+      });
+    });
+
+    // Readiness check endpoint - returns 503 until full initialization completes
+    // Used by ProcessManager and worker-utils to ensure worker is fully ready before routing requests
+    this.app.get('/api/readiness', (_req, res) => {
+      if (this.initializationCompleteFlag) {
+        res.status(200).json({
+          status: 'ready',
+          mcpReady: this.mcpReady,
+        });
+      } else {
+        res.status(503).json({
+          status: 'initializing',
+          message: 'Worker is still initializing, please retry',
+        });
+      }
     });
 
     // Version endpoint - returns the worker's current version
     this.app.get('/api/version', (_req, res) => {
+      const { homedir } = require('os');
+      const { readFileSync } = require('fs');
+      const marketplaceRoot = path.join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');
+      const packageJsonPath = path.join(marketplaceRoot, 'package.json');
+
       try {
         // Read version from marketplace package.json
-        const { homedir } = require('os');
-        const { readFileSync } = require('fs');
-        const marketplaceRoot = path.join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');
-        const packageJsonPath = path.join(marketplaceRoot, 'package.json');
         const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
         res.status(200).json({ version: packageJson.version });
       } catch (error) {
@@ -146,26 +178,35 @@ export class WorkerService {
     // Instructions endpoint - loads SKILL.md sections on-demand for progressive instruction loading
     this.app.get('/api/instructions', async (req, res) => {
       const topic = (req.query.topic as string) || 'all';
-      // Read SKILL.md from plugin directory
+      const operation = req.query.operation as string | undefined;
+
       // Path resolution: __dirname is build output directory (plugin/scripts/)
       // SKILL.md is at plugin/skills/mem-search/SKILL.md
-      const skillPath = path.join(__dirname, '../skills/mem-search/SKILL.md');
+      // Operations are at plugin/skills/mem-search/operations/*.md
 
       try {
-        const fullContent = await fs.promises.readFile(skillPath, 'utf-8');
+        let content: string;
 
-        // Extract section based on topic
-        const section = this.extractInstructionSection(fullContent, topic);
+        if (operation) {
+          // Load specific operation file
+          const operationPath = path.join(__dirname, '../skills/mem-search/operations', `${operation}.md`);
+          content = await fs.promises.readFile(operationPath, 'utf-8');
+        } else {
+          // Load SKILL.md and extract section based on topic (backward compatibility)
+          const skillPath = path.join(__dirname, '../skills/mem-search/SKILL.md');
+          const fullContent = await fs.promises.readFile(skillPath, 'utf-8');
+          content = this.extractInstructionSection(fullContent, topic);
+        }
 
         // Return in MCP format
         res.json({
           content: [{
             type: 'text',
-            text: section
+            text: content
           }]
         });
       } catch (error) {
-        logger.error('WORKER', 'Failed to load instructions', { topic, skillPath }, error as Error);
+        logger.error('WORKER', 'Failed to load instructions', { topic, operation }, error as Error);
         res.status(500).json({
           content: [{
             type: 'text',
@@ -176,21 +217,46 @@ export class WorkerService {
       }
     });
 
-    // Admin endpoints for process management
-    this.app.post('/api/admin/restart', async (_req, res) => {
+    // Admin endpoints for process management (localhost-only)
+    this.app.post('/api/admin/restart', requireLocalhost, async (_req, res) => {
       res.json({ status: 'restarting' });
-      setTimeout(async () => {
-        await this.shutdown();
-        process.exit(0);
-      }, 100);
+
+      // On Windows, if managed by wrapper, send message to parent to handle restart
+      // This solves the Windows zombie port problem where sockets aren't properly released
+      const isWindowsManaged = process.platform === 'win32' &&
+        process.env.CLAUDE_MEM_MANAGED === 'true' &&
+        process.send;
+
+      if (isWindowsManaged) {
+        logger.info('SYSTEM', 'Sending restart request to wrapper');
+        process.send!({ type: 'restart' });
+      } else {
+        // Unix or standalone Windows - handle restart ourselves
+        setTimeout(async () => {
+          await this.shutdown();
+          process.exit(0);
+        }, 100);
+      }
     });
 
-    this.app.post('/api/admin/shutdown', async (_req, res) => {
+    this.app.post('/api/admin/shutdown', requireLocalhost, async (_req, res) => {
       res.json({ status: 'shutting_down' });
-      setTimeout(async () => {
-        await this.shutdown();
-        process.exit(0);
-      }, 100);
+
+      // On Windows, if managed by wrapper, send message to parent to handle shutdown
+      const isWindowsManaged = process.platform === 'win32' &&
+        process.env.CLAUDE_MEM_MANAGED === 'true' &&
+        process.send;
+
+      if (isWindowsManaged) {
+        logger.info('SYSTEM', 'Sending shutdown request to wrapper');
+        process.send!({ type: 'shutdown' });
+      } else {
+        // Unix or standalone Windows - handle shutdown ourselves
+        setTimeout(async () => {
+          await this.shutdown();
+          process.exit(0);
+        }, 100);
+      }
     });
 
     this.viewerRoutes.setupRoutes(this.app);
@@ -261,25 +327,47 @@ export class WorkerService {
    */
   private async cleanupOrphanedProcesses(): Promise<void> {
     try {
-      // Find all chroma-mcp processes
-      const { stdout } = await execAsync('ps aux | grep "chroma-mcp" | grep -v grep || true');
-
-      if (!stdout.trim()) {
-        logger.debug('SYSTEM', 'No orphaned chroma-mcp processes found');
-        return;
-      }
-
-      const lines = stdout.trim().split('\n');
+      const isWindows = process.platform === 'win32';
       const pids: number[] = [];
 
-      for (const line of lines) {
-        const parts = line.trim().split(/\s+/);
-        if (parts.length > 1) {
-          const pid = parseInt(parts[1], 10);
-          if (!isNaN(pid)) {
+      if (isWindows) {
+        // Windows: Use PowerShell Get-CimInstance to find chroma-mcp processes
+        const cmd = `powershell -Command "Get-CimInstance Win32_Process | Where-Object { $_.Name -like '*python*' -and $_.CommandLine -like '*chroma-mcp*' } | Select-Object -ExpandProperty ProcessId"`;
+        const { stdout } = await execAsync(cmd, { timeout: 5000 });
+
+        if (!stdout.trim()) {
+          logger.debug('SYSTEM', 'No orphaned chroma-mcp processes found (Windows)');
+          return;
+        }
+
+        const pidStrings = stdout.trim().split('\n');
+        for (const pidStr of pidStrings) {
+          const pid = parseInt(pidStr.trim(), 10);
+          // SECURITY: Validate PID is positive integer before adding to list
+          if (!isNaN(pid) && Number.isInteger(pid) && pid > 0) {
             pids.push(pid);
           }
         }
+      } else {
+        // Unix: Use ps aux | grep
+        const { stdout } = await execAsync('ps aux | grep "chroma-mcp" | grep -v grep || true');
+
+        if (!stdout.trim()) {
+          logger.debug('SYSTEM', 'No orphaned chroma-mcp processes found (Unix)');
+          return;
+        }
+
+        const lines = stdout.trim().split('\n');
+        for (const line of lines) {
+          const parts = line.trim().split(/\s+/);
+          if (parts.length > 1) {
+            const pid = parseInt(parts[1], 10);
+            // SECURITY: Validate PID is positive integer before adding to list
+            if (!isNaN(pid) && Number.isInteger(pid) && pid > 0) {
+              pids.push(pid);
+            }
+          }
+        }
       }
 
       if (pids.length === 0) {
@@ -287,12 +375,28 @@ export class WorkerService {
       }
 
       logger.info('SYSTEM', 'Cleaning up orphaned chroma-mcp processes', {
+        platform: isWindows ? 'Windows' : 'Unix',
         count: pids.length,
         pids
       });
 
       // Kill all found processes
-      await execAsync(`kill ${pids.join(' ')}`);
+      if (isWindows) {
+        for (const pid of pids) {
+          // SECURITY: Double-check PID validation before using in taskkill command
+          if (!Number.isInteger(pid) || pid <= 0) {
+            logger.warn('SYSTEM', 'Skipping invalid PID', { pid });
+            continue;
+          }
+          try {
+            execSync(`taskkill /PID ${pid} /T /F`, { timeout: 5000, stdio: 'ignore' });
+          } catch (error) {
+            logger.warn('SYSTEM', 'Failed to kill orphaned process', { pid }, error as Error);
+          }
+        }
+      } else {
+        await execAsync(`kill ${pids.join(' ')}`);
+      }
 
       logger.info('SYSTEM', 'Orphaned processes cleaned up', { count: pids.length });
     } catch (error) {
@@ -346,7 +450,7 @@ export class WorkerService {
       this.searchRoutes.setupRoutes(this.app); // Setup search routes now that SearchManager is ready
       logger.info('WORKER', 'SearchManager initialized and search routes registered');
 
-      // Connect to MCP server
+      // Connect to MCP server with timeout guard
       const mcpServerPath = path.join(__dirname, 'mcp-server.cjs');
       const transport = new StdioClientTransport({
         command: 'node',
@@ -354,16 +458,24 @@ export class WorkerService {
         env: process.env
       });
 
-      await this.mcpClient.connect(transport);
+      // Add timeout guard to prevent hanging on MCP connection (15 seconds)
+      const MCP_INIT_TIMEOUT_MS = 15000;
+      const mcpConnectionPromise = this.mcpClient.connect(transport);
+      const timeoutPromise = new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error('MCP connection timeout after 15s')), MCP_INIT_TIMEOUT_MS)
+      );
+
+      await Promise.race([mcpConnectionPromise, timeoutPromise]);
+      this.mcpReady = true;
       logger.success('WORKER', 'Connected to MCP server');
 
       // Signal that initialization is complete
+      this.initializationCompleteFlag = true;
       this.resolveInitialization();
       logger.info('SYSTEM', 'Background initialization complete');
     } catch (error) {
       logger.error('SYSTEM', 'Background initialization failed', {}, error as Error);
-      // Still resolve to prevent hanging requests, but they'll see searchRoutes is null
-      this.resolveInitialization();
+      // Don't resolve - let the promise remain pending so readiness check continues to fail
       throw error;
     }
   }
@@ -399,12 +511,32 @@ export class WorkerService {
 
   /**
    * Shutdown the worker service
+   *
+   * IMPORTANT: On Windows, we must kill all child processes before exiting
+   * to prevent zombie ports. The socket handle can be inherited by children,
+   * and if not properly closed, the port stays bound after process death.
    */
   async shutdown(): Promise<void> {
-    // Shutdown all active sessions
+    logger.info('SYSTEM', 'Shutdown initiated');
+
+    // STEP 1: Enumerate all child processes BEFORE we start closing things
+    const childPids = await this.getChildProcesses(process.pid);
+    logger.info('SYSTEM', 'Found child processes', { count: childPids.length, pids: childPids });
+
+    // STEP 2: Close HTTP server first
+    if (this.server) {
+      this.server.closeAllConnections();
+      await new Promise<void>((resolve, reject) => {
+        this.server!.close(err => err ? reject(err) : resolve());
+      });
+      this.server = null;
+      logger.info('SYSTEM', 'HTTP server closed');
+    }
+
+    // STEP 3: Shutdown active sessions
     await this.sessionManager.shutdownAll();
 
-    // Close MCP client connection (terminates MCP server process)
+    // STEP 4: Close MCP client connection (signals child to exit gracefully)
     if (this.mcpClient) {
       try {
         await this.mcpClient.close();
@@ -414,19 +546,102 @@ export class WorkerService {
       }
     }
 
-    // Close HTTP server
-    if (this.server) {
-      await new Promise<void>((resolve, reject) => {
-        this.server!.close(err => err ? reject(err) : resolve());
-      });
-    }
-
-    // Close database connection (includes ChromaSync cleanup)
+    // STEP 5: Close database connection (includes ChromaSync cleanup)
     await this.dbManager.close();
 
+    // STEP 6: Force kill any remaining child processes (Windows zombie port fix)
+    if (childPids.length > 0) {
+      logger.info('SYSTEM', 'Force killing remaining children');
+      for (const pid of childPids) {
+        await this.forceKillProcess(pid);
+      }
+      // Wait for children to fully exit
+      await this.waitForProcessesExit(childPids, 5000);
+    }
+
     logger.info('SYSTEM', 'Worker shutdown complete');
   }
 
+  /**
+   * Get all child process PIDs (Windows-specific)
+   */
+  private async getChildProcesses(parentPid: number): Promise<number[]> {
+    if (process.platform !== 'win32') {
+      return [];
+    }
+
+    // SECURITY: Validate PID is a positive integer to prevent command injection
+    if (!Number.isInteger(parentPid) || parentPid <= 0) {
+      logger.warn('SYSTEM', 'Invalid parent PID for child process enumeration', { parentPid });
+      return [];
+    }
+
+    try {
+      const cmd = `powershell -Command "Get-CimInstance Win32_Process | Where-Object { $_.ParentProcessId -eq ${parentPid} } | Select-Object -ExpandProperty ProcessId"`;
+      const { stdout } = await execAsync(cmd, { timeout: 5000 });
+      return stdout
+        .trim()
+        .split('\n')
+        .map(s => parseInt(s.trim(), 10))
+        .filter(n => !isNaN(n) && Number.isInteger(n) && n > 0); // SECURITY: Validate each PID
+    } catch (error) {
+      logger.warn('SYSTEM', 'Failed to enumerate child processes', {}, error as Error);
+      return [];
+    }
+  }
+
+  /**
+   * Force kill a process by PID (Windows: uses taskkill /F /T)
+   */
+  private async forceKillProcess(pid: number): Promise<void> {
+    // SECURITY: Validate PID is a positive integer to prevent command injection
+    if (!Number.isInteger(pid) || pid <= 0) {
+      logger.warn('SYSTEM', 'Invalid PID for force kill', { pid });
+      return;
+    }
+
+    try {
+      if (process.platform === 'win32') {
+        // /T kills entire process tree, /F forces termination
+        await execAsync(`taskkill /PID ${pid} /T /F`, { timeout: 5000 });
+        logger.info('SYSTEM', 'Killed process', { pid });
+      } else {
+        process.kill(pid, 'SIGKILL');
+      }
+    } catch (error) {
+      // Process may already be dead, which is fine
+      logger.debug('SYSTEM', 'Process already dead or kill failed', { pid });
+    }
+  }
+
+  /**
+   * Wait for processes to fully exit
+   */
+  private async waitForProcessesExit(pids: number[], timeoutMs: number): Promise<void> {
+    const start = Date.now();
+
+    while (Date.now() - start < timeoutMs) {
+      const stillAlive = pids.filter(pid => {
+        try {
+          process.kill(pid, 0); // Signal 0 checks if process exists
+          return true;
+        } catch {
+          return false;
+        }
+      });
+
+      if (stillAlive.length === 0) {
+        logger.info('SYSTEM', 'All child processes exited');
+        return;
+      }
+
+      logger.debug('SYSTEM', 'Waiting for processes to exit', { stillAlive });
+      await new Promise(r => setTimeout(r, 100));
+    }
+
+    logger.warn('SYSTEM', 'Timeout waiting for child processes to exit');
+  }
+
   /**
    * Summarize request body for logging
    * Used to avoid logging sensitive data or large payloads

src/services/worker-types.ts

@@ -14,13 +14,14 @@ export interface ActiveSession {
   sdkSessionId: string | null;
   project: string;
   userPrompt: string;
-  pendingMessages: PendingMessage[];
+  pendingMessages: PendingMessage[];  // Deprecated: now using persistent store, kept for compatibility
   abortController: AbortController;
   generatorPromise: Promise<void> | null;
   lastPromptNumber: number;
   startTime: number;
   cumulativeInputTokens: number;   // Track input tokens for discovery cost
   cumulativeOutputTokens: number;  // Track output tokens for discovery cost
+  pendingProcessingIds: Set<number>;  // Track ALL message IDs yielded but not yet processed
 }
 
 export interface PendingMessage {
@@ -34,6 +35,16 @@ export interface PendingMessage {
   last_assistant_message?: string;
 }
 
+/**
+ * PendingMessage with database ID for completion tracking.
+ * The _persistentId is used to mark the message as processed after SDK success.
+ * The _originalTimestamp is the epoch when the message was first queued (for accurate observation timestamps).
+ */
+export interface PendingMessageWithId extends PendingMessage {
+  _persistentId: number;
+  _originalTimestamp: number;
+}
+
 export interface ObservationData {
   tool_name: string;
   tool_input: any;

src/services/worker-wrapper.ts

@@ -0,0 +1,157 @@
+/**
+ * Worker Wrapper - Manages worker process lifecycle
+ *
+ * This wrapper exists to solve the Windows zombie port problem.
+ * The wrapper spawns the actual worker as a child process.
+ * When shutdown is requested, the wrapper kills the child and exits.
+ * The hooks will start a fresh wrapper+worker if needed.
+ *
+ * The wrapper itself has no sockets, so Bun's socket cleanup bug
+ * doesn't affect it.
+ *
+ * NOTE: The wrapper does NOT auto-restart the worker on crash.
+ * This is intentional - the hooks handle startup via ensureWorkerRunning().
+ * Auto-restart would cause PID file mismatches and potential infinite loops.
+ */
+
+import { spawn, ChildProcess, execSync } from 'child_process';
+import path from 'path';
+
+const isWindows = process.platform === 'win32';
+
+const SCRIPT_DIR = __dirname;
+const INNER_SCRIPT = path.join(SCRIPT_DIR, 'worker-service.cjs');
+
+let inner: ChildProcess | null = null;
+let isShuttingDown = false;
+
+function log(msg: string) {
+  const timestamp = new Date().toISOString();
+  console.log(`[${timestamp}] [wrapper] ${msg}`);
+}
+
+function spawnInner() {
+  log(`Spawning inner worker: ${INNER_SCRIPT}`);
+
+  inner = spawn(process.execPath, [INNER_SCRIPT], {
+    stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
+    env: { ...process.env, CLAUDE_MEM_MANAGED: 'true' },
+    cwd: path.dirname(INNER_SCRIPT),
+  });
+
+  inner.on('message', async (msg: { type: string }) => {
+    if (msg.type === 'restart' || msg.type === 'shutdown') {
+      // Both restart and shutdown: kill inner and exit wrapper
+      // The hooks will start a fresh wrapper+inner if needed
+      log(`${msg.type} requested by inner`);
+      isShuttingDown = true;
+      await killInner();
+      log('Exiting wrapper');
+      process.exit(0);
+    }
+  });
+
+  inner.on('exit', (code, signal) => {
+    log(`Inner exited with code=${code}, signal=${signal}`);
+    inner = null;
+
+    // Don't auto-restart - let hooks handle it via ensureWorkerRunning()
+    // Auto-restart causes PID file mismatches and potential infinite loops
+    if (!isShuttingDown) {
+      log('Inner exited unexpectedly, wrapper exiting (hooks will restart if needed)');
+      process.exit(code ?? 1);
+    }
+  });
+
+  inner.on('error', (err) => {
+    log(`Inner error: ${err.message}`);
+  });
+}
+
+async function killInner(): Promise<void> {
+  if (!inner || !inner.pid) {
+    log('No inner process to kill');
+    return;
+  }
+
+  const pid = inner.pid;
+  log(`Killing inner process tree (pid=${pid})`);
+
+  if (isWindows) {
+    // On Windows, use taskkill /T /F to kill entire process tree
+    // This ensures all children (MCP server, ChromaSync, etc.) are killed
+    // which is necessary to properly release the socket
+    try {
+      execSync(`taskkill /PID ${pid} /T /F`, { timeout: 10000, stdio: 'ignore' });
+      log(`taskkill completed for pid=${pid}`);
+    } catch (error) {
+      // Process may already be dead
+      log(`taskkill failed (process may be dead): ${error}`);
+    }
+  } else {
+    // On Unix, SIGTERM then SIGKILL
+    inner.kill('SIGTERM');
+
+    // Wait for exit with timeout
+    const exitPromise = new Promise<void>(resolve => {
+      if (!inner) {
+        resolve();
+        return;
+      }
+      inner.on('exit', () => resolve());
+    });
+
+    const timeoutPromise = new Promise<void>(resolve =>
+      setTimeout(() => resolve(), 5000)
+    );
+
+    await Promise.race([exitPromise, timeoutPromise]);
+
+    // Force kill if still alive
+    if (inner && !inner.killed) {
+      log('Inner did not exit gracefully, force killing');
+      inner.kill('SIGKILL');
+    }
+  }
+
+  // Wait for the process to fully exit
+  await waitForProcessExit(pid, 5000);
+
+  inner = null;
+  log('Inner process terminated');
+}
+
+async function waitForProcessExit(pid: number, timeoutMs: number): Promise<void> {
+  const start = Date.now();
+
+  while (Date.now() - start < timeoutMs) {
+    try {
+      process.kill(pid, 0); // Check if process exists
+      await new Promise(r => setTimeout(r, 100));
+    } catch {
+      // Process is dead
+      return;
+    }
+  }
+
+  log(`Timeout waiting for process ${pid} to exit`);
+}
+
+// Handle wrapper signals
+process.on('SIGTERM', async () => {
+  log('Wrapper received SIGTERM');
+  isShuttingDown = true;
+  await killInner();
+  process.exit(0);
+});
+
+process.on('SIGINT', async () => {
+  log('Wrapper received SIGINT');
+  isShuttingDown = true;
+  await killInner();
+  process.exit(0);
+});
+
+// Start the inner worker
+log('Wrapper starting');
+spawnInner();

src/services/worker/BranchManager.ts

@@ -5,7 +5,7 @@
  * The installed plugin at ~/.claude/plugins/marketplaces/thedotmack/ is a git repo.
  */
 
-import { execSync } from 'child_process';
+import { execSync, spawnSync } from 'child_process';
 import { existsSync, unlinkSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
@@ -13,6 +13,21 @@ import { logger } from '../../utils/logger.js';
 
 const INSTALLED_PLUGIN_PATH = join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');
 
+/**
+ * Validate branch name to prevent command injection
+ * Only allows alphanumeric, hyphens, underscores, forward slashes, and dots
+ */
+function isValidBranchName(branchName: string): boolean {
+  if (!branchName || typeof branchName !== 'string') {
+    return false;
+  }
+  // Git branch name validation: alphanumeric, hyphen, underscore, slash, dot
+  // Must not start with dot, hyphen, or slash
+  // Must not contain double dots (..)
+  const validBranchRegex = /^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/;
+  return validBranchRegex.test(branchName) && !branchName.includes('..');
+}
+
 // Timeout constants
 const GIT_COMMAND_TIMEOUT_MS = 30_000;
 const NPM_INSTALL_TIMEOUT_MS = 120_000;
@@ -35,27 +50,54 @@ export interface SwitchResult {
 }
 
 /**
- * Execute git command in installed plugin directory
+ * Execute git command in installed plugin directory using safe array-based arguments
+ * SECURITY: Uses spawnSync with argument array to prevent command injection
  */
-function execGit(command: string): string {
-  return execSync(`git ${command}`, {
+function execGit(args: string[]): string {
+  const result = spawnSync('git', args, {
     cwd: INSTALLED_PLUGIN_PATH,
     encoding: 'utf-8',
     timeout: GIT_COMMAND_TIMEOUT_MS,
-    windowsHide: true
-  }).trim();
+    windowsHide: true,
+    shell: false  // CRITICAL: Never use shell with user input
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(result.stderr || result.stdout || 'Git command failed');
+  }
+
+  return result.stdout.trim();
 }
 
 /**
- * Execute shell command in installed plugin directory
+ * Execute npm command in installed plugin directory using safe array-based arguments
+ * SECURITY: Uses spawnSync with argument array to prevent command injection
  */
-function execShell(command: string, timeoutMs: number = DEFAULT_SHELL_TIMEOUT_MS): string {
-  return execSync(command, {
+function execNpm(args: string[], timeoutMs: number = NPM_INSTALL_TIMEOUT_MS): string {
+  const isWindows = process.platform === 'win32';
+  const npmCmd = isWindows ? 'npm.cmd' : 'npm';
+
+  const result = spawnSync(npmCmd, args, {
     cwd: INSTALLED_PLUGIN_PATH,
     encoding: 'utf-8',
     timeout: timeoutMs,
-    windowsHide: true
-  }).trim();
+    windowsHide: true,
+    shell: false  // CRITICAL: Never use shell with user input
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(result.stderr || result.stdout || 'npm command failed');
+  }
+
+  return result.stdout.trim();
 }
 
 /**
@@ -77,10 +119,10 @@ export function getBranchInfo(): BranchInfo {
 
   try {
     // Get current branch
-    const branch = execGit('rev-parse --abbrev-ref HEAD');
+    const branch = execGit(['rev-parse', '--abbrev-ref', 'HEAD']);
 
     // Check if dirty (has uncommitted changes)
-    const status = execGit('status --porcelain');
+    const status = execGit(['status', '--porcelain']);
     const isDirty = status.length > 0;
 
     // Determine if on beta branch
@@ -118,6 +160,14 @@ export function getBranchInfo(): BranchInfo {
  * 6. Restart worker (handled by caller after response)
  */
 export async function switchBranch(targetBranch: string): Promise<SwitchResult> {
+  // SECURITY: Validate branch name to prevent command injection
+  if (!isValidBranchName(targetBranch)) {
+    return {
+      success: false,
+      error: `Invalid branch name: ${targetBranch}. Branch names must be alphanumeric with hyphens, underscores, slashes, or dots.`
+    };
+  }
+
   const info = getBranchInfo();
 
   if (!info.isGitRepo) {
@@ -143,25 +193,25 @@ export async function switchBranch(targetBranch: string): Promise<SwitchResult>
 
     // 1. Discard local changes (safe - user data is at ~/.claude-mem/)
     logger.debug('BRANCH', 'Discarding local changes');
-    execGit('checkout -- .');
-    execGit('clean -fd'); // Remove untracked files too
+    execGit(['checkout', '--', '.']);
+    execGit(['clean', '-fd']); // Remove untracked files too
 
     // 2. Fetch latest
     logger.debug('BRANCH', 'Fetching from origin');
-    execGit('fetch origin');
+    execGit(['fetch', 'origin']);
 
     // 3. Checkout target branch
     logger.debug('BRANCH', 'Checking out branch', { branch: targetBranch });
     try {
-      execGit(`checkout ${targetBranch}`);
+      execGit(['checkout', targetBranch]);
     } catch {
       // Branch might not exist locally, try tracking remote
-      execGit(`checkout -b ${targetBranch} origin/${targetBranch}`);
+      execGit(['checkout', '-b', targetBranch, `origin/${targetBranch}`]);
     }
 
     // 4. Pull latest
     logger.debug('BRANCH', 'Pulling latest');
-    execGit(`pull origin ${targetBranch}`);
+    execGit(['pull', 'origin', targetBranch]);
 
     // 5. Clear install marker and run npm install
     const installMarker = join(INSTALLED_PLUGIN_PATH, '.install-version');
@@ -170,7 +220,7 @@ export async function switchBranch(targetBranch: string): Promise<SwitchResult>
     }
 
     logger.debug('BRANCH', 'Running npm install');
-    execShell('npm install', NPM_INSTALL_TIMEOUT_MS);
+    execNpm(['install'], NPM_INSTALL_TIMEOUT_MS);
 
     logger.success('BRANCH', 'Branch switch complete', {
       branch: targetBranch
@@ -186,8 +236,8 @@ export async function switchBranch(targetBranch: string): Promise<SwitchResult>
 
     // Try to recover by checking out original branch
     try {
-      if (info.branch) {
-        execGit(`checkout ${info.branch}`);
+      if (info.branch && isValidBranchName(info.branch)) {
+        execGit(['checkout', info.branch]);
       }
     } catch {
       // Recovery failed, user needs manual intervention
@@ -214,21 +264,29 @@ export async function pullUpdates(): Promise<SwitchResult> {
   }
 
   try {
+    // SECURITY: Validate branch name before use
+    if (!isValidBranchName(info.branch)) {
+      return {
+        success: false,
+        error: `Invalid current branch name: ${info.branch}`
+      };
+    }
+
     logger.info('BRANCH', 'Pulling updates', { branch: info.branch });
 
     // Discard local changes first
-    execGit('checkout -- .');
+    execGit(['checkout', '--', '.']);
 
     // Fetch and pull
-    execGit('fetch origin');
-    execGit(`pull origin ${info.branch}`);
+    execGit(['fetch', 'origin']);
+    execGit(['pull', 'origin', info.branch]);
 
     // Clear install marker and reinstall
     const installMarker = join(INSTALLED_PLUGIN_PATH, '.install-version');
     if (existsSync(installMarker)) {
       unlinkSync(installMarker);
     }
-    execShell('npm install', NPM_INSTALL_TIMEOUT_MS);
+    execNpm(['install'], NPM_INSTALL_TIMEOUT_MS);
 
     logger.success('BRANCH', 'Updates pulled', { branch: info.branch });
 

src/services/worker/FormattingService.ts

@@ -18,7 +18,7 @@ export class FormattingService {
 💡 Search Strategy:
 1. Search with index to see titles, dates, IDs
 2. Use timeline to get context around interesting results
-3. Batch fetch full details: get_batch_observations(ids=[...])
+3. Batch fetch full details: get_observations(ids=[...])
 
 Tips:
 • Filter by type: obs_type="bugfix,feature"

src/services/worker/README.md

@@ -108,7 +108,7 @@ Settings and configuration (use domain services directly):
 - Keep all existing behavior identical
 
 **MCP vs Direct DB Split** (inherited, not changed in Phase 1):
-- Search operations → MCP server (claude-mem-search)
+- Search operations → MCP server (mem-search)
 - Session/data operations → Direct DB access via domain services
 
 ## Future Phase 2

src/services/worker/SDKAgent.ts

@@ -113,7 +113,7 @@ export class SDKAgent {
           // Calculate discovery tokens (delta for this response only)
           const discoveryTokens = (session.cumulativeInputTokens + session.cumulativeOutputTokens) - tokensBeforeResponse;
 
-          // Only log non-empty responses (filter out noise)
+          // Process response (empty or not) and mark messages as processed
           if (responseSize > 0) {
             const truncatedResponse = responseSize > 100
               ? textContent.substring(0, 100) + '...'
@@ -125,6 +125,9 @@ export class SDKAgent {
 
             // Parse and process response with discovery token delta
             await this.processSDKResponse(session, textContent, worker, discoveryTokens);
+          } else {
+            // Empty response - still need to mark pending messages as processed
+            await this.markMessagesProcessed(session, worker);
           }
         }
 
@@ -396,6 +399,36 @@ export class SDKAgent {
       }
     }
 
+    // Mark messages as processed after successful observation/summary storage
+    await this.markMessagesProcessed(session, worker);
+  }
+
+  /**
+   * Mark all pending messages as successfully processed
+   * CRITICAL: Prevents message loss and duplicate processing
+   */
+  private async markMessagesProcessed(session: ActiveSession, worker: any | undefined): Promise<void> {
+    const pendingMessageStore = this.sessionManager.getPendingMessageStore();
+    if (session.pendingProcessingIds.size > 0) {
+      for (const messageId of session.pendingProcessingIds) {
+        pendingMessageStore.markProcessed(messageId);
+      }
+      logger.debug('SDK', 'Messages marked as processed', {
+        sessionId: session.sessionDbId,
+        messageIds: Array.from(session.pendingProcessingIds),
+        count: session.pendingProcessingIds.size
+      });
+      session.pendingProcessingIds.clear();
+
+      // Clean up old processed messages (keep last 100 for UI display)
+      const deletedCount = pendingMessageStore.cleanupProcessed(100);
+      if (deletedCount > 0) {
+        logger.debug('SDK', 'Cleaned up old processed messages', {
+          deletedCount
+        });
+      }
+    }
+
     // Broadcast activity status after processing (queue may have changed)
     if (worker && typeof worker.broadcastProcessingStatus === 'function') {
       worker.broadcastProcessingStatus();

src/services/worker/SearchManager.ts

@@ -14,7 +14,7 @@ import { FormattingService } from './FormattingService.js';
 import { TimelineService, TimelineItem } from './TimelineService.js';
 import { ObservationSearchResult, SessionSummarySearchResult, UserPromptSearchResult } from '../sqlite/types.js';
 import { logger } from '../../utils/logger.js';
-import { formatDate, formatTime, extractFirstFile, groupByDate } from '../../shared/timeline-formatting.js';
+import { formatDate, formatTime, formatDateTime, extractFirstFile, groupByDate, estimateTokens } from '../../shared/timeline-formatting.js';
 
 const COLLECTION_NAME = 'cm__claude-mem';
 const RECENCY_WINDOW_DAYS = 90;
@@ -87,10 +87,11 @@ export class SearchManager {
       try {
         // Normalize URL-friendly params to internal format
         const normalized = this.normalizeParams(args);
-        const { query, type, obs_type, concepts, files, ...options } = normalized;
+        const { query, type, obs_type, concepts, files, format, ...options } = normalized;
         let observations: ObservationSearchResult[] = [];
         let sessions: SessionSummarySearchResult[] = [];
         let prompts: UserPromptSearchResult[] = [];
+        let chromaFailed = false;
 
         // Determine which types to query based on type filter
         const searchObservations = !type || type === 'observations';
@@ -181,17 +182,19 @@ export class SearchManager {
               logger.debug('SEARCH', 'ChromaDB found no matches (final result, no FTS5 fallback)', {});
             }
           } catch (chromaError: any) {
-            logger.debug('SEARCH', 'ChromaDB failed - returning empty results (FTS5 fallback removed)', { error: chromaError.message });
+            chromaFailed = true;
+            logger.debug('SEARCH', 'ChromaDB failed - semantic search unavailable', { error: chromaError.message });
             logger.debug('SEARCH', 'Install UVX/Python to enable vector search', { url: 'https://docs.astral.sh/uv/getting-started/installation/' });
-            // Return empty results - no fallback
+            // Set empty results - will show error message to user
             observations = [];
             sessions = [];
             prompts = [];
           }
         }
-        // ChromaDB not initialized - return empty results (no fallback)
-        else {
-          logger.debug('SEARCH', 'ChromaDB not initialized - returning empty results (FTS5 fallback removed)', {});
+        // ChromaDB not initialized - mark as failed to show proper error message
+        else if (query) {
+          chromaFailed = true;
+          logger.debug('SEARCH', 'ChromaDB not initialized - semantic search unavailable', {});
           logger.debug('SEARCH', 'Install UVX/Python to enable vector search', { url: 'https://docs.astral.sh/uv/getting-started/installation/' });
           observations = [];
           sessions = [];
@@ -200,7 +203,26 @@ export class SearchManager {
 
         const totalResults = observations.length + sessions.length + prompts.length;
 
+        // JSON format: return raw data for programmatic access (e.g., export scripts)
+        if (format === 'json') {
+          return {
+            observations,
+            sessions,
+            prompts,
+            totalResults,
+            query: query || ''
+          };
+        }
+
         if (totalResults === 0) {
+          if (chromaFailed) {
+            return {
+              content: [{
+                type: 'text' as const,
+                text: `⚠️  Vector search failed - semantic search unavailable.\n\nTo enable semantic search:\n1. Install uv: https://docs.astral.sh/uv/getting-started/installation/\n2. Restart the worker: npm run worker:restart\n\nNote: You can still use filter-only searches (date ranges, types, files) without a query term.`
+              }]
+            };
+          }
           return {
             content: [{
               type: 'text' as const,
@@ -473,41 +495,6 @@ export class SearchManager {
           };
         }
 
-        // Format timeline (helper functions)
-        const formatDate = (epochMs: number): string => {
-          const date = new Date(epochMs);
-          return date.toLocaleString('en-US', {
-            month: 'short',
-            day: 'numeric',
-            year: 'numeric'
-          });
-        };
-
-        const formatTime = (epochMs: number): string => {
-          const date = new Date(epochMs);
-          return date.toLocaleString('en-US', {
-            hour: 'numeric',
-            minute: '2-digit',
-            hour12: true
-          });
-        };
-
-        const 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
-          });
-        };
-
-        const estimateTokens = (text: string | null): number => {
-          if (!text) return 0;
-          return Math.ceil(text.length / 4);
-        };
-
         // Format results
         const lines: string[] = [];
 
@@ -1592,41 +1579,6 @@ export class SearchManager {
           };
         }
 
-        // Helper functions matching context-hook.ts
-        const formatDate = (epochMs: number): string => {
-          const date = new Date(epochMs);
-          return date.toLocaleString('en-US', {
-            month: 'short',
-            day: 'numeric',
-            year: 'numeric'
-          });
-        };
-
-        const formatTime = (epochMs: number): string => {
-          const date = new Date(epochMs);
-          return date.toLocaleString('en-US', {
-            hour: 'numeric',
-            minute: '2-digit',
-            hour12: true
-          });
-        };
-
-        const 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
-          });
-        };
-
-        const estimateTokens = (text: string | null): number => {
-          if (!text) return 0;
-          return Math.ceil(text.length / 4);
-        };
-
         // Format results matching context-hook.ts exactly
         const lines: string[] = [];
 
@@ -1882,41 +1834,6 @@ export class SearchManager {
             };
           }
 
-          // Helper functions (reused from get_context_timeline)
-          const formatDate = (epochMs: number): string => {
-            const date = new Date(epochMs);
-            return date.toLocaleString('en-US', {
-              month: 'short',
-              day: 'numeric',
-              year: 'numeric'
-            });
-          };
-
-          const formatTime = (epochMs: number): string => {
-            const date = new Date(epochMs);
-            return date.toLocaleString('en-US', {
-              hour: 'numeric',
-              minute: '2-digit',
-              hour12: true
-            });
-          };
-
-          const 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
-            });
-          };
-
-          const estimateTokens = (text: string | null): number => {
-            if (!text) return 0;
-            return Math.ceil(text.length / 4);
-          };
-
           // Format timeline (reused from get_context_timeline)
           const lines: string[] = [];
 

src/services/worker/SessionManager.ts

@@ -11,18 +11,31 @@
 import { EventEmitter } from 'events';
 import { DatabaseManager } from './DatabaseManager.js';
 import { logger } from '../../utils/logger.js';
-import type { ActiveSession, PendingMessage, ObservationData } from '../worker-types.js';
+import type { ActiveSession, PendingMessage, PendingMessageWithId, ObservationData } from '../worker-types.js';
+import { PendingMessageStore } from '../sqlite/PendingMessageStore.js';
 
 export class SessionManager {
   private dbManager: DatabaseManager;
   private sessions: Map<number, ActiveSession> = new Map();
   private sessionQueues: Map<number, EventEmitter> = new Map();
   private onSessionDeletedCallback?: () => void;
+  private pendingStore: PendingMessageStore | null = null;
 
   constructor(dbManager: DatabaseManager) {
     this.dbManager = dbManager;
   }
 
+  /**
+   * Get or create PendingMessageStore (lazy initialization to avoid circular dependency)
+   */
+  private getPendingStore(): PendingMessageStore {
+    if (!this.pendingStore) {
+      const sessionStore = this.dbManager.getSessionStore();
+      this.pendingStore = new PendingMessageStore(sessionStore.db, 3);
+    }
+    return this.pendingStore;
+  }
+
   /**
    * Set callback to be called when a session is deleted (for broadcasting status)
    */
@@ -103,7 +116,8 @@ export class SessionManager {
       lastPromptNumber: promptNumber || this.dbManager.getSessionStore().getPromptCounter(sessionDbId),
       startTime: Date.now(),
       cumulativeInputTokens: 0,
-      cumulativeOutputTokens: 0
+      cumulativeOutputTokens: 0,
+      pendingProcessingIds: new Set()
     };
 
     this.sessions.set(sessionDbId, session);
@@ -133,6 +147,9 @@ export class SessionManager {
   /**
    * Queue an observation for processing (zero-latency notification)
    * Auto-initializes session if not in memory but exists in database
+   *
+   * CRITICAL: Persists to database FIRST before adding to in-memory queue.
+   * This ensures observations survive worker crashes.
    */
   queueObservation(sessionDbId: number, data: ObservationData): void {
     // Auto-initialize from database if needed (handles worker restarts)
@@ -143,14 +160,33 @@ export class SessionManager {
 
     const beforeDepth = session.pendingMessages.length;
 
-    session.pendingMessages.push({
+    // CRITICAL: Persist to database FIRST
+    const message: PendingMessage = {
       type: 'observation',
       tool_name: data.tool_name,
       tool_input: data.tool_input,
       tool_response: data.tool_response,
       prompt_number: data.prompt_number,
       cwd: data.cwd
-    });
+    };
+
+    try {
+      const messageId = this.getPendingStore().enqueue(sessionDbId, session.claudeSessionId, message);
+      logger.debug('SESSION', `Observation persisted to DB`, {
+        sessionId: sessionDbId,
+        messageId,
+        tool: data.tool_name
+      });
+    } catch (error) {
+      logger.error('SESSION', 'Failed to persist observation to DB', {
+        sessionId: sessionDbId,
+        tool: data.tool_name
+      }, error);
+      throw error; // Don't continue if we can't persist
+    }
+
+    // Add to in-memory queue (for backward compatibility with existing iterator)
+    session.pendingMessages.push(message);
 
     const afterDepth = session.pendingMessages.length;
 
@@ -171,6 +207,9 @@ export class SessionManager {
   /**
    * Queue a summarize request (zero-latency notification)
    * Auto-initializes session if not in memory but exists in database
+   *
+   * CRITICAL: Persists to database FIRST before adding to in-memory queue.
+   * This ensures summarize requests survive worker crashes.
    */
   queueSummarize(sessionDbId: number, lastUserMessage: string, lastAssistantMessage?: string): void {
     // Auto-initialize from database if needed (handles worker restarts)
@@ -181,11 +220,28 @@ export class SessionManager {
 
     const beforeDepth = session.pendingMessages.length;
 
-    session.pendingMessages.push({
+    // CRITICAL: Persist to database FIRST
+    const message: PendingMessage = {
       type: 'summarize',
       last_user_message: lastUserMessage,
       last_assistant_message: lastAssistantMessage
-    });
+    };
+
+    try {
+      const messageId = this.getPendingStore().enqueue(sessionDbId, session.claudeSessionId, message);
+      logger.debug('SESSION', `Summarize persisted to DB`, {
+        sessionId: sessionDbId,
+        messageId
+      });
+    } catch (error) {
+      logger.error('SESSION', 'Failed to persist summarize to DB', {
+        sessionId: sessionDbId
+      }, error);
+      throw error; // Don't continue if we can't persist
+    }
+
+    // Add to in-memory queue (for backward compatibility with existing iterator)
+    session.pendingMessages.push(message);
 
     const afterDepth = session.pendingMessages.length;
 
@@ -306,8 +362,12 @@ export class SessionManager {
   /**
    * Get message iterator for SDKAgent to consume (event-driven, no polling)
    * Auto-initializes session if not in memory but exists in database
+   *
+   * CRITICAL: Uses PendingMessageStore for crash-safe message persistence.
+   * Messages are marked as 'processing' when yielded and must be marked 'processed'
+   * by the SDK agent after successful completion.
    */
-  async *getMessageIterator(sessionDbId: number): AsyncIterableIterator<PendingMessage> {
+  async *getMessageIterator(sessionDbId: number): AsyncIterableIterator<PendingMessageWithId> {
     // Auto-initialize from database if needed (handles worker restarts)
     let session = this.sessions.get(sessionDbId);
     if (!session) {
@@ -319,32 +379,100 @@ export class SessionManager {
       throw new Error(`No emitter for session ${sessionDbId}`);
     }
 
+    // Linger timeout: how long to wait for new messages before exiting
+    // This keeps the agent alive between messages, reducing "No active agent" windows
+    const LINGER_TIMEOUT_MS = 5000; // 5 seconds
+
     while (!session.abortController.signal.aborted) {
-      // Wait for messages if queue is empty
-      if (session.pendingMessages.length === 0) {
-        await new Promise<void>(resolve => {
-          const handler = () => resolve();
-          emitter.once('message', handler);
+      // Check for pending messages in persistent store
+      const persistentMessage = this.getPendingStore().peekPending(sessionDbId);
+
+      if (!persistentMessage) {
+        // Wait for new messages with timeout
+        const gotMessage = await new Promise<boolean>(resolve => {
+          let resolved = false;
+
+          const messageHandler = () => {
+            if (!resolved) {
+              resolved = true;
+              clearTimeout(timeoutId);
+              resolve(true);
+            }
+          };
+
+          const timeoutHandler = () => {
+            if (!resolved) {
+              resolved = true;
+              emitter.off('message', messageHandler);
+              resolve(false);
+            }
+          };
+
+          const timeoutId = setTimeout(timeoutHandler, LINGER_TIMEOUT_MS);
+
+          emitter.once('message', messageHandler);
 
           // Also listen for abort
           session.abortController.signal.addEventListener('abort', () => {
-            emitter.off('message', handler);
-            resolve();
+            if (!resolved) {
+              resolved = true;
+              clearTimeout(timeoutId);
+              emitter.off('message', messageHandler);
+              resolve(false);
+            }
           }, { once: true });
         });
-      }
 
-      // Yield all pending messages
-      while (session.pendingMessages.length > 0) {
-        const message = session.pendingMessages.shift()!;
-        yield message;
+        // Re-check for messages after waking up (handles race condition)
+        const recheckMessage = this.getPendingStore().peekPending(sessionDbId);
+        if (recheckMessage) {
+          // Got a message, continue processing
+          continue;
+        }
 
-        // If we just yielded a summary, that's the end of this batch - stop the iterator
-        if (message.type === 'summarize') {
-          logger.info('SESSION', `Summary yielded - ending generator`, { sessionId: sessionDbId });
+        if (!gotMessage) {
+          // Timeout or abort - exit the loop
+          logger.info('SESSION', `Generator exiting after linger timeout`, { sessionId: sessionDbId });
           return;
         }
+
+        continue;
+      }
+
+      // Mark as processing BEFORE yielding (status: pending -> processing)
+      this.getPendingStore().markProcessing(persistentMessage.id);
+
+      // Track this message ID for completion marking
+      session.pendingProcessingIds.add(persistentMessage.id);
+
+      // Convert to PendingMessageWithId and yield
+      // Include original timestamp for accurate observation timestamps (survives stuck processing)
+      const message: PendingMessageWithId = {
+        _persistentId: persistentMessage.id,
+        _originalTimestamp: persistentMessage.created_at_epoch,
+        ...this.getPendingStore().toPendingMessage(persistentMessage)
+      };
+
+      // Also add to in-memory queue for backward compatibility (status tracking)
+      session.pendingMessages.push(message);
+
+      yield message;
+
+      // Remove from in-memory queue after yielding
+      session.pendingMessages.shift();
+
+      // If we just yielded a summary, that's the end of this batch - stop the iterator
+      if (message.type === 'summarize') {
+        logger.info('SESSION', `Summary yielded - ending generator`, { sessionId: sessionDbId });
+        return;
       }
     }
   }
+
+  /**
+   * Get the PendingMessageStore (for SDKAgent to mark messages as processed)
+   */
+  getPendingMessageStore(): PendingMessageStore {
+    return this.getPendingStore();
+  }
 }

src/services/worker/http/middleware.ts

@@ -30,7 +30,9 @@ export function createMiddleware(
   // 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('.')) {
+    const staticExtensions = ['.html', '.js', '.css', '.svg', '.png', '.jpg', '.jpeg', '.webp', '.woff', '.woff2', '.ttf', '.eot'];
+    const isStaticAsset = staticExtensions.some(ext => req.path.endsWith(ext));
+    if (req.path.startsWith('/health') || req.path === '/' || isStaticAsset) {
       return next();
     }
 
@@ -60,6 +62,34 @@ export function createMiddleware(
   return middlewares;
 }
 
+/**
+ * Middleware to require localhost-only access
+ * Used for admin endpoints that should not be exposed when binding to 0.0.0.0
+ */
+export function requireLocalhost(req: Request, res: Response, next: NextFunction): void {
+  const clientIp = req.ip || req.connection.remoteAddress || '';
+  const isLocalhost =
+    clientIp === '127.0.0.1' ||
+    clientIp === '::1' ||
+    clientIp === '::ffff:127.0.0.1' ||
+    clientIp === 'localhost';
+
+  if (!isLocalhost) {
+    logger.warn('SECURITY', 'Admin endpoint access denied - not localhost', {
+      endpoint: req.path,
+      clientIp,
+      method: req.method
+    });
+    res.status(403).json({
+      error: 'Forbidden',
+      message: 'Admin endpoints are only accessible from localhost'
+    });
+    return;
+  }
+
+  next();
+}
+
 /**
  * Summarize request body for logging
  * Used to avoid logging sensitive data or large payloads

src/services/worker/http/routes/DataRoutes.ts

@@ -40,6 +40,7 @@ export class DataRoutes extends BaseRouteHandler {
     app.get('/api/observation/:id', this.handleGetObservationById.bind(this));
     app.post('/api/observations/batch', this.handleGetObservationsByIds.bind(this));
     app.get('/api/session/:id', this.handleGetSessionById.bind(this));
+    app.post('/api/sdk-sessions/batch', this.handleGetSdkSessionsByIds.bind(this));
     app.get('/api/prompt/:id', this.handleGetPromptById.bind(this));
 
     // Metadata endpoints
@@ -49,6 +50,9 @@ export class DataRoutes extends BaseRouteHandler {
     // Processing status endpoints
     app.get('/api/processing-status', this.handleGetProcessingStatus.bind(this));
     app.post('/api/processing', this.handleSetProcessing.bind(this));
+
+    // Import endpoint
+    app.post('/api/import', this.handleImport.bind(this));
   }
 
   /**
@@ -146,6 +150,24 @@ export class DataRoutes extends BaseRouteHandler {
     res.json(sessions[0]);
   });
 
+  /**
+   * Get SDK sessions by SDK session IDs
+   * POST /api/sdk-sessions/batch
+   * Body: { sdkSessionIds: string[] }
+   */
+  private handleGetSdkSessionsByIds = this.wrapHandler((req: Request, res: Response): void => {
+    const { sdkSessionIds } = req.body;
+
+    if (!Array.isArray(sdkSessionIds)) {
+      this.badRequest(res, 'sdkSessionIds must be an array');
+      return;
+    }
+
+    const store = this.dbManager.getSessionStore();
+    const sessions = store.getSdkSessionsBySessionIds(sdkSessionIds);
+    res.json(sessions);
+  });
+
   /**
    * Get user prompt by ID
    * GET /api/prompt/:id
@@ -254,7 +276,7 @@ export class DataRoutes extends BaseRouteHandler {
     const queueDepth = this.sessionManager.getTotalQueueDepth();
     const activeSessions = this.sessionManager.getActiveSessionCount();
 
-    res.json({ status: 'ok', isProcessing });
+    res.json({ status: 'ok', isProcessing, queueDepth, activeSessions });
   });
 
   /**
@@ -267,4 +289,79 @@ export class DataRoutes extends BaseRouteHandler {
 
     return { offset, limit, project };
   }
+
+  /**
+   * Import memories from export file
+   * POST /api/import
+   * Body: { sessions: [], summaries: [], observations: [], prompts: [] }
+   */
+  private handleImport = this.wrapHandler((req: Request, res: Response): void => {
+    const { sessions, summaries, observations, prompts } = req.body;
+
+    const stats = {
+      sessionsImported: 0,
+      sessionsSkipped: 0,
+      summariesImported: 0,
+      summariesSkipped: 0,
+      observationsImported: 0,
+      observationsSkipped: 0,
+      promptsImported: 0,
+      promptsSkipped: 0
+    };
+
+    const store = this.dbManager.getSessionStore();
+
+    // Import sessions first (dependency for everything else)
+    if (Array.isArray(sessions)) {
+      for (const session of sessions) {
+        const result = store.importSdkSession(session);
+        if (result.imported) {
+          stats.sessionsImported++;
+        } else {
+          stats.sessionsSkipped++;
+        }
+      }
+    }
+
+    // Import summaries (depends on sessions)
+    if (Array.isArray(summaries)) {
+      for (const summary of summaries) {
+        const result = store.importSessionSummary(summary);
+        if (result.imported) {
+          stats.summariesImported++;
+        } else {
+          stats.summariesSkipped++;
+        }
+      }
+    }
+
+    // Import observations (depends on sessions)
+    if (Array.isArray(observations)) {
+      for (const obs of observations) {
+        const result = store.importObservation(obs);
+        if (result.imported) {
+          stats.observationsImported++;
+        } else {
+          stats.observationsSkipped++;
+        }
+      }
+    }
+
+    // Import prompts (depends on sessions)
+    if (Array.isArray(prompts)) {
+      for (const prompt of prompts) {
+        const result = store.importUserPrompt(prompt);
+        if (result.imported) {
+          stats.promptsImported++;
+        } else {
+          stats.promptsSkipped++;
+        }
+      }
+    }
+
+    res.json({
+      success: true,
+      stats
+    });
+  });
 }

src/services/worker/http/routes/SessionRoutes.ts

@@ -277,19 +277,14 @@ export class SessionRoutes extends BaseRouteHandler {
     // Skip meta-observations: file operations on session-memory files
     const fileOperationTools = new Set(['Edit', 'Write', 'Read', 'NotebookEdit']);
     if (fileOperationTools.has(tool_name) && tool_input) {
-      try {
-        const filePath = tool_input.file_path || tool_input.notebook_path;
-        if (filePath && filePath.includes('session-memory')) {
-          logger.debug('SESSION', 'Skipping meta-observation for session-memory file', {
-            tool_name,
-            file_path: filePath
-          });
-          res.json({ status: 'skipped', reason: 'session_memory_meta' });
-          return;
-        }
-      } catch (error) {
-        // If we can't parse tool_input, continue normally
-        logger.debug('SESSION', 'Could not check file_path for session-memory filter', { tool_name }, error);
+      const filePath = tool_input.file_path || tool_input.notebook_path;
+      if (filePath && filePath.includes('session-memory')) {
+        logger.debug('SESSION', 'Skipping meta-observation for session-memory file', {
+          tool_name,
+          file_path: filePath
+        });
+        res.json({ status: 'skipped', reason: 'session_memory_meta' });
+        return;
       }
     }
 

src/services/worker/http/routes/SettingsRoutes.ts

@@ -59,70 +59,8 @@ export class SettingsRoutes extends BaseRouteHandler {
    * Update environment settings (in ~/.claude-mem/settings.json) with validation
    */
   private handleUpdateSettings = this.wrapHandler((req: Request, res: Response): void => {
-    // Validate CLAUDE_MEM_CONTEXT_OBSERVATIONS
-    if (req.body.CLAUDE_MEM_CONTEXT_OBSERVATIONS) {
-      const obsCount = parseInt(req.body.CLAUDE_MEM_CONTEXT_OBSERVATIONS, 10);
-      if (isNaN(obsCount) || obsCount < 1 || obsCount > 200) {
-        res.status(400).json({
-          success: false,
-          error: 'CLAUDE_MEM_CONTEXT_OBSERVATIONS must be between 1 and 200'
-        });
-        return;
-      }
-    }
-
-    // Validate CLAUDE_MEM_WORKER_PORT
-    if (req.body.CLAUDE_MEM_WORKER_PORT) {
-      const port = parseInt(req.body.CLAUDE_MEM_WORKER_PORT, 10);
-      if (isNaN(port) || port < 1024 || port > 65535) {
-        res.status(400).json({
-          success: false,
-          error: 'CLAUDE_MEM_WORKER_PORT must be between 1024 and 65535'
-        });
-        return;
-      }
-    }
-
-    // Validate CLAUDE_MEM_WORKER_HOST (IP address or 0.0.0.0)
-    if (req.body.CLAUDE_MEM_WORKER_HOST) {
-      const host = req.body.CLAUDE_MEM_WORKER_HOST;
-      // Allow localhost variants and valid IP patterns
-      const validHostPattern = /^(127\.0\.0\.1|0\.0\.0\.0|localhost|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/;
-      if (!validHostPattern.test(host)) {
-        res.status(400).json({
-          success: false,
-          error: 'CLAUDE_MEM_WORKER_HOST must be a valid IP address (e.g., 127.0.0.1, 0.0.0.0)'
-        });
-        return;
-      }
-    }
-
-    // Validate CLAUDE_MEM_LOG_LEVEL
-    if (req.body.CLAUDE_MEM_LOG_LEVEL) {
-      const validLevels = ['DEBUG', 'INFO', 'WARN', 'ERROR', 'SILENT'];
-      if (!validLevels.includes(req.body.CLAUDE_MEM_LOG_LEVEL.toUpperCase())) {
-        res.status(400).json({
-          success: false,
-          error: 'CLAUDE_MEM_LOG_LEVEL must be one of: DEBUG, INFO, WARN, ERROR, SILENT'
-        });
-        return;
-      }
-    }
-
-    // Validate CLAUDE_MEM_PYTHON_VERSION (must be valid Python version format)
-    if (req.body.CLAUDE_MEM_PYTHON_VERSION) {
-      const pythonVersionRegex = /^3\.\d{1,2}$/;
-      if (!pythonVersionRegex.test(req.body.CLAUDE_MEM_PYTHON_VERSION)) {
-        res.status(400).json({
-          success: false,
-          error: 'CLAUDE_MEM_PYTHON_VERSION must be in format "3.X" or "3.XX" (e.g., "3.13")'
-        });
-        return;
-      }
-    }
-
-    // Validate context settings
-    const validation = this.validateContextSettings(req.body);
+    // Validate all settings
+    const validation = this.validateSettings(req.body);
     if (!validation.valid) {
       res.status(400).json({
         success: false,
@@ -274,9 +212,51 @@ export class SettingsRoutes extends BaseRouteHandler {
   });
 
   /**
-   * Validate context settings from request body
+   * Validate all settings from request body (single source of truth)
    */
-  private validateContextSettings(settings: any): { valid: boolean; error?: string } {
+  private validateSettings(settings: any): { valid: boolean; error?: string } {
+    // Validate CLAUDE_MEM_CONTEXT_OBSERVATIONS
+    if (settings.CLAUDE_MEM_CONTEXT_OBSERVATIONS) {
+      const obsCount = parseInt(settings.CLAUDE_MEM_CONTEXT_OBSERVATIONS, 10);
+      if (isNaN(obsCount) || obsCount < 1 || obsCount > 200) {
+        return { valid: false, error: 'CLAUDE_MEM_CONTEXT_OBSERVATIONS must be between 1 and 200' };
+      }
+    }
+
+    // Validate CLAUDE_MEM_WORKER_PORT
+    if (settings.CLAUDE_MEM_WORKER_PORT) {
+      const port = parseInt(settings.CLAUDE_MEM_WORKER_PORT, 10);
+      if (isNaN(port) || port < 1024 || port > 65535) {
+        return { valid: false, error: 'CLAUDE_MEM_WORKER_PORT must be between 1024 and 65535' };
+      }
+    }
+
+    // Validate CLAUDE_MEM_WORKER_HOST (IP address or 0.0.0.0)
+    if (settings.CLAUDE_MEM_WORKER_HOST) {
+      const host = settings.CLAUDE_MEM_WORKER_HOST;
+      // Allow localhost variants and valid IP patterns
+      const validHostPattern = /^(127\.0\.0\.1|0\.0\.0\.0|localhost|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/;
+      if (!validHostPattern.test(host)) {
+        return { valid: false, error: 'CLAUDE_MEM_WORKER_HOST must be a valid IP address (e.g., 127.0.0.1, 0.0.0.0)' };
+      }
+    }
+
+    // Validate CLAUDE_MEM_LOG_LEVEL
+    if (settings.CLAUDE_MEM_LOG_LEVEL) {
+      const validLevels = ['DEBUG', 'INFO', 'WARN', 'ERROR', 'SILENT'];
+      if (!validLevels.includes(settings.CLAUDE_MEM_LOG_LEVEL.toUpperCase())) {
+        return { valid: false, error: 'CLAUDE_MEM_LOG_LEVEL must be one of: DEBUG, INFO, WARN, ERROR, SILENT' };
+      }
+    }
+
+    // Validate CLAUDE_MEM_PYTHON_VERSION (must be valid Python version format)
+    if (settings.CLAUDE_MEM_PYTHON_VERSION) {
+      const pythonVersionRegex = /^3\.\d{1,2}$/;
+      if (!pythonVersionRegex.test(settings.CLAUDE_MEM_PYTHON_VERSION)) {
+        return { valid: false, error: 'CLAUDE_MEM_PYTHON_VERSION must be in format "3.X" or "3.XX" (e.g., "3.13")' };
+      }
+    }
+
     // Validate boolean string values
     const booleanSettings = [
       'CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS',

src/services/worker/http/routes/ViewerRoutes.ts

@@ -7,7 +7,7 @@
 
 import express, { Request, Response } from 'express';
 import path from 'path';
-import { readFileSync } from 'fs';
+import { readFileSync, existsSync } from 'fs';
 import { getPackageRoot } from '../../../../shared/paths.js';
 import { SSEBroadcaster } from '../../SSEBroadcaster.js';
 import { DatabaseManager } from '../../DatabaseManager.js';
@@ -41,7 +41,19 @@ export class ViewerRoutes extends BaseRouteHandler {
    */
   private handleViewerUI = this.wrapHandler((req: Request, res: Response): void => {
     const packageRoot = getPackageRoot();
-    const viewerPath = path.join(packageRoot, 'plugin', 'ui', 'viewer.html');
+
+    // Try cache structure first (ui/viewer.html), then marketplace structure (plugin/ui/viewer.html)
+    const viewerPaths = [
+      path.join(packageRoot, 'ui', 'viewer.html'),
+      path.join(packageRoot, 'plugin', 'ui', 'viewer.html')
+    ];
+
+    const viewerPath = viewerPaths.find(p => existsSync(p));
+
+    if (!viewerPath) {
+      throw new Error('Viewer UI not found at any expected location');
+    }
+
     const html = readFileSync(viewerPath, 'utf-8');
     res.setHeader('Content-Type', 'text/html');
     res.send(html);

src/shared/SettingsDefaultsManager.ts

@@ -104,39 +104,45 @@ export class SettingsDefaultsManager {
   /**
    * Load settings from file with fallback to defaults
    * Returns merged settings with defaults as fallback
+   * Handles all errors (missing file, corrupted JSON, permissions) by returning defaults
    */
   static loadFromFile(settingsPath: string): SettingsDefaults {
-    if (!existsSync(settingsPath)) {
+    try {
+      if (!existsSync(settingsPath)) {
+        return this.getAllDefaults();
+      }
+
+      const settingsData = readFileSync(settingsPath, 'utf-8');
+      const settings = JSON.parse(settingsData);
+
+      // MIGRATION: Handle old nested schema { env: {...} }
+      let flatSettings = settings;
+      if (settings.env && typeof settings.env === 'object') {
+        // Migrate from nested to flat schema
+        flatSettings = settings.env;
+
+        // Auto-migrate the file to flat schema
+        try {
+          writeFileSync(settingsPath, JSON.stringify(flatSettings, null, 2), 'utf-8');
+          logger.info('SETTINGS', 'Migrated settings file from nested to flat schema', { settingsPath });
+        } catch (error) {
+          logger.warn('SETTINGS', 'Failed to auto-migrate settings file', { settingsPath }, error);
+          // Continue with in-memory migration even if write fails
+        }
+      }
+
+      // Merge file settings with defaults (flat schema)
+      const result: SettingsDefaults = { ...this.DEFAULTS };
+      for (const key of Object.keys(this.DEFAULTS) as Array<keyof SettingsDefaults>) {
+        if (flatSettings[key] !== undefined) {
+          result[key] = flatSettings[key];
+        }
+      }
+
+      return result;
+    } catch (error) {
+      logger.warn('SETTINGS', 'Failed to load settings, using defaults', { settingsPath }, error);
       return this.getAllDefaults();
     }
-
-    const settingsData = readFileSync(settingsPath, 'utf-8');
-    const settings = JSON.parse(settingsData);
-
-    // MIGRATION: Handle old nested schema { env: {...} }
-    let flatSettings = settings;
-    if (settings.env && typeof settings.env === 'object') {
-      // Migrate from nested to flat schema
-      flatSettings = settings.env;
-
-      // Auto-migrate the file to flat schema
-      try {
-        writeFileSync(settingsPath, JSON.stringify(flatSettings, null, 2), 'utf-8');
-        logger.info('SETTINGS', 'Migrated settings file from nested to flat schema', { settingsPath });
-      } catch (error) {
-        logger.warn('SETTINGS', 'Failed to auto-migrate settings file', { settingsPath }, error);
-        // Continue with in-memory migration even if write fails
-      }
-    }
-
-    // Merge file settings with defaults (flat schema)
-    const result: SettingsDefaults = { ...this.DEFAULTS };
-    for (const key of Object.keys(this.DEFAULTS) as Array<keyof SettingsDefaults>) {
-      if (flatSettings[key] !== undefined) {
-        result[key] = flatSettings[key];
-      }
-    }
-
-    return result;
   }
 }

src/shared/timeline-formatting.ts

@@ -22,9 +22,10 @@ export function parseJsonArray(json: string | null): string[] {
 
 /**
  * Format date with time (e.g., "Dec 14, 7:30 PM")
+ * Accepts either ISO date string or epoch milliseconds
  */
-export function formatDateTime(dateStr: string): string {
-  const date = new Date(dateStr);
+export function formatDateTime(dateInput: string | number): string {
+  const date = new Date(dateInput);
   return date.toLocaleString('en-US', {
     month: 'short',
     day: 'numeric',
@@ -36,9 +37,10 @@ export function formatDateTime(dateStr: string): string {
 
 /**
  * Format just time, no date (e.g., "7:30 PM")
+ * Accepts either ISO date string or epoch milliseconds
  */
-export function formatTime(dateStr: string): string {
-  const date = new Date(dateStr);
+export function formatTime(dateInput: string | number): string {
+  const date = new Date(dateInput);
   return date.toLocaleString('en-US', {
     hour: 'numeric',
     minute: '2-digit',
@@ -48,9 +50,10 @@ export function formatTime(dateStr: string): string {
 
 /**
  * Format just date (e.g., "Dec 14, 2025")
+ * Accepts either ISO date string or epoch milliseconds
  */
-export function formatDate(dateStr: string): string {
-  const date = new Date(dateStr);
+export function formatDate(dateInput: string | number): string {
+  const date = new Date(dateInput);
   return date.toLocaleString('en-US', {
     month: 'short',
     day: 'numeric',
@@ -76,6 +79,14 @@ export function extractFirstFile(filesModified: string | null, cwd: string): str
   return files.length > 0 ? toRelativePath(files[0], cwd) : 'General';
 }
 
+/**
+ * Estimate token count for text (rough approximation: ~4 chars per token)
+ */
+export function estimateTokens(text: string | null): number {
+  if (!text) return 0;
+  return Math.ceil(text.length / 4);
+}
+
 /**
  * Group items by date
  *

src/shared/transcript-parser.ts

@@ -56,6 +56,20 @@ export function extractLastMessage(
                 .filter((c: any) => c.type === 'text')
                 .map((c: any) => c.text)
                 .join('\n');
+            } else {
+              // Unknown content format - log error and skip this message
+              logger.error(
+                'PARSER',
+                'Unknown message content format',
+                {
+                  role,
+                  transcriptPath,
+                  contentType: typeof msgContent,
+                  content: msgContent
+                },
+                new Error('Message content is neither string nor array')
+              );
+              continue;
             }
 
             if (stripSystemReminders) {

src/shared/worker-utils.ts

@@ -13,8 +13,9 @@ const MARKETPLACE_ROOT = path.join(homedir(), '.claude', 'plugins', 'marketplace
 // Named constants for health checks
 const HEALTH_CHECK_TIMEOUT_MS = getTimeout(HOOK_TIMEOUTS.HEALTH_CHECK);
 
-// Port cache to avoid repeated settings file reads
+// Cache to avoid repeated settings file reads
 let cachedPort: number | null = null;
+let cachedHost: string | null = null;
 
 /**
  * Get the worker port number from settings
@@ -26,49 +27,50 @@ export function getWorkerPort(): number {
     return cachedPort;
   }
 
-  try {
-    const settingsPath = path.join(SettingsDefaultsManager.get('CLAUDE_MEM_DATA_DIR'), 'settings.json');
-    const settings = SettingsDefaultsManager.loadFromFile(settingsPath);
-    cachedPort = parseInt(settings.CLAUDE_MEM_WORKER_PORT, 10);
-    return cachedPort;
-  } catch (error) {
-    // Fallback to default if settings load fails
-    logger.debug('SYSTEM', 'Failed to load port from settings, using default', { error });
-    cachedPort = parseInt(SettingsDefaultsManager.get('CLAUDE_MEM_WORKER_PORT'), 10);
-    return cachedPort;
-  }
-}
-
-/**
- * Clear the cached port value
- * Call this when settings are updated to force re-reading from file
- */
-export function clearPortCache(): void {
-  cachedPort = null;
+  const settingsPath = path.join(SettingsDefaultsManager.get('CLAUDE_MEM_DATA_DIR'), 'settings.json');
+  const settings = SettingsDefaultsManager.loadFromFile(settingsPath);
+  cachedPort = parseInt(settings.CLAUDE_MEM_WORKER_PORT, 10);
+  return cachedPort;
 }
 
 /**
  * Get the worker host address
- * Priority: ~/.claude-mem/settings.json > env var > default (127.0.0.1)
+ * Uses CLAUDE_MEM_WORKER_HOST from settings file or default (127.0.0.1)
+ * Caches the host value to avoid repeated file reads
  */
 export function getWorkerHost(): string {
-  const settingsPath = path.join(homedir(), '.claude-mem', 'settings.json');
+  if (cachedHost !== null) {
+    return cachedHost;
+  }
+
+  const settingsPath = path.join(SettingsDefaultsManager.get('CLAUDE_MEM_DATA_DIR'), 'settings.json');
   const settings = SettingsDefaultsManager.loadFromFile(settingsPath);
-  return settings.CLAUDE_MEM_WORKER_HOST;
+  cachedHost = settings.CLAUDE_MEM_WORKER_HOST;
+  return cachedHost;
 }
 
 /**
- * Check if worker is responsive by trying the health endpoint
+ * Clear the cached port and host values
+ * Call this when settings are updated to force re-reading from file
+ */
+export function clearPortCache(): void {
+  cachedPort = null;
+  cachedHost = null;
+}
+
+/**
+ * Check if worker is responsive and fully initialized by trying the readiness endpoint
+ * Changed from /health to /api/readiness to ensure MCP initialization is complete
  */
 async function isWorkerHealthy(): Promise<boolean> {
   try {
     const port = getWorkerPort();
-    const response = await fetch(`http://127.0.0.1:${port}/health`, {
+    const response = await fetch(`http://127.0.0.1:${port}/api/readiness`, {
       signal: AbortSignal.timeout(HEALTH_CHECK_TIMEOUT_MS)
     });
     return response.ok;
   } catch (error) {
-    logger.debug('SYSTEM', 'Worker health check failed', {
+    logger.debug('SYSTEM', 'Worker readiness check failed', {
       error: error instanceof Error ? error.message : String(error),
       errorType: error?.constructor?.name
     });

src/ui/viewer/components/ContextSettingsModal.tsx

@@ -195,11 +195,6 @@ export function ContextSettingsModal({
 }: ContextSettingsModalProps) {
   const [formState, setFormState] = useState<Settings>(settings);
 
-  // MCP toggle state
-  const [mcpEnabled, setMcpEnabled] = useState(true);
-  const [mcpToggling, setMcpToggling] = useState(false);
-  const [mcpStatus, setMcpStatus] = useState('');
-
   // Create debounced save function
   const debouncedSave = useCallback(
     debounce((newSettings: Settings) => {
@@ -213,14 +208,6 @@ export function ContextSettingsModal({
     setFormState(settings);
   }, [settings]);
 
-  // Fetch MCP status on mount
-  useEffect(() => {
-    fetch('/api/mcp/status')
-      .then(res => res.json())
-      .then(data => setMcpEnabled(data.enabled))
-      .catch(error => console.error('Failed to load MCP status:', error));
-  }, []);
-
   // Get context preview based on current form state
   const { preview, isLoading, error, projects, selectedProject, setSelectedProject } = useContextPreview(formState);
 
@@ -254,36 +241,6 @@ export function ContextSettingsModal({
     updateSetting(key, values.join(','));
   }, [updateSetting]);
 
-  // Handle MCP toggle
-  const handleMcpToggle = async (enabled: boolean) => {
-    setMcpToggling(true);
-    setMcpStatus('Toggling...');
-
-    try {
-      const response = await fetch('/api/mcp/toggle', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ enabled })
-      });
-
-      const result = await response.json();
-
-      if (result.success) {
-        setMcpEnabled(result.enabled);
-        setMcpStatus('Updated (restart to apply)');
-        setTimeout(() => setMcpStatus(''), 3000);
-      } else {
-        setMcpStatus(`Error: ${result.error}`);
-        setTimeout(() => setMcpStatus(''), 3000);
-      }
-    } catch (err) {
-      setMcpStatus(`Error: ${err instanceof Error ? err.message : 'Unknown error'}`);
-      setTimeout(() => setMcpStatus(''), 3000);
-    } finally {
-      setMcpToggling(false);
-    }
-  };
-
   // Handle ESC key
   useEffect(() => {
     const handleEsc = (e: KeyboardEvent) => {
@@ -521,14 +478,6 @@ export function ContextSettingsModal({
               </FormField>
 
               <div className="toggle-group" style={{ marginTop: '12px' }}>
-                <ToggleSwitch
-                  id="mcp-enabled"
-                  label="MCP search server"
-                  description={mcpStatus || "Enable Model Context Protocol search"}
-                  checked={mcpEnabled}
-                  onChange={handleMcpToggle}
-                  disabled={mcpToggling}
-                />
                 <ToggleSwitch
                   id="show-last-summary"
                   label="Include last summary"

src/ui/viewer/components/Sidebar.tsx

@@ -1,428 +0,0 @@
-import React, { useState, useEffect } from 'react';
-import { Settings, Stats } from '../types';
-import { DEFAULT_SETTINGS } from '../constants/settings';
-import { formatUptime, formatBytes } from '../utils/formatters';
-
-interface SidebarProps {
-  isOpen: boolean;
-  settings: Settings;
-  stats: Stats;
-  isSaving: boolean;
-  saveStatus: string;
-  isConnected: boolean;
-  projects: string[];
-  currentFilter: string;
-  onFilterChange: (filter: string) => void;
-  onSave: (settings: Settings) => void;
-  onClose: () => void;
-  onRefreshStats: () => void;
-}
-
-export function Sidebar({ isOpen, settings, stats, isSaving, saveStatus, isConnected, projects, currentFilter, onFilterChange, onSave, onClose, onRefreshStats }: SidebarProps) {
-  // Consolidated settings form state
-  const [formState, setFormState] = useState<Settings>({
-    CLAUDE_MEM_MODEL: settings.CLAUDE_MEM_MODEL || DEFAULT_SETTINGS.CLAUDE_MEM_MODEL,
-    CLAUDE_MEM_CONTEXT_OBSERVATIONS: settings.CLAUDE_MEM_CONTEXT_OBSERVATIONS || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_OBSERVATIONS,
-    CLAUDE_MEM_WORKER_PORT: settings.CLAUDE_MEM_WORKER_PORT || DEFAULT_SETTINGS.CLAUDE_MEM_WORKER_PORT,
-    CLAUDE_MEM_WORKER_HOST: settings.CLAUDE_MEM_WORKER_HOST || DEFAULT_SETTINGS.CLAUDE_MEM_WORKER_HOST,
-    CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS: settings.CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS,
-    CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS: settings.CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS,
-    CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT: settings.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT,
-    CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_PERCENT: settings.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_PERCENT || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_PERCENT,
-    CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES: settings.CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES,
-    CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS: settings.CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS,
-    CLAUDE_MEM_CONTEXT_FULL_COUNT: settings.CLAUDE_MEM_CONTEXT_FULL_COUNT || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_FULL_COUNT,
-    CLAUDE_MEM_CONTEXT_FULL_FIELD: settings.CLAUDE_MEM_CONTEXT_FULL_FIELD || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_FULL_FIELD,
-    CLAUDE_MEM_CONTEXT_SESSION_COUNT: settings.CLAUDE_MEM_CONTEXT_SESSION_COUNT || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SESSION_COUNT,
-    CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY: settings.CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY,
-    CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE: settings.CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE,
-  });
-
-  // MCP toggle state (separate from settings)
-  const [mcpEnabled, setMcpEnabled] = useState(true);
-  const [mcpToggling, setMcpToggling] = useState(false);
-  const [mcpStatus, setMcpStatus] = useState('');
-
-  // Helper to update form state
-  const updateFormState = (field: keyof Settings, value: string) => {
-    setFormState(prev => ({ ...prev, [field]: value }));
-  };
-
-  // Update settings form state when settings prop changes
-  useEffect(() => {
-    setFormState({
-      CLAUDE_MEM_MODEL: settings.CLAUDE_MEM_MODEL || DEFAULT_SETTINGS.CLAUDE_MEM_MODEL,
-      CLAUDE_MEM_CONTEXT_OBSERVATIONS: settings.CLAUDE_MEM_CONTEXT_OBSERVATIONS || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_OBSERVATIONS,
-      CLAUDE_MEM_WORKER_PORT: settings.CLAUDE_MEM_WORKER_PORT || DEFAULT_SETTINGS.CLAUDE_MEM_WORKER_PORT,
-      CLAUDE_MEM_WORKER_HOST: settings.CLAUDE_MEM_WORKER_HOST || DEFAULT_SETTINGS.CLAUDE_MEM_WORKER_HOST,
-      CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS: settings.CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS,
-      CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS: settings.CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS,
-      CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT: settings.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT,
-      CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_PERCENT: settings.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_PERCENT || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_PERCENT,
-      CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES: settings.CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES,
-      CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS: settings.CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS,
-      CLAUDE_MEM_CONTEXT_FULL_COUNT: settings.CLAUDE_MEM_CONTEXT_FULL_COUNT || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_FULL_COUNT,
-      CLAUDE_MEM_CONTEXT_FULL_FIELD: settings.CLAUDE_MEM_CONTEXT_FULL_FIELD || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_FULL_FIELD,
-      CLAUDE_MEM_CONTEXT_SESSION_COUNT: settings.CLAUDE_MEM_CONTEXT_SESSION_COUNT || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SESSION_COUNT,
-      CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY: settings.CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY,
-      CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE: settings.CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE || DEFAULT_SETTINGS.CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE,
-    });
-  }, [settings]);
-
-  // Fetch MCP status on mount
-  useEffect(() => {
-    fetch('/api/mcp/status')
-      .then(res => res.json())
-      .then(data => setMcpEnabled(data.enabled))
-      .catch(error => console.error('Failed to load MCP status:', error));
-  }, []);
-
-  // Refresh stats when sidebar opens
-  useEffect(() => {
-    if (isOpen) {
-      onRefreshStats();
-    }
-  }, [isOpen, onRefreshStats]);
-
-  const handleSave = () => {
-    onSave(formState);
-  };
-
-  const handleMcpToggle = async (enabled: boolean) => {
-    setMcpToggling(true);
-    setMcpStatus('Toggling...');
-
-    try {
-      const response = await fetch('/api/mcp/toggle', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ enabled })
-      });
-
-      const result = await response.json();
-
-      if (result.success) {
-        setMcpEnabled(result.enabled);
-        setMcpStatus('✓ Updated (restart Claude Code to apply)');
-        setTimeout(() => setMcpStatus(''), 3000);
-      } else {
-        setMcpStatus(`✗ Error: ${result.error}`);
-        setTimeout(() => setMcpStatus(''), 3000);
-      }
-    } catch (error) {
-      setMcpStatus(`✗ Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
-      setTimeout(() => setMcpStatus(''), 3000);
-    } finally {
-      setMcpToggling(false);
-    }
-  };
-
-  return (
-    <div className={`sidebar ${isOpen ? 'open' : ''}`}>
-      <div className="sidebar-header">
-        <h1>Settings</h1>
-        <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
-          <div style={{ display: 'flex', alignItems: 'center', gap: '6px' }}>
-            <span className={`status-dot ${isConnected ? 'connected' : ''}`} />
-            <span style={{ fontSize: '11px', opacity: 0.5, fontWeight: 300 }}>{isConnected ? 'Connected' : 'Disconnected'}</span>
-          </div>
-          <button onClick={handleSave} disabled={isSaving}>
-            {isSaving ? 'Saving...' : 'Save'}
-          </button>
-          <button
-            onClick={onClose}
-            title="Close settings"
-            style={{
-              background: 'transparent',
-              border: '1px solid #404040',
-              padding: '8px',
-              width: '36px',
-              height: '36px',
-              display: 'flex',
-              alignItems: 'center',
-              justifyContent: 'center'
-            }}
-          >
-            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-              <line x1="18" y1="6" x2="6" y2="18"></line>
-              <line x1="6" y1="6" x2="18" y2="18"></line>
-            </svg>
-          </button>
-        </div>
-      </div>
-      <a
-        href="https://discord.gg/J4wttp9vDu"
-        target="_blank"
-        rel="noopener noreferrer"
-        className="sidebar-community-btn"
-        title="Join our Discord community"
-      >
-        <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" style={{ marginRight: '6px' }}>
-          <path d="M20.317 4.37a19.791 19.791 0 0 0-4.885-1.515a.074.074 0 0 0-.079.037c-.21.375-.444.864-.608 1.25a18.27 18.27 0 0 0-5.487 0a12.64 12.64 0 0 0-.617-1.25a.077.077 0 0 0-.079-.037A19.736 19.736 0 0 0 3.677 4.37a.07.07 0 0 0-.032.027C.533 9.046-.32 13.58.099 18.057a.082.082 0 0 0 .031.057a19.9 19.9 0 0 0 5.993 3.03a.078.078 0 0 0 .084-.028a14.09 14.09 0 0 0 1.226-1.994a.076.076 0 0 0-.041-.106a13.107 13.107 0 0 1-1.872-.892a.077.077 0 0 1-.008-.128a10.2 10.2 0 0 0 .372-.292a.074.074 0 0 1 .077-.01c3.928 1.793 8.18 1.793 12.062 0a.074.074 0 0 1 .078.01c.12.098.246.198.373.292a.077.077 0 0 1-.006.127a12.299 12.299 0 0 1-1.873.892a.077.077 0 0 0-.041.107c.36.698.772 1.362 1.225 1.993a.076.076 0 0 0 .084.028a19.839 19.839 0 0 0 6.002-3.03a.077.077 0 0 0 .032-.054c.5-5.177-.838-9.674-3.549-13.66a.061.061 0 0 0-.031-.03zM8.02 15.33c-1.183 0-2.157-1.085-2.157-2.419c0-1.333.956-2.419 2.157-2.419c1.21 0 2.176 1.096 2.157 2.42c0 1.333-.956 2.418-2.157 2.418zm7.975 0c-1.183 0-2.157-1.085-2.157-2.419c0-1.333.955-2.419 2.157-2.419c1.21 0 2.176 1.096 2.157 2.42c0 1.333-.946 2.418-2.157 2.418z" />
-        </svg>
-        <span>Community</span>
-      </a>
-      <div className="sidebar-social-links">
-        <a
-          href="https://docs.claude-mem.ai"
-          target="_blank"
-          rel="noopener noreferrer"
-          title="Documentation"
-          className="icon-link"
-        >
-          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-            <path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20"></path>
-            <path d="M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z"></path>
-          </svg>
-        </a>
-        <a
-          href="https://github.com/thedotmack/claude-mem/"
-          target="_blank"
-          rel="noopener noreferrer"
-          title="GitHub"
-          className="icon-link"
-        >
-          <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor">
-            <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z" />
-          </svg>
-        </a>
-        <a
-          href="https://x.com/Claude_Memory"
-          target="_blank"
-          rel="noopener noreferrer"
-          title="X (Twitter)"
-          className="icon-link"
-        >
-          <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor">
-            <path d="M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z" />
-          </svg>
-        </a>
-      </div>
-      <div className="sidebar-project-filter">
-        <label htmlFor="sidebar-project-select">Filter by Project</label>
-        <select
-          id="sidebar-project-select"
-          value={currentFilter}
-          onChange={e => onFilterChange(e.target.value)}
-        >
-          <option value="">All Projects</option>
-          {projects.map(project => (
-            <option key={project} value={project}>{project}</option>
-          ))}
-        </select>
-      </div>
-      <div className="stats-scroll">
-
-        <div className="settings-section">
-          <h3>Environment Variables</h3>
-          <div className="form-group">
-            <label htmlFor="model">CLAUDE_MEM_MODEL</label>
-            <div className="setting-description">
-              Model used for AI compression of tool observations. Haiku is fast and cheap, Sonnet offers better quality, Opus is most capable but expensive.
-            </div>
-            <select
-              id="model"
-              value={formState.CLAUDE_MEM_MODEL}
-              onChange={e => updateFormState('CLAUDE_MEM_MODEL', e.target.value)}
-            >
-              {/* Shorthand names forward to latest model version */}
-              <option value="haiku">haiku</option>
-              <option value="sonnet">sonnet</option>
-              <option value="opus">opus</option>
-            </select>
-          </div>
-          <div className="form-group">
-            <label htmlFor="contextObs">CLAUDE_MEM_CONTEXT_OBSERVATIONS</label>
-            <div className="setting-description">
-              Number of recent observations to inject at session start. Higher values provide more context but increase token usage. Default: 50
-            </div>
-            <input
-              type="number"
-              id="contextObs"
-              min="1"
-              max="200"
-              value={formState.CLAUDE_MEM_CONTEXT_OBSERVATIONS}
-              onChange={e => updateFormState('CLAUDE_MEM_CONTEXT_OBSERVATIONS', e.target.value)}
-            />
-          </div>
-          <div className="form-group">
-            <label htmlFor="workerPort">CLAUDE_MEM_WORKER_PORT</label>
-            <div className="setting-description">
-              Port number for the background worker service. Change only if port 37777 conflicts with another service.
-            </div>
-            <input
-              type="number"
-              id="workerPort"
-              min="1024"
-              max="65535"
-              value={formState.CLAUDE_MEM_WORKER_PORT}
-              onChange={e => updateFormState('CLAUDE_MEM_WORKER_PORT', e.target.value)}
-            />
-          </div>
-          <div className="form-group">
-            <label htmlFor="workerHost">CLAUDE_MEM_WORKER_HOST</label>
-            <div className="setting-description">
-              IP address to bind the worker service. Use 127.0.0.1 (default) for local-only access, or 0.0.0.0 for remote access on servers.
-            </div>
-            <input
-              type="text"
-              id="workerHost"
-              value={formState.CLAUDE_MEM_WORKER_HOST}
-              onChange={e => updateFormState('CLAUDE_MEM_WORKER_HOST', e.target.value)}
-              placeholder="127.0.0.1"
-            />
-          </div>
-
-          {/* Token Economics Display */}
-          <div className="form-group">
-            <label>Token Economics Display</label>
-            <div className="setting-description">
-              Choose which token metrics to show in session start context.
-            </div>
-            <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
-              <label style={{ display: 'flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }}>
-                <input type="checkbox" checked={formState.CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS === 'true'} onChange={e => updateFormState('CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS', e.target.checked ? 'true' : 'false')} />
-                Show read tokens
-              </label>
-              <label style={{ display: 'flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }}>
-                <input type="checkbox" checked={formState.CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS === 'true'} onChange={e => updateFormState('CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS', e.target.checked ? 'true' : 'false')} />
-                Show work tokens
-              </label>
-              <label style={{ display: 'flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }}>
-                <input type="checkbox" checked={formState.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT === 'true'} onChange={e => updateFormState('CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT', e.target.checked ? 'true' : 'false')} />
-                Show savings amount
-              </label>
-              <label style={{ display: 'flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }}>
-                <input type="checkbox" checked={formState.CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_PERCENT === 'true'} onChange={e => updateFormState('CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_PERCENT', e.target.checked ? 'true' : 'false')} />
-                Show savings percentage
-              </label>
-            </div>
-          </div>
-
-          {/* Display Configuration */}
-          <div className="form-group">
-            <label>Display Configuration</label>
-            <div className="setting-description">
-              Control how observations are displayed in the timeline.
-            </div>
-            <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', marginTop: '8px' }}>
-              <div>
-                <label htmlFor="fullCount" style={{ display: 'block', marginBottom: '4px', fontSize: '13px' }}>
-                  Full observation count (0-20)
-                </label>
-                <input type="number" id="fullCount" min="0" max="20" value={formState.CLAUDE_MEM_CONTEXT_FULL_COUNT} onChange={e => updateFormState('CLAUDE_MEM_CONTEXT_FULL_COUNT', e.target.value)} style={{ width: '100%' }} />
-                <div style={{ fontSize: '12px', color: '#999', marginTop: '4px' }}>
-                  Number of most recent observations to show with full details
-                </div>
-              </div>
-              <div>
-                <label htmlFor="fullField" style={{ display: 'block', marginBottom: '4px', fontSize: '13px' }}>
-                  Full observation field
-                </label>
-                <select id="fullField" value={formState.CLAUDE_MEM_CONTEXT_FULL_FIELD} onChange={e => updateFormState('CLAUDE_MEM_CONTEXT_FULL_FIELD', e.target.value)} style={{ width: '100%' }}>
-                  <option value="narrative">Narrative</option>
-                  <option value="facts">Facts</option>
-                </select>
-              </div>
-              <div>
-                <label htmlFor="sessionCount" style={{ display: 'block', marginBottom: '4px', fontSize: '13px' }}>
-                  Session summary count (1-50)
-                </label>
-                <input type="number" id="sessionCount" min="1" max="50" value={formState.CLAUDE_MEM_CONTEXT_SESSION_COUNT} onChange={e => updateFormState('CLAUDE_MEM_CONTEXT_SESSION_COUNT', e.target.value)} style={{ width: '100%' }} />
-              </div>
-            </div>
-          </div>
-
-          {/* Feature Toggles */}
-          <div className="form-group">
-            <label>Context Features</label>
-            <div className="setting-description">
-              Toggle additional features in session start context.
-            </div>
-            <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
-              <label style={{ display: 'flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }}>
-                <input type="checkbox" checked={formState.CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY === 'true'} onChange={e => updateFormState('CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY', e.target.checked ? 'true' : 'false')} />
-                Show last session summary
-              </label>
-              <label style={{ display: 'flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }}>
-                <input type="checkbox" checked={formState.CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE === 'true'} onChange={e => updateFormState('CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE', e.target.checked ? 'true' : 'false')} />
-                Include last session message
-              </label>
-            </div>
-          </div>
-
-          {saveStatus && (
-            <div className="save-status">{saveStatus}</div>
-          )}
-        </div>
-
-        <div className="settings-section">
-          <h3>MCP Search Server</h3>
-          <div className="form-group">
-            <label htmlFor="mcpEnabled" style={{ display: 'flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }}>
-              <input
-                type="checkbox"
-                id="mcpEnabled"
-                checked={mcpEnabled}
-                onChange={e => handleMcpToggle(e.target.checked)}
-                disabled={mcpToggling}
-                style={{ cursor: mcpToggling ? 'not-allowed' : 'pointer' }}
-              />
-              Enable MCP Search Server
-            </label>
-            <div className="setting-description">
-              claude-mem suggests using skill-based search (saves ~2,500 tokens at session start), but some users prefer MCP. Disable to only use skill-based search. Requires Claude Code restart to apply changes.
-            </div>
-            {mcpStatus && (
-              <div className="save-status">{mcpStatus}</div>
-            )}
-          </div>
-        </div>
-
-        <div className="settings-section">
-          <h3>Worker Stats</h3>
-          <div className="stats-grid">
-            <div className="stat">
-              <div className="stat-label">Version</div>
-              <div className="stat-value">{stats.worker?.version || '-'}</div>
-            </div>
-            <div className="stat">
-              <div className="stat-label">Uptime</div>
-              <div className="stat-value">{formatUptime(stats.worker?.uptime)}</div>
-            </div>
-            <div className="stat">
-              <div className="stat-label">Active Sessions</div>
-              <div className="stat-value">{stats.worker?.activeSessions || '0'}</div>
-            </div>
-            <div className="stat">
-              <div className="stat-label">SSE Clients</div>
-              <div className="stat-value">{stats.worker?.sseClients || '0'}</div>
-            </div>
-          </div>
-        </div>
-
-        <div className="settings-section">
-          <h3>Database Stats</h3>
-          <div className="stats-grid">
-            <div className="stat">
-              <div className="stat-label">DB Size</div>
-              <div className="stat-value">{formatBytes(stats.database?.size)}</div>
-            </div>
-            <div className="stat">
-              <div className="stat-label">Observations</div>
-              <div className="stat-value">{stats.database?.observations || '0'}</div>
-            </div>
-            <div className="stat">
-              <div className="stat-label">Sessions</div>
-              <div className="stat-value">{stats.database?.sessions || '0'}</div>
-            </div>
-            <div className="stat">
-              <div className="stat-label">Summaries</div>
-              <div className="stat-value">{stats.database?.summaries || '0'}</div>
-            </div>
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-}

src/utils/bun-path.ts

@@ -23,7 +23,7 @@ export function getBunPath(): string | null {
     const result = spawnSync('bun', ['--version'], {
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
-      shell: isWindows
+      shell: false  // SECURITY: No need for shell, bun is the executable
     });
     if (result.status === 0) {
       return 'bun'; // Available in PATH

src/utils/error-messages.ts

@@ -24,18 +24,6 @@ export function getWorkerRestartInstructions(
     actualError
   } = options;
 
-  const isWindows = process.platform === 'win32';
-
-  // Platform-specific directory paths
-  const pluginDir = isWindows
-    ? '%USERPROFILE%\\.claude\\plugins\\marketplaces\\thedotmack'
-    : '~/.claude/plugins/marketplaces/thedotmack';
-
-  // Platform-specific terminal name
-  const terminal = isWindows
-    ? 'Command Prompt or PowerShell'
-    : 'Terminal';
-
   // Build error message
   const prefix = customPrefix || 'Worker service connection failed.';
   const portInfo = port ? ` (port ${port})` : '';
@@ -43,10 +31,8 @@ export function getWorkerRestartInstructions(
   let message = `${prefix}${portInfo}\n\n`;
   message += `To restart the worker:\n`;
   message += `1. Exit Claude Code completely\n`;
-  message += `2. Open ${terminal}\n`;
-  message += `3. Navigate to: ${pluginDir}\n`;
-  message += `4. Run: npm run worker:restart\n`;
-  message += `5. Restart Claude Code`;
+  message += `2. Run: claude-mem restart\n`;
+  message += `3. Restart Claude Code`;
 
   if (includeSkillFallback) {
     message += `\n\nIf that doesn't work, try: /troubleshoot`;