chore: bump version to 7.4.3

🤖 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.3.3",
+      "version": "7.4.3",
       "source": "./plugin",
       "description": "Persistent memory system for Claude Code - context compression across sessions"
     }

.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

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-and-sync        # Build, sync to marketplace, restart worker
-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
 ```
 
 **Viewer UI**: http://localhost:37777
@@ -77,6 +72,26 @@ Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created
 **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.
+No need to edit the changelog ever, it's generated automatically.

README.md

@@ -396,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/public/architecture/pm2-to-bun-migration.mdx

@@ -106,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
 ```
@@ -305,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 |
@@ -451,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)
@@ -483,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

@@ -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

@@ -240,7 +240,7 @@ POST /api/observations/batch
 - `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_batch_observations` MCP tool to efficiently retrieve multiple observations in a single request, avoiding the overhead of multiple individual requests.
+**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
 ```
@@ -500,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/configuration.mdx

@@ -316,7 +316,7 @@ Edit `~/.claude-mem/settings.json`:
 
 Then restart the worker:
 ```bash
-npm run worker:restart
+claude-mem restart
 ```
 
 ### Custom Model
@@ -331,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
@@ -388,7 +388,7 @@ Enable debug logging:
 
 ```bash
 export DEBUG=claude-mem:*
-npm run worker:restart
+claude-mem restart
 npm run worker:logs
 ```
 
@@ -406,7 +406,7 @@ npm run worker:logs
 
 1. Restart worker after changes:
    ```bash
-   npm run worker:restart
+   claude-mem restart
    ```
 
 2. Verify environment variables:
@@ -440,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/endless-mode.mdx

@@ -94,7 +94,7 @@ git checkout beta/endless-mode
 npm install
 
 # Restart the worker
-npm run worker:restart
+claude-mem restart
 ```
 
 **To return to stable:**
@@ -103,7 +103,7 @@ npm run worker:restart
 cd ~/.claude/plugins/marketplaces/thedotmack/
 git checkout main
 npm install
-npm run worker:restart
+claude-mem restart
 ```
 
 ## Summary

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.3.3",
+  "version": "7.4.3",
   "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.3.3",
+  "version": "7.4.3",
   "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.3.2",
+  "version": "7.4.2",
   "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
+help(topic="workflow")  # Get 4-step workflow
-progressive_description(topic="search_params")  # Get parameters reference
+help(topic="search_params")  # Get parameters reference
-progressive_description(topic="examples")  # Get usage examples
+help(topic="examples")  # Get usage examples
-progressive_description(topic="all")  # Get complete guide
+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

@@ -288,7 +288,7 @@ npm run worker:status
 If the worker is stopped, restart it:
 
 ```bash
-npm run worker:restart
+claude-mem restart
 ```
 ```
 

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

@@ -44,7 +44,7 @@ npm run worker:status
 ```bash
 cd ~/.claude/plugins/marketplaces/thedotmack/ && \
 npm install && \
-npm run worker:restart
+claude-mem restart
 ```
 
 ## Fix: Stale PID File
@@ -70,7 +70,7 @@ curl -s http://127.0.0.1:37777/health
 mkdir -p ~/.claude-mem && \
 echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json && \
 cd ~/.claude/plugins/marketplaces/thedotmack/ && \
-npm run worker:restart && \
+claude-mem restart && \
 sleep 2 && \
 curl -s http://127.0.0.1:37778/health
 ```
@@ -86,7 +86,7 @@ curl -s http://127.0.0.1:37778/health
 cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup && \
 sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;" && \
 cd ~/.claude/plugins/marketplaces/thedotmack/ && \
-npm run worker:restart
+claude-mem restart
 ```
 
 **If integrity check fails, recreate database:**
@@ -94,7 +94,7 @@ npm run worker:restart
 # WARNING: This deletes all memory data
 mv ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.old && \
 cd ~/.claude/plugins/marketplaces/thedotmack/ && \
-npm run worker:restart
+claude-mem restart
 ```
 
 ## Fix: Clean Reinstall
@@ -135,7 +135,7 @@ find ~/.claude-mem/logs/ -name "worker-*.log" -mtime +7 -delete
 
 # Restart worker for fresh log
 cd ~/.claude/plugins/marketplaces/thedotmack/
-npm run worker:restart
+claude-mem restart
 ```
 
 **Note:** Logs auto-rotate daily, manual cleanup rarely needed.

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

@@ -29,7 +29,7 @@ Quick fixes for frequently encountered claude-mem problems.
 3. Restart worker and start new session:
    ```bash
    cd ~/.claude/plugins/marketplaces/thedotmack/
-   npm run worker:restart
+   claude-mem restart
    ```
 
 4. Create a test observation: `/skill version-bump` then cancel
@@ -173,7 +173,7 @@ Quick fixes for frequently encountered claude-mem problems.
 4. If FTS5 out of sync, restart worker (triggers reindex):
    ```bash
    cd ~/.claude/plugins/marketplaces/thedotmack/
-   npm run worker:restart
+   claude-mem restart
    ```
 
 ## Issue: Port Conflicts
@@ -194,7 +194,7 @@ Quick fixes for frequently encountered claude-mem problems.
    mkdir -p ~/.claude-mem
    echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
    cd ~/.claude/plugins/marketplaces/thedotmack/
-   npm run worker:restart
+   claude-mem restart
    ```
 
 ## Issue: Database Corrupted
@@ -219,7 +219,7 @@ Quick fixes for frequently encountered claude-mem problems.
    ```bash
    rm ~/.claude-mem/claude-mem.db
    cd ~/.claude/plugins/marketplaces/thedotmack/
-   npm run worker:restart
+   claude-mem restart
    # Worker will create new database
    ```
 

plugin/skills/troubleshoot/operations/database.md

@@ -173,7 +173,7 @@ If FTS5 counts don't match, triggers may have failed. Restart worker to rebuild:
 
 ```bash
 cd ~/.claude/plugins/marketplaces/thedotmack/
-npm run worker:restart
+claude-mem restart
 ```
 
 The worker will rebuild FTS5 indexes on startup if they're out of sync.
@@ -263,7 +263,7 @@ sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
    ```bash
    mv ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.archive
    cd ~/.claude/plugins/marketplaces/thedotmack/
-   npm run worker:restart
+   claude-mem restart
    ```
 
 ## Database Recovery

plugin/skills/troubleshoot/operations/reference.md

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

plugin/skills/troubleshoot/operations/worker.md

@@ -152,7 +152,7 @@ npm run worker:start
 ```bash
 # Restart worker (stops and starts)
 cd ~/.claude/plugins/marketplaces/thedotmack/
-npm run worker:restart
+claude-mem restart
 
 # Or manually stop and start
 npm run worker:stop
@@ -219,7 +219,7 @@ npm run worker:start
 **Port conflict:**
 ```bash
 echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
-npm run worker:restart
+claude-mem restart
 ```
 
 **Stale PID file:**
@@ -261,14 +261,14 @@ If fails, backup and recreate database.
 **Out of memory:**
 Check if database is too large or memory leak. Restart:
 ```bash
-npm run worker:restart
+claude-mem restart
 ```
 
 **Port conflict race condition:**
 Another process grabbing port intermittently. Change port:
 ```bash
 echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
-npm run worker:restart
+claude-mem restart
 ```
 
 ## Worker Management Commands
@@ -284,7 +284,7 @@ npm run worker:start
 npm run worker:stop
 
 # Restart worker
-npm run worker:restart
+claude-mem restart
 
 # View logs
 npm run worker:logs
@@ -355,7 +355,7 @@ All should return appropriate responses (HTML for viewer, JSON for APIs).
 |---------|---------|----------------|
 | Check if running | `npm run worker:status` | Shows PID and uptime |
 | Worker not running | `npm run worker:start` | Worker starts successfully |
-| Worker crashed | `npm run worker:restart` | Worker restarts |
+| 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 |

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();

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/new-hook.ts

@@ -1,9 +1,9 @@
-import path from 'path';
 import { stdin } from 'process';
 import { createHookResponse } 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();
 

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',
+    description: 'Search memory. All parameters optional - call get_schema("search") for details',
-    inputSchema: z.object({
+    inputSchema: {
-      query: z.string().optional(),
+      type: 'object',
-      type: z.enum(['observations', 'sessions', 'prompts']).optional(),
+      properties: {},
-      obs_type: z.string().optional(),
+      additionalProperties: true
-      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')
-    }),
     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',
+    description: 'Timeline context. All parameters optional - call get_schema("timeline") for details',
-    inputSchema: z.object({
+    inputSchema: {
-      query: z.string().optional(),
+      type: 'object',
-      anchor: z.number().optional(),
+      properties: {},
-      depth_before: z.number().min(0).max(100).default(10),
+      additionalProperties: true
-      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()
-    }),
     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',
+    description: 'Recent context. All parameters optional - call get_schema("get_recent_context") for details',
-    inputSchema: z.object({
+    inputSchema: {
-      limit: z.number().min(1).max(100).default(30),
+      type: 'object',
-      type: z.string().optional(),
+      properties: {},
-      concepts: z.string().optional(),
+      additionalProperties: true
-      files: z.string().optional(),
+    },
-      project: z.string().optional(),
-      dateStart: z.union([z.string(), z.number()]).optional(),
-      dateEnd: z.union([z.string(), z.number()]).optional()
-    }),
     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',
+    description: 'Timeline around observation ID',
-    inputSchema: z.object({
+    inputSchema: {
-      anchor: z.number(),
+      type: 'object',
-      depth_before: z.number().min(0).max(100).default(10),
+      properties: {
-      depth_after: z.number().min(0).max(100).default(10),
+        anchor: {
-      type: z.string().optional(),
+          type: 'number',
-      concepts: z.string().optional(),
+          description: 'Observation ID (required). Optional params: get_schema("get_context_timeline")'
-      files: z.string().optional(),
+        }
-      project: z.string().optional()
+      },
-    }),
+      required: ['anchor'],
+      additionalProperties: true
+    },
     handler: async (args: any) => {
       const endpoint = TOOL_ENDPOINT_MAP['get_context_timeline'];
       return await callWorkerAPI(endpoint, args);
     }
   },
   {
-    name: 'progressive_description',
+    name: 'help',
-    description: 'Usage help',
+    description: 'Get detailed docs. All parameters optional - call get_schema("help") for details',
-    inputSchema: z.object({
+    inputSchema: {
-      topic: z.enum(['workflow', 'search_params', 'examples', 'all']).default('all')
+      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',
+    description: 'Fetch observation by ID',
-    inputSchema: z.object({
+    inputSchema: {
-      id: z.number()
+      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',
+    name: 'get_observations',
-    description: 'Batch fetch',
+    description: 'Batch fetch observations',
-    inputSchema: z.object({
+    inputSchema: {
-      ids: z.array(z.number()),
+      type: 'object',
-      orderBy: z.enum(['date_desc', 'date_asc']).optional(),
+      properties: {
-      limit: z.number().optional(),
+        ids: {
-      project: z.string().optional()
+          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',
+    description: 'Fetch session by ID',
-    inputSchema: z.object({
+    inputSchema: {
-      id: z.number()
+      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',
+    description: 'Fetch prompt by ID',
-    inputSchema: z.object({
+    inputSchema: {
-      id: z.number()
+      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

@@ -5,6 +5,7 @@ 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');
@@ -16,6 +17,7 @@ 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;
+const HTTP_SHUTDOWN_TIMEOUT_MS = 2000;
 
 interface PidInfo {
   pid: number;
@@ -43,8 +45,10 @@ export class ProcessManager {
     // Ensure log directory exists
     mkdirSync(LOG_DIR, { recursive: true });
 
-    // Get worker script path
+    // On Windows, use the wrapper script to solve zombie port problem
-    const workerScript = join(MARKETPLACE_ROOT, 'plugin', 'scripts', 'worker-service.cjs');
+    // 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}` };
@@ -86,6 +90,10 @@ export class ProcessManager {
         // 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
@@ -93,8 +101,9 @@ export class ProcessManager {
         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 -PassThru | Select-Object -ExpandProperty Id`;
+        const psCommand = `${envVars}; Start-Process -FilePath '${escapedBunPath}' -ArgumentList '${escapedScript}' -WorkingDirectory '${escapedWorkDir}' -WindowStyle Hidden -RedirectStandardOutput '${escapedLogFile}' -RedirectStandardError '${escapedLogFile}.err' -PassThru | Select-Object -ExpandProperty Id`;
 
         const result = spawnSync('powershell', ['-Command', psCommand], {
           stdio: 'pipe',
@@ -165,21 +174,65 @@ export class ProcessManager {
 
   static async stop(timeout: number = PROCESS_STOP_TIMEOUT_MS): Promise<boolean> {
     const info = this.getPidInfo();
-    if (!info) return true;
 
-    try {
+    if (process.platform === 'win32') {
-      process.kill(info.pid, 'SIGTERM');
+      // Windows: Try graceful HTTP shutdown first - this works regardless of PID file state
-      await this.waitForExit(info.pid, timeout);
+      // because the worker shuts itself down from the inside (via wrapper IPC)
-    } catch {
+      const port = info?.port ?? this.getPortFromSettings();
-      try {
+      const httpShutdownSucceeded = await this.tryHttpShutdown(port);
-        process.kill(info.pid, 'SIGKILL');
+
-      } catch {
+      if (httpShutdownSucceeded) {
-        // Process already dead
+        // HTTP shutdown succeeded - worker confirmed down, safe to remove PID file
+        this.removePidFile();
+        return true;
       }
-    }
 
-    this.removePidFile();
+      // HTTP shutdown failed (worker not responding), fall back to taskkill
-    return true;
+      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 }> {
@@ -210,6 +263,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(HTTP_SHUTDOWN_TIMEOUT_MS)
+      });
+
+      if (!response.ok) {
+        return false;
+      }
+
+      // Wait for worker to actually stop responding
+      return await this.waitForWorkerDown(port, PROCESS_STOP_TIMEOUT_MS);
+    } 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, PROCESS_EXIT_CHECK_INTERVAL_MS));
+      } catch {
+        // Worker stopped responding - success
+        return true;
+      }
+    }
+
+    // Timeout - worker still responding
+    return false;
+  }
+
   // Helper methods
   private static getPidInfo(): PidInfo | null {
     try {
@@ -252,29 +365,39 @@ export class ProcessManager {
 
   private static async waitForHealth(pid: number, port: number, timeoutMs: number = HEALTH_CHECK_TIMEOUT_MS): Promise<{ success: boolean; pid?: number; error?: string }> {
     const startTime = Date.now();
+    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`, {
+        const response = await fetch(`http://127.0.0.1:${port}/api/readiness`, {
           signal: AbortSignal.timeout(HEALTH_CHECK_FETCH_TIMEOUT_MS)
         });
         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));
     }
 
-    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> {

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
+        if (operation) {
-        const section = this.extractInstructionSection(fullContent, topic);
+          // 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
+    // Admin endpoints for process management (localhost-only)
-    this.app.post('/api/admin/restart', async (_req, res) => {
+    this.app.post('/api/admin/restart', requireLocalhost, async (_req, res) => {
       res.json({ status: 'restarting' });
-      setTimeout(async () => {
+
-        await this.shutdown();
+      // On Windows, if managed by wrapper, send message to parent to handle restart
-        process.exit(0);
+      // This solves the Windows zombie port problem where sockets aren't properly released
-      }, 100);
+      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();
+      // On Windows, if managed by wrapper, send message to parent to handle shutdown
-        process.exit(0);
+      const isWindowsManaged = process.platform === 'win32' &&
-      }, 100);
+        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 isWindows = process.platform === 'win32';
-      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 pids: number[] = [];
 
-      for (const line of lines) {
+      if (isWindows) {
-        const parts = line.trim().split(/\s+/);
+        // Windows: Use PowerShell Get-CimInstance to find chroma-mcp processes
-        if (parts.length > 1) {
+        const cmd = `powershell -Command "Get-CimInstance Win32_Process | Where-Object { $_.Name -like '*python*' -and $_.CommandLine -like '*chroma-mcp*' } | Select-Object -ExpandProperty ProcessId"`;
-          const pid = parseInt(parts[1], 10);
+        const { stdout } = await execAsync(cmd, { timeout: 5000 });
-          if (!isNaN(pid)) {
+
+        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,10 +458,19 @@ 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) {
@@ -399,12 +512,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 +547,102 @@ export class WorkerService {
       }
     }
 
-    // Close HTTP server
+    // STEP 5: Close database connection (includes ChromaSync cleanup)
-    if (this.server) {
-      await new Promise<void>((resolve, reject) => {
-        this.server!.close(err => err ? reject(err) : resolve());
-      });
-    }
-
-    // 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-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/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,8 +399,15 @@ export class SDKAgent {
       }
     }
 
-    // CRITICAL: Mark ALL pending messages as successfully processed
+    // Mark messages as processed after successful observation/summary storage
-    // This prevents message loss if worker crashes before SDK finishes
+    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) {

src/services/worker/http/middleware.ts

@@ -60,6 +60,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/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/worker-utils.ts

@@ -58,17 +58,18 @@ export function getWorkerHost(): string {
 }
 
 /**
- * Check if worker is responsive by trying the health endpoint
+ * 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/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 += `2. Run: claude-mem restart\n`;
-  message += `3. Navigate to: ${pluginDir}\n`;
+  message += `3. Restart Claude Code`;
-  message += `4. Run: npm run worker:restart\n`;
-  message += `5. Restart Claude Code`;
 
   if (includeSkillFallback) {
     message += `\n\nIf that doesn't work, try: /troubleshoot`;

src/utils/project-name.ts

@@ -0,0 +1,37 @@
+import path from 'path';
+import { logger } from './logger.js';
+
+/**
+ * Extract project name from working directory path
+ * Handles edge cases: null/undefined cwd, drive roots, trailing slashes
+ *
+ * @param cwd - Current working directory (absolute path)
+ * @returns Project name or "unknown-project" if extraction fails
+ */
+export function getProjectName(cwd: string | null | undefined): string {
+  if (!cwd || cwd.trim() === '') {
+    logger.warn('PROJECT_NAME', 'Empty cwd provided, using fallback', { cwd });
+    return 'unknown-project';
+  }
+
+  // Extract basename (handles trailing slashes automatically)
+  const basename = path.basename(cwd);
+
+  // Edge case: Drive roots on Windows (C:\, J:\) or Unix root (/)
+  // path.basename('C:\') returns '' (empty string)
+  if (basename === '') {
+    // Extract drive letter on Windows, or use 'root' on Unix
+    const isWindows = process.platform === 'win32';
+    if (isWindows && cwd.match(/^[A-Z]:\\/i)) {
+      const driveLetter = cwd[0].toUpperCase();
+      const projectName = `drive-${driveLetter}`;
+      logger.info('PROJECT_NAME', 'Drive root detected', { cwd, projectName });
+      return projectName;
+    } else {
+      logger.warn('PROJECT_NAME', 'Root directory detected, using fallback', { cwd });
+      return 'unknown-project';
+    }
+  }
+
+  return basename;
+}

tests/error-handling/hook-error-logging.test.ts

@@ -48,7 +48,7 @@ describe('Hook Error Logging', () => {
         handleFetchError(mockResponse, errorText, context);
       } catch (error: any) {
         expect(error.message).toContain('Failed Observation storage for Bash');
-        expect(error.message).toContain('npm run worker:restart');
+        expect(error.message).toContain('claude-mem restart');
       }
     });
 
@@ -119,7 +119,7 @@ describe('Hook Error Logging', () => {
 
       expect(() => {
         handleWorkerError(connError);
-      }).toThrow('npm run worker:restart');
+      }).toThrow('claude-mem restart');
     });
 
     it('re-throws non-connection errors unchanged', () => {
@@ -130,7 +130,7 @@ describe('Hook Error Logging', () => {
         expect.fail('Should have thrown');
       } catch (error: any) {
         expect(error.message).toBe('Something went wrong');
-        expect(error.message).not.toContain('npm run worker:restart');
+        expect(error.message).not.toContain('claude-mem restart');
       }
     });
 
@@ -227,7 +227,7 @@ describe('Hook Error Logging', () => {
         handleFetchError(mockResponse, 'error', context);
       } catch (error: any) {
         // Must include restart command
-        expect(error.message).toMatch(/npm run worker:restart/);
+        expect(error.message).toMatch(/claude-mem restart/);
 
         // Must be user-facing (no technical jargon)
         expect(error.message).not.toContain('ECONNREFUSED');