diff --git a/docs/public/troubleshooting.mdx b/docs/public/troubleshooting.mdx
index 826a77936..7bcbbd5f0 100644
--- a/docs/public/troubleshooting.mdx
+++ b/docs/public/troubleshooting.mdx
@@ -32,8 +32,8 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
 1. Check if worker is running on port 37777:
    ```bash
    lsof -i :37777
-   # or
-   npm run worker:status
+   # or (from any directory)
+   npx claude-mem status
    ```
 
 2. Verify worker is healthy:
@@ -43,19 +43,19 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
 
 3. Check worker logs for errors:
    ```bash
-   npm run worker:logs
+   npx claude-mem logs
    ```
 
 4. Restart worker service:
    ```bash
-   npm run worker:restart
+   npx 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
+   npx claude-mem restart
    ```
 
 ### Theme Toggle Not Persisting
@@ -101,7 +101,7 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
 
 3. Verify worker is running:
    ```bash
-   npm run worker:status
+   npx claude-mem status
    ```
 
 4. Check for network/proxy issues blocking SSE
@@ -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
+   npx claude-mem restart
    ```
 
 ### Chroma/Python Dependency Issues (v5.0.0+)
@@ -181,23 +181,23 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
 
 1. Check worker status:
    ```bash
-   npm run worker:status
+   npx claude-mem status
    ```
 
 2. Try starting manually:
    ```bash
-   npm run worker:start
+   npx claude-mem start
    ```
 
 3. Check worker logs for errors:
    ```bash
-   npm run worker:logs
+   npx claude-mem logs
    ```
 
 4. Full reset:
    ```bash
-   npm run worker:stop
-   npm run worker:start
+   npx claude-mem stop
+   npx claude-mem start
    ```
 
 5. Verify Bun is installed:
@@ -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
+   npx claude-mem restart
    ```
 
 4. Verify new port:
@@ -241,12 +241,12 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
 
 1. Check error logs:
    ```bash
-   npm run worker:logs
+   npx claude-mem logs
    ```
 
 2. Check worker status:
    ```bash
-   npm run worker:status
+   npx claude-mem status
    ```
 
 3. Check database for corruption:
@@ -267,12 +267,12 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
 
 1. Check worker is running:
    ```bash
-   npm run worker:status
+   npx claude-mem status
    ```
 
 2. Check worker logs:
    ```bash
-   npm run worker:logs
+   npx claude-mem logs
    ```
 
 3. Verify database has observations:
@@ -282,7 +282,7 @@ The skill includes comprehensive diagnostics, automated repair sequences, and de
 
 4. Restart worker:
    ```bash
-   npm run worker:restart
+   npx claude-mem restart
    ```
 
 ### Manual Recovery for Stuck Observations
@@ -385,7 +385,7 @@ Messages progress through these states:
 2. Use the CLI tool for interactive sessions (provides feedback)
 3. Use the HTTP API for automation/scripting
 4. Start with a low session limit (5-10) to avoid overwhelming the worker
-5. Monitor worker logs during recovery: `npm run worker:logs`
+5. Monitor worker logs during recovery: `npx claude-mem logs`
 6. Check recently processed messages to confirm recovery worked
 
 #### Troubleshooting Recovery Issues
@@ -430,7 +430,7 @@ If recovery fails or messages remain stuck:
 
 5. **Check worker logs for SDK errors**:
    ```bash
-   npm run worker:logs | grep -i error
+   npx claude-mem logs | grep -i error
    ```
 
 #### Understanding the Queue Table
@@ -550,7 +550,7 @@ sqlite3 ~/.claude-mem/claude-mem.db "
 
 2. Check worker is running (prevents timeout waiting for worker):
    ```bash
-   npm run worker:status
+   npx claude-mem status
    ```
 
 3. Check database size (large database = slow queries):
@@ -596,7 +596,7 @@ sqlite3 ~/.claude-mem/claude-mem.db "
 
 1. Close all connections:
    ```bash
-   npm run worker:stop
+   npx claude-mem stop
    ```
 
 2. Check for stale locks:
@@ -611,7 +611,7 @@ sqlite3 ~/.claude-mem/claude-mem.db "
 
 4. Restart worker:
    ```bash
-   npm run worker:start
+   npx claude-mem start
    ```
 
 ### Database Corruption
@@ -638,7 +638,7 @@ sqlite3 ~/.claude-mem/claude-mem.db "
 4. Nuclear option - recreate database:
    ```bash
    rm ~/.claude-mem/claude-mem.db
-   npm run worker:start  # Will recreate schema
+   npx claude-mem start  # Will recreate schema
    ```
 
 ### FTS5 Search Not Working
@@ -846,12 +846,12 @@ sqlite3 ~/.claude-mem/claude-mem.db "
 
 1. Check current usage:
    ```bash
-   npm run worker:status
+   npx claude-mem status
    ```
 
 2. Restart worker:
    ```bash
-   npm run worker:restart
+   npx claude-mem restart
    ```
 
 3. Clean up old data (see "Database Too Large" above)
@@ -928,8 +928,8 @@ sqlite3 ~/.claude-mem/claude-mem.db "
 
 ```bash
 export DEBUG=claude-mem:*
-npm run worker:restart
-npm run worker:logs
+npx claude-mem restart
+npx claude-mem logs
 ```
 
 ### Check Correlation IDs
@@ -949,10 +949,10 @@ sqlite3 ~/.claude-mem/claude-mem.db "
 
 ```bash
 # Check if worker is running
-npm run worker:status
+npx claude-mem status
 
 # View logs
-npm run worker:logs
+npx claude-mem logs
 
 # Check port file
 cat ~/.claude-mem/worker.port
@@ -988,7 +988,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 `npx claude-mem restart`.
 
 ### "Database is locked"
 
@@ -1020,7 +1020,7 @@ If none of these solutions work:
 
 1. **Check logs**:
    ```bash
-   npm run worker:logs
+   npx claude-mem logs
    ```
 
 2. **Create issue**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
diff --git a/openclaw/SKILL.md b/openclaw/SKILL.md
index 3cbc00b77..571b8747c 100644
--- a/openclaw/SKILL.md
+++ b/openclaw/SKILL.md
@@ -80,7 +80,7 @@ If claude-mem is installed as a Claude Code plugin (at `~/.claude/plugins/market
 
 ```bash
 cd ~/.claude/plugins/marketplaces/thedotmack
-npm run worker:restart
+npx claude-mem restart
 ```
 
 Verify:
@@ -90,7 +90,7 @@ curl http://localhost:37777/api/health
 
 **Got `{"status":"ok"}`?** You're set. Skip to Step 3.
 
-**Still not working?** Check `npm run worker:status` for error details, or check that bun is installed and on your PATH.
+**Still not working?** Check `npx claude-mem status` for error details, or check that bun is installed and on your PATH.
 
 #### If there's no Claude Code installation
 
@@ -98,7 +98,7 @@ Run the worker from the cloned repo:
 
 ```bash
 cd /opt/claude-mem  # wherever you cloned it
-npm run worker:start
+npx claude-mem start
 ```
 
 Verify:
@@ -110,9 +110,9 @@ curl http://localhost:37777/api/health
 
 **Still not working?** Debug steps:
 - Check that bun is installed: `bun --version`
-- Check the worker status: `npm run worker:status`
+- Check the worker status: `npx claude-mem status`
 - Check if something else is using port 37777: `lsof -i :37777`
-- Check logs: `npm run worker:logs` (if available)
+- Check logs: `npx claude-mem logs` (if available)
 - Try running it directly to see errors: `bun plugin/scripts/worker-service.cjs start`
 
 ### Step 3: Add the Plugin to Your Gateway
@@ -418,8 +418,8 @@ A background service connects to the worker's SSE stream and forwards `new_obser
 | Problem | What to check |
 |---------|---------------|
 | Worker health check fails | Is bun installed? (`bun --version`). Is something else on port 37777? (`lsof -i :37777`). Try running directly: `bun plugin/scripts/worker-service.cjs start` |
-| Worker started from Claude Code install but not responding | Check `cd ~/.claude/plugins/marketplaces/thedotmack && npm run worker:status`. May need `npm run worker:restart`. |
-| Worker started from cloned repo but not responding | Check `cd /path/to/claude-mem && npm run worker:status`. Make sure you ran `npm install && npm run build` first. |
+| Worker started from Claude Code install but not responding | Check `cd ~/.claude/plugins/marketplaces/thedotmack && npx claude-mem status`. May need `npx claude-mem restart`. |
+| Worker started from cloned repo but not responding | Check `cd /path/to/claude-mem && npx claude-mem status`. Make sure you ran `npm install && npm run build` first. |
 | No context in agent system prompt | Check that `syncMemoryFile` is not set to `false`. Check that the agent's ID is not in `syncMemoryFileExclude`. Verify the worker is running and has observations. |
 | Observations not being recorded | Check gateway logs for `[claude-mem]` messages. The worker must be running and reachable on localhost:37777. |
 | Feed shows `disconnected` | Worker's `/stream` endpoint not reachable. Check `workerPort` matches the actual worker port. |
diff --git a/package.json b/package.json
index e3d70cb38..7bb4ffb24 100644
--- a/package.json
+++ b/package.json
@@ -120,6 +120,7 @@
     "picocolors": "^1.1.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "tree-sitter": "^0.25.0",
     "yaml": "^2.8.2",
     "zod-to-json-schema": "^3.24.6"
   },
diff --git a/src/services/worker/BranchManager.ts b/src/services/worker/BranchManager.ts
index 4027af455..9781507ac 100644
--- a/src/services/worker/BranchManager.ts
+++ b/src/services/worker/BranchManager.ts
@@ -7,7 +7,8 @@
 
 import { execSync, spawnSync } from 'child_process';
 import { existsSync, unlinkSync } from 'fs';
-import { join } from 'path';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
 import { logger } from '../../utils/logger.js';
 import { MARKETPLACE_ROOT } from '../../shared/paths.js';
 
@@ -101,6 +102,27 @@ function execNpm(args: string[], timeoutMs: number = NPM_INSTALL_TIMEOUT_MS): st
   return result.stdout.trim();
 }
 
+/**
+ * Detect if the plugin was installed via Claude Code's cache layout
+ * (e.g., ~/.claude/plugins/cache/thedotmack/claude-mem/<version>/) rather than git clone.
+ *
+ * NOTE: INSTALLED_PLUGIN_PATH is an alias for MARKETPLACE_ROOT which always
+ * resolves to ~/.claude/plugins/marketplaces/thedotmack — it never contains
+ * '/cache/'. We must check the actual runtime module path instead.
+ */
+function isCacheLayoutInstall(): boolean {
+  // Derive the actual path this module is running from at runtime
+  let runtimeDir: string;
+  if (typeof __dirname !== 'undefined') {
+    runtimeDir = __dirname;
+  } else {
+    runtimeDir = dirname(fileURLToPath(import.meta.url));
+  }
+
+  const normalizedRuntimePath = runtimeDir.replace(/\\/g, '/');
+  return normalizedRuntimePath.includes('/cache/thedotmack/claude-mem/');
+}
+
 /**
  * Get current branch information
  */
@@ -108,13 +130,16 @@ export function getBranchInfo(): BranchInfo {
   // Check if git repo exists
   const gitDir = join(INSTALLED_PLUGIN_PATH, '.git');
   if (!existsSync(gitDir)) {
+    const isCacheLayout = isCacheLayoutInstall();
     return {
       branch: null,
       isBeta: false,
       isGitRepo: false,
       isDirty: false,
       canSwitch: false,
-      error: 'Installed plugin is not a git repository'
+      error: isCacheLayout
+        ? 'Plugin installed via cache layout. Use `npx claude-mem install` or Claude Code plugin UI to update.'
+        : 'Installed plugin is not a git repository'
     };
   }
 
@@ -262,7 +287,7 @@ export async function pullUpdates(): Promise<SwitchResult> {
   if (!info.isGitRepo || !info.branch) {
     return {
       success: false,
-      error: 'Cannot pull updates: not a git repository'
+      error: info.error || 'Cannot pull updates: not a git repository'
     };
   }
 
diff --git a/src/services/worker/http/routes/SettingsRoutes.ts b/src/services/worker/http/routes/SettingsRoutes.ts
index 66a5f2d60..ee1758f38 100644
--- a/src/services/worker/http/routes/SettingsRoutes.ts
+++ b/src/services/worker/http/routes/SettingsRoutes.ts
@@ -9,7 +9,7 @@ import express, { Request, Response } from 'express';
 import path from 'path';
 import { readFileSync, writeFileSync, existsSync, renameSync, mkdirSync } from 'fs';
 import { homedir } from 'os';
-import { getPackageRoot } from '../../../../shared/paths.js';
+import { getPackageRoot, MARKETPLACE_ROOT } from '../../../../shared/paths.js';
 import { logger } from '../../../../utils/logger.js';
 import { SettingsManager } from '../../SettingsManager.js';
 import { getBranchInfo, switchBranch, pullUpdates } from '../../BranchManager.js';
@@ -186,6 +186,15 @@ export class SettingsRoutes extends BaseRouteHandler {
       return;
     }
 
+    // Check if marketplace directory exists before attempting git operations
+    if (!existsSync(MARKETPLACE_ROOT)) {
+      res.json({
+        success: false,
+        error: 'Marketplace directory not found. This is a cache-only installation. Use `npx claude-mem install` to update.'
+      });
+      return;
+    }
+
     // Validate branch name
     const allowedBranches = ['main', 'beta/7.0', 'feature/bun-executable'];
     if (!allowedBranches.includes(branch)) {
@@ -217,6 +226,15 @@ export class SettingsRoutes extends BaseRouteHandler {
   private handleUpdateBranch = this.wrapHandler(async (req: Request, res: Response): Promise<void> => {
     logger.info('WORKER', 'Branch update requested');
 
+    // Check if marketplace directory exists before attempting git operations
+    if (!existsSync(MARKETPLACE_ROOT)) {
+      res.json({
+        success: false,
+        error: 'Marketplace directory not found. This is a cache-only installation. Use `npx claude-mem install` to update.'
+      });
+      return;
+    }
+
     const result = await pullUpdates();
 
     if (result.success) {