Merge remote-tracking branch 'origin/thedotmack/npx-gemini-cli' into thedotmack/npx-gemini-cli

Resolve merge conflicts in adapter index, gemini-cli adapter, and rebuilt CJS artifacts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.gitignore

@@ -1,7 +1,6 @@
 datasets/
 node_modules/
 dist/
-!installer/dist/
 **/_tree-sitter/
 *.log
 .DS_Store

.npmignore

@@ -0,0 +1,48 @@
+# Source code (dist/ and plugin/ are the shipped artifacts)
+src/
+scripts/
+tests/
+docs/
+datasets/
+private/
+antipattern-czar/
+
+# Heavy binaries installed at runtime via smart-install.js
+plugin/node_modules/
+plugin/scripts/claude-mem
+plugin/bun.lock
+plugin/data/
+plugin/data.backup/
+
+# Development files
+*.ts
+!*.d.ts
+tsconfig*.json
+.eslintrc*
+.prettierrc*
+.editorconfig
+jest.config*
+vitest.config*
+
+# Git and CI
+.git/
+.github/
+.gitignore
+.claude/
+.cursor/
+.mcp.json
+.plan/
+
+# OS files
+.DS_Store
+*.log
+*.tmp
+*.temp
+Thumbs.db
+
+# Misc
+Auto Run Docs/
+~*/
+http*/
+https*/
+.idea/

README.md

@@ -127,7 +127,19 @@
 
 ## Quick Start
 
-Start a new Claude Code session in the terminal and enter the following commands:
+Install with a single command:
+
+```bash
+npx claude-mem install
+```
+
+Or install for Gemini CLI (auto-detects `~/.gemini`):
+
+```bash
+npx claude-mem install --ide gemini-cli
+```
+
+Or install from the plugin marketplace inside Claude Code:
 
 ```
 /plugin marketplace add thedotmack/claude-mem
@@ -135,9 +147,9 @@ Start a new Claude Code session in the terminal and enter the following commands
 /plugin install claude-mem
 ```
 
-Restart Claude Code. Context from previous sessions will automatically appear in new sessions.
+Restart Claude Code or Gemini CLI. Context from previous sessions will automatically appear in new sessions.
 
-> **Note:** Claude-Mem is also published on npm, but `npm install -g claude-mem` installs the **SDK/library only** — it does not register the plugin hooks or set up the worker service. To use Claude-Mem as a plugin, always install via the `/plugin` commands above.
+> **Note:** Claude-Mem is also published on npm, but `npm install -g claude-mem` installs the **SDK/library only** — it does not register the plugin hooks or set up the worker service. Always install via `npx claude-mem install` or the `/plugin` commands above.
 
 ### 🦞 OpenClaw Gateway
 
@@ -171,6 +183,7 @@ The installer handles dependencies, plugin setup, AI provider configuration, wor
 ### Getting Started
 
 - **[Installation Guide](https://docs.claude-mem.ai/installation)** - Quick start & advanced installation
+- **[Gemini CLI Setup](https://docs.claude-mem.ai/gemini-cli/setup)** - Dedicated guide for Google's Gemini CLI integration
 - **[Usage Guide](https://docs.claude-mem.ai/usage/getting-started)** - How Claude-Mem works automatically
 - **[Search Tools](https://docs.claude-mem.ai/usage/search-tools)** - Query your project history with natural language
 - **[Beta Features](https://docs.claude-mem.ai/beta-features)** - Try experimental features like Endless Mode

docs/public/docs.json

@@ -57,6 +57,13 @@
           "cursor/openrouter-setup"
         ]
       },
+      {
+        "group": "Gemini CLI Integration",
+        "icon": "terminal",
+        "pages": [
+          "gemini-cli/setup"
+        ]
+      },
       {
         "group": "Best Practices",
         "icon": "lightbulb",

docs/public/gemini-cli/setup.mdx

@@ -0,0 +1,192 @@
+---
+title: "Gemini CLI Setup"
+description: "Add persistent memory to Gemini CLI with claude-mem"
+---
+
+# Gemini CLI Setup
+
+> **Give Gemini CLI persistent memory across sessions.**
+
+Gemini CLI starts every session from scratch. Claude-mem changes that by capturing observations, decisions, and patterns — then injecting relevant context into each new session.
+
+<Info>
+**How it works:** Claude-mem installs lifecycle hooks into Gemini CLI that capture tool usage, agent responses, and session events. A local worker service extracts semantic observations and injects relevant history at session start.
+</Info>
+
+## Prerequisites
+
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and configured
+- [Node.js](https://nodejs.org/) 18+
+- The `~/.gemini` directory must exist (created by Gemini CLI on first run)
+
+## Installation
+
+### Step 1: Install claude-mem
+
+```bash
+npx claude-mem install
+```
+
+The installer will:
+1. Auto-detect Gemini CLI (checks for `~/.gemini` directory)
+2. Prompt you to select **Gemini CLI** from the IDE picker
+3. Install 8 lifecycle hooks into `~/.gemini/settings.json`
+4. Inject context configuration into `~/.gemini/GEMINI.md`
+5. Start the worker service
+
+### Step 2: Configure an AI provider
+
+Claude-mem needs an AI provider to extract observations from your sessions. Choose one:
+
+<Tabs>
+  <Tab title="Gemini API (Free)">
+    The simplest option — use Gemini's own API for observation extraction:
+
+    1. Get a free API key from [Google AI Studio](https://aistudio.google.com/apikey)
+    2. Add it to your settings:
+
+    ```bash
+    mkdir -p ~/.claude-mem
+    cat > ~/.claude-mem/settings.json << 'EOF'
+    {
+      "CLAUDE_MEM_PROVIDER": "gemini",
+      "CLAUDE_MEM_GEMINI_API_KEY": "YOUR_API_KEY"
+    }
+    EOF
+    ```
+
+    <Tip>
+    **Free tier:** 1,500 requests/day with `gemini-2.5-flash-lite`. Enable billing on Google Cloud for 4,000 RPM without charges.
+    </Tip>
+  </Tab>
+  <Tab title="Claude SDK">
+    If you have a Claude API key:
+
+    ```bash
+    mkdir -p ~/.claude-mem
+    cat > ~/.claude-mem/settings.json << 'EOF'
+    {
+      "CLAUDE_MEM_PROVIDER": "claude"
+    }
+    EOF
+    ```
+
+    Set your API key via environment variable:
+    ```bash
+    export ANTHROPIC_API_KEY="your-key"
+    ```
+  </Tab>
+  <Tab title="OpenRouter">
+    For access to 100+ models:
+
+    ```bash
+    mkdir -p ~/.claude-mem
+    cat > ~/.claude-mem/settings.json << 'EOF'
+    {
+      "CLAUDE_MEM_PROVIDER": "openrouter",
+      "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_KEY"
+    }
+    EOF
+    ```
+  </Tab>
+</Tabs>
+
+### Step 3: Verify installation
+
+```bash
+# Check worker is running
+npx claude-mem status
+
+# Check hooks are installed — look for claude-mem entries
+cat ~/.gemini/settings.json | grep claude-mem
+```
+
+Open http://localhost:37777 to see the memory viewer.
+
+### Step 4: Start using Gemini CLI
+
+Launch Gemini CLI normally. Claude-mem works in the background:
+
+```bash
+gemini
+```
+
+On session start, you'll see claude-mem context injected with your recent observations and project history.
+
+## What gets captured
+
+Claude-mem registers 8 of Gemini CLI's 11 lifecycle hooks:
+
+| Hook | Purpose |
+|------|---------|
+| **SessionStart** | Injects memory context into the session |
+| **SessionEnd** | Marks session complete, triggers summary |
+| **PreCompress** | Captures session summary before compression |
+| **Notification** | Records system events (permissions, etc.) |
+| **BeforeAgent** | Captures user prompts |
+| **AfterAgent** | Records full agent responses |
+| **BeforeTool** | Logs tool invocations before execution |
+| **AfterTool** | Captures tool results after execution |
+
+Three model-level hooks (BeforeModel, AfterModel, BeforeToolSelection) are intentionally skipped — they fire per-LLM-call and are too noisy for memory capture.
+
+## Troubleshooting
+
+### Hooks not firing
+
+1. Verify hooks exist in settings:
+   ```bash
+   cat ~/.gemini/settings.json
+   ```
+   You should see entries like `"SessionStart"`, `"AfterTool"`, etc. with claude-mem commands.
+
+2. Restart Gemini CLI after installation.
+
+3. Re-run the installer:
+   ```bash
+   npx claude-mem install
+   ```
+
+### Worker not running
+
+```bash
+# Check status
+npx claude-mem status
+
+# View logs
+npx claude-mem logs
+
+# Restart worker
+npx claude-mem restart
+```
+
+### No context appearing at session start
+
+1. Ensure the worker is running (check http://localhost:37777)
+2. You need at least one previous session with observations for context to appear
+3. Check your AI provider is configured in `~/.claude-mem/settings.json`
+
+### Raw escape codes in output
+
+If you see characters like `[31m` or `[0m` in the session context, your claude-mem version may need updating:
+
+```bash
+npx claude-mem install
+```
+
+This was fixed in v10.6.3+ — the Gemini CLI adapter now strips ANSI color codes automatically.
+
+## Uninstalling
+
+```bash
+npx claude-mem uninstall
+```
+
+This removes hooks from `~/.gemini/settings.json` and cleans up `~/.gemini/GEMINI.md`.
+
+## Next Steps
+
+- [Gemini Provider](/usage/gemini-provider) — Configure the Gemini AI provider for observation extraction
+- [Configuration](/configuration) — All settings options
+- [Search Tools](/usage/search-tools) — Search your memory from within sessions
+- [Troubleshooting](/troubleshooting) — Common issues and solutions

docs/public/installation.mdx

@@ -7,24 +7,35 @@ description: "Install Claude-Mem plugin for persistent memory across sessions"
 
 ## Quick Start
 
-Install Claude-Mem directly from the plugin marketplace:
+### Option 1: npx (Recommended)
+
+Install and configure Claude-Mem with a single command:
+
+```bash
+npx claude-mem install
+```
+
+The interactive installer will:
+- Detect your installed IDEs (Claude Code, Cursor, Gemini CLI, Windsurf, etc.)
+- Copy plugin files to the correct locations
+- Register the plugin with Claude Code
+- Install all dependencies (including Bun and uv)
+- Auto-start the worker service
+
+### Option 2: Plugin Marketplace
+
+Install Claude-Mem directly from the plugin marketplace inside Claude Code:
 
 ```bash
 /plugin marketplace add thedotmack/claude-mem
 /plugin install claude-mem
 ```
 
-That's it! The plugin will automatically:
+Both methods will automatically configure hooks and start the worker service. Start a new Claude Code session and you'll see context from previous sessions automatically loaded.
-- Download prebuilt binaries (no compilation needed)
-- Install all dependencies (including SQLite binaries)
-- Configure hooks for session lifecycle management
-- Auto-start the worker service on first session
-
-Start a new Claude Code session and you'll see context from previous sessions automatically loaded.
 
 > **Important:** Claude-Mem is published on npm, but running `npm install -g claude-mem` installs the
 > **SDK/library only**. It does **not** register plugin hooks or start the worker service.
-> To use Claude-Mem as a persistent memory plugin, always install via the `/plugin` commands above.
+> Always install via `npx claude-mem install` or the `/plugin` commands above.
 
 ## System Requirements
 

docs/public/introduction.mdx

@@ -11,7 +11,13 @@ Claude-Mem seamlessly preserves context across sessions by automatically capturi
 
 ## Quick Start
 
-Start a new Claude Code session in the terminal and enter the following commands:
+Install with a single command:
+
+```bash
+npx claude-mem install
+```
+
+Or install from the plugin marketplace inside Claude Code:
 
 ```bash
 /plugin marketplace add thedotmack/claude-mem

install/public/install.sh

@@ -1,59 +1,25 @@
 #!/bin/bash
 set -euo pipefail
 
-# claude-mem installer bootstrap
+# claude-mem installer redirect
-# Usage: curl -fsSL https://install.cmem.ai | bash
+# The old curl-pipe-bash installer has been replaced by npx claude-mem.
-#   or:  curl -fsSL https://install.cmem.ai | bash -s -- --provider=gemini --api-key=YOUR_KEY
+# This script now redirects users to the new install method.
-
-INSTALLER_URL="https://install.cmem.ai/installer.js"
 
 # Colors
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 CYAN='\033[0;36m'
+YELLOW='\033[0;33m'
 NC='\033[0m' # No Color
 
-error() { echo -e "${RED}Error: $1${NC}" >&2; exit 1; }
+echo ""
-info() { echo -e "${CYAN}$1${NC}"; }
+echo -e "${YELLOW}The curl-pipe-bash installer has been replaced.${NC}"
-
+echo ""
-# Check Node.js
+echo -e "${GREEN}Install claude-mem with a single command:${NC}"
-if ! command -v node &> /dev/null; then
+echo ""
-  error "Node.js is required but not found. Install from https://nodejs.org"
+echo -e "  ${CYAN}npx claude-mem install${NC}"
-fi
+echo ""
-
+echo -e "This requires Node.js >= 18. Get it from ${CYAN}https://nodejs.org${NC}"
-NODE_VERSION=$(node -v | sed 's/v//')
+echo ""
-NODE_MAJOR=$(echo "$NODE_VERSION" | cut -d. -f1)
+echo -e "For more info, visit: ${CYAN}https://docs.claude-mem.ai/installation${NC}"
-if [ "$NODE_MAJOR" -lt 18 ]; then
+echo ""
-  error "Node.js >= 18 required. Current: v${NODE_VERSION}"
-fi
-
-info "claude-mem installer (Node.js v${NODE_VERSION})"
-
-# Create temp file for installer
-TMPFILE=$(mktemp "${TMPDIR:-/tmp}/claude-mem-installer.XXXXXX.mjs")
-
-# Cleanup on exit
-cleanup() {
-  rm -f "$TMPFILE"
-}
-trap cleanup EXIT INT TERM
-
-# Download installer
-info "Downloading installer..."
-if command -v curl &> /dev/null; then
-  curl -fsSL "$INSTALLER_URL" -o "$TMPFILE"
-elif command -v wget &> /dev/null; then
-  wget -q "$INSTALLER_URL" -O "$TMPFILE"
-else
-  error "curl or wget required to download installer"
-fi
-
-# Run installer with TTY access
-# When piped (curl | bash), stdin is the script. We need to reconnect to the terminal.
-if [ -t 0 ]; then
-  # Already have TTY (script was downloaded and run directly)
-  node "$TMPFILE" "$@"
-else
-  # Piped execution -- reconnect stdin to terminal
-  node "$TMPFILE" "$@" </dev/tty
-fi

installer/build.mjs

@@ -1,16 +0,0 @@
-import { build } from 'esbuild';
-
-await build({
-  entryPoints: ['src/index.ts'],
-  bundle: true,
-  format: 'esm',
-  platform: 'node',
-  target: 'node18',
-  outfile: 'dist/index.js',
-  banner: {
-    js: '#!/usr/bin/env node',
-  },
-  external: [],
-});
-
-console.log('Build complete: dist/index.js');

installer/package.json

@@ -1,21 +0,0 @@
-{
-  "name": "claude-mem-installer",
-  "version": "1.0.0",
-  "type": "module",
-  "bin": { "claude-mem-installer": "./dist/index.js" },
-  "files": ["dist"],
-  "scripts": {
-    "build": "node build.mjs",
-    "dev": "node build.mjs && node dist/index.js"
-  },
-  "dependencies": {
-    "@clack/prompts": "^1.0.1",
-    "picocolors": "^1.1.1"
-  },
-  "devDependencies": {
-    "esbuild": "^0.24.0",
-    "typescript": "^5.7.0",
-    "@types/node": "^22.0.0"
-  },
-  "engines": { "node": ">=18.0.0" }
-}

installer/src/index.ts

@@ -1,49 +0,0 @@
-import * as p from '@clack/prompts';
-import { runWelcome } from './steps/welcome.js';
-import { runDependencyChecks } from './steps/dependencies.js';
-import { runIdeSelection } from './steps/ide-selection.js';
-import { runProviderConfiguration } from './steps/provider.js';
-import { runSettingsConfiguration } from './steps/settings.js';
-import { writeSettings } from './utils/settings-writer.js';
-import { runInstallation } from './steps/install.js';
-import { runWorkerStartup } from './steps/worker.js';
-import { runCompletion } from './steps/complete.js';
-
-async function runInstaller(): Promise<void> {
-  if (!process.stdin.isTTY) {
-    console.error('Error: This installer requires an interactive terminal.');
-    console.error('Run directly: npx claude-mem-installer');
-    process.exit(1);
-  }
-
-  const installMode = await runWelcome();
-
-  // Dependency checks (all modes)
-  await runDependencyChecks();
-
-  // IDE and provider selection
-  const selectedIDEs = await runIdeSelection();
-  const providerConfig = await runProviderConfiguration();
-
-  // Settings configuration
-  const settingsConfig = await runSettingsConfiguration();
-
-  // Write settings file
-  writeSettings(providerConfig, settingsConfig);
-  p.log.success('Settings saved.');
-
-  // Installation (fresh or upgrade)
-  if (installMode !== 'configure') {
-    await runInstallation(selectedIDEs);
-    await runWorkerStartup(settingsConfig.workerPort, settingsConfig.dataDir);
-  }
-
-  // Completion summary
-  runCompletion(providerConfig, settingsConfig, selectedIDEs);
-}
-
-runInstaller().catch((error) => {
-  p.cancel('Installation failed.');
-  console.error(error);
-  process.exit(1);
-});

installer/src/steps/complete.ts

@@ -1,56 +0,0 @@
-import * as p from '@clack/prompts';
-import pc from 'picocolors';
-import type { ProviderConfig } from './provider.js';
-import type { SettingsConfig } from './settings.js';
-import type { IDE } from './ide-selection.js';
-
-function getProviderLabel(config: ProviderConfig): string {
-  switch (config.provider) {
-    case 'claude':
-      return config.claudeAuthMethod === 'api' ? 'Claude (API Key)' : 'Claude (CLI subscription)';
-    case 'gemini':
-      return `Gemini (${config.model ?? 'gemini-2.5-flash-lite'})`;
-    case 'openrouter':
-      return `OpenRouter (${config.model ?? 'xiaomi/mimo-v2-flash:free'})`;
-  }
-}
-
-function getIDELabels(ides: IDE[]): string {
-  return ides.map((ide) => {
-    switch (ide) {
-      case 'claude-code': return 'Claude Code';
-      case 'cursor': return 'Cursor';
-    }
-  }).join(', ');
-}
-
-export function runCompletion(
-  providerConfig: ProviderConfig,
-  settingsConfig: SettingsConfig,
-  selectedIDEs: IDE[],
-): void {
-  const summaryLines = [
-    `Provider:   ${pc.cyan(getProviderLabel(providerConfig))}`,
-    `IDEs:       ${pc.cyan(getIDELabels(selectedIDEs))}`,
-    `Data dir:   ${pc.cyan(settingsConfig.dataDir)}`,
-    `Port:       ${pc.cyan(settingsConfig.workerPort)}`,
-    `Chroma:     ${settingsConfig.chromaEnabled ? pc.green('enabled') : pc.dim('disabled')}`,
-  ];
-
-  p.note(summaryLines.join('\n'), 'Configuration Summary');
-
-  const nextStepsLines: string[] = [];
-
-  if (selectedIDEs.includes('claude-code')) {
-    nextStepsLines.push('Open Claude Code and start a conversation — memory is automatic!');
-  }
-  if (selectedIDEs.includes('cursor')) {
-    nextStepsLines.push('Open Cursor — hooks are active in your projects.');
-  }
-  nextStepsLines.push(`View your memories: ${pc.underline(`http://localhost:${settingsConfig.workerPort}`)}`);
-  nextStepsLines.push(`Search past work: use ${pc.bold('/mem-search')} in Claude Code`);
-
-  p.note(nextStepsLines.join('\n'), 'Next Steps');
-
-  p.outro(pc.green('claude-mem installed successfully!'));
-}

installer/src/steps/dependencies.ts

@@ -1,168 +0,0 @@
-import * as p from '@clack/prompts';
-import pc from 'picocolors';
-import { findBinary, compareVersions, installBun, installUv } from '../utils/dependencies.js';
-import { detectOS } from '../utils/system.js';
-
-const BUN_EXTRA_PATHS = ['~/.bun/bin/bun', '/usr/local/bin/bun', '/opt/homebrew/bin/bun'];
-const UV_EXTRA_PATHS = ['~/.local/bin/uv', '~/.cargo/bin/uv'];
-
-interface DependencyStatus {
-  nodeOk: boolean;
-  gitOk: boolean;
-  bunOk: boolean;
-  uvOk: boolean;
-  bunPath: string | null;
-  uvPath: string | null;
-}
-
-export async function runDependencyChecks(): Promise<DependencyStatus> {
-  const status: DependencyStatus = {
-    nodeOk: false,
-    gitOk: false,
-    bunOk: false,
-    uvOk: false,
-    bunPath: null,
-    uvPath: null,
-  };
-
-  await p.tasks([
-    {
-      title: 'Checking Node.js',
-      task: async () => {
-        const version = process.version.slice(1); // remove 'v'
-        if (compareVersions(version, '18.0.0')) {
-          status.nodeOk = true;
-          return `Node.js ${process.version} ${pc.green('✓')}`;
-        }
-        return `Node.js ${process.version} — requires >= 18.0.0 ${pc.red('✗')}`;
-      },
-    },
-    {
-      title: 'Checking git',
-      task: async () => {
-        const info = findBinary('git');
-        if (info.found) {
-          status.gitOk = true;
-          return `git ${info.version ?? ''} ${pc.green('✓')}`;
-        }
-        return `git not found ${pc.red('✗')}`;
-      },
-    },
-    {
-      title: 'Checking Bun',
-      task: async () => {
-        const info = findBinary('bun', BUN_EXTRA_PATHS);
-        if (info.found && info.version && compareVersions(info.version, '1.1.14')) {
-          status.bunOk = true;
-          status.bunPath = info.path;
-          return `Bun ${info.version} ${pc.green('✓')}`;
-        }
-        if (info.found && info.version) {
-          return `Bun ${info.version} — requires >= 1.1.14 ${pc.yellow('⚠')}`;
-        }
-        return `Bun not found ${pc.yellow('⚠')}`;
-      },
-    },
-    {
-      title: 'Checking uv',
-      task: async () => {
-        const info = findBinary('uv', UV_EXTRA_PATHS);
-        if (info.found) {
-          status.uvOk = true;
-          status.uvPath = info.path;
-          return `uv ${info.version ?? ''} ${pc.green('✓')}`;
-        }
-        return `uv not found ${pc.yellow('⚠')}`;
-      },
-    },
-  ]);
-
-  // Handle missing dependencies
-  if (!status.gitOk) {
-    const os = detectOS();
-    p.log.error('git is required but not found.');
-    if (os === 'macos') {
-      p.log.info('Install with: xcode-select --install');
-    } else if (os === 'linux') {
-      p.log.info('Install with: sudo apt install git (or your distro equivalent)');
-    } else {
-      p.log.info('Download from: https://git-scm.com/downloads');
-    }
-    p.cancel('Please install git and try again.');
-    process.exit(1);
-  }
-
-  if (!status.nodeOk) {
-    p.log.error(`Node.js >= 18.0.0 is required. Current: ${process.version}`);
-    p.cancel('Please upgrade Node.js and try again.');
-    process.exit(1);
-  }
-
-  if (!status.bunOk) {
-    const shouldInstall = await p.confirm({
-      message: 'Bun is required but not found. Install it now?',
-      initialValue: true,
-    });
-
-    if (p.isCancel(shouldInstall)) {
-      p.cancel('Installation cancelled.');
-      process.exit(0);
-    }
-
-    if (shouldInstall) {
-      const s = p.spinner();
-      s.start('Installing Bun...');
-      try {
-        installBun();
-        const recheck = findBinary('bun', BUN_EXTRA_PATHS);
-        if (recheck.found) {
-          status.bunOk = true;
-          status.bunPath = recheck.path;
-          s.stop(`Bun installed ${pc.green('✓')}`);
-        } else {
-          s.stop(`Bun installed but not found in PATH. You may need to restart your shell.`);
-        }
-      } catch {
-        s.stop(`Bun installation failed. Install manually: curl -fsSL https://bun.sh/install | bash`);
-      }
-    } else {
-      p.log.warn('Bun is required for claude-mem. Install manually: curl -fsSL https://bun.sh/install | bash');
-      p.cancel('Cannot continue without Bun.');
-      process.exit(1);
-    }
-  }
-
-  if (!status.uvOk) {
-    const shouldInstall = await p.confirm({
-      message: 'uv (Python package manager) is recommended for Chroma. Install it now?',
-      initialValue: true,
-    });
-
-    if (p.isCancel(shouldInstall)) {
-      p.cancel('Installation cancelled.');
-      process.exit(0);
-    }
-
-    if (shouldInstall) {
-      const s = p.spinner();
-      s.start('Installing uv...');
-      try {
-        installUv();
-        const recheck = findBinary('uv', UV_EXTRA_PATHS);
-        if (recheck.found) {
-          status.uvOk = true;
-          status.uvPath = recheck.path;
-          s.stop(`uv installed ${pc.green('✓')}`);
-        } else {
-          s.stop('uv installed but not found in PATH. You may need to restart your shell.');
-        }
-      } catch {
-        s.stop('uv installation failed. Install manually: curl -fsSL https://astral.sh/uv/install.sh | sh');
-      }
-    } else {
-      p.log.warn('Skipping uv — Chroma vector search will not be available.');
-    }
-  }
-
-  return status;
-}

installer/src/steps/ide-selection.ts

@@ -1,32 +0,0 @@
-import * as p from '@clack/prompts';
-
-export type IDE = 'claude-code' | 'cursor';
-
-export async function runIdeSelection(): Promise<IDE[]> {
-  const result = await p.multiselect({
-    message: 'Which IDEs do you use?',
-    options: [
-      { value: 'claude-code' as const, label: 'Claude Code', hint: 'recommended' },
-      { value: 'cursor' as const, label: 'Cursor' },
-      // Windsurf coming soon - not yet selectable
-    ],
-    initialValues: ['claude-code'],
-    required: true,
-  });
-
-  if (p.isCancel(result)) {
-    p.cancel('Installation cancelled.');
-    process.exit(0);
-  }
-
-  const selectedIDEs = result as IDE[];
-
-  if (selectedIDEs.includes('claude-code')) {
-    p.log.info('Claude Code: Plugin will be registered via marketplace.');
-  }
-  if (selectedIDEs.includes('cursor')) {
-    p.log.info('Cursor: Hooks will be configured for your projects.');
-  }
-
-  return selectedIDEs;
-}

installer/src/steps/install.ts

@@ -1,167 +0,0 @@
-import * as p from '@clack/prompts';
-import pc from 'picocolors';
-import { execSync } from 'child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } from 'fs';
-import { join } from 'path';
-import { homedir, tmpdir } from 'os';
-import type { IDE } from './ide-selection.js';
-
-const MARKETPLACE_DIR = join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');
-const PLUGINS_DIR = join(homedir(), '.claude', 'plugins');
-const CLAUDE_SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
-
-function ensureDir(directoryPath: string): void {
-  if (!existsSync(directoryPath)) {
-    mkdirSync(directoryPath, { recursive: true });
-  }
-}
-
-function readJsonFile(filepath: string): any {
-  if (!existsSync(filepath)) return {};
-  return JSON.parse(readFileSync(filepath, 'utf-8'));
-}
-
-function writeJsonFile(filepath: string, data: any): void {
-  ensureDir(join(filepath, '..'));
-  writeFileSync(filepath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
-}
-
-function registerMarketplace(): void {
-  const knownMarketplacesPath = join(PLUGINS_DIR, 'known_marketplaces.json');
-  const knownMarketplaces = readJsonFile(knownMarketplacesPath);
-
-  knownMarketplaces['thedotmack'] = {
-    source: {
-      source: 'github',
-      repo: 'thedotmack/claude-mem',
-    },
-    installLocation: MARKETPLACE_DIR,
-    lastUpdated: new Date().toISOString(),
-    autoUpdate: true,
-  };
-
-  ensureDir(PLUGINS_DIR);
-  writeJsonFile(knownMarketplacesPath, knownMarketplaces);
-}
-
-function registerPlugin(version: string): void {
-  const installedPluginsPath = join(PLUGINS_DIR, 'installed_plugins.json');
-  const installedPlugins = readJsonFile(installedPluginsPath);
-
-  if (!installedPlugins.version) installedPlugins.version = 2;
-  if (!installedPlugins.plugins) installedPlugins.plugins = {};
-
-  const pluginCachePath = join(PLUGINS_DIR, 'cache', 'thedotmack', 'claude-mem', version);
-  const now = new Date().toISOString();
-
-  installedPlugins.plugins['claude-mem@thedotmack'] = [
-    {
-      scope: 'user',
-      installPath: pluginCachePath,
-      version,
-      installedAt: now,
-      lastUpdated: now,
-    },
-  ];
-
-  writeJsonFile(installedPluginsPath, installedPlugins);
-
-  // Copy built plugin to cache directory
-  ensureDir(pluginCachePath);
-  const pluginSourceDir = join(MARKETPLACE_DIR, 'plugin');
-  if (existsSync(pluginSourceDir)) {
-    cpSync(pluginSourceDir, pluginCachePath, { recursive: true });
-  }
-}
-
-function enablePluginInClaudeSettings(): void {
-  const settings = readJsonFile(CLAUDE_SETTINGS_PATH);
-
-  if (!settings.enabledPlugins) settings.enabledPlugins = {};
-  settings.enabledPlugins['claude-mem@thedotmack'] = true;
-
-  writeJsonFile(CLAUDE_SETTINGS_PATH, settings);
-}
-
-function getPluginVersion(): string {
-  const pluginJsonPath = join(MARKETPLACE_DIR, 'plugin', '.claude-plugin', 'plugin.json');
-  if (existsSync(pluginJsonPath)) {
-    const pluginJson = JSON.parse(readFileSync(pluginJsonPath, 'utf-8'));
-    return pluginJson.version ?? '1.0.0';
-  }
-  return '1.0.0';
-}
-
-export async function runInstallation(selectedIDEs: IDE[]): Promise<void> {
-  const tempDir = join(tmpdir(), `claude-mem-install-${Date.now()}`);
-
-  await p.tasks([
-    {
-      title: 'Cloning claude-mem repository',
-      task: async (message) => {
-        message('Downloading latest release...');
-        execSync(
-          `git clone --depth 1 https://github.com/thedotmack/claude-mem.git "${tempDir}"`,
-          { stdio: 'pipe' },
-        );
-        return `Repository cloned ${pc.green('OK')}`;
-      },
-    },
-    {
-      title: 'Installing dependencies',
-      task: async (message) => {
-        message('Running npm install...');
-        execSync('npm install', { cwd: tempDir, stdio: 'pipe' });
-        return `Dependencies installed ${pc.green('OK')}`;
-      },
-    },
-    {
-      title: 'Building plugin',
-      task: async (message) => {
-        message('Compiling TypeScript and bundling...');
-        execSync('npm run build', { cwd: tempDir, stdio: 'pipe' });
-        return `Plugin built ${pc.green('OK')}`;
-      },
-    },
-    {
-      title: 'Registering plugin',
-      task: async (message) => {
-        message('Copying files to marketplace directory...');
-        ensureDir(MARKETPLACE_DIR);
-
-        // Sync from cloned repo to marketplace dir, excluding .git and lock files
-        execSync(
-          `rsync -a --delete --exclude=.git --exclude=package-lock.json --exclude=bun.lock "${tempDir}/" "${MARKETPLACE_DIR}/"`,
-          { stdio: 'pipe' },
-        );
-
-        message('Registering marketplace...');
-        registerMarketplace();
-
-        message('Installing marketplace dependencies...');
-        execSync('npm install', { cwd: MARKETPLACE_DIR, stdio: 'pipe' });
-
-        message('Registering plugin in Claude Code...');
-        const version = getPluginVersion();
-        registerPlugin(version);
-
-        message('Enabling plugin...');
-        enablePluginInClaudeSettings();
-
-        return `Plugin registered (v${getPluginVersion()}) ${pc.green('OK')}`;
-      },
-    },
-  ]);
-
-  // Cleanup temp directory (non-critical if it fails)
-  try {
-    execSync(`rm -rf "${tempDir}"`, { stdio: 'pipe' });
-  } catch {
-    // Temp dir will be cleaned by OS eventually
-  }
-
-  if (selectedIDEs.includes('cursor')) {
-    p.log.info('Cursor hook configuration will be available after first launch.');
-    p.log.info('Run: claude-mem cursor-setup (coming soon)');
-  }
-}

installer/src/steps/provider.ts

@@ -1,140 +0,0 @@
-import * as p from '@clack/prompts';
-import pc from 'picocolors';
-
-export type ProviderType = 'claude' | 'gemini' | 'openrouter';
-export type ClaudeAuthMethod = 'cli' | 'api';
-
-export interface ProviderConfig {
-  provider: ProviderType;
-  claudeAuthMethod?: ClaudeAuthMethod;
-  apiKey?: string;
-  model?: string;
-  rateLimitingEnabled?: boolean;
-}
-
-export async function runProviderConfiguration(): Promise<ProviderConfig> {
-  const provider = await p.select({
-    message: 'Which AI provider should claude-mem use for memory compression?',
-    options: [
-      { value: 'claude' as const, label: 'Claude', hint: 'uses your Claude subscription' },
-      { value: 'gemini' as const, label: 'Gemini', hint: 'free tier available' },
-      { value: 'openrouter' as const, label: 'OpenRouter', hint: 'free models available' },
-    ],
-  });
-
-  if (p.isCancel(provider)) {
-    p.cancel('Installation cancelled.');
-    process.exit(0);
-  }
-
-  const config: ProviderConfig = { provider };
-
-  if (provider === 'claude') {
-    const authMethod = await p.select({
-      message: 'How should Claude authenticate?',
-      options: [
-        { value: 'cli' as const, label: 'CLI (Max Plan subscription)', hint: 'no API key needed' },
-        { value: 'api' as const, label: 'API Key', hint: 'uses Anthropic API credits' },
-      ],
-    });
-
-    if (p.isCancel(authMethod)) {
-      p.cancel('Installation cancelled.');
-      process.exit(0);
-    }
-
-    config.claudeAuthMethod = authMethod;
-
-    if (authMethod === 'api') {
-      const apiKey = await p.password({
-        message: 'Enter your Anthropic API key:',
-        validate: (value) => {
-          if (!value || value.trim().length === 0) return 'API key is required';
-          if (!value.startsWith('sk-ant-')) return 'Anthropic API keys start with sk-ant-';
-        },
-      });
-
-      if (p.isCancel(apiKey)) {
-        p.cancel('Installation cancelled.');
-        process.exit(0);
-      }
-
-      config.apiKey = apiKey;
-    }
-  }
-
-  if (provider === 'gemini') {
-    const apiKey = await p.password({
-      message: 'Enter your Gemini API key:',
-      validate: (value) => {
-        if (!value || value.trim().length === 0) return 'API key is required';
-      },
-    });
-
-    if (p.isCancel(apiKey)) {
-      p.cancel('Installation cancelled.');
-      process.exit(0);
-    }
-
-    config.apiKey = apiKey;
-
-    const model = await p.select({
-      message: 'Which Gemini model?',
-      options: [
-        { value: 'gemini-2.5-flash-lite' as const, label: 'Gemini 2.5 Flash Lite', hint: 'fastest, highest free RPM' },
-        { value: 'gemini-2.5-flash' as const, label: 'Gemini 2.5 Flash', hint: 'balanced' },
-        { value: 'gemini-3-flash-preview' as const, label: 'Gemini 3 Flash Preview', hint: 'latest' },
-      ],
-    });
-
-    if (p.isCancel(model)) {
-      p.cancel('Installation cancelled.');
-      process.exit(0);
-    }
-
-    config.model = model;
-
-    const rateLimiting = await p.confirm({
-      message: 'Enable rate limiting? (recommended for free tier)',
-      initialValue: true,
-    });
-
-    if (p.isCancel(rateLimiting)) {
-      p.cancel('Installation cancelled.');
-      process.exit(0);
-    }
-
-    config.rateLimitingEnabled = rateLimiting;
-  }
-
-  if (provider === 'openrouter') {
-    const apiKey = await p.password({
-      message: 'Enter your OpenRouter API key:',
-      validate: (value) => {
-        if (!value || value.trim().length === 0) return 'API key is required';
-      },
-    });
-
-    if (p.isCancel(apiKey)) {
-      p.cancel('Installation cancelled.');
-      process.exit(0);
-    }
-
-    config.apiKey = apiKey;
-
-    const model = await p.text({
-      message: 'Which OpenRouter model?',
-      defaultValue: 'xiaomi/mimo-v2-flash:free',
-      placeholder: 'xiaomi/mimo-v2-flash:free',
-    });
-
-    if (p.isCancel(model)) {
-      p.cancel('Installation cancelled.');
-      process.exit(0);
-    }
-
-    config.model = model;
-  }
-
-  return config;
-}

installer/src/steps/settings.ts

@@ -1,174 +0,0 @@
-import * as p from '@clack/prompts';
-import pc from 'picocolors';
-
-export interface SettingsConfig {
-  workerPort: string;
-  dataDir: string;
-  contextObservations: string;
-  logLevel: string;
-  pythonVersion: string;
-  chromaEnabled: boolean;
-  chromaMode?: 'local' | 'remote';
-  chromaHost?: string;
-  chromaPort?: string;
-  chromaSsl?: boolean;
-}
-
-export async function runSettingsConfiguration(): Promise<SettingsConfig> {
-  const useDefaults = await p.confirm({
-    message: 'Use default settings? (recommended for most users)',
-    initialValue: true,
-  });
-
-  if (p.isCancel(useDefaults)) {
-    p.cancel('Installation cancelled.');
-    process.exit(0);
-  }
-
-  if (useDefaults) {
-    return {
-      workerPort: '37777',
-      dataDir: '~/.claude-mem',
-      contextObservations: '50',
-      logLevel: 'INFO',
-      pythonVersion: '3.13',
-      chromaEnabled: true,
-      chromaMode: 'local',
-    };
-  }
-
-  // Custom settings
-  const workerPort = await p.text({
-    message: 'Worker service port:',
-    defaultValue: '37777',
-    placeholder: '37777',
-    validate: (value = '') => {
-      const port = parseInt(value, 10);
-      if (isNaN(port) || port < 1024 || port > 65535) {
-        return 'Port must be between 1024 and 65535';
-      }
-    },
-  });
-  if (p.isCancel(workerPort)) { p.cancel('Installation cancelled.'); process.exit(0); }
-
-  const dataDir = await p.text({
-    message: 'Data directory:',
-    defaultValue: '~/.claude-mem',
-    placeholder: '~/.claude-mem',
-  });
-  if (p.isCancel(dataDir)) { p.cancel('Installation cancelled.'); process.exit(0); }
-
-  const contextObservations = await p.text({
-    message: 'Number of context observations per session:',
-    defaultValue: '50',
-    placeholder: '50',
-    validate: (value = '') => {
-      const num = parseInt(value, 10);
-      if (isNaN(num) || num < 1 || num > 200) {
-        return 'Must be between 1 and 200';
-      }
-    },
-  });
-  if (p.isCancel(contextObservations)) { p.cancel('Installation cancelled.'); process.exit(0); }
-
-  const logLevel = await p.select({
-    message: 'Log level:',
-    options: [
-      { value: 'DEBUG', label: 'DEBUG', hint: 'verbose' },
-      { value: 'INFO', label: 'INFO', hint: 'default' },
-      { value: 'WARN', label: 'WARN' },
-      { value: 'ERROR', label: 'ERROR', hint: 'errors only' },
-    ],
-    initialValue: 'INFO',
-  });
-  if (p.isCancel(logLevel)) { p.cancel('Installation cancelled.'); process.exit(0); }
-
-  const pythonVersion = await p.text({
-    message: 'Python version (for Chroma):',
-    defaultValue: '3.13',
-    placeholder: '3.13',
-  });
-  if (p.isCancel(pythonVersion)) { p.cancel('Installation cancelled.'); process.exit(0); }
-
-  const chromaEnabled = await p.confirm({
-    message: 'Enable Chroma vector search?',
-    initialValue: true,
-  });
-  if (p.isCancel(chromaEnabled)) { p.cancel('Installation cancelled.'); process.exit(0); }
-
-  let chromaMode: 'local' | 'remote' | undefined;
-  let chromaHost: string | undefined;
-  let chromaPort: string | undefined;
-  let chromaSsl: boolean | undefined;
-
-  if (chromaEnabled) {
-    const mode = await p.select({
-      message: 'Chroma mode:',
-      options: [
-        { value: 'local' as const, label: 'Local', hint: 'starts local Chroma server' },
-        { value: 'remote' as const, label: 'Remote', hint: 'connect to existing server' },
-      ],
-    });
-    if (p.isCancel(mode)) { p.cancel('Installation cancelled.'); process.exit(0); }
-    chromaMode = mode;
-
-    if (mode === 'remote') {
-      const host = await p.text({
-        message: 'Chroma host:',
-        defaultValue: '127.0.0.1',
-        placeholder: '127.0.0.1',
-      });
-      if (p.isCancel(host)) { p.cancel('Installation cancelled.'); process.exit(0); }
-      chromaHost = host;
-
-      const port = await p.text({
-        message: 'Chroma port:',
-        defaultValue: '8000',
-        placeholder: '8000',
-        validate: (value = '') => {
-          const portNum = parseInt(value, 10);
-          if (isNaN(portNum) || portNum < 1 || portNum > 65535) return 'Port must be between 1 and 65535';
-        },
-      });
-      if (p.isCancel(port)) { p.cancel('Installation cancelled.'); process.exit(0); }
-      chromaPort = port;
-
-      const ssl = await p.confirm({
-        message: 'Use SSL for Chroma connection?',
-        initialValue: false,
-      });
-      if (p.isCancel(ssl)) { p.cancel('Installation cancelled.'); process.exit(0); }
-      chromaSsl = ssl;
-    }
-  }
-
-  const config: SettingsConfig = {
-    workerPort,
-    dataDir,
-    contextObservations,
-    logLevel,
-    pythonVersion,
-    chromaEnabled,
-    chromaMode,
-    chromaHost,
-    chromaPort,
-    chromaSsl,
-  };
-
-  // Show summary
-  const summaryLines = [
-    `Worker port: ${pc.cyan(workerPort)}`,
-    `Data directory: ${pc.cyan(dataDir)}`,
-    `Context observations: ${pc.cyan(contextObservations)}`,
-    `Log level: ${pc.cyan(logLevel)}`,
-    `Python version: ${pc.cyan(pythonVersion)}`,
-    `Chroma: ${chromaEnabled ? pc.green('enabled') : pc.dim('disabled')}`,
-  ];
-  if (chromaEnabled && chromaMode) {
-    summaryLines.push(`Chroma mode: ${pc.cyan(chromaMode)}`);
-  }
-
-  p.note(summaryLines.join('\n'), 'Settings Summary');
-
-  return config;
-}

installer/src/steps/welcome.ts

@@ -1,43 +0,0 @@
-import * as p from '@clack/prompts';
-import pc from 'picocolors';
-import { existsSync } from 'fs';
-import { expandHome } from '../utils/system.js';
-
-export type InstallMode = 'fresh' | 'upgrade' | 'configure';
-
-export async function runWelcome(): Promise<InstallMode> {
-  p.intro(pc.bgCyan(pc.black(' claude-mem installer ')));
-
-  p.log.info(`Version: 1.0.0`);
-  p.log.info(`Platform: ${process.platform} (${process.arch})`);
-
-  const settingsExist = existsSync(expandHome('~/.claude-mem/settings.json'));
-  const pluginExist = existsSync(expandHome('~/.claude/plugins/marketplaces/thedotmack/'));
-
-  const alreadyInstalled = settingsExist && pluginExist;
-
-  if (alreadyInstalled) {
-    p.log.warn('Existing claude-mem installation detected.');
-  }
-
-  const installMode = await p.select({
-    message: 'What would you like to do?',
-    options: alreadyInstalled
-      ? [
-          { value: 'upgrade' as const, label: 'Upgrade', hint: 'update to latest version' },
-          { value: 'configure' as const, label: 'Configure', hint: 'change settings only' },
-          { value: 'fresh' as const, label: 'Fresh Install', hint: 'reinstall from scratch' },
-        ]
-      : [
-          { value: 'fresh' as const, label: 'Fresh Install', hint: 'recommended' },
-          { value: 'configure' as const, label: 'Configure Only', hint: 'set up settings without installing' },
-        ],
-  });
-
-  if (p.isCancel(installMode)) {
-    p.cancel('Installation cancelled.');
-    process.exit(0);
-  }
-
-  return installMode;
-}

installer/src/steps/worker.ts

@@ -1,67 +0,0 @@
-import * as p from '@clack/prompts';
-import pc from 'picocolors';
-import { spawn } from 'child_process';
-import { join } from 'path';
-import { homedir } from 'os';
-import { expandHome } from '../utils/system.js';
-import { findBinary } from '../utils/dependencies.js';
-
-const MARKETPLACE_DIR = join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');
-
-const HEALTH_CHECK_INTERVAL_MS = 1000;
-const HEALTH_CHECK_MAX_ATTEMPTS = 30;
-
-async function pollHealthEndpoint(port: string, maxAttempts: number = HEALTH_CHECK_MAX_ATTEMPTS): Promise<boolean> {
-  for (let attempt = 0; attempt < maxAttempts; attempt++) {
-    try {
-      const response = await fetch(`http://127.0.0.1:${port}/api/health`);
-      if (response.ok) return true;
-    } catch {
-      // Expected during startup — worker not listening yet
-    }
-    await new Promise((resolve) => setTimeout(resolve, HEALTH_CHECK_INTERVAL_MS));
-  }
-  return false;
-}
-
-export async function runWorkerStartup(workerPort: string, dataDir: string): Promise<void> {
-  const bunInfo = findBinary('bun', ['~/.bun/bin/bun', '/usr/local/bin/bun', '/opt/homebrew/bin/bun']);
-
-  if (!bunInfo.found || !bunInfo.path) {
-    p.log.error('Bun is required to start the worker but was not found.');
-    p.log.info('Install Bun: curl -fsSL https://bun.sh/install | bash');
-    return;
-  }
-
-  const workerScript = join(MARKETPLACE_DIR, 'plugin', 'scripts', 'worker-service.cjs');
-  const expandedDataDir = expandHome(dataDir);
-  const logPath = join(expandedDataDir, 'logs');
-
-  const s = p.spinner();
-  s.start('Starting worker service...');
-
-  // Start worker as a detached background process
-  const child = spawn(bunInfo.path, [workerScript], {
-    cwd: MARKETPLACE_DIR,
-    detached: true,
-    stdio: 'ignore',
-    env: {
-      ...process.env,
-      CLAUDE_MEM_WORKER_PORT: workerPort,
-      CLAUDE_MEM_DATA_DIR: expandedDataDir,
-    },
-  });
-
-  child.unref();
-
-  // Poll the health endpoint until the worker is responsive
-  const workerIsHealthy = await pollHealthEndpoint(workerPort);
-
-  if (workerIsHealthy) {
-    s.stop(`Worker running on port ${pc.cyan(workerPort)} ${pc.green('OK')}`);
-  } else {
-    s.stop(`Worker may still be starting. Check logs at: ${logPath}`);
-    p.log.warn('Health check timed out. The worker might need more time to initialize.');
-    p.log.info(`Check status: curl http://127.0.0.1:${workerPort}/api/health`);
-  }
-}

installer/src/utils/dependencies.ts

@@ -1,74 +0,0 @@
-import { existsSync } from 'fs';
-import { execSync } from 'child_process';
-import { commandExists, runCommand, expandHome, detectOS } from './system.js';
-
-export interface BinaryInfo {
-  found: boolean;
-  path: string | null;
-  version: string | null;
-}
-
-export function findBinary(name: string, extraPaths: string[] = []): BinaryInfo {
-  // Check PATH first
-  if (commandExists(name)) {
-    const result = runCommand('which', [name]);
-    const versionResult = runCommand(name, ['--version']);
-    return {
-      found: true,
-      path: result.stdout,
-      version: parseVersion(versionResult.stdout) || parseVersion(versionResult.stderr),
-    };
-  }
-
-  // Check extra known locations
-  for (const extraPath of extraPaths) {
-    const fullPath = expandHome(extraPath);
-    if (existsSync(fullPath)) {
-      const versionResult = runCommand(fullPath, ['--version']);
-      return {
-        found: true,
-        path: fullPath,
-        version: parseVersion(versionResult.stdout) || parseVersion(versionResult.stderr),
-      };
-    }
-  }
-
-  return { found: false, path: null, version: null };
-}
-
-function parseVersion(output: string): string | null {
-  if (!output) return null;
-  const match = output.match(/(\d+\.\d+(\.\d+)?)/);
-  return match ? match[1] : null;
-}
-
-export function compareVersions(current: string, minimum: string): boolean {
-  const currentParts = current.split('.').map(Number);
-  const minimumParts = minimum.split('.').map(Number);
-
-  for (let i = 0; i < Math.max(currentParts.length, minimumParts.length); i++) {
-    const a = currentParts[i] || 0;
-    const b = minimumParts[i] || 0;
-    if (a > b) return true;
-    if (a < b) return false;
-  }
-  return true; // equal
-}
-
-export function installBun(): void {
-  const os = detectOS();
-  if (os === 'windows') {
-    execSync('powershell -c "irm bun.sh/install.ps1 | iex"', { stdio: 'inherit' });
-  } else {
-    execSync('curl -fsSL https://bun.sh/install | bash', { stdio: 'inherit' });
-  }
-}
-
-export function installUv(): void {
-  const os = detectOS();
-  if (os === 'windows') {
-    execSync('powershell -c "irm https://astral.sh/uv/install.ps1 | iex"', { stdio: 'inherit' });
-  } else {
-    execSync('curl -fsSL https://astral.sh/uv/install.sh | sh', { stdio: 'inherit' });
-  }
-}

installer/src/utils/settings-writer.ts

@@ -1,82 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
-import type { ProviderConfig } from '../steps/provider.js';
-import type { SettingsConfig } from '../steps/settings.js';
-
-export function expandDataDir(dataDir: string): string {
-  if (dataDir.startsWith('~')) {
-    return join(homedir(), dataDir.slice(1));
-  }
-  return dataDir;
-}
-
-export function buildSettingsObject(
-  providerConfig: ProviderConfig,
-  settingsConfig: SettingsConfig,
-): Record<string, string> {
-  const settings: Record<string, string> = {
-    CLAUDE_MEM_WORKER_PORT: settingsConfig.workerPort,
-    CLAUDE_MEM_WORKER_HOST: '127.0.0.1',
-    CLAUDE_MEM_DATA_DIR: expandDataDir(settingsConfig.dataDir),
-    CLAUDE_MEM_CONTEXT_OBSERVATIONS: settingsConfig.contextObservations,
-    CLAUDE_MEM_LOG_LEVEL: settingsConfig.logLevel,
-    CLAUDE_MEM_PYTHON_VERSION: settingsConfig.pythonVersion,
-    CLAUDE_MEM_PROVIDER: providerConfig.provider,
-  };
-
-  // Provider-specific settings
-  if (providerConfig.provider === 'claude') {
-    settings.CLAUDE_MEM_CLAUDE_AUTH_METHOD = providerConfig.claudeAuthMethod ?? 'cli';
-  }
-
-  if (providerConfig.provider === 'gemini') {
-    if (providerConfig.apiKey) settings.CLAUDE_MEM_GEMINI_API_KEY = providerConfig.apiKey;
-    if (providerConfig.model) settings.CLAUDE_MEM_GEMINI_MODEL = providerConfig.model;
-    settings.CLAUDE_MEM_GEMINI_RATE_LIMITING_ENABLED = providerConfig.rateLimitingEnabled !== false ? 'true' : 'false';
-  }
-
-  if (providerConfig.provider === 'openrouter') {
-    if (providerConfig.apiKey) settings.CLAUDE_MEM_OPENROUTER_API_KEY = providerConfig.apiKey;
-    if (providerConfig.model) settings.CLAUDE_MEM_OPENROUTER_MODEL = providerConfig.model;
-  }
-
-  // Chroma settings
-  if (settingsConfig.chromaEnabled) {
-    settings.CLAUDE_MEM_CHROMA_MODE = settingsConfig.chromaMode ?? 'local';
-    if (settingsConfig.chromaMode === 'remote') {
-      if (settingsConfig.chromaHost) settings.CLAUDE_MEM_CHROMA_HOST = settingsConfig.chromaHost;
-      if (settingsConfig.chromaPort) settings.CLAUDE_MEM_CHROMA_PORT = settingsConfig.chromaPort;
-      if (settingsConfig.chromaSsl !== undefined) settings.CLAUDE_MEM_CHROMA_SSL = String(settingsConfig.chromaSsl);
-    }
-  }
-
-  return settings;
-}
-
-export function writeSettings(
-  providerConfig: ProviderConfig,
-  settingsConfig: SettingsConfig,
-): void {
-  const dataDir = expandDataDir(settingsConfig.dataDir);
-  const settingsPath = join(dataDir, 'settings.json');
-
-  // Ensure data directory exists
-  if (!existsSync(dataDir)) {
-    mkdirSync(dataDir, { recursive: true });
-  }
-
-  // Merge with existing settings if upgrading
-  let existingSettings: Record<string, string> = {};
-  if (existsSync(settingsPath)) {
-    const raw = readFileSync(settingsPath, 'utf-8');
-    existingSettings = JSON.parse(raw);
-  }
-
-  const newSettings = buildSettingsObject(providerConfig, settingsConfig);
-
-  // Merge: new settings override existing ones
-  const merged = { ...existingSettings, ...newSettings };
-
-  writeFileSync(settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
-}

installer/src/utils/system.ts

@@ -1,49 +0,0 @@
-import { execSync } from 'child_process';
-import { homedir } from 'os';
-import { join } from 'path';
-
-export type OSType = 'macos' | 'linux' | 'windows';
-
-export function detectOS(): OSType {
-  switch (process.platform) {
-    case 'darwin': return 'macos';
-    case 'win32': return 'windows';
-    default: return 'linux';
-  }
-}
-
-export function commandExists(command: string): boolean {
-  try {
-    execSync(`which ${command}`, { stdio: 'pipe' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export interface CommandResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}
-
-export function runCommand(command: string, args: string[] = []): CommandResult {
-  try {
-    const fullCommand = [command, ...args].join(' ');
-    const stdout = execSync(fullCommand, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
-    return { stdout: stdout.trim(), stderr: '', exitCode: 0 };
-  } catch (error: any) {
-    return {
-      stdout: error.stdout?.toString().trim() ?? '',
-      stderr: error.stderr?.toString().trim() ?? '',
-      exitCode: error.status ?? 1,
-    };
-  }
-}
-
-export function expandHome(filepath: string): string {
-  if (filepath.startsWith('~')) {
-    return join(homedir(), filepath.slice(1));
-  }
-  return filepath;
-}

installer/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "compilerOptions": {
-    "module": "ESNext",
-    "target": "ES2022",
-    "moduleResolution": "bundler",
-    "esModuleInterop": true,
-    "strict": true,
-    "outDir": "dist",
-    "rootDir": "src",
-    "declaration": false,
-    "skipLibCheck": true,
-    "resolveJsonModule": true,
-    "forceConsistentCasingInFileNames": true
-  },
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "dist"]
-}

openclaw/.npmignore

@@ -0,0 +1 @@
+node_modules/

package.json

@@ -26,6 +26,9 @@
     "url": "https://github.com/thedotmack/claude-mem/issues"
   },
   "type": "module",
+  "bin": {
+    "claude-mem": "./dist/npx-cli/index.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -39,7 +42,17 @@
   },
   "files": [
     "dist",
-    "plugin"
+    "plugin/.claude-plugin",
+    "plugin/CLAUDE.md",
+    "plugin/package.json",
+    "plugin/hooks",
+    "plugin/modes",
+    "plugin/scripts/*.js",
+    "plugin/scripts/*.cjs",
+    "plugin/scripts/CLAUDE.md",
+    "plugin/skills",
+    "plugin/ui",
+    "openclaw"
   ],
   "engines": {
     "node": ">=18.0.0",
@@ -97,12 +110,14 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.1.76",
+    "@clack/prompts": "^0.9.1",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "ansi-to-html": "^0.7.2",
     "dompurify": "^3.3.1",
     "express": "^4.18.2",
     "glob": "^11.0.3",
     "handlebars": "^4.7.8",
+    "picocolors": "^1.1.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "yaml": "^2.8.2",

scripts/build-hooks.js

@@ -187,6 +187,88 @@ async function buildHooks() {
     const contextGenStats = fs.statSync(`${hooksDir}/${CONTEXT_GENERATOR.name}.cjs`);
     console.log(`✓ context-generator built (${(contextGenStats.size / 1024).toFixed(2)} KB)`);
 
+    // Build NPX CLI (pure Node.js — no Bun dependency)
+    console.log(`\n🔧 Building NPX CLI...`);
+    const npxCliOutDir = 'dist/npx-cli';
+    if (!fs.existsSync(npxCliOutDir)) {
+      fs.mkdirSync(npxCliOutDir, { recursive: true });
+    }
+    await build({
+      entryPoints: ['src/npx-cli/index.ts'],
+      bundle: true,
+      platform: 'node',
+      target: 'node18',
+      format: 'esm',
+      outfile: `${npxCliOutDir}/index.js`,
+      minify: true,
+      logLevel: 'error',
+      external: [
+        'fs', 'fs/promises', 'path', 'os', 'child_process', 'url',
+        'crypto', 'http', 'https', 'net', 'stream', 'util', 'events',
+        'buffer', 'querystring', 'readline', 'tty', 'assert',
+      ],
+      define: {
+        '__DEFAULT_PACKAGE_VERSION__': `"${version}"`
+      },
+    });
+
+    // Make NPX CLI executable
+    fs.chmodSync(`${npxCliOutDir}/index.js`, 0o755);
+    const npxCliStats = fs.statSync(`${npxCliOutDir}/index.js`);
+    console.log(`✓ npx-cli built (${(npxCliStats.size / 1024).toFixed(2)} KB)`);
+
+    // Build OpenClaw plugin (self-contained, only Node builtins external)
+    if (fs.existsSync('openclaw/src/index.ts')) {
+      console.log(`\n🔧 Building OpenClaw plugin...`);
+      const openclawOutDir = 'openclaw/dist';
+      if (!fs.existsSync(openclawOutDir)) {
+        fs.mkdirSync(openclawOutDir, { recursive: true });
+      }
+      await build({
+        entryPoints: ['openclaw/src/index.ts'],
+        bundle: true,
+        platform: 'node',
+        target: 'node18',
+        format: 'esm',
+        outfile: `${openclawOutDir}/index.js`,
+        minify: true,
+        logLevel: 'error',
+        external: [
+          'fs', 'fs/promises', 'path', 'os', 'child_process', 'url',
+          'crypto', 'http', 'https', 'net', 'stream', 'util', 'events',
+        ],
+      });
+
+      const openclawStats = fs.statSync(`${openclawOutDir}/index.js`);
+      console.log(`✓ openclaw plugin built (${(openclawStats.size / 1024).toFixed(2)} KB)`);
+    }
+
+    // Build OpenCode plugin (self-contained, runs in Bun)
+    if (fs.existsSync('src/integrations/opencode-plugin/index.ts')) {
+      console.log(`\n🔧 Building OpenCode plugin...`);
+      const opencodeOutDir = 'dist/opencode-plugin';
+      if (!fs.existsSync(opencodeOutDir)) {
+        fs.mkdirSync(opencodeOutDir, { recursive: true });
+      }
+      await build({
+        entryPoints: ['src/integrations/opencode-plugin/index.ts'],
+        bundle: true,
+        platform: 'node',
+        target: 'node18',
+        format: 'esm',
+        outfile: `${opencodeOutDir}/index.js`,
+        minify: true,
+        logLevel: 'error',
+        external: [
+          'fs', 'fs/promises', 'path', 'os', 'child_process', 'url',
+          'crypto', 'http', 'https', 'net', 'stream', 'util', 'events',
+        ],
+      });
+
+      const opencodeStats = fs.statSync(`${opencodeOutDir}/index.js`);
+      console.log(`✓ opencode plugin built (${(opencodeStats.size / 1024).toFixed(2)} KB)`);
+    }
+
     // Verify critical distribution files exist (skills are source files, not build outputs)
     console.log('\n📋 Verifying distribution files...');
     const requiredDistributionFiles = [
@@ -202,11 +284,21 @@ async function buildHooks() {
     }
     console.log('✓ All required distribution files present');
 
-    console.log('\n✅ Worker service, MCP server, and context generator built successfully!');
+    console.log('\n✅ All build targets compiled successfully!');
     console.log(`   Output: ${hooksDir}/`);
     console.log(`   - Worker: worker-service.cjs`);
     console.log(`   - MCP Server: mcp-server.cjs`);
     console.log(`   - Context Generator: context-generator.cjs`);
+    console.log(`   Output: ${npxCliOutDir}/`);
+    console.log(`   - NPX CLI: index.js`);
+    if (fs.existsSync('openclaw/dist/index.js')) {
+      console.log(`   Output: openclaw/dist/`);
+      console.log(`   - OpenClaw Plugin: index.js`);
+    }
+    if (fs.existsSync('dist/opencode-plugin/index.js')) {
+      console.log(`   Output: dist/opencode-plugin/`);
+      console.log(`   - OpenCode Plugin: index.js`);
+    }
 
   } catch (error) {
     console.error('\n❌ Build failed:', error.message);

src/cli/adapters/index.ts

@@ -3,6 +3,7 @@ import { claudeCodeAdapter } from './claude-code.js';
 import { cursorAdapter } from './cursor.js';
 import { geminiCliAdapter } from './gemini-cli.js';
 import { rawAdapter } from './raw.js';
+import { windsurfAdapter } from './windsurf.js';
 
 export function getPlatformAdapter(platform: string): PlatformAdapter {
   switch (platform) {
@@ -10,10 +11,11 @@ export function getPlatformAdapter(platform: string): PlatformAdapter {
     case 'cursor': return cursorAdapter;
     case 'gemini':
     case 'gemini-cli': return geminiCliAdapter;
+    case 'windsurf': return windsurfAdapter;
     case 'raw': return rawAdapter;
     // Codex CLI and other compatible platforms use the raw adapter (accepts both camelCase and snake_case fields)
     default: return rawAdapter;
   }
 }
 
-export { claudeCodeAdapter, cursorAdapter, geminiCliAdapter, rawAdapter };
+export { claudeCodeAdapter, cursorAdapter, geminiCliAdapter, rawAdapter, windsurfAdapter };

src/cli/adapters/windsurf.ts

@@ -0,0 +1,79 @@
+import type { PlatformAdapter, NormalizedHookInput, HookResult } from '../types.js';
+
+// Maps Windsurf stdin format — JSON envelope with agent_action_name + tool_info payload
+//
+// Common envelope (all hooks):
+//   { agent_action_name, trajectory_id, execution_id, timestamp, tool_info: { ... } }
+//
+// Event-specific tool_info payloads:
+//   pre_user_prompt:      { user_prompt: string }
+//   post_write_code:      { file_path, edits: [{ old_string, new_string }] }
+//   post_run_command:     { command_line, cwd }
+//   post_mcp_tool_use:    { mcp_server_name, mcp_tool_name, mcp_tool_arguments, mcp_result }
+//   post_cascade_response: { response }
+export const windsurfAdapter: PlatformAdapter = {
+  normalizeInput(raw) {
+    const r = (raw ?? {}) as any;
+    const toolInfo = r.tool_info ?? {};
+    const actionName: string = r.agent_action_name ?? '';
+
+    const base: NormalizedHookInput = {
+      sessionId: r.trajectory_id ?? r.execution_id,
+      cwd: toolInfo.cwd ?? process.cwd(),
+      platform: 'windsurf',
+    };
+
+    switch (actionName) {
+      case 'pre_user_prompt':
+        return {
+          ...base,
+          prompt: toolInfo.user_prompt,
+        };
+
+      case 'post_write_code':
+        return {
+          ...base,
+          toolName: 'Write',
+          filePath: toolInfo.file_path,
+          edits: toolInfo.edits,
+          toolInput: {
+            file_path: toolInfo.file_path,
+            edits: toolInfo.edits,
+          },
+        };
+
+      case 'post_run_command':
+        return {
+          ...base,
+          cwd: toolInfo.cwd ?? base.cwd,
+          toolName: 'Bash',
+          toolInput: { command: toolInfo.command_line },
+        };
+
+      case 'post_mcp_tool_use':
+        return {
+          ...base,
+          toolName: toolInfo.mcp_tool_name ?? 'mcp_tool',
+          toolInput: toolInfo.mcp_tool_arguments,
+          toolResponse: toolInfo.mcp_result,
+        };
+
+      case 'post_cascade_response':
+        return {
+          ...base,
+          toolName: 'cascade_response',
+          toolResponse: toolInfo.response,
+        };
+
+      default:
+        // Unknown action — pass through what we can
+        return base;
+    }
+  },
+
+  formatOutput(result) {
+    // Windsurf exit codes: 0 = success, 2 = block (pre-hooks only)
+    // The CLI layer handles exit codes; here we just return a simple continue flag
+    return { continue: result.continue ?? true };
+  },
+};

src/cli/handlers/context.ts

@@ -39,7 +39,7 @@ export const contextHandler: EventHandler = {
     // Pass all projects (parent + worktree if applicable) for unified timeline
     const projectsParam = context.allProjects.join(',');
     const apiPath = `/api/context/inject?projects=${encodeURIComponent(projectsParam)}`;
-    const colorApiPath = `${apiPath}&colors=true`;
+    const colorApiPath = input.platform === 'claude-code' ? `${apiPath}&colors=true` : apiPath;
 
     // Note: Removed AbortSignal.timeout due to Windows Bun cleanup issue (libuv assertion)
     // Worker service has its own timeouts, so client-side timeout is redundant

src/cli/handlers/user-message.ts

@@ -23,9 +23,11 @@ export const userMessageHandler: EventHandler = {
     const project = basename(input.cwd ?? process.cwd());
 
     // Fetch formatted context directly from worker API
+    // Only request ANSI colors for platforms that render them (claude-code)
+    const colorsParam = input.platform === 'claude-code' ? '&colors=true' : '';
     try {
       const response = await workerHttpRequest(
-        `/api/context/inject?project=${encodeURIComponent(project)}&colors=true`
+        `/api/context/inject?project=${encodeURIComponent(project)}${colorsParam}`
       );
 
       if (!response.ok) {

src/cli/types.ts

@@ -1,7 +1,7 @@
 export interface NormalizedHookInput {
   sessionId: string;
   cwd: string;
-  platform?: string;   // 'claude-code' or 'cursor'
+  platform?: string;   // 'claude-code', 'cursor', 'gemini-cli', etc.
   prompt?: string;
   toolName?: string;
   toolInput?: unknown;
@@ -10,6 +10,8 @@ export interface NormalizedHookInput {
   // Cursor-specific fields
   filePath?: string;   // afterFileEdit
   edits?: unknown[];   // afterFileEdit
+  // Platform-specific metadata (source, reason, trigger, mcp_context, etc.)
+  metadata?: Record<string, unknown>;
 }
 
 export interface HookResult {

src/integrations/opencode-plugin/index.ts

@@ -0,0 +1,355 @@
+/**
+ * OpenCode Plugin for claude-mem
+ *
+ * Integrates claude-mem persistent memory with OpenCode (110k+ stars).
+ * Runs inside OpenCode's Bun-based plugin runtime.
+ *
+ * Plugin hooks:
+ * - tool.execute.after: Captures tool execution observations
+ * - Bus events: session.created, message.updated, session.compacted,
+ *   file.edited, session.deleted
+ *
+ * Custom tool:
+ * - claude_mem_search: Search memory database from within OpenCode
+ */
+
+// ============================================================================
+// Minimal type declarations for OpenCode Plugin SDK
+// These match the runtime API provided by @opencode-ai/plugin
+// ============================================================================
+
+interface OpenCodeProject {
+  name?: string;
+  path?: string;
+}
+
+interface OpenCodePluginContext {
+  client: unknown;
+  project: OpenCodeProject;
+  directory: string;
+  worktree: string;
+  serverUrl: URL;
+  $: unknown; // BunShell
+}
+
+interface ToolExecuteAfterInput {
+  tool: string;
+  sessionID: string;
+  callID: string;
+  args: Record<string, unknown>;
+}
+
+interface ToolExecuteAfterOutput {
+  title: string;
+  output: string;
+  metadata: Record<string, unknown>;
+}
+
+interface ToolDefinition {
+  description: string;
+  args: Record<string, unknown>;
+  execute: (args: Record<string, unknown>, context: unknown) => Promise<string>;
+}
+
+// Bus event payloads
+interface SessionCreatedEvent {
+  event: {
+    sessionID: string;
+    directory?: string;
+    project?: string;
+  };
+}
+
+interface MessageUpdatedEvent {
+  event: {
+    sessionID: string;
+    role: string;
+    content: string;
+  };
+}
+
+interface SessionCompactedEvent {
+  event: {
+    sessionID: string;
+    summary?: string;
+    messageCount?: number;
+  };
+}
+
+interface FileEditedEvent {
+  event: {
+    sessionID: string;
+    path: string;
+    diff?: string;
+  };
+}
+
+interface SessionDeletedEvent {
+  event: {
+    sessionID: string;
+  };
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const WORKER_BASE_URL = "http://127.0.0.1:37777";
+const MAX_TOOL_RESPONSE_LENGTH = 1000;
+
+// ============================================================================
+// Worker HTTP Client
+// ============================================================================
+
+async function workerPost(
+  path: string,
+  body: Record<string, unknown>,
+): Promise<Record<string, unknown> | null> {
+  try {
+    const response = await fetch(`${WORKER_BASE_URL}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+      console.warn(`[claude-mem] Worker POST ${path} returned ${response.status}`);
+      return null;
+    }
+    return (await response.json()) as Record<string, unknown>;
+  } catch (error: unknown) {
+    // Gracefully handle ECONNREFUSED — worker may not be running
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.includes("ECONNREFUSED")) {
+      console.warn(`[claude-mem] Worker POST ${path} failed: ${message}`);
+    }
+    return null;
+  }
+}
+
+function workerPostFireAndForget(
+  path: string,
+  body: Record<string, unknown>,
+): void {
+  fetch(`${WORKER_BASE_URL}${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  }).catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.includes("ECONNREFUSED")) {
+      console.warn(`[claude-mem] Worker POST ${path} failed: ${message}`);
+    }
+  });
+}
+
+async function workerGetText(path: string): Promise<string | null> {
+  try {
+    const response = await fetch(`${WORKER_BASE_URL}${path}`);
+    if (!response.ok) {
+      console.warn(`[claude-mem] Worker GET ${path} returned ${response.status}`);
+      return null;
+    }
+    return await response.text();
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.includes("ECONNREFUSED")) {
+      console.warn(`[claude-mem] Worker GET ${path} failed: ${message}`);
+    }
+    return null;
+  }
+}
+
+// ============================================================================
+// Session tracking
+// ============================================================================
+
+const contentSessionIdsByOpenCodeSessionId = new Map<string, string>();
+
+function getOrCreateContentSessionId(openCodeSessionId: string): string {
+  if (!contentSessionIdsByOpenCodeSessionId.has(openCodeSessionId)) {
+    contentSessionIdsByOpenCodeSessionId.set(
+      openCodeSessionId,
+      `opencode-${openCodeSessionId}-${Date.now()}`,
+    );
+  }
+  return contentSessionIdsByOpenCodeSessionId.get(openCodeSessionId)!;
+}
+
+// ============================================================================
+// Plugin Entry Point
+// ============================================================================
+
+export const ClaudeMemPlugin = async (ctx: OpenCodePluginContext) => {
+  const projectName = ctx.project?.name || "opencode";
+
+  console.log(`[claude-mem] OpenCode plugin loading (project: ${projectName})`);
+
+  return {
+    // ------------------------------------------------------------------
+    // Direct interceptor hooks
+    // ------------------------------------------------------------------
+    hooks: {
+      tool: {
+        execute: {
+          after: (
+            input: ToolExecuteAfterInput,
+            output: ToolExecuteAfterOutput,
+          ) => {
+            const contentSessionId = getOrCreateContentSessionId(input.sessionID);
+
+            // Truncate long tool output
+            let toolResponseText = output.output || "";
+            if (toolResponseText.length > MAX_TOOL_RESPONSE_LENGTH) {
+              toolResponseText = toolResponseText.slice(0, MAX_TOOL_RESPONSE_LENGTH);
+            }
+
+            workerPostFireAndForget("/api/sessions/observations", {
+              contentSessionId,
+              tool_name: input.tool,
+              tool_input: input.args || {},
+              tool_response: toolResponseText,
+              cwd: ctx.directory,
+            });
+          },
+        },
+      },
+    },
+
+    // ------------------------------------------------------------------
+    // Bus event handlers
+    // ------------------------------------------------------------------
+    event: (eventName: string, payload: unknown) => {
+      switch (eventName) {
+        case "session.created": {
+          const { event } = payload as SessionCreatedEvent;
+          const contentSessionId = getOrCreateContentSessionId(event.sessionID);
+
+          workerPostFireAndForget("/api/sessions/init", {
+            contentSessionId,
+            project: projectName,
+            prompt: "",
+          });
+          break;
+        }
+
+        case "message.updated": {
+          const { event } = payload as MessageUpdatedEvent;
+
+          // Only capture assistant messages as observations
+          if (event.role !== "assistant") break;
+
+          const contentSessionId = getOrCreateContentSessionId(event.sessionID);
+
+          let messageText = event.content || "";
+          if (messageText.length > MAX_TOOL_RESPONSE_LENGTH) {
+            messageText = messageText.slice(0, MAX_TOOL_RESPONSE_LENGTH);
+          }
+
+          workerPostFireAndForget("/api/sessions/observations", {
+            contentSessionId,
+            tool_name: "assistant_message",
+            tool_input: {},
+            tool_response: messageText,
+            cwd: ctx.directory,
+          });
+          break;
+        }
+
+        case "session.compacted": {
+          const { event } = payload as SessionCompactedEvent;
+          const contentSessionId = getOrCreateContentSessionId(event.sessionID);
+
+          workerPostFireAndForget("/api/sessions/summarize", {
+            contentSessionId,
+            last_assistant_message: event.summary || "",
+          });
+          break;
+        }
+
+        case "file.edited": {
+          const { event } = payload as FileEditedEvent;
+          const contentSessionId = getOrCreateContentSessionId(event.sessionID);
+
+          workerPostFireAndForget("/api/sessions/observations", {
+            contentSessionId,
+            tool_name: "file_edit",
+            tool_input: { path: event.path },
+            tool_response: event.diff
+              ? event.diff.slice(0, MAX_TOOL_RESPONSE_LENGTH)
+              : `File edited: ${event.path}`,
+            cwd: ctx.directory,
+          });
+          break;
+        }
+
+        case "session.deleted": {
+          const { event } = payload as SessionDeletedEvent;
+          const contentSessionId = contentSessionIdsByOpenCodeSessionId.get(
+            event.sessionID,
+          );
+
+          if (contentSessionId) {
+            workerPostFireAndForget("/api/sessions/complete", {
+              contentSessionId,
+            });
+            contentSessionIdsByOpenCodeSessionId.delete(event.sessionID);
+          }
+          break;
+        }
+      }
+    },
+
+    // ------------------------------------------------------------------
+    // Custom tools
+    // ------------------------------------------------------------------
+    tool: {
+      claude_mem_search: {
+        description:
+          "Search claude-mem memory database for past observations, sessions, and context",
+        args: {
+          query: {
+            type: "string",
+            description: "Search query for memory observations",
+          },
+        },
+        async execute(
+          args: Record<string, unknown>,
+        ): Promise<string> {
+          const query = String(args.query || "");
+          if (!query) {
+            return "Please provide a search query.";
+          }
+
+          const text = await workerGetText(
+            `/api/search/observations?query=${encodeURIComponent(query)}&limit=10`,
+          );
+
+          if (!text) {
+            return "claude-mem worker is not running. Start it with: npx claude-mem start";
+          }
+
+          try {
+            const data = JSON.parse(text);
+            const items = Array.isArray(data.items) ? data.items : [];
+            if (items.length === 0) {
+              return `No results found for "${query}".`;
+            }
+
+            return items
+              .slice(0, 10)
+              .map((item: Record<string, unknown>, index: number) => {
+                const title = String(item.title || item.subtitle || "Untitled");
+                const project = item.project ? ` [${String(item.project)}]` : "";
+                return `${index + 1}. ${title}${project}`;
+              })
+              .join("\n");
+          } catch {
+            return "Failed to parse search results.";
+          }
+        },
+      } satisfies ToolDefinition,
+    },
+  };
+};
+
+export default ClaudeMemPlugin;

src/npx-cli/commands/ide-detection.ts

@@ -0,0 +1,172 @@
+/**
+ * IDE Auto-Detection
+ *
+ * Detects which AI coding IDEs / tools are installed on the system by
+ * probing known config directories and checking for binaries in PATH.
+ *
+ * Pure Node.js — no Bun APIs used.
+ */
+import { execSync } from 'child_process';
+import { existsSync, readdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { IS_WINDOWS } from '../utils/paths.js';
+
+// ---------------------------------------------------------------------------
+// IDE type and metadata
+// ---------------------------------------------------------------------------
+
+export interface IDEInfo {
+  /** Machine-readable identifier. */
+  id: string;
+  /** Human-readable label for display in prompts. */
+  label: string;
+  /** Whether the IDE was detected on this system. */
+  detected: boolean;
+  /** Whether claude-mem has implemented setup for this IDE. */
+  supported: boolean;
+  /** Short hint text shown in the multi-select. */
+  hint?: string;
+}
+
+// ---------------------------------------------------------------------------
+// PATH helper
+// ---------------------------------------------------------------------------
+
+function isCommandInPath(command: string): boolean {
+  try {
+    const whichCommand = IS_WINDOWS ? 'where' : 'which';
+    execSync(`${whichCommand} ${command}`, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// VS Code extension directory scanner
+// ---------------------------------------------------------------------------
+
+function hasVscodeExtension(extensionNameFragment: string): boolean {
+  const extensionsDirectory = join(homedir(), '.vscode', 'extensions');
+  if (!existsSync(extensionsDirectory)) return false;
+  try {
+    const entries = readdirSync(extensionsDirectory);
+    return entries.some((entry) => entry.toLowerCase().includes(extensionNameFragment.toLowerCase()));
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection map
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect all known IDEs and return an array of `IDEInfo` objects.
+ * Each entry indicates whether the IDE was found and whether claude-mem
+ * currently supports setting it up.
+ */
+export function detectInstalledIDEs(): IDEInfo[] {
+  const home = homedir();
+
+  return [
+    {
+      id: 'claude-code',
+      label: 'Claude Code',
+      detected: existsSync(join(home, '.claude')),
+      supported: true,
+      hint: 'recommended',
+    },
+    {
+      id: 'gemini-cli',
+      label: 'Gemini CLI',
+      detected: existsSync(join(home, '.gemini')),
+      supported: true,
+    },
+    {
+      id: 'opencode',
+      label: 'OpenCode',
+      detected:
+        existsSync(join(home, '.config', 'opencode')) || isCommandInPath('opencode'),
+      supported: true,
+      hint: 'plugin-based integration',
+    },
+    {
+      id: 'openclaw',
+      label: 'OpenClaw',
+      detected: existsSync(join(home, '.openclaw')),
+      supported: true,
+      hint: 'plugin-based integration',
+    },
+    {
+      id: 'windsurf',
+      label: 'Windsurf',
+      detected: existsSync(join(home, '.codeium', 'windsurf')),
+      supported: true,
+    },
+    {
+      id: 'codex-cli',
+      label: 'Codex CLI',
+      detected: existsSync(join(home, '.codex')),
+      supported: true,
+      hint: 'transcript-based integration',
+    },
+    {
+      id: 'cursor',
+      label: 'Cursor',
+      detected: existsSync(join(home, '.cursor')),
+      supported: true,
+    },
+    {
+      id: 'copilot-cli',
+      label: 'Copilot CLI',
+      detected: isCommandInPath('copilot'),
+      supported: true,
+      hint: 'MCP-based integration',
+    },
+    {
+      id: 'antigravity',
+      label: 'Antigravity',
+      detected: existsSync(join(home, '.gemini', 'antigravity')),
+      supported: true,
+      hint: 'MCP-based integration',
+    },
+    {
+      id: 'goose',
+      label: 'Goose',
+      detected:
+        existsSync(join(home, '.config', 'goose')) || isCommandInPath('goose'),
+      supported: true,
+      hint: 'MCP-based integration',
+    },
+    {
+      id: 'crush',
+      label: 'Crush',
+      detected: isCommandInPath('crush'),
+      supported: true,
+      hint: 'MCP-based integration',
+    },
+    {
+      id: 'roo-code',
+      label: 'Roo Code',
+      detected: hasVscodeExtension('roo-code'),
+      supported: true,
+      hint: 'MCP-based integration',
+    },
+    {
+      id: 'warp',
+      label: 'Warp',
+      detected: existsSync(join(home, '.warp')) || isCommandInPath('warp'),
+      supported: true,
+      hint: 'MCP-based integration',
+    },
+  ];
+}
+
+/**
+ * Return only the IDEs that were detected on this system.
+ */
+export function getDetectedIDEs(): IDEInfo[] {
+  return detectInstalledIDEs().filter((ide) => ide.detected);
+}

src/npx-cli/commands/install.ts

@@ -0,0 +1,465 @@
+/**
+ * Install command for `npx claude-mem install`.
+ *
+ * Replaces the git-clone + build workflow. The npm package already ships
+ * a pre-built `plugin/` directory; this command copies it into the right
+ * locations and registers it with Claude Code.
+ *
+ * Pure Node.js — no Bun APIs used.
+ */
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { execSync } from 'child_process';
+import { cpSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import {
+  claudeSettingsPath,
+  ensureDirectoryExists,
+  installedPluginsPath,
+  IS_WINDOWS,
+  knownMarketplacesPath,
+  marketplaceDirectory,
+  npmPackagePluginDirectory,
+  npmPackageRootDirectory,
+  pluginCacheDirectory,
+  pluginsDirectory,
+  readJsonFileSafe,
+  readPluginVersion,
+  writeJsonFileAtomic,
+} from '../utils/paths.js';
+import { detectInstalledIDEs } from './ide-detection.js';
+
+// ---------------------------------------------------------------------------
+// Registration helpers
+// ---------------------------------------------------------------------------
+
+function registerMarketplace(): void {
+  const knownMarketplaces = readJsonFileSafe(knownMarketplacesPath());
+
+  knownMarketplaces['thedotmack'] = {
+    source: {
+      source: 'github',
+      repo: 'thedotmack/claude-mem',
+    },
+    installLocation: marketplaceDirectory(),
+    lastUpdated: new Date().toISOString(),
+    autoUpdate: true,
+  };
+
+  ensureDirectoryExists(pluginsDirectory());
+  writeJsonFileAtomic(knownMarketplacesPath(), knownMarketplaces);
+}
+
+function registerPlugin(version: string): void {
+  const installedPlugins = readJsonFileSafe(installedPluginsPath());
+
+  if (!installedPlugins.version) installedPlugins.version = 2;
+  if (!installedPlugins.plugins) installedPlugins.plugins = {};
+
+  const cachePath = pluginCacheDirectory(version);
+  const now = new Date().toISOString();
+
+  installedPlugins.plugins['claude-mem@thedotmack'] = [
+    {
+      scope: 'user',
+      installPath: cachePath,
+      version,
+      installedAt: now,
+      lastUpdated: now,
+    },
+  ];
+
+  writeJsonFileAtomic(installedPluginsPath(), installedPlugins);
+}
+
+function enablePluginInClaudeSettings(): void {
+  const settings = readJsonFileSafe(claudeSettingsPath());
+
+  if (!settings.enabledPlugins) settings.enabledPlugins = {};
+  settings.enabledPlugins['claude-mem@thedotmack'] = true;
+
+  writeJsonFileAtomic(claudeSettingsPath(), settings);
+}
+
+// ---------------------------------------------------------------------------
+// IDE setup dispatcher
+// ---------------------------------------------------------------------------
+
+async function setupIDEs(selectedIDEs: string[]): Promise<void> {
+  for (const ideId of selectedIDEs) {
+    switch (ideId) {
+      case 'claude-code':
+        // Claude Code picks up the plugin via marketplace registration — nothing
+        // else to do beyond what registerMarketplace / registerPlugin already did.
+        p.log.success('Claude Code: plugin registered via marketplace.');
+        break;
+
+      case 'cursor':
+        p.log.info('Cursor: hook configuration available after first launch.');
+        p.log.info(`  Run: npx claude-mem cursor-setup (coming soon)`);
+        break;
+
+      case 'gemini-cli': {
+        const { installGeminiCliHooks } = await import('../../services/integrations/GeminiCliHooksInstaller.js');
+        const geminiResult = await installGeminiCliHooks();
+        if (geminiResult === 0) {
+          p.log.success('Gemini CLI: hooks installed.');
+        } else {
+          p.log.error('Gemini CLI: hook installation failed.');
+        }
+        break;
+      }
+
+      case 'opencode': {
+        const { installOpenCodeIntegration } = await import('../../services/integrations/OpenCodeInstaller.js');
+        const openCodeResult = await installOpenCodeIntegration();
+        if (openCodeResult === 0) {
+          p.log.success('OpenCode: plugin installed.');
+        } else {
+          p.log.error('OpenCode: plugin installation failed.');
+        }
+        break;
+      }
+
+      case 'windsurf': {
+        const { installWindsurfHooks } = await import('../../services/integrations/WindsurfHooksInstaller.js');
+        const windsurfResult = await installWindsurfHooks();
+        if (windsurfResult === 0) {
+          p.log.success('Windsurf: hooks installed.');
+        } else {
+          p.log.error('Windsurf: hook installation failed.');
+        }
+        break;
+      }
+
+      case 'openclaw': {
+        const { installOpenClawIntegration } = await import('../../services/integrations/OpenClawInstaller.js');
+        const openClawResult = await installOpenClawIntegration();
+        if (openClawResult === 0) {
+          p.log.success('OpenClaw: plugin installed.');
+        } else {
+          p.log.error('OpenClaw: plugin installation failed.');
+        }
+        break;
+      }
+
+      case 'codex-cli': {
+        const { installCodexCli } = await import('../../services/integrations/CodexCliInstaller.js');
+        const codexResult = await installCodexCli();
+        if (codexResult === 0) {
+          p.log.success('Codex CLI: transcript watching configured.');
+        } else {
+          p.log.error('Codex CLI: integration setup failed.');
+        }
+        break;
+      }
+
+      case 'copilot-cli':
+      case 'antigravity':
+      case 'goose':
+      case 'crush':
+      case 'roo-code':
+      case 'warp': {
+        const { MCP_IDE_INSTALLERS } = await import('../../services/integrations/McpIntegrations.js');
+        const mcpInstaller = MCP_IDE_INSTALLERS[ideId];
+        if (mcpInstaller) {
+          const mcpResult = await mcpInstaller();
+          const allIDEs = detectInstalledIDEs();
+          const ideInfo = allIDEs.find((i) => i.id === ideId);
+          const ideLabel = ideInfo?.label ?? ideId;
+          if (mcpResult === 0) {
+            p.log.success(`${ideLabel}: MCP integration installed.`);
+          } else {
+            p.log.error(`${ideLabel}: MCP integration failed.`);
+          }
+        }
+        break;
+      }
+
+      default: {
+        const allIDEs = detectInstalledIDEs();
+        const ide = allIDEs.find((i) => i.id === ideId);
+        if (ide && !ide.supported) {
+          p.log.warn(`Support for ${ide.label} coming soon.`);
+        }
+        break;
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Interactive IDE selection
+// ---------------------------------------------------------------------------
+
+async function promptForIDESelection(): Promise<string[]> {
+  const detectedIDEs = detectInstalledIDEs();
+  const detected = detectedIDEs.filter((ide) => ide.detected);
+
+  if (detected.length === 0) {
+    p.log.warn('No supported IDEs detected. Installing for Claude Code by default.');
+    return ['claude-code'];
+  }
+
+  const options = detected.map((ide) => ({
+    value: ide.id,
+    label: ide.label,
+    hint: ide.supported ? ide.hint : 'coming soon',
+  }));
+
+  const result = await p.multiselect({
+    message: 'Which IDEs do you use?',
+    options,
+    initialValues: detected
+      .filter((ide) => ide.supported)
+      .map((ide) => ide.id),
+    required: true,
+  });
+
+  if (p.isCancel(result)) {
+    p.cancel('Installation cancelled.');
+    process.exit(0);
+  }
+
+  return result as string[];
+}
+
+// ---------------------------------------------------------------------------
+// Core copy logic
+// ---------------------------------------------------------------------------
+
+function copyPluginToMarketplace(): void {
+  const marketplaceDir = marketplaceDirectory();
+  const packageRoot = npmPackageRootDirectory();
+
+  ensureDirectoryExists(marketplaceDir);
+
+  // Only copy directories/files that are actually needed at runtime.
+  // The npm package ships plugin/, package.json, node_modules/, openclaw/, dist/.
+  // When running from a dev checkout, the root contains many extra dirs
+  // (.claude, .agents, src, docs, etc.) that must NOT be copied.
+  const allowedTopLevelEntries = [
+    'plugin',
+    'package.json',
+    'package-lock.json',
+    'node_modules',
+    'openclaw',
+    'dist',
+    'LICENSE',
+    'README.md',
+    'CHANGELOG.md',
+  ];
+
+  for (const entry of allowedTopLevelEntries) {
+    const sourcePath = join(packageRoot, entry);
+    const destPath = join(marketplaceDir, entry);
+    if (!existsSync(sourcePath)) continue;
+
+    cpSync(sourcePath, destPath, {
+      recursive: true,
+      force: true,
+    });
+  }
+}
+
+function copyPluginToCache(version: string): void {
+  const sourcePluginDirectory = npmPackagePluginDirectory();
+  const cachePath = pluginCacheDirectory(version);
+
+  ensureDirectoryExists(cachePath);
+  cpSync(sourcePluginDirectory, cachePath, { recursive: true, force: true });
+}
+
+// ---------------------------------------------------------------------------
+// npm install in marketplace dir
+// ---------------------------------------------------------------------------
+
+function runNpmInstallInMarketplace(): void {
+  const marketplaceDir = marketplaceDirectory();
+  const packageJsonPath = join(marketplaceDir, 'package.json');
+
+  if (!existsSync(packageJsonPath)) return;
+
+  execSync('npm install --production', {
+    cwd: marketplaceDir,
+    stdio: 'pipe',
+    ...(IS_WINDOWS ? { shell: true as const } : {}),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Trigger smart-install for Bun / uv
+// ---------------------------------------------------------------------------
+
+function runSmartInstall(): void {
+  const smartInstallPath = join(marketplaceDirectory(), 'plugin', 'scripts', 'smart-install.js');
+
+  if (!existsSync(smartInstallPath)) {
+    p.log.warn('smart-install.js not found — skipping Bun/uv auto-install.');
+    return;
+  }
+
+  try {
+    execSync(`node "${smartInstallPath}"`, {
+      stdio: 'inherit',
+      ...(IS_WINDOWS ? { shell: true as const } : {}),
+    });
+  } catch {
+    p.log.warn('smart-install encountered an issue. You may need to install Bun/uv manually.');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface InstallOptions {
+  /** When provided, skip the interactive IDE multi-select and use this IDE. */
+  ide?: string;
+}
+
+export async function runInstallCommand(options: InstallOptions = {}): Promise<void> {
+  const version = readPluginVersion();
+
+  p.intro(pc.bgCyan(pc.black(' claude-mem install ')));
+  p.log.info(`Version: ${pc.cyan(version)}`);
+  p.log.info(`Platform: ${process.platform} (${process.arch})`);
+
+  // Check for existing installation
+  const marketplaceDir = marketplaceDirectory();
+  const alreadyInstalled = existsSync(join(marketplaceDir, 'plugin', '.claude-plugin', 'plugin.json'));
+
+  if (alreadyInstalled) {
+    // Read existing version
+    try {
+      const existingPluginJson = JSON.parse(
+        readFileSync(join(marketplaceDir, 'plugin', '.claude-plugin', 'plugin.json'), 'utf-8'),
+      );
+      p.log.warn(`Existing installation detected (v${existingPluginJson.version ?? 'unknown'}).`);
+    } catch {
+      p.log.warn('Existing installation detected.');
+    }
+
+    if (process.stdin.isTTY) {
+      const shouldContinue = await p.confirm({
+        message: 'Overwrite existing installation?',
+        initialValue: true,
+      });
+
+      if (p.isCancel(shouldContinue) || !shouldContinue) {
+        p.cancel('Installation cancelled.');
+        process.exit(0);
+      }
+    }
+  }
+
+  // IDE selection
+  let selectedIDEs: string[];
+  if (options.ide) {
+    selectedIDEs = [options.ide];
+    const allIDEs = detectInstalledIDEs();
+    const match = allIDEs.find((i) => i.id === options.ide);
+    if (match && !match.supported) {
+      p.log.error(`Support for ${match.label} coming soon.`);
+      process.exit(1);
+    }
+    if (!match) {
+      p.log.error(`Unknown IDE: ${options.ide}`);
+      p.log.info(`Available IDEs: ${allIDEs.map((i) => i.id).join(', ')}`);
+      process.exit(1);
+    }
+  } else if (process.stdin.isTTY) {
+    selectedIDEs = await promptForIDESelection();
+  } else {
+    // Non-interactive: default to claude-code
+    selectedIDEs = ['claude-code'];
+  }
+
+  // Run tasks
+  await p.tasks([
+    {
+      title: 'Copying plugin files',
+      task: async (message) => {
+        message('Copying to marketplace directory...');
+        copyPluginToMarketplace();
+        return `Plugin files copied ${pc.green('OK')}`;
+      },
+    },
+    {
+      title: 'Caching plugin version',
+      task: async (message) => {
+        message(`Caching v${version}...`);
+        copyPluginToCache(version);
+        return `Plugin cached (v${version}) ${pc.green('OK')}`;
+      },
+    },
+    {
+      title: 'Registering marketplace',
+      task: async () => {
+        registerMarketplace();
+        return `Marketplace registered ${pc.green('OK')}`;
+      },
+    },
+    {
+      title: 'Registering plugin',
+      task: async () => {
+        registerPlugin(version);
+        return `Plugin registered ${pc.green('OK')}`;
+      },
+    },
+    {
+      title: 'Enabling plugin in Claude settings',
+      task: async () => {
+        enablePluginInClaudeSettings();
+        return `Plugin enabled ${pc.green('OK')}`;
+      },
+    },
+    {
+      title: 'Installing dependencies',
+      task: async (message) => {
+        message('Running npm install...');
+        try {
+          runNpmInstallInMarketplace();
+          return `Dependencies installed ${pc.green('OK')}`;
+        } catch {
+          return `Dependencies may need manual install ${pc.yellow('!')}`;
+        }
+      },
+    },
+    {
+      title: 'Setting up Bun and uv',
+      task: async (message) => {
+        message('Running smart-install...');
+        try {
+          runSmartInstall();
+          return `Runtime dependencies ready ${pc.green('OK')}`;
+        } catch {
+          return `Runtime setup may need attention ${pc.yellow('!')}`;
+        }
+      },
+    },
+  ]);
+
+  // IDE-specific setup
+  await setupIDEs(selectedIDEs);
+
+  // Summary
+  const summaryLines = [
+    `Version:     ${pc.cyan(version)}`,
+    `Plugin dir:  ${pc.cyan(marketplaceDir)}`,
+    `IDEs:        ${pc.cyan(selectedIDEs.join(', '))}`,
+  ];
+
+  p.note(summaryLines.join('\n'), 'Installation Complete');
+
+  const nextSteps = [
+    'Open Claude Code and start a conversation -- memory is automatic!',
+    `View your memories: ${pc.underline('http://localhost:37777')}`,
+    `Search past work: use ${pc.bold('/mem-search')} in Claude Code`,
+    `Start worker: ${pc.bold('npx claude-mem start')}`,
+  ];
+
+  p.note(nextSteps.join('\n'), 'Next Steps');
+
+  p.outro(pc.green('claude-mem installed successfully!'));
+}

src/npx-cli/commands/runtime.ts

@@ -0,0 +1,184 @@
+/**
+ * Runtime command routing for `npx claude-mem start|stop|restart|status|search|transcript`.
+ *
+ * These commands delegate to the installed plugin's worker-service.cjs via Bun,
+ * or hit the worker's HTTP API directly (for `search`).
+ *
+ * Pure Node.js — no Bun APIs used.
+ */
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import pc from 'picocolors';
+import { resolveBunBinaryPath } from '../utils/bun-resolver.js';
+import { isPluginInstalled, marketplaceDirectory } from '../utils/paths.js';
+
+// ---------------------------------------------------------------------------
+// Installation guard
+// ---------------------------------------------------------------------------
+
+function ensureInstalledOrExit(): void {
+  if (!isPluginInstalled()) {
+    console.error(pc.red('claude-mem is not installed.'));
+    console.error(`Run: ${pc.bold('npx claude-mem install')}`);
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Bun guard
+// ---------------------------------------------------------------------------
+
+function resolveBunOrExit(): string {
+  const bunPath = resolveBunBinaryPath();
+  if (!bunPath) {
+    console.error(pc.red('Bun not found.'));
+    console.error('Install Bun: https://bun.sh');
+    console.error('After installation, restart your terminal.');
+    process.exit(1);
+  }
+  return bunPath;
+}
+
+// ---------------------------------------------------------------------------
+// Worker-service path
+// ---------------------------------------------------------------------------
+
+function workerServiceScriptPath(): string {
+  return join(marketplaceDirectory(), 'plugin', 'scripts', 'worker-service.cjs');
+}
+
+// ---------------------------------------------------------------------------
+// Spawn helper
+// ---------------------------------------------------------------------------
+
+function spawnBunWorkerCommand(command: string, extraArgs: string[] = []): void {
+  ensureInstalledOrExit();
+  const bunPath = resolveBunOrExit();
+  const workerScript = workerServiceScriptPath();
+
+  if (!existsSync(workerScript)) {
+    console.error(pc.red(`Worker script not found at: ${workerScript}`));
+    console.error('The installation may be corrupted. Try: npx claude-mem install');
+    process.exit(1);
+  }
+
+  const args = [workerScript, command, ...extraArgs];
+
+  const child = spawn(bunPath, args, {
+    stdio: 'inherit',
+    cwd: marketplaceDirectory(),
+    env: process.env,
+  });
+
+  child.on('error', (error) => {
+    console.error(pc.red(`Failed to start Bun: ${error.message}`));
+    process.exit(1);
+  });
+
+  child.on('close', (exitCode) => {
+    process.exit(exitCode ?? 0);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function runStartCommand(): void {
+  spawnBunWorkerCommand('start');
+}
+
+export function runStopCommand(): void {
+  spawnBunWorkerCommand('stop');
+}
+
+export function runRestartCommand(): void {
+  spawnBunWorkerCommand('restart');
+}
+
+export function runStatusCommand(): void {
+  spawnBunWorkerCommand('status');
+}
+
+/**
+ * Search the worker API at `GET /api/search?q=<query>`.
+ */
+export async function runSearchCommand(queryParts: string[]): Promise<void> {
+  ensureInstalledOrExit();
+
+  const query = queryParts.join(' ').trim();
+  if (!query) {
+    console.error(pc.red('Usage: npx claude-mem search <query>'));
+    process.exit(1);
+  }
+
+  const workerPort = process.env.CLAUDE_MEM_WORKER_PORT || '37777';
+  const searchUrl = `http://127.0.0.1:${workerPort}/api/search?q=${encodeURIComponent(query)}`;
+
+  try {
+    const response = await fetch(searchUrl);
+
+    if (!response.ok) {
+      if (response.status === 404) {
+        console.error(pc.red('Search endpoint not found. Is the worker running?'));
+        console.error(`Try: ${pc.bold('npx claude-mem start')}`);
+        process.exit(1);
+      }
+      console.error(pc.red(`Search failed: HTTP ${response.status}`));
+      process.exit(1);
+    }
+
+    const data = await response.json();
+
+    if (typeof data === 'object' && data !== null) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      console.log(data);
+    }
+  } catch (error: any) {
+    if (error?.cause?.code === 'ECONNREFUSED' || error?.message?.includes('ECONNREFUSED')) {
+      console.error(pc.red('Worker is not running.'));
+      console.error(`Start it with: ${pc.bold('npx claude-mem start')}`);
+      process.exit(1);
+    }
+    console.error(pc.red(`Search failed: ${error.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Start the transcript watcher via Bun.
+ */
+export function runTranscriptWatchCommand(): void {
+  ensureInstalledOrExit();
+  const bunPath = resolveBunOrExit();
+
+  const transcriptWatcherPath = join(
+    marketplaceDirectory(),
+    'plugin',
+    'scripts',
+    'transcript-watcher.cjs',
+  );
+
+  if (!existsSync(transcriptWatcherPath)) {
+    // Fall back to worker-service with transcript subcommand
+    spawnBunWorkerCommand('transcript', ['watch']);
+    return;
+  }
+
+  const child = spawn(bunPath, [transcriptWatcherPath, 'watch'], {
+    stdio: 'inherit',
+    cwd: marketplaceDirectory(),
+    env: process.env,
+  });
+
+  child.on('error', (error) => {
+    console.error(pc.red(`Failed to start transcript watcher: ${error.message}`));
+    process.exit(1);
+  });
+
+  child.on('close', (exitCode) => {
+    process.exit(exitCode ?? 0);
+  });
+}

src/npx-cli/commands/uninstall.ts

@@ -0,0 +1,171 @@
+/**
+ * Uninstall command for `npx claude-mem uninstall`.
+ *
+ * Removes the plugin from the marketplace directory, cache, plugin
+ * registrations, and Claude settings. Optionally cleans up IDE-specific
+ * configurations.
+ *
+ * Pure Node.js — no Bun APIs used.
+ */
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { existsSync, rmSync } from 'fs';
+import { join } from 'path';
+import {
+  claudeSettingsPath,
+  installedPluginsPath,
+  isPluginInstalled,
+  knownMarketplacesPath,
+  marketplaceDirectory,
+  pluginsDirectory,
+  readJsonFileSafe,
+  writeJsonFileAtomic,
+} from '../utils/paths.js';
+
+// ---------------------------------------------------------------------------
+// Cleanup helpers
+// ---------------------------------------------------------------------------
+
+function removeMarketplaceDirectory(): boolean {
+  const marketplaceDir = marketplaceDirectory();
+  if (existsSync(marketplaceDir)) {
+    rmSync(marketplaceDir, { recursive: true, force: true });
+    return true;
+  }
+  return false;
+}
+
+function removeCacheDirectory(): boolean {
+  const cacheBaseDirectory = join(pluginsDirectory(), 'cache', 'thedotmack');
+  if (existsSync(cacheBaseDirectory)) {
+    rmSync(cacheBaseDirectory, { recursive: true, force: true });
+    return true;
+  }
+  return false;
+}
+
+function removeFromKnownMarketplaces(): void {
+  const knownMarketplaces = readJsonFileSafe(knownMarketplacesPath());
+  if (knownMarketplaces['thedotmack']) {
+    delete knownMarketplaces['thedotmack'];
+    writeJsonFileAtomic(knownMarketplacesPath(), knownMarketplaces);
+  }
+}
+
+function removeFromInstalledPlugins(): void {
+  const installedPlugins = readJsonFileSafe(installedPluginsPath());
+  if (installedPlugins.plugins?.['claude-mem@thedotmack']) {
+    delete installedPlugins.plugins['claude-mem@thedotmack'];
+    writeJsonFileAtomic(installedPluginsPath(), installedPlugins);
+  }
+}
+
+function removeFromClaudeSettings(): void {
+  const settings = readJsonFileSafe(claudeSettingsPath());
+  if (settings.enabledPlugins?.['claude-mem@thedotmack'] !== undefined) {
+    delete settings.enabledPlugins['claude-mem@thedotmack'];
+    writeJsonFileAtomic(claudeSettingsPath(), settings);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export async function runUninstallCommand(): Promise<void> {
+  p.intro(pc.bgRed(pc.white(' claude-mem uninstall ')));
+
+  if (!isPluginInstalled()) {
+    p.log.warn('claude-mem does not appear to be installed.');
+
+    // Still offer to clean up partial state
+    if (process.stdin.isTTY) {
+      const shouldCleanup = await p.confirm({
+        message: 'Clean up any remaining registration data anyway?',
+        initialValue: false,
+      });
+
+      if (p.isCancel(shouldCleanup) || !shouldCleanup) {
+        p.outro('Nothing to do.');
+        return;
+      }
+    } else {
+      p.outro('Nothing to do.');
+      return;
+    }
+  } else if (process.stdin.isTTY) {
+    const shouldContinue = await p.confirm({
+      message: 'Are you sure you want to uninstall claude-mem?',
+      initialValue: false,
+    });
+
+    if (p.isCancel(shouldContinue) || !shouldContinue) {
+      p.cancel('Uninstall cancelled.');
+      return;
+    }
+  }
+
+  // Stop the worker first (best-effort)
+  try {
+    const workerPort = process.env.CLAUDE_MEM_WORKER_PORT || '37777';
+    await fetch(`http://127.0.0.1:${workerPort}/api/admin/shutdown`, {
+      method: 'POST',
+      signal: AbortSignal.timeout(5000),
+    });
+    p.log.info('Worker service stopped.');
+  } catch {
+    // Worker may not be running — that is fine
+  }
+
+  await p.tasks([
+    {
+      title: 'Removing marketplace directory',
+      task: async () => {
+        const removed = removeMarketplaceDirectory();
+        return removed
+          ? `Marketplace directory removed ${pc.green('OK')}`
+          : `Marketplace directory not found ${pc.dim('skipped')}`;
+      },
+    },
+    {
+      title: 'Removing cache directory',
+      task: async () => {
+        const removed = removeCacheDirectory();
+        return removed
+          ? `Cache directory removed ${pc.green('OK')}`
+          : `Cache directory not found ${pc.dim('skipped')}`;
+      },
+    },
+    {
+      title: 'Removing marketplace registration',
+      task: async () => {
+        removeFromKnownMarketplaces();
+        return `Marketplace registration removed ${pc.green('OK')}`;
+      },
+    },
+    {
+      title: 'Removing plugin registration',
+      task: async () => {
+        removeFromInstalledPlugins();
+        return `Plugin registration removed ${pc.green('OK')}`;
+      },
+    },
+    {
+      title: 'Removing from Claude settings',
+      task: async () => {
+        removeFromClaudeSettings();
+        return `Claude settings updated ${pc.green('OK')}`;
+      },
+    },
+  ]);
+
+  p.note(
+    [
+      `Your data directory at ${pc.cyan('~/.claude-mem')} was preserved.`,
+      'To remove it manually: rm -rf ~/.claude-mem',
+    ].join('\n'),
+    'Note',
+  );
+
+  p.outro(pc.green('claude-mem has been uninstalled.'));
+}

src/npx-cli/index.ts

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * NPX CLI entry point for claude-mem.
+ *
+ * Usage:
+ *   npx claude-mem                     → interactive install
+ *   npx claude-mem install             → interactive install
+ *   npx claude-mem install --ide <id>  → direct IDE setup
+ *   npx claude-mem update              → update to latest version
+ *   npx claude-mem uninstall           → remove plugin and IDE configs
+ *   npx claude-mem version             → print version
+ *   npx claude-mem start               → start worker service
+ *   npx claude-mem stop                → stop worker service
+ *   npx claude-mem restart             → restart worker service
+ *   npx claude-mem status              → show worker status
+ *   npx claude-mem search <query>      → search observations
+ *   npx claude-mem transcript watch    → start transcript watcher
+ *
+ * This file is pure Node.js — Bun is NOT required for install commands.
+ * Runtime commands (`start`, `stop`, etc.) delegate to Bun via the installed plugin.
+ */
+import pc from 'picocolors';
+import { readPluginVersion } from './utils/paths.js';
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+const command = args[0]?.toLowerCase() ?? '';
+
+// ---------------------------------------------------------------------------
+// Help text
+// ---------------------------------------------------------------------------
+
+function printHelp(): void {
+  const version = readPluginVersion();
+
+  console.log(`
+${pc.bold('claude-mem')} v${version} — persistent memory for AI coding assistants
+
+${pc.bold('Install Commands')} (no Bun required):
+  ${pc.cyan('npx claude-mem')}                     Interactive install
+  ${pc.cyan('npx claude-mem install')}              Interactive install
+  ${pc.cyan('npx claude-mem install --ide <id>')}   Install for specific IDE
+  ${pc.cyan('npx claude-mem update')}               Update to latest version
+  ${pc.cyan('npx claude-mem uninstall')}            Remove plugin and configs
+  ${pc.cyan('npx claude-mem version')}              Print version
+
+${pc.bold('Runtime Commands')} (requires Bun, delegates to installed plugin):
+  ${pc.cyan('npx claude-mem start')}                Start worker service
+  ${pc.cyan('npx claude-mem stop')}                 Stop worker service
+  ${pc.cyan('npx claude-mem restart')}              Restart worker service
+  ${pc.cyan('npx claude-mem status')}               Show worker status
+  ${pc.cyan('npx claude-mem search <query>')}       Search observations
+  ${pc.cyan('npx claude-mem transcript watch')}     Start transcript watcher
+
+${pc.bold('IDE Identifiers')}:
+  claude-code, cursor, gemini-cli, opencode, openclaw,
+  windsurf, codex-cli, copilot-cli, antigravity, goose,
+  crush, roo-code, warp
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Command routing
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  switch (command) {
+    // -- No command: default to install ------------------------------------
+    case '': {
+      const { runInstallCommand } = await import('./commands/install.js');
+      await runInstallCommand();
+      break;
+    }
+
+    // -- Install -----------------------------------------------------------
+    case 'install': {
+      const ideIndex = args.indexOf('--ide');
+      const ideValue = ideIndex !== -1 ? args[ideIndex + 1] : undefined;
+
+      const { runInstallCommand } = await import('./commands/install.js');
+      await runInstallCommand({ ide: ideValue });
+      break;
+    }
+
+    // -- Update (alias for install — overwrite with latest) ----------------
+    case 'update':
+    case 'upgrade': {
+      const { runInstallCommand } = await import('./commands/install.js');
+      await runInstallCommand();
+      break;
+    }
+
+    // -- Uninstall ---------------------------------------------------------
+    case 'uninstall':
+    case 'remove': {
+      const { runUninstallCommand } = await import('./commands/uninstall.js');
+      await runUninstallCommand();
+      break;
+    }
+
+    // -- Version -----------------------------------------------------------
+    case 'version':
+    case '--version':
+    case '-v': {
+      console.log(readPluginVersion());
+      break;
+    }
+
+    // -- Help --------------------------------------------------------------
+    case 'help':
+    case '--help':
+    case '-h': {
+      printHelp();
+      break;
+    }
+
+    // -- Runtime: start / stop / restart / status --------------------------
+    case 'start': {
+      const { runStartCommand } = await import('./commands/runtime.js');
+      runStartCommand();
+      break;
+    }
+    case 'stop': {
+      const { runStopCommand } = await import('./commands/runtime.js');
+      runStopCommand();
+      break;
+    }
+    case 'restart': {
+      const { runRestartCommand } = await import('./commands/runtime.js');
+      runRestartCommand();
+      break;
+    }
+    case 'status': {
+      const { runStatusCommand } = await import('./commands/runtime.js');
+      runStatusCommand();
+      break;
+    }
+
+    // -- Search ------------------------------------------------------------
+    case 'search': {
+      const { runSearchCommand } = await import('./commands/runtime.js');
+      await runSearchCommand(args.slice(1));
+      break;
+    }
+
+    // -- Transcript --------------------------------------------------------
+    case 'transcript': {
+      const subCommand = args[1]?.toLowerCase();
+      if (subCommand === 'watch') {
+        const { runTranscriptWatchCommand } = await import('./commands/runtime.js');
+        runTranscriptWatchCommand();
+      } else {
+        console.error(pc.red(`Unknown transcript subcommand: ${subCommand ?? '(none)'}`));
+        console.error(`Usage: npx claude-mem transcript watch`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    // -- Unknown -----------------------------------------------------------
+    default: {
+      console.error(pc.red(`Unknown command: ${command}`));
+      console.error(`Run ${pc.bold('npx claude-mem --help')} for usage information.`);
+      process.exit(1);
+    }
+  }
+}
+
+main().catch((error) => {
+  console.error(pc.red('Fatal error:'), error.message || error);
+  process.exit(1);
+});

src/npx-cli/utils/bun-resolver.ts

@@ -0,0 +1,85 @@
+/**
+ * Bun binary resolution utility.
+ *
+ * Extracted from `plugin/scripts/bun-runner.js` so that the NPX CLI
+ * can locate Bun without duplicating the search logic.
+ *
+ * Pure Node.js — no Bun APIs used.
+ */
+import { spawnSync } from 'child_process';
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { IS_WINDOWS } from './paths.js';
+
+/**
+ * Well-known locations where Bun might be installed, beyond PATH.
+ * Order matches the search priority in bun-runner.js and smart-install.js.
+ */
+function bunCandidatePaths(): string[] {
+  if (IS_WINDOWS) {
+    return [
+      join(homedir(), '.bun', 'bin', 'bun.exe'),
+      join(process.env.USERPROFILE || homedir(), '.bun', 'bin', 'bun.exe'),
+    ];
+  }
+
+  return [
+    join(homedir(), '.bun', 'bin', 'bun'),
+    '/usr/local/bin/bun',
+    '/opt/homebrew/bin/bun',
+    '/home/linuxbrew/.linuxbrew/bin/bun',
+  ];
+}
+
+/**
+ * Attempt to locate the Bun executable.
+ *
+ * 1. Check PATH via `which` / `where`.
+ * 2. Probe well-known installation directories.
+ *
+ * Returns the absolute path to the binary, `'bun'` if it is in PATH,
+ * or `null` if Bun cannot be found.
+ */
+export function resolveBunBinaryPath(): string | null {
+  // Try PATH first
+  const whichCommand = IS_WINDOWS ? 'where' : 'which';
+  const pathCheck = spawnSync(whichCommand, ['bun'], {
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    shell: IS_WINDOWS,
+  });
+
+  if (pathCheck.status === 0 && pathCheck.stdout.trim()) {
+    return 'bun'; // Available in PATH — use short name
+  }
+
+  // Probe known install locations
+  for (const candidatePath of bunCandidatePaths()) {
+    if (existsSync(candidatePath)) {
+      return candidatePath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get the installed Bun version string (e.g. `"1.2.3"`), or `null`
+ * if Bun is not available.
+ */
+export function getBunVersionString(): string | null {
+  const bunPath = resolveBunBinaryPath();
+  if (!bunPath) return null;
+
+  try {
+    const result = spawnSync(bunPath, ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS,
+    });
+    return result.status === 0 ? result.stdout.trim() : null;
+  } catch {
+    return null;
+  }
+}

src/npx-cli/utils/paths.ts

@@ -0,0 +1,152 @@
+/**
+ * Shared path utilities for the NPX CLI.
+ *
+ * All platform-specific path logic is centralized here so that every command
+ * resolves directories in exactly the same way, regardless of OS.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+// ---------------------------------------------------------------------------
+// Platform detection
+// ---------------------------------------------------------------------------
+
+export const IS_WINDOWS = process.platform === 'win32';
+
+// ---------------------------------------------------------------------------
+// Core paths
+// ---------------------------------------------------------------------------
+
+/** Root of the Claude Code config directory. */
+export function claudeConfigDirectory(): string {
+  return process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+}
+
+/** Marketplace install directory for thedotmack. */
+export function marketplaceDirectory(): string {
+  return join(claudeConfigDirectory(), 'plugins', 'marketplaces', 'thedotmack');
+}
+
+/** Top-level plugins directory. */
+export function pluginsDirectory(): string {
+  return join(claudeConfigDirectory(), 'plugins');
+}
+
+/** Path to `known_marketplaces.json`. */
+export function knownMarketplacesPath(): string {
+  return join(pluginsDirectory(), 'known_marketplaces.json');
+}
+
+/** Path to `installed_plugins.json`. */
+export function installedPluginsPath(): string {
+  return join(pluginsDirectory(), 'installed_plugins.json');
+}
+
+/** Path to `~/.claude/settings.json`. */
+export function claudeSettingsPath(): string {
+  return join(claudeConfigDirectory(), 'settings.json');
+}
+
+/** Plugin cache directory for a specific version. */
+export function pluginCacheDirectory(version: string): string {
+  return join(pluginsDirectory(), 'cache', 'thedotmack', 'claude-mem', version);
+}
+
+/** claude-mem data directory (default `~/.claude-mem`). */
+export function claudeMemDataDirectory(): string {
+  return join(homedir(), '.claude-mem');
+}
+
+// ---------------------------------------------------------------------------
+// NPM package root (where the NPX package lives on disk)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the root of the installed npm package.
+ *
+ * After bundling, the CLI entry point lives at `<pkg>/dist/npx-cli/index.js`.
+ * Walking up 2 levels from `import.meta.url` reaches the package root
+ * where `plugin/` and `package.json` can be found.
+ */
+export function npmPackageRootDirectory(): string {
+  const currentFilePath = fileURLToPath(import.meta.url);
+  // <pkg>/dist/npx-cli/index.js  ->  up 2 levels  ->  <pkg>
+  return join(dirname(currentFilePath), '..', '..');
+}
+
+/**
+ * Path to the `plugin/` directory bundled inside the npm package.
+ */
+export function npmPackagePluginDirectory(): string {
+  return join(npmPackageRootDirectory(), 'plugin');
+}
+
+// ---------------------------------------------------------------------------
+// Version helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the current plugin version from the npm package's
+ * `plugin/.claude-plugin/plugin.json` (preferred) or from `package.json`.
+ */
+export function readPluginVersion(): string {
+  // Try plugin.json first (authoritative for plugin version)
+  const pluginJsonPath = join(npmPackagePluginDirectory(), '.claude-plugin', 'plugin.json');
+  if (existsSync(pluginJsonPath)) {
+    try {
+      const pluginJson = JSON.parse(readFileSync(pluginJsonPath, 'utf-8'));
+      if (pluginJson.version) return pluginJson.version;
+    } catch {
+      // Fall through to package.json
+    }
+  }
+
+  // Fall back to package.json at package root
+  const packageJsonPath = join(npmPackageRootDirectory(), 'package.json');
+  if (existsSync(packageJsonPath)) {
+    try {
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+      if (packageJson.version) return packageJson.version;
+    } catch {
+      // Unable to read
+    }
+  }
+
+  return '0.0.0';
+}
+
+// ---------------------------------------------------------------------------
+// Installation detection
+// ---------------------------------------------------------------------------
+
+/** Returns true if the plugin appears to be installed in the marketplace dir. */
+export function isPluginInstalled(): boolean {
+  const marketplaceDir = marketplaceDirectory();
+  return existsSync(join(marketplaceDir, 'plugin', '.claude-plugin', 'plugin.json'));
+}
+
+// ---------------------------------------------------------------------------
+// JSON file helpers
+// ---------------------------------------------------------------------------
+
+export function ensureDirectoryExists(directoryPath: string): void {
+  if (!existsSync(directoryPath)) {
+    mkdirSync(directoryPath, { recursive: true });
+  }
+}
+
+export function readJsonFileSafe(filepath: string): any {
+  if (!existsSync(filepath)) return {};
+  try {
+    return JSON.parse(readFileSync(filepath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+export function writeJsonFileAtomic(filepath: string, data: any): void {
+  ensureDirectoryExists(dirname(filepath));
+  writeFileSync(filepath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}

src/services/integrations/CodexCliInstaller.ts

@@ -0,0 +1,373 @@
+/**
+ * CodexCliInstaller - Codex CLI integration for claude-mem
+ *
+ * Uses transcript-only watching (no notify hook). The watcher infrastructure
+ * already exists in src/services/transcripts/. This installer:
+ *
+ * 1. Writes/merges transcript-watch config to ~/.claude-mem/transcript-watch.json
+ * 2. Sets up watch for ~/.codex/sessions/**\/*.jsonl using existing watcher
+ * 3. Injects context via ~/.codex/AGENTS.md (Codex reads this natively)
+ *
+ * Anti-patterns:
+ *   - Does NOT add notify hooks -- transcript watching is sufficient
+ *   - Does NOT modify existing transcript watcher infrastructure
+ *   - Does NOT overwrite existing transcript-watch.json -- merges only
+ */
+
+import path from 'path';
+import { homedir } from 'os';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { logger } from '../../utils/logger.js';
+import { replaceTaggedContent } from '../../utils/claude-md-utils.js';
+import {
+  DEFAULT_CONFIG_PATH,
+  DEFAULT_STATE_PATH,
+  SAMPLE_CONFIG,
+} from '../transcripts/config.js';
+import type { TranscriptWatchConfig, WatchTarget } from '../transcripts/types.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const CODEX_DIR = path.join(homedir(), '.codex');
+const CODEX_AGENTS_MD_PATH = path.join(CODEX_DIR, 'AGENTS.md');
+const CLAUDE_MEM_DIR = path.join(homedir(), '.claude-mem');
+
+/**
+ * The watch name used to identify the Codex CLI entry in transcript-watch.json.
+ * Must match the name in SAMPLE_CONFIG for merging to work correctly.
+ */
+const CODEX_WATCH_NAME = 'codex';
+
+// ---------------------------------------------------------------------------
+// Transcript Watch Config Merging
+// ---------------------------------------------------------------------------
+
+/**
+ * Load existing transcript-watch.json, or return an empty config scaffold.
+ * Never throws -- returns a valid empty config on any parse error.
+ */
+function loadExistingTranscriptWatchConfig(): TranscriptWatchConfig {
+  const configPath = DEFAULT_CONFIG_PATH;
+
+  if (!existsSync(configPath)) {
+    return { version: 1, schemas: {}, watches: [], stateFile: DEFAULT_STATE_PATH };
+  }
+
+  try {
+    const raw = readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(raw) as TranscriptWatchConfig;
+
+    // Ensure required fields exist
+    if (!parsed.version) parsed.version = 1;
+    if (!parsed.watches) parsed.watches = [];
+    if (!parsed.schemas) parsed.schemas = {};
+    if (!parsed.stateFile) parsed.stateFile = DEFAULT_STATE_PATH;
+
+    return parsed;
+  } catch (parseError) {
+    logger.error('CODEX', 'Corrupt transcript-watch.json, creating backup', { path: configPath }, parseError as Error);
+
+    // Back up corrupt file
+    const backupPath = `${configPath}.backup.${Date.now()}`;
+    writeFileSync(backupPath, readFileSync(configPath));
+    console.warn(`  Backed up corrupt transcript-watch.json to ${backupPath}`);
+
+    return { version: 1, schemas: {}, watches: [], stateFile: DEFAULT_STATE_PATH };
+  }
+}
+
+/**
+ * Merge Codex watch configuration into existing transcript-watch.json.
+ *
+ * - If a watch with name 'codex' already exists, it is replaced in-place.
+ * - If the 'codex' schema already exists, it is replaced in-place.
+ * - All other watches and schemas are preserved untouched.
+ */
+function mergeCodexWatchConfig(existingConfig: TranscriptWatchConfig): TranscriptWatchConfig {
+  const merged = { ...existingConfig };
+
+  // Merge schemas: add/replace the codex schema
+  merged.schemas = { ...merged.schemas };
+  const codexSchema = SAMPLE_CONFIG.schemas?.[CODEX_WATCH_NAME];
+  if (codexSchema) {
+    merged.schemas[CODEX_WATCH_NAME] = codexSchema;
+  }
+
+  // Merge watches: add/replace the codex watch entry
+  const codexWatchFromSample = SAMPLE_CONFIG.watches.find(
+    (w: WatchTarget) => w.name === CODEX_WATCH_NAME,
+  );
+
+  if (codexWatchFromSample) {
+    const existingWatchIndex = merged.watches.findIndex(
+      (w: WatchTarget) => w.name === CODEX_WATCH_NAME,
+    );
+
+    if (existingWatchIndex !== -1) {
+      // Replace existing codex watch in-place
+      merged.watches[existingWatchIndex] = codexWatchFromSample;
+    } else {
+      // Append new codex watch
+      merged.watches.push(codexWatchFromSample);
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Write the merged transcript-watch.json config atomically.
+ */
+function writeTranscriptWatchConfig(config: TranscriptWatchConfig): void {
+  mkdirSync(CLAUDE_MEM_DIR, { recursive: true });
+  writeFileSync(DEFAULT_CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// Context Injection (AGENTS.md)
+// ---------------------------------------------------------------------------
+
+/**
+ * Inject claude-mem context section into ~/.codex/AGENTS.md.
+ * Uses the same <claude-mem-context> tag pattern as CLAUDE.md and GEMINI.md.
+ * Preserves any existing user content outside the tags.
+ */
+function injectCodexAgentsMdContext(): void {
+  try {
+    mkdirSync(CODEX_DIR, { recursive: true });
+
+    let existingContent = '';
+    if (existsSync(CODEX_AGENTS_MD_PATH)) {
+      existingContent = readFileSync(CODEX_AGENTS_MD_PATH, 'utf-8');
+    }
+
+    // Initial placeholder content -- will be populated after first session
+    const contextContent = [
+      '# Recent Activity',
+      '',
+      '<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->',
+      '',
+      '*No context yet. Complete your first session and context will appear here.*',
+    ].join('\n');
+
+    const finalContent = replaceTaggedContent(existingContent, contextContent);
+    writeFileSync(CODEX_AGENTS_MD_PATH, finalContent);
+    console.log(`  Injected context placeholder into ${CODEX_AGENTS_MD_PATH}`);
+  } catch (error) {
+    // Non-fatal -- transcript watching still works without context injection
+    logger.warn('CODEX', 'Failed to inject AGENTS.md context', { error: (error as Error).message });
+    console.warn(`  Warning: Could not inject context into AGENTS.md: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * Remove claude-mem context section from AGENTS.md.
+ * Preserves user content outside the <claude-mem-context> tags.
+ */
+function removeCodexAgentsMdContext(): void {
+  try {
+    if (!existsSync(CODEX_AGENTS_MD_PATH)) return;
+
+    const content = readFileSync(CODEX_AGENTS_MD_PATH, 'utf-8');
+    const startTag = '<claude-mem-context>';
+    const endTag = '</claude-mem-context>';
+
+    const startIdx = content.indexOf(startTag);
+    const endIdx = content.indexOf(endTag);
+
+    if (startIdx === -1 || endIdx === -1) return;
+
+    // Remove the tagged section and any surrounding blank lines
+    const before = content.substring(0, startIdx).replace(/\n+$/, '');
+    const after = content.substring(endIdx + endTag.length).replace(/^\n+/, '');
+    const finalContent = (before + (after ? '\n\n' + after : '')).trim();
+
+    if (finalContent) {
+      writeFileSync(CODEX_AGENTS_MD_PATH, finalContent + '\n');
+    } else {
+      // File would be empty -- leave it empty rather than deleting
+      // (user may have other tooling that expects it to exist)
+      writeFileSync(CODEX_AGENTS_MD_PATH, '');
+    }
+
+    console.log(`  Removed context section from ${CODEX_AGENTS_MD_PATH}`);
+  } catch (error) {
+    logger.warn('CODEX', 'Failed to clean AGENTS.md context', { error: (error as Error).message });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API: Install
+// ---------------------------------------------------------------------------
+
+/**
+ * Install Codex CLI integration for claude-mem.
+ *
+ * 1. Merges Codex transcript-watch config into ~/.claude-mem/transcript-watch.json
+ * 2. Injects context placeholder into ~/.codex/AGENTS.md
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export async function installCodexCli(): Promise<number> {
+  console.log('\nInstalling Claude-Mem for Codex CLI (transcript watching)...\n');
+
+  try {
+    // Step 1: Merge transcript-watch config
+    const existingConfig = loadExistingTranscriptWatchConfig();
+    const mergedConfig = mergeCodexWatchConfig(existingConfig);
+    writeTranscriptWatchConfig(mergedConfig);
+    console.log(`  Updated ${DEFAULT_CONFIG_PATH}`);
+    console.log(`  Watch path: ~/.codex/sessions/**/*.jsonl`);
+    console.log(`  Schema: codex (v${SAMPLE_CONFIG.schemas?.codex?.version ?? '?'})`);
+
+    // Step 2: Inject context into AGENTS.md
+    injectCodexAgentsMdContext();
+
+    console.log(`
+Installation complete!
+
+Transcript watch config: ${DEFAULT_CONFIG_PATH}
+Context file: ${CODEX_AGENTS_MD_PATH}
+
+How it works:
+  - claude-mem watches Codex session JSONL files for new activity
+  - No hooks needed -- transcript watching is fully automatic
+  - Context from past sessions is injected via ${CODEX_AGENTS_MD_PATH}
+
+Next steps:
+  1. Start claude-mem worker: npx claude-mem start
+  2. Use Codex CLI as usual -- memory capture is automatic!
+`);
+
+    return 0;
+  } catch (error) {
+    console.error(`\nInstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API: Uninstall
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove Codex CLI integration from claude-mem.
+ *
+ * 1. Removes the codex watch and schema from transcript-watch.json (preserves others)
+ * 2. Removes context section from AGENTS.md (preserves user content)
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export function uninstallCodexCli(): number {
+  console.log('\nUninstalling Claude-Mem Codex CLI integration...\n');
+
+  try {
+    // Step 1: Remove codex watch from transcript-watch.json
+    if (existsSync(DEFAULT_CONFIG_PATH)) {
+      const config = loadExistingTranscriptWatchConfig();
+
+      // Remove codex watch
+      config.watches = config.watches.filter(
+        (w: WatchTarget) => w.name !== CODEX_WATCH_NAME,
+      );
+
+      // Remove codex schema
+      if (config.schemas) {
+        delete config.schemas[CODEX_WATCH_NAME];
+      }
+
+      writeTranscriptWatchConfig(config);
+      console.log(`  Removed codex watch from ${DEFAULT_CONFIG_PATH}`);
+    } else {
+      console.log('  No transcript-watch.json found -- nothing to remove.');
+    }
+
+    // Step 2: Remove context section from AGENTS.md
+    removeCodexAgentsMdContext();
+
+    console.log('\nUninstallation complete!');
+    console.log('Restart claude-mem worker to apply changes.\n');
+
+    return 0;
+  } catch (error) {
+    console.error(`\nUninstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API: Status Check
+// ---------------------------------------------------------------------------
+
+/**
+ * Check Codex CLI integration status.
+ *
+ * @returns 0 always (informational)
+ */
+export function checkCodexCliStatus(): number {
+  console.log('\nClaude-Mem Codex CLI Integration Status\n');
+
+  // Check transcript-watch.json
+  if (!existsSync(DEFAULT_CONFIG_PATH)) {
+    console.log('Status: Not installed');
+    console.log(`  No transcript watch config at ${DEFAULT_CONFIG_PATH}`);
+    console.log('\nRun: npx claude-mem install --ide codex-cli\n');
+    return 0;
+  }
+
+  try {
+    const config = loadExistingTranscriptWatchConfig();
+    const codexWatch = config.watches.find(
+      (w: WatchTarget) => w.name === CODEX_WATCH_NAME,
+    );
+    const codexSchema = config.schemas?.[CODEX_WATCH_NAME];
+
+    if (!codexWatch) {
+      console.log('Status: Not installed');
+      console.log('  transcript-watch.json exists but no codex watch configured.');
+      console.log('\nRun: npx claude-mem install --ide codex-cli\n');
+      return 0;
+    }
+
+    console.log('Status: Installed');
+    console.log(`  Config: ${DEFAULT_CONFIG_PATH}`);
+    console.log(`  Watch path: ${codexWatch.path}`);
+    console.log(`  Schema: ${codexSchema ? `codex (v${codexSchema.version ?? '?'})` : 'missing'}`);
+    console.log(`  Start at end: ${codexWatch.startAtEnd ?? false}`);
+
+    // Check context config
+    if (codexWatch.context) {
+      console.log(`  Context mode: ${codexWatch.context.mode}`);
+      console.log(`  Context path: ${codexWatch.context.path ?? 'default'}`);
+      console.log(`  Context updates on: ${codexWatch.context.updateOn?.join(', ') ?? 'none'}`);
+    }
+
+    // Check AGENTS.md
+    if (existsSync(CODEX_AGENTS_MD_PATH)) {
+      const mdContent = readFileSync(CODEX_AGENTS_MD_PATH, 'utf-8');
+      if (mdContent.includes('<claude-mem-context>')) {
+        console.log(`  Context: Active (${CODEX_AGENTS_MD_PATH})`);
+      } else {
+        console.log(`  Context: AGENTS.md exists but no context tags`);
+      }
+    } else {
+      console.log(`  Context: No AGENTS.md file`);
+    }
+
+    // Check if ~/.codex/sessions exists (indicates Codex has been used)
+    const sessionsDir = path.join(CODEX_DIR, 'sessions');
+    if (existsSync(sessionsDir)) {
+      console.log(`  Sessions directory: exists`);
+    } else {
+      console.log(`  Sessions directory: not yet created (use Codex CLI to generate sessions)`);
+    }
+  } catch {
+    console.log('Status: Unknown');
+    console.log('  Could not parse transcript-watch.json.');
+  }
+
+  console.log('');
+  return 0;
+}

src/services/integrations/CursorHooksInstaller.ts

@@ -133,9 +133,7 @@ export function findMcpServerPath(): string | null {
   const possiblePaths = [
     // Marketplace install location
     path.join(MARKETPLACE_ROOT, 'plugin', 'scripts', 'mcp-server.cjs'),
-    // Development/source location (relative to built worker-service.cjs in plugin/scripts/)
+    // Development/source location
-    path.join(path.dirname(__filename), 'mcp-server.cjs'),
-    // Alternative dev location
     path.join(process.cwd(), 'plugin', 'scripts', 'mcp-server.cjs'),
   ];
 
@@ -155,9 +153,7 @@ export function findWorkerServicePath(): string | null {
   const possiblePaths = [
     // Marketplace install location
     path.join(MARKETPLACE_ROOT, 'plugin', 'scripts', 'worker-service.cjs'),
-    // Development/source location (relative to built worker-service.cjs in plugin/scripts/)
+    // Development/source location
-    path.join(path.dirname(__filename), 'worker-service.cjs'),
-    // Alternative dev location
     path.join(process.cwd(), 'plugin', 'scripts', 'worker-service.cjs'),
   ];
 

src/services/integrations/GeminiCliHooksInstaller.ts

@@ -0,0 +1,470 @@
+/**
+ * GeminiCliHooksInstaller - First-class Gemini CLI integration for claude-mem
+ *
+ * Installs claude-mem hooks into ~/.gemini/settings.json using deep merge
+ * to preserve any existing user configuration.
+ *
+ * Gemini CLI hook config format:
+ * {
+ *   "hooks": {
+ *     "AfterTool": [{
+ *       "matcher": "*",
+ *       "hooks": [{ "name": "claude-mem", "type": "command", "command": "...", "timeout": 5000, "description": "..." }]
+ *     }]
+ *   }
+ * }
+ *
+ * Registers 8 of 11 Gemini CLI hooks:
+ *   SessionStart  — inject memory context (via hookSpecificOutput.additionalContext)
+ *   BeforeAgent   — capture user prompt
+ *   AfterAgent    — capture full agent response
+ *   BeforeTool    — capture tool intent before execution
+ *   AfterTool     — capture all tool results (matcher: "*")
+ *   Notification  — capture system events (ToolPermission, etc.)
+ *   PreCompress   — trigger summary generation
+ *   SessionEnd    — finalize session
+ *
+ * Skipped (model-level, too chatty):
+ *   BeforeModel, AfterModel, BeforeToolSelection
+ */
+
+import path from 'path';
+import { homedir } from 'os';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { logger } from '../../utils/logger.js';
+import { replaceTaggedContent } from '../../utils/claude-md-utils.js';
+import { findBunPath, findWorkerServicePath } from './CursorHooksInstaller.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface GeminiHookEntry {
+  name: string;
+  type: 'command';
+  command: string;
+  timeout: number;
+  description?: string;
+}
+
+interface GeminiHookMatcher {
+  matcher: string;
+  hooks: GeminiHookEntry[];
+}
+
+interface GeminiSettingsJson {
+  hooks?: Record<string, GeminiHookMatcher[]>;
+  [otherKeys: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const GEMINI_DIR = path.join(homedir(), '.gemini');
+const GEMINI_SETTINGS_PATH = path.join(GEMINI_DIR, 'settings.json');
+const GEMINI_MD_PATH = path.join(GEMINI_DIR, 'GEMINI.md');
+const HOOK_NAME = 'claude-mem';
+const HOOK_TIMEOUT_MS = 5000;
+
+/**
+ * Gemini CLI events → claude-mem internal events.
+ *
+ * We register 8 of 11 hooks. Skipped: BeforeModel, AfterModel, BeforeToolSelection
+ * (model-level events fire per-LLM-call — too chatty for observation capture).
+ */
+interface GeminiEventConfig {
+  claudeMemEvent: string;
+  description: string;
+}
+
+const GEMINI_EVENTS: Record<string, GeminiEventConfig> = {
+  'SessionStart': { claudeMemEvent: 'context', description: 'Inject memory context from past sessions' },
+  'BeforeAgent': { claudeMemEvent: 'session-init', description: 'Initialize session and capture user prompt' },
+  'AfterAgent': { claudeMemEvent: 'observation', description: 'Capture full agent response' },
+  'BeforeTool': { claudeMemEvent: 'observation', description: 'Capture tool intent before execution' },
+  'AfterTool': { claudeMemEvent: 'observation', description: 'Capture tool results after execution' },
+  'Notification': { claudeMemEvent: 'observation', description: 'Capture system events (permissions, etc.)' },
+  'PreCompress': { claudeMemEvent: 'summarize', description: 'Generate session summary before compression' },
+  'SessionEnd': { claudeMemEvent: 'session-complete', description: 'Finalize session and persist memory' },
+};
+
+// ---------------------------------------------------------------------------
+// Deep Merge for Hook Arrays
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge claude-mem hooks into an existing event's hook matcher array.
+ * If a matcher with the same `matcher` value already has a hook named "claude-mem",
+ * it is replaced. Otherwise, the hook is appended.
+ */
+function mergeHookMatchers(
+  existingMatchers: GeminiHookMatcher[],
+  newMatcher: GeminiHookMatcher,
+): GeminiHookMatcher[] {
+  const result = [...existingMatchers];
+
+  const existingMatcherIndex = result.findIndex(
+    (m) => m.matcher === newMatcher.matcher,
+  );
+
+  if (existingMatcherIndex !== -1) {
+    // Matcher exists — replace or add our hook within it
+    const existing = result[existingMatcherIndex];
+    const hookIndex = existing.hooks.findIndex((h) => h.name === HOOK_NAME);
+    if (hookIndex !== -1) {
+      existing.hooks[hookIndex] = newMatcher.hooks[0];
+    } else {
+      existing.hooks.push(newMatcher.hooks[0]);
+    }
+  } else {
+    // No matching matcher — add the whole entry
+    result.push(newMatcher);
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Hook Installation
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the hook command string for a given Gemini CLI event.
+ *
+ * Invokes: <bun-path> <worker-service.cjs> hook gemini-cli <event>
+ */
+function buildHookCommand(bunPath: string, workerServicePath: string, claudeMemEvent: string): string {
+  const escapedBunPath = bunPath.replace(/\\/g, '\\\\');
+  const escapedWorkerPath = workerServicePath.replace(/\\/g, '\\\\');
+  return `"${escapedBunPath}" "${escapedWorkerPath}" hook gemini-cli ${claudeMemEvent}`;
+}
+
+/**
+ * Install claude-mem hooks into Gemini CLI's settings.json.
+ * Deep-merges with existing configuration — never overwrites.
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export async function installGeminiCliHooks(): Promise<number> {
+  console.log('\nInstalling Claude-Mem Gemini CLI hooks...\n');
+
+  // Find required paths
+  const workerServicePath = findWorkerServicePath();
+  if (!workerServicePath) {
+    console.error('Could not find worker-service.cjs');
+    console.error('   Expected at: ~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/worker-service.cjs');
+    return 1;
+  }
+
+  const bunPath = findBunPath();
+  console.log(`  Using Bun runtime: ${bunPath}`);
+  console.log(`  Worker service: ${workerServicePath}`);
+
+  try {
+    // Ensure ~/.gemini exists
+    mkdirSync(GEMINI_DIR, { recursive: true });
+
+    // Read existing settings (deep merge, never overwrite)
+    let settings: GeminiSettingsJson = {};
+    if (existsSync(GEMINI_SETTINGS_PATH)) {
+      try {
+        settings = JSON.parse(readFileSync(GEMINI_SETTINGS_PATH, 'utf-8'));
+      } catch (parseError) {
+        logger.error('GEMINI', 'Corrupt settings.json, creating backup', { path: GEMINI_SETTINGS_PATH }, parseError as Error);
+        // Back up corrupt file
+        const backupPath = `${GEMINI_SETTINGS_PATH}.backup.${Date.now()}`;
+        writeFileSync(backupPath, readFileSync(GEMINI_SETTINGS_PATH));
+        console.warn(`  Backed up corrupt settings.json to ${backupPath}`);
+        settings = {};
+      }
+    }
+
+    // Initialize hooks object if missing
+    if (!settings.hooks) {
+      settings.hooks = {};
+    }
+
+    // Register each event
+    for (const [geminiEvent, config] of Object.entries(GEMINI_EVENTS)) {
+      const command = buildHookCommand(bunPath, workerServicePath, config.claudeMemEvent);
+
+      const newMatcher: GeminiHookMatcher = {
+        matcher: '*',
+        hooks: [{
+          name: HOOK_NAME,
+          type: 'command',
+          command,
+          timeout: HOOK_TIMEOUT_MS,
+          description: config.description,
+        }],
+      };
+
+      const existingMatchers = settings.hooks[geminiEvent] ?? [];
+      settings.hooks[geminiEvent] = mergeHookMatchers(existingMatchers, newMatcher);
+    }
+
+    // Write merged settings
+    writeFileSync(GEMINI_SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+    console.log(`  Updated ${GEMINI_SETTINGS_PATH}`);
+    console.log(`  Registered hooks for: ${Object.keys(GEMINI_EVENTS).join(', ')}`);
+
+    // Inject context into GEMINI.md
+    injectGeminiMdContext();
+
+    console.log(`
+Installation complete! (8 hooks registered)
+
+Hooks installed to: ${GEMINI_SETTINGS_PATH}
+Using unified CLI: bun worker-service.cjs hook gemini-cli <event>
+
+Registered hooks:
+  SessionStart  → Inject memory context from past sessions
+  BeforeAgent   → Capture user prompt for memory
+  AfterAgent    → Capture full agent response
+  BeforeTool    → Capture tool intent before execution
+  AfterTool     → Capture tool results after execution
+  Notification  → Capture system events (permissions, etc.)
+  PreCompress   → Generate session summary before compression
+  SessionEnd    → Finalize session and persist memory
+
+Next steps:
+  1. Start claude-mem worker: npx claude-mem start
+  2. Restart Gemini CLI to load the hooks
+  3. Memory capture is now automatic!
+
+Context Injection:
+  Memory from past sessions is injected via hookSpecificOutput.additionalContext
+  on SessionStart, and persisted in ${GEMINI_MD_PATH} for static context.
+`);
+
+    return 0;
+  } catch (error) {
+    console.error(`\nInstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Context Injection (GEMINI.md)
+// ---------------------------------------------------------------------------
+
+/**
+ * Inject claude-mem context section into ~/.gemini/GEMINI.md.
+ * Uses the same <claude-mem-context> tag pattern as CLAUDE.md.
+ * Preserves any existing user content outside the tags.
+ */
+function injectGeminiMdContext(): void {
+  try {
+    let existingContent = '';
+    if (existsSync(GEMINI_MD_PATH)) {
+      existingContent = readFileSync(GEMINI_MD_PATH, 'utf-8');
+    }
+
+    // Initial placeholder content — will be populated after first session
+    const contextContent = [
+      '# Recent Activity',
+      '',
+      '<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->',
+      '',
+      '*No context yet. Complete your first session and context will appear here.*',
+    ].join('\n');
+
+    const finalContent = replaceTaggedContent(existingContent, contextContent);
+    writeFileSync(GEMINI_MD_PATH, finalContent);
+    console.log(`  Injected context placeholder into ${GEMINI_MD_PATH}`);
+  } catch (error) {
+    // Non-fatal — hooks still work without context injection
+    logger.warn('GEMINI', 'Failed to inject GEMINI.md context', { error: (error as Error).message });
+    console.warn(`  Warning: Could not inject context into GEMINI.md: ${(error as Error).message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Uninstallation
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove claude-mem hooks from Gemini CLI settings.json.
+ * Preserves all other hooks and settings.
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export function uninstallGeminiCliHooks(): number {
+  console.log('\nUninstalling Claude-Mem Gemini CLI hooks...\n');
+
+  try {
+    if (!existsSync(GEMINI_SETTINGS_PATH)) {
+      console.log('  No settings.json found — nothing to uninstall.');
+      return 0;
+    }
+
+    let settings: GeminiSettingsJson;
+    try {
+      settings = JSON.parse(readFileSync(GEMINI_SETTINGS_PATH, 'utf-8'));
+    } catch {
+      console.error('  Could not parse settings.json');
+      return 1;
+    }
+
+    if (!settings.hooks) {
+      console.log('  No hooks configured — nothing to uninstall.');
+      return 0;
+    }
+
+    let removedCount = 0;
+
+    // Remove claude-mem hooks from each event
+    for (const eventName of Object.keys(settings.hooks)) {
+      const matchers = settings.hooks[eventName];
+      if (!Array.isArray(matchers)) continue;
+
+      for (const matcher of matchers) {
+        if (!Array.isArray(matcher.hooks)) continue;
+        const beforeLength = matcher.hooks.length;
+        matcher.hooks = matcher.hooks.filter((h) => h.name !== HOOK_NAME);
+        removedCount += beforeLength - matcher.hooks.length;
+      }
+
+      // Clean up empty matchers
+      settings.hooks[eventName] = matchers.filter(
+        (m) => m.hooks.length > 0,
+      );
+
+      // Clean up empty event arrays
+      if (settings.hooks[eventName].length === 0) {
+        delete settings.hooks[eventName];
+      }
+    }
+
+    // Clean up empty hooks object
+    if (Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks;
+    }
+
+    writeFileSync(GEMINI_SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+    console.log(`  Removed ${removedCount} claude-mem hook(s) from settings.json`);
+
+    // Remove context section from GEMINI.md
+    removeGeminiMdContext();
+
+    console.log('\nUninstallation complete!');
+    console.log('Restart Gemini CLI to apply changes.\n');
+
+    return 0;
+  } catch (error) {
+    console.error(`\nUninstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+/**
+ * Remove claude-mem context section from GEMINI.md.
+ * Preserves user content outside the <claude-mem-context> tags.
+ */
+function removeGeminiMdContext(): void {
+  try {
+    if (!existsSync(GEMINI_MD_PATH)) return;
+
+    const content = readFileSync(GEMINI_MD_PATH, 'utf-8');
+    const startTag = '<claude-mem-context>';
+    const endTag = '</claude-mem-context>';
+
+    const startIdx = content.indexOf(startTag);
+    const endIdx = content.indexOf(endTag);
+
+    if (startIdx === -1 || endIdx === -1) return;
+
+    // Remove the tagged section and any surrounding blank lines
+    const before = content.substring(0, startIdx).replace(/\n+$/, '');
+    const after = content.substring(endIdx + endTag.length).replace(/^\n+/, '');
+    const finalContent = (before + (after ? '\n\n' + after : '')).trim();
+
+    if (finalContent) {
+      writeFileSync(GEMINI_MD_PATH, finalContent + '\n');
+    } else {
+      // File would be empty — leave it empty rather than deleting
+      // (user may have other tooling that expects it to exist)
+      writeFileSync(GEMINI_MD_PATH, '');
+    }
+
+    console.log(`  Removed context section from ${GEMINI_MD_PATH}`);
+  } catch (error) {
+    logger.warn('GEMINI', 'Failed to clean GEMINI.md context', { error: (error as Error).message });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Status Check
+// ---------------------------------------------------------------------------
+
+/**
+ * Check Gemini CLI hooks installation status.
+ *
+ * @returns 0 always (informational)
+ */
+export function checkGeminiCliHooksStatus(): number {
+  console.log('\nClaude-Mem Gemini CLI Hooks Status\n');
+
+  if (!existsSync(GEMINI_SETTINGS_PATH)) {
+    console.log('Status: Not installed');
+    console.log(`  No settings file at ${GEMINI_SETTINGS_PATH}`);
+    console.log('\nRun: npx claude-mem install --ide gemini-cli\n');
+    return 0;
+  }
+
+  try {
+    const settings: GeminiSettingsJson = JSON.parse(readFileSync(GEMINI_SETTINGS_PATH, 'utf-8'));
+
+    if (!settings.hooks) {
+      console.log('Status: Not installed');
+      console.log('  settings.json exists but has no hooks section.');
+      return 0;
+    }
+
+    const installedEvents: string[] = [];
+    for (const [eventName, matchers] of Object.entries(settings.hooks)) {
+      if (!Array.isArray(matchers)) continue;
+      for (const matcher of matchers) {
+        if (matcher.hooks?.some((h: GeminiHookEntry) => h.name === HOOK_NAME)) {
+          installedEvents.push(eventName);
+        }
+      }
+    }
+
+    if (installedEvents.length === 0) {
+      console.log('Status: Not installed');
+      console.log('  settings.json exists but no claude-mem hooks found.');
+    } else {
+      console.log('Status: Installed');
+      console.log(`  Config: ${GEMINI_SETTINGS_PATH}`);
+      console.log(`  Events: ${installedEvents.join(', ')}`);
+
+      // Check GEMINI.md context
+      if (existsSync(GEMINI_MD_PATH)) {
+        const mdContent = readFileSync(GEMINI_MD_PATH, 'utf-8');
+        if (mdContent.includes('<claude-mem-context>')) {
+          console.log(`  Context: Active (${GEMINI_MD_PATH})`);
+        } else {
+          console.log(`  Context: GEMINI.md exists but no context tags`);
+        }
+      } else {
+        console.log(`  Context: No GEMINI.md file`);
+      }
+
+      // Check expected vs actual events
+      const expectedEvents = Object.keys(GEMINI_EVENTS);
+      const missingEvents = expectedEvents.filter((e) => !installedEvents.includes(e));
+      if (missingEvents.length > 0) {
+        console.log(`  Warning: Missing events: ${missingEvents.join(', ')}`);
+        console.log('  Run install again to add missing hooks.');
+      }
+    }
+  } catch {
+    console.log('Status: Unknown');
+    console.log('  Could not parse settings.json.');
+  }
+
+  console.log('');
+  return 0;
+}

src/services/integrations/McpIntegrations.ts

@@ -0,0 +1,610 @@
+/**
+ * McpIntegrations - MCP-based IDE integrations for claude-mem
+ *
+ * Handles MCP config writing and context injection for IDEs that support
+ * the Model Context Protocol. These are "MCP-only" integrations: they provide
+ * search tools and context injection but do NOT capture transcripts.
+ *
+ * Supported IDEs:
+ *   - Copilot CLI
+ *   - Antigravity (Gemini)
+ *   - Goose
+ *   - Crush
+ *   - Roo Code
+ *   - Warp
+ *
+ * All IDEs point to the same MCP server: plugin/scripts/mcp-server.cjs
+ */
+
+import path from 'path';
+import { homedir } from 'os';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { logger } from '../../utils/logger.js';
+import { findMcpServerPath } from './CursorHooksInstaller.js';
+
+// ============================================================================
+// Shared Constants
+// ============================================================================
+
+const CONTEXT_TAG_OPEN = '<claude-mem-context>';
+const CONTEXT_TAG_CLOSE = '</claude-mem-context>';
+
+const PLACEHOLDER_CONTEXT = `# claude-mem: Cross-Session Memory
+
+*No context yet. Complete your first session and context will appear here.*
+
+Use claude-mem's MCP search tools for manual memory queries.`;
+
+// ============================================================================
+// Shared Utilities
+// ============================================================================
+
+/**
+ * Build the standard MCP server entry that all IDEs use.
+ * Points to the same mcp-server.cjs script.
+ */
+function buildMcpServerEntry(mcpServerPath: string): { command: string; args: string[] } {
+  return {
+    command: 'node',
+    args: [mcpServerPath],
+  };
+}
+
+/**
+ * Read a JSON file safely, returning a default value if it doesn't exist or is corrupt.
+ */
+function readJsonSafe<T>(filePath: string, defaultValue: T): T {
+  if (!existsSync(filePath)) return defaultValue;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch (error) {
+    logger.error('MCP', `Corrupt JSON file, using default`, { path: filePath }, error as Error);
+    return defaultValue;
+  }
+}
+
+/**
+ * Inject or update a <claude-mem-context> section in a markdown file.
+ * Creates the file if it doesn't exist. Preserves content outside the tags.
+ */
+function injectContextIntoMarkdownFile(filePath: string, contextContent: string): void {
+  const parentDirectory = path.dirname(filePath);
+  mkdirSync(parentDirectory, { recursive: true });
+
+  const wrappedContent = `${CONTEXT_TAG_OPEN}\n${contextContent}\n${CONTEXT_TAG_CLOSE}`;
+
+  if (existsSync(filePath)) {
+    let existingContent = readFileSync(filePath, 'utf-8');
+
+    const tagStartIndex = existingContent.indexOf(CONTEXT_TAG_OPEN);
+    const tagEndIndex = existingContent.indexOf(CONTEXT_TAG_CLOSE);
+
+    if (tagStartIndex !== -1 && tagEndIndex !== -1) {
+      // Replace existing section
+      existingContent =
+        existingContent.slice(0, tagStartIndex) +
+        wrappedContent +
+        existingContent.slice(tagEndIndex + CONTEXT_TAG_CLOSE.length);
+    } else {
+      // Append section
+      existingContent = existingContent.trimEnd() + '\n\n' + wrappedContent + '\n';
+    }
+
+    writeFileSync(filePath, existingContent, 'utf-8');
+  } else {
+    writeFileSync(filePath, wrappedContent + '\n', 'utf-8');
+  }
+}
+
+/**
+ * Write a standard MCP JSON config file, merging with existing config.
+ * Supports both { "mcpServers": { ... } } and { "servers": { ... } } formats.
+ */
+function writeMcpJsonConfig(
+  configFilePath: string,
+  mcpServerPath: string,
+  serversKeyName: string = 'mcpServers',
+): void {
+  const parentDirectory = path.dirname(configFilePath);
+  mkdirSync(parentDirectory, { recursive: true });
+
+  const existingConfig = readJsonSafe<Record<string, any>>(configFilePath, {});
+
+  if (!existingConfig[serversKeyName]) {
+    existingConfig[serversKeyName] = {};
+  }
+
+  existingConfig[serversKeyName]['claude-mem'] = buildMcpServerEntry(mcpServerPath);
+
+  writeFileSync(configFilePath, JSON.stringify(existingConfig, null, 2) + '\n');
+}
+
+// ============================================================================
+// Copilot CLI
+// ============================================================================
+
+/**
+ * Get the Copilot CLI MCP config path.
+ * Copilot CLI uses ~/.github/copilot/mcp.json for user-level MCP config.
+ */
+function getCopilotCliMcpConfigPath(): string {
+  return path.join(homedir(), '.github', 'copilot', 'mcp.json');
+}
+
+/**
+ * Get the Copilot CLI context injection path for the current workspace.
+ * Copilot reads instructions from .github/copilot-instructions.md in the workspace.
+ */
+function getCopilotCliContextPath(): string {
+  return path.join(process.cwd(), '.github', 'copilot-instructions.md');
+}
+
+/**
+ * Install claude-mem MCP integration for Copilot CLI.
+ *
+ * - Writes MCP config to ~/.github/copilot/mcp.json
+ * - Injects context into .github/copilot-instructions.md in the workspace
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export async function installCopilotCliMcpIntegration(): Promise<number> {
+  console.log('\nInstalling Claude-Mem MCP integration for Copilot CLI...\n');
+
+  const mcpServerPath = findMcpServerPath();
+  if (!mcpServerPath) {
+    console.error('Could not find MCP server script');
+    console.error('   Expected at: ~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs');
+    return 1;
+  }
+
+  try {
+    // Write MCP config — Copilot CLI uses { "servers": { ... } } format
+    const configPath = getCopilotCliMcpConfigPath();
+    writeMcpJsonConfig(configPath, mcpServerPath, 'servers');
+    console.log(`  MCP config written to: ${configPath}`);
+
+    // Inject context into workspace instructions
+    const contextPath = getCopilotCliContextPath();
+    injectContextIntoMarkdownFile(contextPath, PLACEHOLDER_CONTEXT);
+    console.log(`  Context placeholder written to: ${contextPath}`);
+
+    console.log(`
+Installation complete!
+
+MCP config:  ${configPath}
+Context:     ${contextPath}
+
+Note: This is an MCP-only integration providing search tools and context.
+Transcript capture is not available for Copilot CLI.
+
+Next steps:
+  1. Start claude-mem worker: npx claude-mem start
+  2. Restart Copilot CLI to pick up the MCP server
+`);
+
+    return 0;
+  } catch (error) {
+    console.error(`\nInstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+// ============================================================================
+// Antigravity
+// ============================================================================
+
+/**
+ * Get the Antigravity MCP config path.
+ * Antigravity stores MCP config at ~/.gemini/antigravity/mcp_config.json.
+ */
+function getAntigravityMcpConfigPath(): string {
+  return path.join(homedir(), '.gemini', 'antigravity', 'mcp_config.json');
+}
+
+/**
+ * Get the Antigravity context injection path for the current workspace.
+ * Antigravity reads agent rules from .agent/rules/ in the workspace.
+ */
+function getAntigravityContextPath(): string {
+  return path.join(process.cwd(), '.agent', 'rules', 'claude-mem-context.md');
+}
+
+/**
+ * Install claude-mem MCP integration for Antigravity.
+ *
+ * - Writes MCP config to ~/.gemini/antigravity/mcp_config.json
+ * - Injects context into .agent/rules/claude-mem-context.md in the workspace
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export async function installAntigravityMcpIntegration(): Promise<number> {
+  console.log('\nInstalling Claude-Mem MCP integration for Antigravity...\n');
+
+  const mcpServerPath = findMcpServerPath();
+  if (!mcpServerPath) {
+    console.error('Could not find MCP server script');
+    console.error('   Expected at: ~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs');
+    return 1;
+  }
+
+  try {
+    // Write MCP config
+    const configPath = getAntigravityMcpConfigPath();
+    writeMcpJsonConfig(configPath, mcpServerPath);
+    console.log(`  MCP config written to: ${configPath}`);
+
+    // Inject context into workspace rules
+    const contextPath = getAntigravityContextPath();
+    injectContextIntoMarkdownFile(contextPath, PLACEHOLDER_CONTEXT);
+    console.log(`  Context placeholder written to: ${contextPath}`);
+
+    console.log(`
+Installation complete!
+
+MCP config:  ${configPath}
+Context:     ${contextPath}
+
+Note: This is an MCP-only integration providing search tools and context.
+Transcript capture is not available for Antigravity.
+
+Next steps:
+  1. Start claude-mem worker: npx claude-mem start
+  2. Restart Antigravity to pick up the MCP server
+`);
+
+    return 0;
+  } catch (error) {
+    console.error(`\nInstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+// ============================================================================
+// Goose
+// ============================================================================
+
+/**
+ * Get the Goose config path.
+ * Goose stores its config at ~/.config/goose/config.yaml.
+ */
+function getGooseConfigPath(): string {
+  return path.join(homedir(), '.config', 'goose', 'config.yaml');
+}
+
+/**
+ * Check if a YAML string already has a claude-mem entry under mcpServers.
+ * Uses string matching to avoid needing a YAML parser.
+ */
+function gooseConfigHasClaudeMemEntry(yamlContent: string): boolean {
+  // Look for "claude-mem:" indented under mcpServers
+  return yamlContent.includes('claude-mem:') &&
+    yamlContent.includes('mcpServers:');
+}
+
+/**
+ * Build the Goose YAML MCP server block as a string.
+ * Produces properly indented YAML without needing a parser.
+ */
+function buildGooseMcpYamlBlock(mcpServerPath: string): string {
+  // Goose expects the mcpServers section at the top level
+  return [
+    'mcpServers:',
+    '  claude-mem:',
+    '    command: node',
+    '    args:',
+    `      - ${mcpServerPath}`,
+  ].join('\n');
+}
+
+/**
+ * Build just the claude-mem server entry (for appending under existing mcpServers).
+ */
+function buildGooseClaudeMemEntryYaml(mcpServerPath: string): string {
+  return [
+    '  claude-mem:',
+    '    command: node',
+    '    args:',
+    `      - ${mcpServerPath}`,
+  ].join('\n');
+}
+
+/**
+ * Install claude-mem MCP integration for Goose.
+ *
+ * - Writes/merges MCP config into ~/.config/goose/config.yaml
+ * - Uses string manipulation for YAML (no parser dependency)
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export async function installGooseMcpIntegration(): Promise<number> {
+  console.log('\nInstalling Claude-Mem MCP integration for Goose...\n');
+
+  const mcpServerPath = findMcpServerPath();
+  if (!mcpServerPath) {
+    console.error('Could not find MCP server script');
+    console.error('   Expected at: ~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs');
+    return 1;
+  }
+
+  try {
+    const configPath = getGooseConfigPath();
+    const configDirectory = path.dirname(configPath);
+    mkdirSync(configDirectory, { recursive: true });
+
+    if (existsSync(configPath)) {
+      let yamlContent = readFileSync(configPath, 'utf-8');
+
+      if (gooseConfigHasClaudeMemEntry(yamlContent)) {
+        // Already configured — replace the claude-mem block
+        // Find the claude-mem entry and replace it
+        const claudeMemPattern = /( {2}claude-mem:\n(?:.*\n)*?(?= {2}\S|\n\n|$))/;
+        const newEntry = buildGooseClaudeMemEntryYaml(mcpServerPath) + '\n';
+
+        if (claudeMemPattern.test(yamlContent)) {
+          yamlContent = yamlContent.replace(claudeMemPattern, newEntry);
+        }
+        writeFileSync(configPath, yamlContent);
+        console.log(`  Updated existing claude-mem entry in: ${configPath}`);
+      } else if (yamlContent.includes('mcpServers:')) {
+        // mcpServers section exists but no claude-mem entry — append under it
+        const mcpServersIndex = yamlContent.indexOf('mcpServers:');
+        const insertionPoint = mcpServersIndex + 'mcpServers:'.length;
+        const newEntry = '\n' + buildGooseClaudeMemEntryYaml(mcpServerPath);
+
+        yamlContent =
+          yamlContent.slice(0, insertionPoint) +
+          newEntry +
+          yamlContent.slice(insertionPoint);
+
+        writeFileSync(configPath, yamlContent);
+        console.log(`  Added claude-mem to existing mcpServers in: ${configPath}`);
+      } else {
+        // No mcpServers section — append the entire block
+        const mcpBlock = '\n' + buildGooseMcpYamlBlock(mcpServerPath) + '\n';
+        yamlContent = yamlContent.trimEnd() + '\n' + mcpBlock;
+        writeFileSync(configPath, yamlContent);
+        console.log(`  Appended mcpServers section to: ${configPath}`);
+      }
+    } else {
+      // File doesn't exist — create from template
+      const templateContent = buildGooseMcpYamlBlock(mcpServerPath) + '\n';
+      writeFileSync(configPath, templateContent);
+      console.log(`  Created config with MCP server: ${configPath}`);
+    }
+
+    console.log(`
+Installation complete!
+
+MCP config:  ${configPath}
+
+Note: This is an MCP-only integration providing search tools and context.
+Transcript capture is not available for Goose.
+
+Next steps:
+  1. Start claude-mem worker: npx claude-mem start
+  2. Restart Goose to pick up the MCP server
+`);
+
+    return 0;
+  } catch (error) {
+    console.error(`\nInstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+// ============================================================================
+// Crush
+// ============================================================================
+
+/**
+ * Get the Crush MCP config path.
+ * Crush stores MCP config at ~/.config/crush/mcp.json.
+ */
+function getCrushMcpConfigPath(): string {
+  return path.join(homedir(), '.config', 'crush', 'mcp.json');
+}
+
+/**
+ * Install claude-mem MCP integration for Crush.
+ *
+ * - Writes MCP config to ~/.config/crush/mcp.json
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export async function installCrushMcpIntegration(): Promise<number> {
+  console.log('\nInstalling Claude-Mem MCP integration for Crush...\n');
+
+  const mcpServerPath = findMcpServerPath();
+  if (!mcpServerPath) {
+    console.error('Could not find MCP server script');
+    console.error('   Expected at: ~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs');
+    return 1;
+  }
+
+  try {
+    // Write MCP config
+    const configPath = getCrushMcpConfigPath();
+    writeMcpJsonConfig(configPath, mcpServerPath);
+    console.log(`  MCP config written to: ${configPath}`);
+
+    console.log(`
+Installation complete!
+
+MCP config:  ${configPath}
+
+Note: This is an MCP-only integration providing search tools and context.
+Transcript capture is not available for Crush.
+
+Next steps:
+  1. Start claude-mem worker: npx claude-mem start
+  2. Restart Crush to pick up the MCP server
+`);
+
+    return 0;
+  } catch (error) {
+    console.error(`\nInstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+// ============================================================================
+// Roo Code
+// ============================================================================
+
+/**
+ * Get the Roo Code MCP config path for the current workspace.
+ * Roo Code reads MCP config from .roo/mcp.json in the workspace.
+ */
+function getRooCodeMcpConfigPath(): string {
+  return path.join(process.cwd(), '.roo', 'mcp.json');
+}
+
+/**
+ * Get the Roo Code context injection path for the current workspace.
+ * Roo Code reads rules from .roo/rules/ in the workspace.
+ */
+function getRooCodeContextPath(): string {
+  return path.join(process.cwd(), '.roo', 'rules', 'claude-mem-context.md');
+}
+
+/**
+ * Install claude-mem MCP integration for Roo Code.
+ *
+ * - Writes MCP config to .roo/mcp.json in the workspace
+ * - Injects context into .roo/rules/claude-mem-context.md in the workspace
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export async function installRooCodeMcpIntegration(): Promise<number> {
+  console.log('\nInstalling Claude-Mem MCP integration for Roo Code...\n');
+
+  const mcpServerPath = findMcpServerPath();
+  if (!mcpServerPath) {
+    console.error('Could not find MCP server script');
+    console.error('   Expected at: ~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs');
+    return 1;
+  }
+
+  try {
+    // Write MCP config to workspace
+    const configPath = getRooCodeMcpConfigPath();
+    writeMcpJsonConfig(configPath, mcpServerPath);
+    console.log(`  MCP config written to: ${configPath}`);
+
+    // Inject context into workspace rules
+    const contextPath = getRooCodeContextPath();
+    injectContextIntoMarkdownFile(contextPath, PLACEHOLDER_CONTEXT);
+    console.log(`  Context placeholder written to: ${contextPath}`);
+
+    console.log(`
+Installation complete!
+
+MCP config:  ${configPath}
+Context:     ${contextPath}
+
+Note: This is an MCP-only integration providing search tools and context.
+Transcript capture is not available for Roo Code.
+
+Next steps:
+  1. Start claude-mem worker: npx claude-mem start
+  2. Restart Roo Code to pick up the MCP server
+`);
+
+    return 0;
+  } catch (error) {
+    console.error(`\nInstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+// ============================================================================
+// Warp
+// ============================================================================
+
+/**
+ * Get the Warp context injection path for the current workspace.
+ * Warp reads project-level instructions from WARP.md in the project root.
+ */
+function getWarpContextPath(): string {
+  return path.join(process.cwd(), 'WARP.md');
+}
+
+/**
+ * Get the Warp MCP config path.
+ * Warp stores MCP config at ~/.warp/mcp.json when supported.
+ */
+function getWarpMcpConfigPath(): string {
+  return path.join(homedir(), '.warp', 'mcp.json');
+}
+
+/**
+ * Install claude-mem MCP integration for Warp.
+ *
+ * - Writes MCP config to ~/.warp/mcp.json
+ * - Injects context into WARP.md in the project root
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export async function installWarpMcpIntegration(): Promise<number> {
+  console.log('\nInstalling Claude-Mem MCP integration for Warp...\n');
+
+  const mcpServerPath = findMcpServerPath();
+  if (!mcpServerPath) {
+    console.error('Could not find MCP server script');
+    console.error('   Expected at: ~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs');
+    return 1;
+  }
+
+  try {
+    // Write MCP config — Warp may also support configuring MCP via Warp Drive UI
+    const configPath = getWarpMcpConfigPath();
+    if (existsSync(path.dirname(configPath))) {
+      writeMcpJsonConfig(configPath, mcpServerPath);
+      console.log(`  MCP config written to: ${configPath}`);
+    } else {
+      console.log(`  Note: ~/.warp/ not found. MCP may need to be configured via Warp Drive UI.`);
+    }
+
+    // Inject context into project-level WARP.md
+    const contextPath = getWarpContextPath();
+    injectContextIntoMarkdownFile(contextPath, PLACEHOLDER_CONTEXT);
+    console.log(`  Context placeholder written to: ${contextPath}`);
+
+    console.log(`
+Installation complete!
+
+MCP config:  ${configPath}
+Context:     ${contextPath}
+
+Note: This is an MCP-only integration providing search tools and context.
+Transcript capture is not available for Warp.
+If MCP config via file is not supported, configure MCP through Warp Drive UI.
+
+Next steps:
+  1. Start claude-mem worker: npx claude-mem start
+  2. Restart Warp to pick up the MCP server
+`);
+
+    return 0;
+  } catch (error) {
+    console.error(`\nInstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+// ============================================================================
+// Unified Installer (used by npx install command)
+// ============================================================================
+
+/**
+ * Map of IDE identifiers to their install functions.
+ * Used by the install command to dispatch to the correct integration.
+ */
+export const MCP_IDE_INSTALLERS: Record<string, () => Promise<number>> = {
+  'copilot-cli': installCopilotCliMcpIntegration,
+  'antigravity': installAntigravityMcpIntegration,
+  'goose': installGooseMcpIntegration,
+  'crush': installCrushMcpIntegration,
+  'roo-code': installRooCodeMcpIntegration,
+  'warp': installWarpMcpIntegration,
+};

src/services/integrations/OpenClawInstaller.ts

@@ -0,0 +1,430 @@
+/**
+ * OpenClawInstaller - OpenClaw gateway integration installer for claude-mem
+ *
+ * Installs the pre-built claude-mem plugin into OpenClaw's extension directory
+ * and registers it in ~/.openclaw/openclaw.json.
+ *
+ * Install strategy: File-based
+ * - Copies the pre-built plugin from the npm package's openclaw/dist/ directory
+ *   to ~/.openclaw/extensions/claude-mem/dist/
+ * - Registers the plugin in openclaw.json under plugins.entries.claude-mem
+ * - Sets the memory slot to claude-mem
+ *
+ * Important: The OpenClaw plugin ships pre-built from the npm package.
+ * It must NOT be rebuilt at install time.
+ */
+
+import path from 'path';
+import { homedir } from 'os';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  cpSync,
+  rmSync,
+  unlinkSync,
+} from 'fs';
+import { logger } from '../../utils/logger.js';
+
+// ============================================================================
+// Path Resolution
+// ============================================================================
+
+/**
+ * Resolve the OpenClaw config directory (~/.openclaw).
+ */
+export function getOpenClawConfigDirectory(): string {
+  return path.join(homedir(), '.openclaw');
+}
+
+/**
+ * Resolve the OpenClaw extensions directory where plugins are installed.
+ */
+export function getOpenClawExtensionsDirectory(): string {
+  return path.join(getOpenClawConfigDirectory(), 'extensions');
+}
+
+/**
+ * Resolve the claude-mem extension install directory.
+ */
+export function getOpenClawClaudeMemExtensionDirectory(): string {
+  return path.join(getOpenClawExtensionsDirectory(), 'claude-mem');
+}
+
+/**
+ * Resolve the path to openclaw.json config file.
+ */
+export function getOpenClawConfigFilePath(): string {
+  return path.join(getOpenClawConfigDirectory(), 'openclaw.json');
+}
+
+// ============================================================================
+// Pre-built Plugin Location
+// ============================================================================
+
+/**
+ * Find the pre-built OpenClaw plugin bundle in the npm package.
+ * Searches in: openclaw/dist/index.js relative to package root,
+ * then the marketplace install location.
+ */
+export function findPreBuiltPluginDirectory(): string | null {
+  const possibleRoots = [
+    // Marketplace install location (production — after `npx claude-mem install`)
+    path.join(
+      process.env.CLAUDE_CONFIG_DIR || path.join(homedir(), '.claude'),
+      'plugins', 'marketplaces', 'thedotmack',
+    ),
+    // Development location (relative to project root)
+    process.cwd(),
+  ];
+
+  for (const root of possibleRoots) {
+    const openclawDistDirectory = path.join(root, 'openclaw', 'dist');
+    const pluginEntryPoint = path.join(openclawDistDirectory, 'index.js');
+    if (existsSync(pluginEntryPoint)) {
+      return openclawDistDirectory;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Find the openclaw.plugin.json file for copying alongside the plugin.
+ */
+export function findPluginManifestPath(): string | null {
+  const possibleRoots = [
+    path.join(
+      process.env.CLAUDE_CONFIG_DIR || path.join(homedir(), '.claude'),
+      'plugins', 'marketplaces', 'thedotmack',
+    ),
+    process.cwd(),
+  ];
+
+  for (const root of possibleRoots) {
+    const manifestPath = path.join(root, 'openclaw', 'openclaw.plugin.json');
+    if (existsSync(manifestPath)) {
+      return manifestPath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Find the openclaw skills directory for copying alongside the plugin.
+ */
+export function findPluginSkillsDirectory(): string | null {
+  const possibleRoots = [
+    path.join(
+      process.env.CLAUDE_CONFIG_DIR || path.join(homedir(), '.claude'),
+      'plugins', 'marketplaces', 'thedotmack',
+    ),
+    process.cwd(),
+  ];
+
+  for (const root of possibleRoots) {
+    const skillsDirectory = path.join(root, 'openclaw', 'skills');
+    if (existsSync(skillsDirectory)) {
+      return skillsDirectory;
+    }
+  }
+
+  return null;
+}
+
+// ============================================================================
+// OpenClaw Config (openclaw.json) Management
+// ============================================================================
+
+/**
+ * Read openclaw.json safely, returning an empty object if missing or invalid.
+ */
+function readOpenClawConfig(): Record<string, any> {
+  const configFilePath = getOpenClawConfigFilePath();
+  if (!existsSync(configFilePath)) return {};
+  try {
+    return JSON.parse(readFileSync(configFilePath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write openclaw.json atomically, creating the directory if needed.
+ */
+function writeOpenClawConfig(config: Record<string, any>): void {
+  const configDirectory = getOpenClawConfigDirectory();
+  mkdirSync(configDirectory, { recursive: true });
+  writeFileSync(getOpenClawConfigFilePath(), JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Register claude-mem in openclaw.json by merging into the existing config.
+ * Does NOT overwrite the entire file -- only touches the claude-mem entry
+ * and the memory slot.
+ */
+function registerPluginInOpenClawConfig(
+  workerPort: number = 37777,
+  project: string = 'openclaw',
+  syncMemoryFile: boolean = true,
+): void {
+  const config = readOpenClawConfig();
+
+  // Ensure the plugins structure exists
+  if (!config.plugins) config.plugins = {};
+  if (!config.plugins.slots) config.plugins.slots = {};
+  if (!config.plugins.entries) config.plugins.entries = {};
+
+  // Set the memory slot to claude-mem
+  config.plugins.slots.memory = 'claude-mem';
+
+  // Create or update the claude-mem plugin entry
+  if (!config.plugins.entries['claude-mem']) {
+    config.plugins.entries['claude-mem'] = {
+      enabled: true,
+      config: {
+        workerPort,
+        project,
+        syncMemoryFile,
+      },
+    };
+  } else {
+    // Merge: enable and update config without losing existing user settings
+    config.plugins.entries['claude-mem'].enabled = true;
+    if (!config.plugins.entries['claude-mem'].config) {
+      config.plugins.entries['claude-mem'].config = {};
+    }
+    const existingPluginConfig = config.plugins.entries['claude-mem'].config;
+    // Only set defaults if not already configured
+    if (existingPluginConfig.workerPort === undefined) existingPluginConfig.workerPort = workerPort;
+    if (existingPluginConfig.project === undefined) existingPluginConfig.project = project;
+    if (existingPluginConfig.syncMemoryFile === undefined) existingPluginConfig.syncMemoryFile = syncMemoryFile;
+  }
+
+  writeOpenClawConfig(config);
+}
+
+/**
+ * Remove claude-mem from openclaw.json without deleting other config.
+ */
+function unregisterPluginFromOpenClawConfig(): void {
+  const configFilePath = getOpenClawConfigFilePath();
+  if (!existsSync(configFilePath)) return;
+
+  const config = readOpenClawConfig();
+
+  // Remove claude-mem entry
+  if (config.plugins?.entries?.['claude-mem']) {
+    delete config.plugins.entries['claude-mem'];
+  }
+
+  // Clear memory slot if it points to claude-mem
+  if (config.plugins?.slots?.memory === 'claude-mem') {
+    delete config.plugins.slots.memory;
+  }
+
+  writeOpenClawConfig(config);
+}
+
+// ============================================================================
+// Plugin Installation
+// ============================================================================
+
+/**
+ * Install the claude-mem plugin into OpenClaw's extensions directory.
+ * Copies the pre-built plugin bundle and registers it in openclaw.json.
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export function installOpenClawPlugin(): number {
+  const preBuiltDistDirectory = findPreBuiltPluginDirectory();
+  if (!preBuiltDistDirectory) {
+    console.error('Could not find pre-built OpenClaw plugin bundle.');
+    console.error('  Expected at: openclaw/dist/index.js');
+    console.error('  Ensure the npm package includes the openclaw directory.');
+    return 1;
+  }
+
+  const extensionDirectory = getOpenClawClaudeMemExtensionDirectory();
+  const destinationDistDirectory = path.join(extensionDirectory, 'dist');
+
+  try {
+    // Create the extension directory structure
+    mkdirSync(destinationDistDirectory, { recursive: true });
+
+    // Copy pre-built dist files
+    cpSync(preBuiltDistDirectory, destinationDistDirectory, { recursive: true, force: true });
+    console.log(`  Plugin dist copied to: ${destinationDistDirectory}`);
+
+    // Copy openclaw.plugin.json if available
+    const manifestPath = findPluginManifestPath();
+    if (manifestPath) {
+      const destinationManifest = path.join(extensionDirectory, 'openclaw.plugin.json');
+      cpSync(manifestPath, destinationManifest, { force: true });
+      console.log(`  Plugin manifest copied to: ${destinationManifest}`);
+    }
+
+    // Copy skills directory if available
+    const skillsDirectory = findPluginSkillsDirectory();
+    if (skillsDirectory) {
+      const destinationSkills = path.join(extensionDirectory, 'skills');
+      cpSync(skillsDirectory, destinationSkills, { recursive: true, force: true });
+      console.log(`  Skills copied to: ${destinationSkills}`);
+    }
+
+    // Create a minimal package.json for the extension (OpenClaw expects this)
+    const extensionPackageJson = {
+      name: 'claude-mem',
+      version: '1.0.0',
+      type: 'module',
+      main: 'dist/index.js',
+      openclaw: { extensions: ['./dist/index.js'] },
+    };
+    writeFileSync(
+      path.join(extensionDirectory, 'package.json'),
+      JSON.stringify(extensionPackageJson, null, 2) + '\n',
+      'utf-8',
+    );
+
+    // Register in openclaw.json (merge, not overwrite)
+    registerPluginInOpenClawConfig();
+    console.log(`  Registered in openclaw.json`);
+
+    logger.info('OPENCLAW', 'Plugin installed', { destination: extensionDirectory });
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Failed to install OpenClaw plugin: ${message}`);
+    return 1;
+  }
+}
+
+// ============================================================================
+// Uninstallation
+// ============================================================================
+
+/**
+ * Remove the claude-mem plugin from OpenClaw.
+ * Removes extension files and unregisters from openclaw.json.
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export function uninstallOpenClawPlugin(): number {
+  let hasErrors = false;
+
+  // Remove extension directory
+  const extensionDirectory = getOpenClawClaudeMemExtensionDirectory();
+  if (existsSync(extensionDirectory)) {
+    try {
+      rmSync(extensionDirectory, { recursive: true, force: true });
+      console.log(`  Removed extension: ${extensionDirectory}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`  Failed to remove extension directory: ${message}`);
+      hasErrors = true;
+    }
+  }
+
+  // Unregister from openclaw.json
+  try {
+    unregisterPluginFromOpenClawConfig();
+    console.log(`  Unregistered from openclaw.json`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`  Failed to update openclaw.json: ${message}`);
+    hasErrors = true;
+  }
+
+  return hasErrors ? 1 : 0;
+}
+
+// ============================================================================
+// Status Check
+// ============================================================================
+
+/**
+ * Check OpenClaw integration status.
+ *
+ * @returns 0 always (informational only)
+ */
+export function checkOpenClawStatus(): number {
+  console.log('\nClaude-Mem OpenClaw Integration Status\n');
+
+  const configDirectory = getOpenClawConfigDirectory();
+  const extensionDirectory = getOpenClawClaudeMemExtensionDirectory();
+  const configFilePath = getOpenClawConfigFilePath();
+  const pluginEntryPoint = path.join(extensionDirectory, 'dist', 'index.js');
+
+  console.log(`Config directory: ${configDirectory}`);
+  console.log(`  Exists: ${existsSync(configDirectory) ? 'yes' : 'no'}`);
+  console.log('');
+
+  console.log(`Extension directory: ${extensionDirectory}`);
+  console.log(`  Exists: ${existsSync(extensionDirectory) ? 'yes' : 'no'}`);
+  console.log(`  Plugin entry: ${existsSync(pluginEntryPoint) ? 'yes' : 'no'}`);
+  console.log('');
+
+  console.log(`Config (openclaw.json): ${configFilePath}`);
+  if (existsSync(configFilePath)) {
+    const config = readOpenClawConfig();
+    const isRegistered = config.plugins?.entries?.['claude-mem'] !== undefined;
+    const isEnabled = config.plugins?.entries?.['claude-mem']?.enabled === true;
+    const isMemorySlot = config.plugins?.slots?.memory === 'claude-mem';
+
+    console.log(`  Exists: yes`);
+    console.log(`  Registered: ${isRegistered ? 'yes' : 'no'}`);
+    console.log(`  Enabled: ${isEnabled ? 'yes' : 'no'}`);
+    console.log(`  Memory slot: ${isMemorySlot ? 'yes' : 'no'}`);
+
+    if (isRegistered) {
+      const pluginConfig = config.plugins.entries['claude-mem'].config;
+      if (pluginConfig) {
+        console.log(`  Worker port: ${pluginConfig.workerPort ?? 'default'}`);
+        console.log(`  Project: ${pluginConfig.project ?? 'default'}`);
+        console.log(`  Sync MEMORY.md: ${pluginConfig.syncMemoryFile ?? 'default'}`);
+      }
+    }
+  } else {
+    console.log(`  Exists: no`);
+  }
+
+  console.log('');
+  return 0;
+}
+
+// ============================================================================
+// Full Install Flow (used by npx install command)
+// ============================================================================
+
+/**
+ * Run the full OpenClaw installation: copy plugin + register in config.
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export async function installOpenClawIntegration(): Promise<number> {
+  console.log('\nInstalling Claude-Mem for OpenClaw...\n');
+
+  // Step 1: Install plugin files and register in config
+  const pluginResult = installOpenClawPlugin();
+  if (pluginResult !== 0) {
+    return pluginResult;
+  }
+
+  const extensionDirectory = getOpenClawClaudeMemExtensionDirectory();
+
+  console.log(`
+Installation complete!
+
+Plugin installed to: ${extensionDirectory}
+Config updated: ${getOpenClawConfigFilePath()}
+
+Next steps:
+  1. Start claude-mem worker: npx claude-mem start
+  2. Restart OpenClaw to load the plugin
+  3. Memory capture is automatic from then on
+`);
+
+  return 0;
+}

src/services/integrations/OpenCodeInstaller.ts

@@ -0,0 +1,373 @@
+/**
+ * OpenCodeInstaller - OpenCode IDE integration installer for claude-mem
+ *
+ * Installs the claude-mem plugin into OpenCode's plugin directory and
+ * sets up context injection via AGENTS.md.
+ *
+ * Install strategy: File-based (Option A)
+ * - Copies the built plugin to the OpenCode plugins directory
+ * - Plugins in that directory are auto-loaded at startup
+ *
+ * Context injection:
+ * - Appends/updates <claude-mem-context> section in AGENTS.md
+ *
+ * Respects OPENCODE_CONFIG_DIR env var for config directory resolution.
+ */
+
+import path from 'path';
+import { homedir } from 'os';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, unlinkSync } from 'fs';
+import { logger } from '../../utils/logger.js';
+
+// ============================================================================
+// Path Resolution
+// ============================================================================
+
+/**
+ * Resolve the OpenCode config directory.
+ * Respects OPENCODE_CONFIG_DIR env var, falls back to ~/.config/opencode.
+ */
+export function getOpenCodeConfigDirectory(): string {
+  if (process.env.OPENCODE_CONFIG_DIR) {
+    return process.env.OPENCODE_CONFIG_DIR;
+  }
+  return path.join(homedir(), '.config', 'opencode');
+}
+
+/**
+ * Resolve the OpenCode plugins directory.
+ */
+export function getOpenCodePluginsDirectory(): string {
+  return path.join(getOpenCodeConfigDirectory(), 'plugins');
+}
+
+/**
+ * Resolve the AGENTS.md path for context injection.
+ */
+export function getOpenCodeAgentsMdPath(): string {
+  return path.join(getOpenCodeConfigDirectory(), 'AGENTS.md');
+}
+
+/**
+ * Resolve the path to the installed plugin file.
+ */
+export function getInstalledPluginPath(): string {
+  return path.join(getOpenCodePluginsDirectory(), 'claude-mem.js');
+}
+
+// ============================================================================
+// Plugin Installation
+// ============================================================================
+
+/**
+ * Find the built OpenCode plugin bundle.
+ * Searches in: dist/opencode-plugin/index.js (built output),
+ * then marketplace location.
+ */
+export function findBuiltPluginPath(): string | null {
+  const possiblePaths = [
+    // Marketplace install location (production)
+    path.join(
+      process.env.CLAUDE_CONFIG_DIR || path.join(homedir(), '.claude'),
+      'plugins', 'marketplaces', 'thedotmack',
+      'dist', 'opencode-plugin', 'index.js',
+    ),
+    // Development location (relative to project root)
+    path.join(process.cwd(), 'dist', 'opencode-plugin', 'index.js'),
+  ];
+
+  for (const candidatePath of possiblePaths) {
+    if (existsSync(candidatePath)) {
+      return candidatePath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Install the claude-mem plugin into OpenCode's plugins directory.
+ * Copies the built plugin bundle to ~/.config/opencode/plugins/claude-mem.js
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export function installOpenCodePlugin(): number {
+  const builtPluginPath = findBuiltPluginPath();
+  if (!builtPluginPath) {
+    console.error('Could not find built OpenCode plugin bundle.');
+    console.error('  Expected at: dist/opencode-plugin/index.js');
+    console.error('  Run the build first: npm run build');
+    return 1;
+  }
+
+  const pluginsDirectory = getOpenCodePluginsDirectory();
+  const destinationPath = getInstalledPluginPath();
+
+  try {
+    // Create plugins directory if needed
+    mkdirSync(pluginsDirectory, { recursive: true });
+
+    // Copy plugin bundle
+    copyFileSync(builtPluginPath, destinationPath);
+
+    console.log(`  Plugin installed to: ${destinationPath}`);
+    logger.info('OPENCODE', 'Plugin installed', { destination: destinationPath });
+
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Failed to install OpenCode plugin: ${message}`);
+    return 1;
+  }
+}
+
+// ============================================================================
+// Context Injection (AGENTS.md)
+// ============================================================================
+
+const CONTEXT_TAG_OPEN = '<claude-mem-context>';
+const CONTEXT_TAG_CLOSE = '</claude-mem-context>';
+
+/**
+ * Inject or update claude-mem context in OpenCode's AGENTS.md file.
+ *
+ * If the file doesn't exist, creates it with the context section.
+ * If the file exists, replaces the existing <claude-mem-context> section
+ * or appends one at the end.
+ *
+ * @param contextContent - The context content to inject (without tags)
+ * @returns 0 on success, 1 on failure
+ */
+export function injectContextIntoAgentsMd(contextContent: string): number {
+  const agentsMdPath = getOpenCodeAgentsMdPath();
+  const wrappedContent = `${CONTEXT_TAG_OPEN}\n${contextContent}\n${CONTEXT_TAG_CLOSE}`;
+
+  try {
+    const configDirectory = getOpenCodeConfigDirectory();
+    mkdirSync(configDirectory, { recursive: true });
+
+    if (existsSync(agentsMdPath)) {
+      let existingContent = readFileSync(agentsMdPath, 'utf-8');
+
+      // Check if context tags already exist
+      const tagStartIndex = existingContent.indexOf(CONTEXT_TAG_OPEN);
+      const tagEndIndex = existingContent.indexOf(CONTEXT_TAG_CLOSE);
+
+      if (tagStartIndex !== -1 && tagEndIndex !== -1) {
+        // Replace existing section
+        existingContent =
+          existingContent.slice(0, tagStartIndex) +
+          wrappedContent +
+          existingContent.slice(tagEndIndex + CONTEXT_TAG_CLOSE.length);
+      } else {
+        // Append section
+        existingContent = existingContent.trimEnd() + '\n\n' + wrappedContent + '\n';
+      }
+
+      writeFileSync(agentsMdPath, existingContent, 'utf-8');
+    } else {
+      // Create new AGENTS.md with context
+      const newContent = `# Claude-Mem Memory Context\n\n${wrappedContent}\n`;
+      writeFileSync(agentsMdPath, newContent, 'utf-8');
+    }
+
+    logger.info('OPENCODE', 'Context injected into AGENTS.md', { path: agentsMdPath });
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Failed to inject context into AGENTS.md: ${message}`);
+    return 1;
+  }
+}
+
+/**
+ * Sync context from the worker into OpenCode's AGENTS.md.
+ * Fetches context from the worker API and writes it to AGENTS.md.
+ *
+ * @param port - Worker port number
+ * @param project - Project name for context filtering
+ */
+export async function syncContextToAgentsMd(
+  port: number,
+  project: string,
+): Promise<void> {
+  try {
+    const response = await fetch(
+      `http://127.0.0.1:${port}/api/context/inject?project=${encodeURIComponent(project)}`,
+    );
+
+    if (!response.ok) return;
+
+    const contextText = await response.text();
+    if (contextText && contextText.trim()) {
+      injectContextIntoAgentsMd(contextText);
+    }
+  } catch {
+    // Worker not available — non-critical
+  }
+}
+
+// ============================================================================
+// Uninstallation
+// ============================================================================
+
+/**
+ * Remove the claude-mem plugin from OpenCode.
+ * Removes the plugin file and cleans up the AGENTS.md context section.
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export function uninstallOpenCodePlugin(): number {
+  let hasErrors = false;
+
+  // Remove plugin file
+  const pluginPath = getInstalledPluginPath();
+  if (existsSync(pluginPath)) {
+    try {
+      unlinkSync(pluginPath);
+      console.log(`  Removed plugin: ${pluginPath}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`  Failed to remove plugin: ${message}`);
+      hasErrors = true;
+    }
+  }
+
+  // Remove context section from AGENTS.md
+  const agentsMdPath = getOpenCodeAgentsMdPath();
+  if (existsSync(agentsMdPath)) {
+    try {
+      let content = readFileSync(agentsMdPath, 'utf-8');
+      const tagStartIndex = content.indexOf(CONTEXT_TAG_OPEN);
+      const tagEndIndex = content.indexOf(CONTEXT_TAG_CLOSE);
+
+      if (tagStartIndex !== -1 && tagEndIndex !== -1) {
+        content =
+          content.slice(0, tagStartIndex).trimEnd() +
+          '\n' +
+          content.slice(tagEndIndex + CONTEXT_TAG_CLOSE.length).trimStart();
+
+        // If the file is now essentially empty, don't bother keeping it
+        if (content.trim().length === 0) {
+          unlinkSync(agentsMdPath);
+          console.log(`  Removed empty AGENTS.md`);
+        } else {
+          writeFileSync(agentsMdPath, content.trimEnd() + '\n', 'utf-8');
+          console.log(`  Cleaned context from AGENTS.md`);
+        }
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`  Failed to clean AGENTS.md: ${message}`);
+      hasErrors = true;
+    }
+  }
+
+  return hasErrors ? 1 : 0;
+}
+
+// ============================================================================
+// Status Check
+// ============================================================================
+
+/**
+ * Check OpenCode integration status.
+ *
+ * @returns 0 always (informational only)
+ */
+export function checkOpenCodeStatus(): number {
+  console.log('\nClaude-Mem OpenCode Integration Status\n');
+
+  const configDirectory = getOpenCodeConfigDirectory();
+  const pluginPath = getInstalledPluginPath();
+  const agentsMdPath = getOpenCodeAgentsMdPath();
+
+  console.log(`Config directory: ${configDirectory}`);
+  console.log(`  Exists: ${existsSync(configDirectory) ? 'yes' : 'no'}`);
+  console.log('');
+
+  console.log(`Plugin: ${pluginPath}`);
+  console.log(`  Installed: ${existsSync(pluginPath) ? 'yes' : 'no'}`);
+  console.log('');
+
+  console.log(`Context (AGENTS.md): ${agentsMdPath}`);
+  if (existsSync(agentsMdPath)) {
+    const content = readFileSync(agentsMdPath, 'utf-8');
+    const hasContextTags = content.includes(CONTEXT_TAG_OPEN);
+    console.log(`  Exists: yes`);
+    console.log(`  Has claude-mem context: ${hasContextTags ? 'yes' : 'no'}`);
+  } else {
+    console.log(`  Exists: no`);
+  }
+
+  console.log('');
+  return 0;
+}
+
+// ============================================================================
+// Full Install Flow (used by npx install command)
+// ============================================================================
+
+/**
+ * Run the full OpenCode installation: plugin + context injection.
+ *
+ * @returns 0 on success, 1 on failure
+ */
+export async function installOpenCodeIntegration(): Promise<number> {
+  console.log('\nInstalling Claude-Mem for OpenCode...\n');
+
+  // Step 1: Install plugin
+  const pluginResult = installOpenCodePlugin();
+  if (pluginResult !== 0) {
+    return pluginResult;
+  }
+
+  // Step 2: Create initial context in AGENTS.md
+  const placeholderContext = `# Memory Context from Past Sessions
+
+*No context yet. Complete your first session and context will appear here.*
+
+Use claude-mem search tools for manual memory queries.`;
+
+  // Try to fetch real context from worker first
+  try {
+    const healthResponse = await fetch('http://127.0.0.1:37777/api/readiness');
+    if (healthResponse.ok) {
+      const contextResponse = await fetch(
+        `http://127.0.0.1:37777/api/context/inject?project=opencode`,
+      );
+      if (contextResponse.ok) {
+        const realContext = await contextResponse.text();
+        if (realContext && realContext.trim()) {
+          injectContextIntoAgentsMd(realContext);
+          console.log('  Context injected from existing memory');
+        } else {
+          injectContextIntoAgentsMd(placeholderContext);
+          console.log('  Placeholder context created (will populate after first session)');
+        }
+      } else {
+        injectContextIntoAgentsMd(placeholderContext);
+      }
+    } else {
+      injectContextIntoAgentsMd(placeholderContext);
+      console.log('  Placeholder context created (worker not running)');
+    }
+  } catch {
+    injectContextIntoAgentsMd(placeholderContext);
+    console.log('  Placeholder context created (worker not running)');
+  }
+
+  console.log(`
+Installation complete!
+
+Plugin installed to: ${getInstalledPluginPath()}
+Context file: ${getOpenCodeAgentsMdPath()}
+
+Next steps:
+  1. Start claude-mem worker: npx claude-mem start
+  2. Restart OpenCode to load the plugin
+  3. Memory capture is automatic from then on
+`);
+
+  return 0;
+}

src/services/integrations/WindsurfHooksInstaller.ts

@@ -0,0 +1,520 @@
+/**
+ * WindsurfHooksInstaller - Windsurf IDE integration for claude-mem
+ *
+ * Handles:
+ * - Windsurf hooks installation/uninstallation to ~/.codeium/windsurf/hooks.json
+ * - Context file generation (.windsurf/rules/claude-mem-context.md)
+ * - Project registry management for auto-context updates
+ *
+ * Windsurf hooks.json format:
+ *   {
+ *     "hooks": {
+ *       "<event_name>": [{ "command": "...", "show_output": false, "working_directory": "..." }]
+ *     }
+ *   }
+ *
+ * Events registered (all post-action, non-blocking):
+ *   - pre_user_prompt      — session init + context injection
+ *   - post_write_code      — code generation observation
+ *   - post_run_command     — command execution observation
+ *   - post_mcp_tool_use    — MCP tool results
+ *   - post_cascade_response — full AI response
+ */
+
+import path from 'path';
+import { homedir } from 'os';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, renameSync } from 'fs';
+import { logger } from '../../utils/logger.js';
+import { getWorkerPort } from '../../shared/worker-utils.js';
+import { DATA_DIR } from '../../shared/paths.js';
+import { findBunPath, findWorkerServicePath } from './CursorHooksInstaller.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface WindsurfHookEntry {
+  command: string;
+  show_output: boolean;
+  working_directory: string;
+}
+
+interface WindsurfHooksJson {
+  hooks: {
+    [eventName: string]: WindsurfHookEntry[];
+  };
+}
+
+interface WindsurfProjectRegistry {
+  [projectName: string]: {
+    workspacePath: string;
+    installedAt: string;
+  };
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** User-level hooks config — global coverage across all Windsurf workspaces */
+const WINDSURF_HOOKS_DIR = path.join(homedir(), '.codeium', 'windsurf');
+const WINDSURF_HOOKS_JSON_PATH = path.join(WINDSURF_HOOKS_DIR, 'hooks.json');
+
+/** Windsurf context rule limit: 6,000 chars per file */
+const WINDSURF_CONTEXT_CHAR_LIMIT = 6000;
+
+/** Registry file for tracking projects with Windsurf hooks */
+const WINDSURF_REGISTRY_FILE = path.join(DATA_DIR, 'windsurf-projects.json');
+
+/** Hook events we register */
+const WINDSURF_HOOK_EVENTS = [
+  'pre_user_prompt',
+  'post_write_code',
+  'post_run_command',
+  'post_mcp_tool_use',
+  'post_cascade_response',
+] as const;
+
+// ============================================================================
+// Project Registry
+// ============================================================================
+
+/**
+ * Read the Windsurf project registry
+ */
+export function readWindsurfRegistry(): WindsurfProjectRegistry {
+  try {
+    if (!existsSync(WINDSURF_REGISTRY_FILE)) return {};
+    return JSON.parse(readFileSync(WINDSURF_REGISTRY_FILE, 'utf-8'));
+  } catch (error) {
+    logger.error('WINDSURF', 'Failed to read registry, using empty', {
+      file: WINDSURF_REGISTRY_FILE,
+    }, error as Error);
+    return {};
+  }
+}
+
+/**
+ * Write the Windsurf project registry
+ */
+export function writeWindsurfRegistry(registry: WindsurfProjectRegistry): void {
+  const dir = path.dirname(WINDSURF_REGISTRY_FILE);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(WINDSURF_REGISTRY_FILE, JSON.stringify(registry, null, 2));
+}
+
+/**
+ * Register a project for auto-context updates
+ */
+export function registerWindsurfProject(projectName: string, workspacePath: string): void {
+  const registry = readWindsurfRegistry();
+  registry[projectName] = {
+    workspacePath,
+    installedAt: new Date().toISOString(),
+  };
+  writeWindsurfRegistry(registry);
+  logger.info('WINDSURF', 'Registered project for auto-context updates', { projectName, workspacePath });
+}
+
+/**
+ * Unregister a project from auto-context updates
+ */
+export function unregisterWindsurfProject(projectName: string): void {
+  const registry = readWindsurfRegistry();
+  if (registry[projectName]) {
+    delete registry[projectName];
+    writeWindsurfRegistry(registry);
+    logger.info('WINDSURF', 'Unregistered project', { projectName });
+  }
+}
+
+/**
+ * Update Windsurf context files for all registered projects matching this project name.
+ * Called by SDK agents after saving a summary.
+ */
+export async function updateWindsurfContextForProject(projectName: string, port: number): Promise<void> {
+  const registry = readWindsurfRegistry();
+  const entry = registry[projectName];
+
+  if (!entry) return; // Project doesn't have Windsurf hooks installed
+
+  try {
+    const response = await fetch(
+      `http://127.0.0.1:${port}/api/context/inject?project=${encodeURIComponent(projectName)}`
+    );
+
+    if (!response.ok) return;
+
+    const context = await response.text();
+    if (!context || !context.trim()) return;
+
+    writeWindsurfContextFile(entry.workspacePath, context);
+    logger.debug('WINDSURF', 'Updated context file', { projectName, workspacePath: entry.workspacePath });
+  } catch (error) {
+    // Background context update — failure is non-critical
+    logger.error('WINDSURF', 'Failed to update context file', { projectName }, error as Error);
+  }
+}
+
+// ============================================================================
+// Context File
+// ============================================================================
+
+/**
+ * Write context to the workspace-level Windsurf rules directory.
+ * Windsurf rules are workspace-scoped: .windsurf/rules/claude-mem-context.md
+ * Rule file limit: 6,000 chars per file.
+ */
+export function writeWindsurfContextFile(workspacePath: string, context: string): void {
+  const rulesDir = path.join(workspacePath, '.windsurf', 'rules');
+  const rulesFile = path.join(rulesDir, 'claude-mem-context.md');
+  const tempFile = `${rulesFile}.tmp`;
+
+  mkdirSync(rulesDir, { recursive: true });
+
+  let content = `# Memory Context from Past Sessions
+
+The following context is from claude-mem, a persistent memory system that tracks your coding sessions.
+
+${context}
+
+---
+*Auto-updated by claude-mem after each session. Use MCP search tools for detailed queries.*
+`;
+
+  // Enforce Windsurf's 6K char limit
+  if (content.length > WINDSURF_CONTEXT_CHAR_LIMIT) {
+    content = content.slice(0, WINDSURF_CONTEXT_CHAR_LIMIT - 50) +
+      '\n\n*[Truncated — use MCP search for full history]*\n';
+  }
+
+  // Atomic write: temp file + rename
+  writeFileSync(tempFile, content);
+  renameSync(tempFile, rulesFile);
+}
+
+// ============================================================================
+// Hook Installation
+// ============================================================================
+
+/**
+ * Build the hook command string for a given event.
+ * Uses bun to run worker-service.cjs with the windsurf platform adapter.
+ */
+function buildHookCommand(bunPath: string, workerServicePath: string, eventName: string): string {
+  // Map Windsurf event names to unified CLI hook commands
+  const eventToCommand: Record<string, string> = {
+    'pre_user_prompt': 'session-init',
+    'post_write_code': 'file-edit',
+    'post_run_command': 'observation',
+    'post_mcp_tool_use': 'observation',
+    'post_cascade_response': 'observation',
+  };
+
+  const hookCommand = eventToCommand[eventName] ?? 'observation';
+
+  // Escape backslashes for JSON on Windows
+  const escapedBunPath = bunPath.replace(/\\/g, '\\\\');
+  const escapedWorkerPath = workerServicePath.replace(/\\/g, '\\\\');
+
+  return `"${escapedBunPath}" "${escapedWorkerPath}" hook windsurf ${hookCommand}`;
+}
+
+/**
+ * Read existing hooks.json, merge our hooks, and write back.
+ * Preserves any existing hooks from other tools.
+ */
+function mergeAndWriteHooksJson(
+  bunPath: string,
+  workerServicePath: string,
+  workingDirectory: string,
+): void {
+  mkdirSync(WINDSURF_HOOKS_DIR, { recursive: true });
+
+  // Read existing hooks.json if present
+  let existingConfig: WindsurfHooksJson = { hooks: {} };
+  if (existsSync(WINDSURF_HOOKS_JSON_PATH)) {
+    try {
+      existingConfig = JSON.parse(readFileSync(WINDSURF_HOOKS_JSON_PATH, 'utf-8'));
+      if (!existingConfig.hooks) {
+        existingConfig.hooks = {};
+      }
+    } catch (error) {
+      logger.error('WINDSURF', 'Corrupt hooks.json, starting fresh', {
+        path: WINDSURF_HOOKS_JSON_PATH,
+      }, error as Error);
+      existingConfig = { hooks: {} };
+    }
+  }
+
+  // For each event, add our hook entry (remove any previous claude-mem entries first)
+  for (const eventName of WINDSURF_HOOK_EVENTS) {
+    const command = buildHookCommand(bunPath, workerServicePath, eventName);
+
+    const hookEntry: WindsurfHookEntry = {
+      command,
+      show_output: false,
+      working_directory: workingDirectory,
+    };
+
+    // Get existing hooks for this event, filtering out old claude-mem ones
+    const existingHooks = (existingConfig.hooks[eventName] ?? []).filter(
+      (hook) => !hook.command.includes('worker-service') || !hook.command.includes('windsurf')
+    );
+
+    existingConfig.hooks[eventName] = [...existingHooks, hookEntry];
+  }
+
+  writeFileSync(WINDSURF_HOOKS_JSON_PATH, JSON.stringify(existingConfig, null, 2));
+}
+
+/**
+ * Install Windsurf hooks to ~/.codeium/windsurf/hooks.json (user-level).
+ * Merges with existing hooks.json to preserve other integrations.
+ */
+export async function installWindsurfHooks(): Promise<number> {
+  console.log('\nInstalling Claude-Mem Windsurf hooks (user level)...\n');
+
+  // Find the worker-service.cjs path
+  const workerServicePath = findWorkerServicePath();
+  if (!workerServicePath) {
+    console.error('Could not find worker-service.cjs');
+    console.error('   Expected at: ~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/worker-service.cjs');
+    return 1;
+  }
+
+  // Find bun executable — required because worker-service.cjs uses bun:sqlite
+  const bunPath = findBunPath();
+
+  // IMPORTANT: Tilde expansion is NOT supported in working_directory — use absolute paths
+  const workingDirectory = path.dirname(workerServicePath);
+
+  try {
+    console.log(`  Using Bun runtime: ${bunPath}`);
+    console.log(`  Worker service: ${workerServicePath}`);
+
+    // Merge our hooks into the existing hooks.json
+    mergeAndWriteHooksJson(bunPath, workerServicePath, workingDirectory);
+    console.log(`  Created/merged hooks.json`);
+
+    // Set up initial context for the current workspace
+    const workspaceRoot = process.cwd();
+    await setupWindsurfProjectContext(workspaceRoot);
+
+    console.log(`
+Installation complete!
+
+Hooks installed to: ${WINDSURF_HOOKS_JSON_PATH}
+Using unified CLI: bun worker-service.cjs hook windsurf <command>
+
+Events registered:
+  - pre_user_prompt      (session init + context injection)
+  - post_write_code      (code generation observation)
+  - post_run_command     (command execution observation)
+  - post_mcp_tool_use    (MCP tool results)
+  - post_cascade_response (full AI response)
+
+Next steps:
+  1. Start claude-mem worker: claude-mem start
+  2. Restart Windsurf to load the hooks
+  3. Context is injected via .windsurf/rules/claude-mem-context.md (workspace-level)
+`);
+
+    return 0;
+  } catch (error) {
+    console.error(`\nInstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+/**
+ * Setup initial context file for a Windsurf workspace
+ */
+async function setupWindsurfProjectContext(workspaceRoot: string): Promise<void> {
+  const port = getWorkerPort();
+  const projectName = path.basename(workspaceRoot);
+  let contextGenerated = false;
+
+  console.log(`  Generating initial context...`);
+
+  try {
+    const healthResponse = await fetch(`http://127.0.0.1:${port}/api/readiness`);
+    if (healthResponse.ok) {
+      const contextResponse = await fetch(
+        `http://127.0.0.1:${port}/api/context/inject?project=${encodeURIComponent(projectName)}`
+      );
+      if (contextResponse.ok) {
+        const context = await contextResponse.text();
+        if (context && context.trim()) {
+          writeWindsurfContextFile(workspaceRoot, context);
+          contextGenerated = true;
+          console.log(`  Generated initial context from existing memory`);
+        }
+      }
+    }
+  } catch (error) {
+    // Worker not running during install — non-critical
+    logger.debug('WINDSURF', 'Worker not running during install', {}, error as Error);
+  }
+
+  if (!contextGenerated) {
+    // Create placeholder context file
+    const rulesDir = path.join(workspaceRoot, '.windsurf', 'rules');
+    mkdirSync(rulesDir, { recursive: true });
+    const rulesFile = path.join(rulesDir, 'claude-mem-context.md');
+    const placeholderContent = `# Memory Context from Past Sessions
+
+*No context yet. Complete your first session and context will appear here.*
+
+Use claude-mem's MCP search tools for manual memory queries.
+`;
+    writeFileSync(rulesFile, placeholderContent);
+    console.log(`  Created placeholder context file (will populate after first session)`);
+  }
+
+  // Register project for automatic context updates after summaries
+  registerWindsurfProject(projectName, workspaceRoot);
+  console.log(`  Registered for auto-context updates`);
+}
+
+/**
+ * Uninstall Windsurf hooks — removes claude-mem entries from hooks.json
+ */
+export function uninstallWindsurfHooks(): number {
+  console.log('\nUninstalling Claude-Mem Windsurf hooks...\n');
+
+  try {
+    // Remove our entries from hooks.json (preserve other integrations)
+    if (existsSync(WINDSURF_HOOKS_JSON_PATH)) {
+      try {
+        const config: WindsurfHooksJson = JSON.parse(readFileSync(WINDSURF_HOOKS_JSON_PATH, 'utf-8'));
+
+        for (const eventName of WINDSURF_HOOK_EVENTS) {
+          if (config.hooks[eventName]) {
+            config.hooks[eventName] = config.hooks[eventName].filter(
+              (hook) => !hook.command.includes('worker-service') || !hook.command.includes('windsurf')
+            );
+            // Remove empty arrays
+            if (config.hooks[eventName].length === 0) {
+              delete config.hooks[eventName];
+            }
+          }
+        }
+
+        // If no hooks remain, remove the file entirely
+        if (Object.keys(config.hooks).length === 0) {
+          unlinkSync(WINDSURF_HOOKS_JSON_PATH);
+          console.log(`  Removed hooks.json (no hooks remaining)`);
+        } else {
+          writeFileSync(WINDSURF_HOOKS_JSON_PATH, JSON.stringify(config, null, 2));
+          console.log(`  Removed claude-mem entries from hooks.json (other hooks preserved)`);
+        }
+      } catch (error) {
+        // Corrupt file — just remove it
+        unlinkSync(WINDSURF_HOOKS_JSON_PATH);
+        console.log(`  Removed corrupt hooks.json`);
+      }
+    } else {
+      console.log(`  No hooks.json found`);
+    }
+
+    // Remove context file from the current workspace
+    const workspaceRoot = process.cwd();
+    const contextFile = path.join(workspaceRoot, '.windsurf', 'rules', 'claude-mem-context.md');
+    if (existsSync(contextFile)) {
+      unlinkSync(contextFile);
+      console.log(`  Removed context file`);
+    }
+
+    // Unregister project
+    const projectName = path.basename(workspaceRoot);
+    unregisterWindsurfProject(projectName);
+    console.log(`  Unregistered from auto-context updates`);
+
+    console.log(`\nUninstallation complete!\n`);
+    console.log('Restart Windsurf to apply changes.');
+
+    return 0;
+  } catch (error) {
+    console.error(`\nUninstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+/**
+ * Check Windsurf hooks installation status
+ */
+export function checkWindsurfHooksStatus(): number {
+  console.log('\nClaude-Mem Windsurf Hooks Status\n');
+
+  if (existsSync(WINDSURF_HOOKS_JSON_PATH)) {
+    console.log(`User-level: Installed`);
+    console.log(`   Config: ${WINDSURF_HOOKS_JSON_PATH}`);
+
+    try {
+      const config: WindsurfHooksJson = JSON.parse(readFileSync(WINDSURF_HOOKS_JSON_PATH, 'utf-8'));
+      const registeredEvents = WINDSURF_HOOK_EVENTS.filter(
+        (event) => config.hooks[event]?.some(
+          (hook) => hook.command.includes('worker-service') && hook.command.includes('windsurf')
+        )
+      );
+      console.log(`   Events: ${registeredEvents.length}/${WINDSURF_HOOK_EVENTS.length} registered`);
+      for (const event of registeredEvents) {
+        console.log(`     - ${event}`);
+      }
+    } catch {
+      console.log(`   Mode: Unable to parse hooks.json`);
+    }
+
+    // Check for context file in current workspace
+    const contextFile = path.join(process.cwd(), '.windsurf', 'rules', 'claude-mem-context.md');
+    if (existsSync(contextFile)) {
+      console.log(`   Context: Active (current workspace)`);
+    } else {
+      console.log(`   Context: Not yet generated for this workspace`);
+    }
+  } else {
+    console.log(`User-level: Not installed`);
+    console.log(`\nNo hooks installed. Run: claude-mem windsurf install\n`);
+  }
+
+  console.log('');
+  return 0;
+}
+
+/**
+ * Handle windsurf subcommand for hooks installation
+ */
+export async function handleWindsurfCommand(subcommand: string, _args: string[]): Promise<number> {
+  switch (subcommand) {
+    case 'install':
+      return installWindsurfHooks();
+
+    case 'uninstall':
+      return uninstallWindsurfHooks();
+
+    case 'status':
+      return checkWindsurfHooksStatus();
+
+    default: {
+      console.log(`
+Claude-Mem Windsurf Integration
+
+Usage: claude-mem windsurf <command>
+
+Commands:
+  install     Install Windsurf hooks (user-level, ~/.codeium/windsurf/hooks.json)
+  uninstall   Remove Windsurf hooks
+  status      Check installation status
+
+Examples:
+  claude-mem windsurf install      # Install hooks globally
+  claude-mem windsurf uninstall    # Remove hooks
+  claude-mem windsurf status       # Check if hooks are installed
+
+For more info: https://docs.claude-mem.ai/windsurf
+      `);
+      return 0;
+    }
+  }
+}

src/services/integrations/index.ts

@@ -1,6 +1,12 @@
 /**
- * Integrations module - IDE integrations (Cursor, etc.)
+ * Integrations module - IDE integrations (Cursor, Gemini CLI, OpenCode, Windsurf, etc.)
  */
 
 export * from './types.js';
 export * from './CursorHooksInstaller.js';
+export * from './GeminiCliHooksInstaller.js';
+export * from './OpenCodeInstaller.js';
+export * from './WindsurfHooksInstaller.js';
+export * from './OpenClawInstaller.js';
+export * from './CodexCliInstaller.js';
+export * from './McpIntegrations.js';

src/services/transcripts/config.ts

@@ -8,7 +8,7 @@ export const DEFAULT_STATE_PATH = join(homedir(), '.claude-mem', 'transcript-wat
 
 const CODEX_SAMPLE_SCHEMA: TranscriptSchema = {
   name: 'codex',
-  version: '0.2',
+  version: '0.3',
   description: 'Schema for Codex session JSONL files under ~/.codex/sessions.',
   events: [
     {
@@ -46,13 +46,14 @@ const CODEX_SAMPLE_SCHEMA: TranscriptSchema = {
     },
     {
       name: 'tool-use',
-      match: { path: 'payload.type', in: ['function_call', 'custom_tool_call', 'web_search_call'] },
+      match: { path: 'payload.type', in: ['function_call', 'custom_tool_call', 'web_search_call', 'exec_command'] },
       action: 'tool_use',
       fields: {
         toolId: 'payload.call_id',
         toolName: {
           coalesce: [
             'payload.name',
+            'payload.type',
             { value: 'web_search' }
           ]
         },
@@ -60,6 +61,7 @@ const CODEX_SAMPLE_SCHEMA: TranscriptSchema = {
           coalesce: [
             'payload.arguments',
             'payload.input',
+            'payload.command',
             'payload.action'
           ]
         }
@@ -67,7 +69,7 @@ const CODEX_SAMPLE_SCHEMA: TranscriptSchema = {
     },
     {
       name: 'tool-result',
-      match: { path: 'payload.type', in: ['function_call_output', 'custom_tool_call_output'] },
+      match: { path: 'payload.type', in: ['function_call_output', 'custom_tool_call_output', 'exec_command_output'] },
       action: 'tool_result',
       fields: {
         toolId: 'payload.call_id',
@@ -76,7 +78,7 @@ const CODEX_SAMPLE_SCHEMA: TranscriptSchema = {
     },
     {
       name: 'session-end',
-      match: { path: 'payload.type', equals: 'turn_aborted' },
+      match: { path: 'payload.type', in: ['turn_aborted', 'turn_completed'] },
       action: 'session_end'
     }
   ]