chore: bump version to 10.7.2

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

.agent/rules/claude-mem-context.md

@@ -0,0 +1,7 @@
+<claude-mem-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.
+</claude-mem-context>

.claude-plugin/marketplace.json

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

.github/copilot-instructions.md

@@ -0,0 +1,7 @@
+<claude-mem-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.
+</claude-mem-context>

.gitignore

@@ -1,7 +1,6 @@
 datasets/
 node_modules/
 dist/
-!installer/dist/
 **/_tree-sitter/
 *.log
 .DS_Store
@@ -35,4 +34,7 @@ src/ui/viewer.html
 .claude-octopus/
 .claude/session-intent.md
 .claude/session-plan.md
-.octo/
+.octo/
+
+# Local contribution analysis (not part of upstream)
+CONTRIB_NOTES.md

.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/

.windsurf/rules/claude-mem-context.md

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

README.md

@@ -127,17 +127,29 @@
 
 ## 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:
+
+```bash
 /plugin marketplace add thedotmack/claude-mem
 
 /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

WARP.md

@@ -0,0 +1,7 @@
+<claude-mem-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.
+</claude-mem-context>

docs/architecture-overview.md

@@ -0,0 +1,140 @@
+# claude-mem Architecture Overview
+
+## System Layers
+
+```text
++-----------------------------------------------------------+
+|  Claude Code (host)                                       |
+|  +-- Hook System (5 events)                               |
+|  +-- MCP Client (search tools)                            |
++-----------------------------------------------------------+
+|  CLI Layer (Bun)                                          |
+|  +-- bun-runner.js (Node->Bun bridge)                     |
+|  +-- hook-command.ts (orchestrator)                        |
+|  +-- handlers/ (context, session-init, observation,        |
+|                 summarize, session-complete)               |
++-----------------------------------------------------------+
+|  Worker Daemon (Express, port 37777)                      |
+|  +-- SessionManager (session lifecycle)                   |
+|  +-- SDKAgent (Claude Agent SDK)                          |
+|  +-- SearchManager (search orchestration)                 |
+|  +-- ProcessRegistry (subprocess management)              |
+|  +-- ChromaSync (embedding synchronization)               |
++-----------------------------------------------------------+
+|  Storage Layer                                            |
+|  +-- SQLite (claude-mem.db) -- structured data            |
+|  +-- ChromaDB (chroma.sqlite3) -- vector embeddings       |
+|  +-- MCP Server (interface for Claude Code)               |
++-----------------------------------------------------------+
+```
+
+## Hook Lifecycle
+
+| Event | Handler | What it does | Timeout |
+|-------|---------|-------------|---------|
+| Setup | setup.sh | Install system dependencies | 300s |
+| SessionStart | smart-install.js + context | Install deps + start worker + inject context | 60s |
+| UserPromptSubmit | session-init | Register session + start SDK agent + semantic injection | 60s |
+| PostToolUse | observation | Capture tool usage -> enqueue in worker | 120s |
+| Summary | summarize | Request session summary from SDK agent | 120s |
+| SessionEnd | session-complete | End session + drain pending messages | 30s |
+
+## Data Flow
+
+```text
+User prompt -> session-init -> /api/sessions/init + /api/context/semantic
+  |
+Tool use -> observation -> /api/sessions/observations
+  |                              |
+  |                    PendingMessageStore.enqueue()
+  |                              |
+  |                    SDKAgent.startSession()
+  |                              |
+  |                    Claude Agent SDK -> ResponseProcessor
+  |                              |
+  |                    +-- storeObservations() -> SQLite
+  |                    +-- chromaSync.sync() -> ChromaDB
+  |                    +-- broadcastObservation() -> SSE/UI
+  |
+Stop -> summarize -> /api/sessions/summarize
+     -> session-complete -> /api/sessions/complete + drain
+```
+
+## Key Patterns
+
+### CLAIM-CONFIRM (PendingMessageStore)
+
+```text
+enqueue()           -> INSERT status='pending'
+claimNextMessage()  -> UPDATE status='processing' (atomic)
+confirmProcessed()  -> DELETE (success)
+markFailed()        -> UPDATE status='failed' (retry < 3)
+
+Self-healing: messages in 'processing' for >60s reset to 'pending'
+```
+
+### Circuit-Breaker (SessionRoutes)
+
+```text
+Generator crash -> retry 1 (1s) -> retry 2 (2s) -> retry 3 (4s)
+  -> consecutiveRestarts > 3 -> CIRCUIT-BREAKER
+  -> markAllSessionMessagesAbandoned(sessionDbId)
+  -> Stop. No infinite loop.
+```
+
+Counter resets to 0 when generator completes work naturally.
+
+### Graceful Degradation (hook-command.ts)
+
+```text
+Transport errors (ECONNREFUSED, timeout, 5xx) -> exit 0 (never block Claude Code)
+Client bugs (4xx, TypeError, ReferenceError)  -> exit 2 (blocking, needs fix)
+```
+
+The worker being unavailable NEVER blocks the user's Claude Code session.
+
+### Deduplication (observations)
+
+```text
+SHA256(memory_session_id + title + narrative)[:16] -> content_hash (16 hex chars)
+If hash exists within 30s window -> return existing ID (no insert)
+```
+
+### Two Types of Session ID
+
+- `contentSessionId` — from Claude Code, invariant during the session
+- `memorySessionId` — from SDK Agent, changes on each worker restart
+
+The conversion between them is handled by SessionStore and is critical for FK constraints.
+
+## Storage
+
+### SQLite (claude-mem.db)
+
+| Table | Key fields | Purpose |
+|-------|-----------|---------|
+| sdk_sessions | content_session_id, memory_session_id, status | Session lifecycle |
+| observations | memory_session_id, type, title, narrative, content_hash | Tool usage observations |
+| session_summaries | memory_session_id, request, learned, completed | Session summaries |
+| user_prompts | content_session_id, prompt_text | User prompt history |
+| pending_messages | session_db_id, status, message_type | CLAIM-CONFIRM queue |
+| observation_feedback | observation_id, signal_type | Usage tracking |
+
+### ChromaDB (chroma.sqlite3)
+
+Vector embeddings for semantic search. Each observation generates multiple documents:
+
+```text
+obs_{id}_narrative  -> main text
+obs_{id}_fact_0     -> first fact
+obs_{id}_fact_1     -> second fact
+...
+```
+
+Accessed via chroma-mcp (MCP process), communication over stdio.
+
+## Process Management
+
+- **ProcessRegistry:** Tracks all Claude SDK subprocesses, manages PID lifecycle
+- **Orphan Reaper (5min):** Kills processes with no active session
+- **GracefulShutdown:** 7-step shutdown (PID file, children, HTTP server, sessions, MCP, DB, force-kill)

docs/production-guide.md

@@ -0,0 +1,111 @@
+# claude-mem Production Guide
+
+Practical guide based on 23 days of production usage with 3,400+ observations across two physical servers and 8 projects.
+
+## Recommended Settings
+
+| Setting | Default | Recommended | Why |
+|---------|---------|-------------|-----|
+| CLAUDE_MEM_MAX_CONCURRENT_AGENTS | 2 | 3 | Better throughput without overload |
+| CLAUDE_MEM_SEMANTIC_INJECT | true | true | Relevant context >> recent context |
+| CLAUDE_MEM_SEMANTIC_INJECT_LIMIT | 5 | 5 | Sweet spot for token cost vs coverage |
+| CLAUDE_MEM_TIER_ROUTING_ENABLED | true | true | ~52% cost savings, no quality loss |
+
+## Health Monitoring
+
+### Key metrics to watch
+
+| Metric | Healthy | Warning | Action |
+|--------|---------|---------|--------|
+| pending_messages (pending) | 0-5 | >10 | Check worker logs, may need restart |
+| pending_messages (failed) | 0 | >0 growing | Circuit-breaker may be tripping |
+| sdk_sessions (active) | 0-3 | >5 stuck | Orphan sessions, worker restart |
+| WAL size | <10 MB | >20 MB | Run `PRAGMA wal_checkpoint(TRUNCATE)` |
+| Chroma size | Growing slowly | Sudden jump | Check for sync loops |
+| Errors/day in logs | 0-2 | >10 | Investigate log patterns |
+
+### Quick health check
+
+```bash
+# Check worker status
+curl -s http://127.0.0.1:37777/api/health | python3 -m json.tool
+
+# Check database stats
+sqlite3 ~/.claude-mem/claude-mem.db "
+  SELECT 'observations' as metric, COUNT(*) as value FROM observations
+  UNION ALL SELECT 'summaries', COUNT(*) FROM session_summaries
+  UNION ALL SELECT 'pending', COUNT(*) FROM pending_messages WHERE status='pending'
+  UNION ALL SELECT 'active_sessions', COUNT(*) FROM sdk_sessions WHERE status='active';
+"
+```
+
+## Multi-Machine Setup
+
+If running claude-mem on multiple machines, use `claude-mem-sync` to keep observations in sync:
+
+```bash
+claude-mem-sync push <remote-host>    # local -> remote
+claude-mem-sync pull <remote-host>    # remote -> local
+claude-mem-sync sync <remote-host>    # bidirectional
+claude-mem-sync status <remote-host>  # compare counts
+```
+
+Deduplication is by `(created_at, title)` — safe to run repeatedly.
+
+## Growth Expectations
+
+Based on active daily development usage:
+
+| Metric | Per day | Per month | Notes |
+|--------|---------|-----------|-------|
+| Observations | ~120 | ~3,600 | Varies with coding activity |
+| Summaries | ~40 | ~1,200 | One per session |
+| SQLite | ~0.8 MB | ~24 MB | ~5 KB per observation |
+| Chroma | ~4 MB | ~120 MB | ~50 KB per observation (embeddings) |
+
+## Common Issues and Solutions
+
+### Summarize error loop
+
+**Symptom:** Repeated `[ERROR] Missing last_assistant_message` in logs.
+**Cause:** Transcript with no assistant messages triggers summary attempt that fails repeatedly.
+**Fix:** PR #1566 — skip summary when transcript is empty.
+
+### Chroma sync failures
+
+**Symptom:** `[ERROR] Batch add failed... IDs already exist`
+**Cause:** MCP timeout during add leaves partial writes; retry fails on existing IDs.
+**Fix:** PR #1566 — fallback to delete+add reconciliation.
+
+### Port conflict on startup
+
+**Symptom:** `Worker failed to start... Is port 37777 in use?`
+**Cause:** Two sessions starting simultaneously — HTTP check is non-atomic (TOCTOU race).
+**Fix:** PR #1566 — atomic socket bind on Unix.
+
+### Orphaned pending messages
+
+**Symptom:** `pending_messages` table growing with old entries for completed sessions.
+**Cause:** SIGTERM kills generator before queue is drained.
+**Fix:** PR #1567 — drain after deleteSession().
+
+### Context not relevant to current topic
+
+**Symptom:** Claude receives observations about CSS when you're asking about authentication.
+**Cause:** Default recency-based injection selects most recent, not most relevant.
+**Fix:** PR #1568 — semantic injection via Chroma on every prompt.
+
+## Log Analysis Tips
+
+```bash
+# Count errors by day
+grep '\[ERROR\]' ~/.claude-mem/logs/claude-mem-*.log | \
+  sed 's/\[20[0-9][0-9]-[0-9][0-9]-/\n&/g' | \
+  grep -oP '^\[20\d{2}-\d{2}-\d{2}' | sort | uniq -c
+
+# Find circuit-breaker trips
+grep 'circuit\|Circuit\|ABANDONED\|abandoned' ~/.claude-mem/logs/claude-mem-*.log
+
+# Check pending message health
+grep 'CLAIMED\|CONFIRMED\|FAILED\|ABANDONED' ~/.claude-mem/logs/claude-mem-$(date +%Y-%m-%d).log | tail -20
+```

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:
-- 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.
+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.
 
 > **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
-# Usage: curl -fsSL https://install.cmem.ai | bash
-#   or:  curl -fsSL https://install.cmem.ai | bash -s -- --provider=gemini --api-key=YOUR_KEY
-
-INSTALLER_URL="https://install.cmem.ai/installer.js"
+# claude-mem installer redirect
+# The old curl-pipe-bash installer has been replaced by npx claude-mem.
+# This script now redirects users to the new install method.
 
 # 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; }
-info() { echo -e "${CYAN}$1${NC}"; }
-
-# Check Node.js
-if ! command -v node &> /dev/null; then
-  error "Node.js is required but not found. Install from https://nodejs.org"
-fi
-
-NODE_VERSION=$(node -v | sed 's/v//')
-NODE_MAJOR=$(echo "$NODE_VERSION" | cut -d. -f1)
-if [ "$NODE_MAJOR" -lt 18 ]; then
-  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
+echo ""
+echo -e "${YELLOW}The curl-pipe-bash installer has been replaced.${NC}"
+echo ""
+echo -e "${GREEN}Install claude-mem with a single command:${NC}"
+echo ""
+echo -e "  ${CYAN}npx claude-mem install${NC}"
+echo ""
+echo -e "This requires Node.js >= 18. Get it from ${CYAN}https://nodejs.org${NC}"
+echo ""
+echo -e "For more info, visit: ${CYAN}https://docs.claude-mem.ai/installation${NC}"
+echo ""

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

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem",
-  "version": "10.6.0",
+  "version": "10.7.2",
   "description": "Memory compression system for Claude Code - persist context across sessions",
   "keywords": [
     "claude",
@@ -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",

plugin/.claude-plugin/plugin.json

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

plugin/hooks/hooks.json

@@ -74,8 +74,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/thedotmack/plugin\"; node \"$_R/scripts/bun-runner.js\" \"$_R/scripts/worker-service.cjs\" hook claude-code session-complete",
-            "timeout": 30
+            "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const{sessionId:s}=JSON.parse(d);if(!s){process.exit(0)}const r=require('http').request({hostname:'127.0.0.1',port:37777,path:'/api/sessions/complete',method:'POST',headers:{'Content-Type':'application/json'}});r.on('error',()=>{});r.end(JSON.stringify({contentSessionId:s}));process.exit(0)}catch{process.exit(0)}})\"",
+            "timeout": 2
           }
         ]
       }

plugin/package.json

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

plugin/skills/timeline-report/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: timeline-report
+description: Generate a "Journey Into [Project]" narrative report analyzing a project's entire development history from claude-mem's timeline. Use when asked for a timeline report, project history analysis, development journey, or full project report.
+---
+
+# Timeline Report
+
+Generate a comprehensive narrative analysis of a project's entire development history using claude-mem's persistent memory timeline.
+
+## When to Use
+
+Use when users ask for:
+
+- "Write a timeline report"
+- "Journey into [project]"
+- "Analyze my project history"
+- "Full project report"
+- "Summarize the entire development history"
+- "What's the story of this project?"
+
+## Prerequisites
+
+The claude-mem worker must be running on localhost:37777. The project must have claude-mem observations recorded.
+
+## Workflow
+
+### Step 1: Determine the Project Name
+
+Ask the user which project to analyze if not obvious from context. The project name is typically the directory name of the project (e.g., "tokyo", "my-app"). If the user says "this project", use the current working directory's basename.
+
+**Worktree Detection:** Before using the directory basename, check if the current directory is a git worktree. In a worktree, the data source is the **parent project**, not the worktree directory itself. Run:
+
+```bash
+git_dir=$(git rev-parse --git-dir 2>/dev/null)
+git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)
+if [ "$git_dir" != "$git_common_dir" ]; then
+  # We're in a worktree — resolve the parent project name
+  parent_project=$(basename "$(dirname "$git_common_dir")")
+  echo "Worktree detected. Parent project: $parent_project"
+else
+  parent_project=$(basename "$PWD")
+fi
+echo "$parent_project"
+```
+
+If a worktree is detected, use `$parent_project` (the basename of the parent repo) as the project name for all API calls. Inform the user: "Detected git worktree. Using parent project '[name]' as the data source."
+
+### Step 2: Fetch the Full Timeline
+
+Use Bash to fetch the complete timeline from the claude-mem worker API:
+
+```bash
+curl -s "http://localhost:37777/api/context/inject?project=PROJECT_NAME&full=true"
+```
+
+This returns the entire compressed timeline -- every observation, session boundary, and summary across the project's full history. The response is pre-formatted markdown optimized for LLM consumption.
+
+**Token estimates:** The full timeline size depends on the project's history:
+- Small project (< 1,000 observations): ~20-50K tokens
+- Medium project (1,000-10,000 observations): ~50-300K tokens
+- Large project (10,000-35,000 observations): ~300-750K tokens
+
+If the response is empty or returns an error, the worker may not be running or the project name may be wrong. Try `curl -s "http://localhost:37777/api/search?query=*&limit=1"` to verify the worker is healthy.
+
+### Step 3: Estimate Token Count
+
+Before proceeding, estimate the token count of the fetched timeline (roughly 1 token per 4 characters). Report this to the user:
+
+```
+Timeline fetched: ~X observations, estimated ~Yk tokens.
+This analysis will consume approximately Yk input tokens + ~5-10k output tokens.
+Proceed? (y/n)
+```
+
+Wait for user confirmation before continuing if the timeline exceeds 100K tokens.
+
+### Step 4: Analyze with a Subagent
+
+Deploy an Agent (using the Task tool) with the full timeline and the following analysis prompt. Pass the ENTIRE timeline as context to the agent. The agent should also be instructed to query the SQLite database at `~/.claude-mem/claude-mem.db` for the Token Economics section.
+
+**Agent prompt:**
+
+```
+You are a technical historian analyzing a software project's complete development timeline from claude-mem's persistent memory system. The timeline below contains every observation, session boundary, and summary recorded across the project's entire history.
+
+You also have access to the claude-mem SQLite database at ~/.claude-mem/claude-mem.db. Use it to run queries for the Token Economics & Memory ROI section. The database has an "observations" table with columns: id, memory_session_id, project, text, type, title, subtitle, facts, narrative, concepts, files_read, files_modified, prompt_number, discovery_tokens, created_at, created_at_epoch, source_tool, source_input_summary.
+
+Write a comprehensive narrative report titled "Journey Into [PROJECT_NAME]" that covers:
+
+## Required Sections
+
+1. **Project Genesis** -- When and how the project started. What were the first commits, the initial vision, the founding technical decisions? What problem was being solved?
+
+2. **Architectural Evolution** -- How did the architecture change over time? What were the major pivots? Why did they happen? Trace the evolution from initial design through each significant restructuring.
+
+3. **Key Breakthroughs** -- Identify the "aha" moments: when a difficult problem was finally solved, when a new approach unlocked progress, when a prototype first worked. These are the observations where the tone shifts from investigation to resolution.
+
+4. **Work Patterns** -- Analyze the rhythm of development. Identify debugging cycles (clusters of bug fixes), feature sprints (rapid observation sequences), refactoring phases (architectural changes without new features), and exploration phases (many discoveries without changes).
+
+5. **Technical Debt** -- Track where shortcuts were taken and when they were paid back. Identify patterns of accumulation (rapid feature work) and resolution (dedicated refactoring sessions).
+
+6. **Challenges and Debugging Sagas** -- The hardest problems encountered. Multi-session debugging efforts, architectural dead-ends that required backtracking, platform-specific issues that took days to resolve.
+
+7. **Memory and Continuity** -- How did persistent memory (claude-mem itself, if applicable) affect the development process? Were there moments where recalled context from prior sessions saved significant time or prevented repeated mistakes?
+
+8. **Token Economics & Memory ROI** -- Quantitative analysis of how memory recall saved work:
+   - Query the database directly for these metrics using `sqlite3 ~/.claude-mem/claude-mem.db`
+   - Count total discovery_tokens across all observations (the original cost of all work)
+   - Count sessions that had context injection available (sessions after the first)
+   - Calculate the compression ratio: average discovery_tokens vs average read_tokens per observation
+   - Identify the highest-value observations (highest discovery_tokens -- these are the most expensive decisions, bugs, and discoveries that memory prevents re-doing)
+   - Identify explicit recall events (observations where source_tool contains "search", "smart_search", "get_observations", "timeline", or where narrative mentions "recalled", "from memory", "previous session")
+   - Estimate passive recall savings: each session with context injection receives ~50 observations. Use a 30% relevance factor (conservative estimate that 30% of injected context prevents re-work). Savings = sessions_with_context × avg_discovery_value_of_50_obs_window × 0.30
+   - Estimate explicit recall savings: ~10K tokens per explicit recall query
+   - Calculate net ROI: total_savings / total_read_tokens_invested
+   - Present as a table with monthly breakdown
+   - Highlight the top 5 most expensive observations by discovery_tokens -- these represent the highest-value memories in the system (architecture decisions, hard bugs, implementation plans that cost 100K+ tokens to produce originally)
+
+   Use these SQL queries as a starting point:
+   ```sql
+   -- Total discovery tokens
+   SELECT SUM(discovery_tokens) FROM observations WHERE project = 'PROJECT_NAME';
+
+   -- Sessions with context available (not the first session)
+   SELECT COUNT(DISTINCT memory_session_id) FROM observations WHERE project = 'PROJECT_NAME';
+
+   -- Average tokens per observation
+   SELECT AVG(discovery_tokens) as avg_discovery, AVG(LENGTH(title || COALESCE(subtitle,'') || COALESCE(narrative,'') || COALESCE(facts,'')) / 4) as avg_read FROM observations WHERE project = 'PROJECT_NAME' AND discovery_tokens > 0;
+
+   -- Top 5 most expensive observations (highest-value memories)
+   SELECT id, title, discovery_tokens FROM observations WHERE project = 'PROJECT_NAME' ORDER BY discovery_tokens DESC LIMIT 5;
+
+   -- Monthly breakdown
+   SELECT strftime('%Y-%m', created_at) as month, COUNT(*) as obs, SUM(discovery_tokens) as total_discovery, COUNT(DISTINCT memory_session_id) as sessions FROM observations WHERE project = 'PROJECT_NAME' GROUP BY month ORDER BY month;
+
+   -- Explicit recall events
+   SELECT COUNT(*) FROM observations WHERE project = 'PROJECT_NAME' AND (source_tool LIKE '%search%' OR source_tool LIKE '%timeline%' OR source_tool LIKE '%get_observations%' OR narrative LIKE '%recalled%' OR narrative LIKE '%from memory%' OR narrative LIKE '%previous session%');
+   ```
+
+9. **Timeline Statistics** -- Quantitative summary:
+   - Date range (first observation to last)
+   - Total observations and sessions
+   - Breakdown by observation type (features, bug fixes, discoveries, decisions, changes)
+   - Most active days/weeks
+   - Longest debugging sessions
+
+10. **Lessons and Meta-Observations** -- What patterns emerge from the full history? What would a new developer learn about this codebase from reading the timeline? What recurring themes or principles guided development?
+
+## Writing Style
+
+- Write as a technical narrative, not a list of bullet points
+- Use specific observation IDs and timestamps when referencing events (e.g., "On Dec 14 (#26766), the root cause was finally identified...")
+- Connect events across time -- show how early decisions created later consequences
+- Be honest about struggles and dead ends, not just successes
+- Target 3,000-6,000 words depending on project size
+- Use markdown formatting with headers, emphasis, and code references where appropriate
+
+## Important
+
+- Analyze the ENTIRE timeline chronologically -- do not skip early history
+- Look for narrative arcs: problem -> investigation -> solution
+- Identify turning points where the project's direction fundamentally changed
+- Note any observations about the development process itself (tooling, workflow, collaboration patterns)
+
+Here is the complete project timeline:
+
+[TIMELINE CONTENT GOES HERE]
+```
+
+### Step 5: Save the Report
+
+Save the agent's output as a markdown file. Default location:
+
+```
+./journey-into-PROJECT_NAME.md
+```
+
+Or if the user specified a different output path, use that instead.
+
+### Step 6: Report Completion
+
+Tell the user:
+- Where the report was saved
+- The approximate token cost (input timeline + output report)
+- The date range covered
+- Number of observations analyzed
+
+## Error Handling
+
+- **Empty timeline:** "No observations found for project 'X'. Check the project name with: `curl -s 'http://localhost:37777/api/search?query=*&limit=1'`"
+- **Worker not running:** "The claude-mem worker is not responding on port 37777. Start it with your usual method or check `ps aux | grep worker-service`."
+- **Timeline too large:** For projects with 50,000+ observations, the timeline may exceed context limits. Suggest using date range filtering: `curl -s "http://localhost:37777/api/context/inject?project=X&full=true"` -- the current endpoint returns all observations; for extremely large projects, the user may want to analyze in time-windowed segments.
+
+## Example
+
+User: "Write a journey report for the tokyo project"
+
+1. Fetch: `curl -s "http://localhost:37777/api/context/inject?project=tokyo&full=true"`
+2. Estimate: "Timeline fetched: ~34,722 observations, estimated ~718K tokens. Proceed?"
+3. User confirms
+4. Deploy analysis agent with full timeline
+5. Save to `./journey-into-tokyo.md`
+6. Report: "Report saved. Analyzed 34,722 observations spanning Oct 2025 - Mar 2026 (~718K input tokens, ~8K output tokens)."

plugin/skills/version-bump/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: claude-code-plugin-release
+description: Automated semantic versioning and release workflow for Claude Code plugins. Handles version increments across package.json, marketplace.json, and plugin.json, build verification, git tagging, GitHub releases, and changelog generation.
+---
+
+# Version Bump & Release Workflow
+
+**IMPORTANT:** You must first plan and write detailed release notes before starting the version bump workflow.
+
+**CRITICAL:** ALWAYS commit EVERYTHING (including build artifacts). At the end of this workflow, NOTHING should be left uncommitted or unpushed. Run `git status` at the end to verify.
+
+## Preparation
+
+1.  **Analyze**: Determine if the change is a **PATCH** (bug fixes), **MINOR** (features), or **MAJOR** (breaking) update.
+2.  **Environment**: Identify the repository owner and name (e.g., from `git remote -v`).
+3.  **Paths**: Verify existence of `package.json`, `.claude-plugin/marketplace.json`, and `plugin/.claude-plugin/plugin.json`.
+
+## Workflow
+
+1.  **Update**: Increment version strings in all configuration files.
+2.  **Verify**: Use `grep` to ensure all files match the new version.
+3.  **Build**: Run `npm run build` to generate fresh artifacts.
+4.  **Commit**: Stage all changes including artifacts: `git add -A && git commit -m "chore: bump version to X.Y.Z"`.
+5.  **Tag**: Create an annotated tag: `git tag -a vX.Y.Z -m "Version X.Y.Z"`.
+6.  **Push**: `git push origin main && git push origin vX.Y.Z`.
+7.  **Release**: `gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES"`.
+8.  **Changelog**: Regenerate `CHANGELOG.md` using the GitHub API and the provided script:
+    ```bash
+    gh api repos/{owner}/{repo}/releases --paginate | ./scripts/generate_changelog.js > CHANGELOG.md
+    ```
+9.  **Sync**: Commit and push the updated `CHANGELOG.md`.
+10. **Notify**: Run `npm run discord:notify vX.Y.Z` if applicable.
+11. **Finalize**: Run `git status` to ensure a clean working tree.
+
+## Checklist
+
+- [ ] All config files have matching versions
+- [ ] `npm run build` succeeded
+- [ ] Git tag created and pushed
+- [ ] GitHub release created with notes
+- [ ] `CHANGELOG.md` updated and pushed
+- [ ] `git status` shows clean tree

plugin/skills/version-bump/scripts/generate_changelog.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+const fs = require('fs');
+
+/**
+ * Processes GitHub release JSON from stdin and outputs a formatted CHANGELOG.md
+ */
+function generate() {
+  try {
+    const input = fs.readFileSync(0, 'utf8');
+    if (!input || input.trim() === '') {
+      process.stderr.write('No input received on stdin
+');
+      process.exit(1);
+    }
+
+    const releases = JSON.parse(input);
+    const lines = ['# Changelog', '', 'All notable changes to this project.', ''];
+    
+    releases.slice(0, 50).forEach(r => {
+      const date = r.published_at.split('T')[0];
+      lines.push(`## [${r.tag_name}] - ${date}`);
+      lines.push('');
+      if (r.body) lines.push(r.body.trim());
+      lines.push('');
+    });
+    
+    process.stdout.write(lines.join('
+') + '
+');
+  } catch (err) {
+    process.stderr.write(`Error generating changelog: ${err.message}
+`);
+    process.exit(1);
+  }
+}
+
+generate();

scripts/build-hooks.js

@@ -116,7 +116,11 @@ async function buildHooks() {
         '__DEFAULT_PACKAGE_VERSION__': `"${version}"`
       },
       banner: {
-        js: '#!/usr/bin/env bun'
+        js: [
+          '#!/usr/bin/env bun',
+          'var __filename = require("node:url").fileURLToPath(import.meta.url);',
+          'var __dirname = require("node:path").dirname(__filename);'
+        ].join('\n')
       }
     });
 
@@ -176,12 +180,96 @@ async function buildHooks() {
       external: ['bun:sqlite'],
       define: {
         '__DEFAULT_PACKAGE_VERSION__': `"${version}"`
-      }
+      },
+      // No banner needed: CJS files under Node.js have __dirname/__filename natively
     });
 
     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`,
+      banner: { js: '#!/usr/bin/env node' },
+      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, Node.js ESM — Bun-compatible)
+    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 = [
@@ -197,11 +285,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);

scripts/claude-mem-sync

@@ -0,0 +1,181 @@
+#!/bin/bash
+# claude-mem-sync — Synchronize claude-mem observations between machines
+#
+# Usage:
+#   claude-mem-sync push <remote-host>    # local → remote
+#   claude-mem-sync pull <remote-host>    # remote → local
+#   claude-mem-sync sync <remote-host>    # bidirectional (push + pull)
+#   claude-mem-sync status <remote-host>  # compare counts
+#
+# Prerequisites:
+#   - SSH access to remote host (key-based auth recommended)
+#   - Python 3 on both machines
+#   - claude-mem installed on both machines (~/.claude-mem/claude-mem.db)
+#
+# Environment variables:
+#   CLAUDE_MEM_DB         Local database path (default: ~/.claude-mem/claude-mem.db)
+#   CLAUDE_MEM_REMOTE_DB  Remote database path (default: ~/.claude-mem/claude-mem.db)
+
+set -euo pipefail
+
+LOCAL_DB="${CLAUDE_MEM_DB:-$HOME/.claude-mem/claude-mem.db}"
+COMMAND="${1:?Usage: claude-mem-sync <push|pull|sync|status> <remote-host>}"
+REMOTE_HOST="${2:?Missing remote host. Usage: claude-mem-sync $COMMAND <remote-host>}"
+REMOTE_DB="${CLAUDE_MEM_REMOTE_DB:-\$HOME/.claude-mem/claude-mem.db}"
+TMPDIR="/tmp/claude-mem-sync-$$"
+
+mkdir -p "$TMPDIR"
+trap "rm -rf $TMPDIR" EXIT
+
+# Column lists for observations and session_summaries
+OBS_COLS="memory_session_id,project,text,type,title,subtitle,facts,narrative,concepts,files_read,files_modified,prompt_number,discovery_tokens,created_at,created_at_epoch"
+SUM_COLS="memory_session_id,project,request,investigated,learned,completed,next_steps,files_read,files_edited,notes,prompt_number,discovery_tokens,created_at,created_at_epoch"
+
+export_obs() {
+    local db="$1" output="$2"
+    python3 -c "
+import sqlite3, json, sys
+conn = sqlite3.connect('$db')
+cur = conn.cursor()
+cur.execute('''SELECT $OBS_COLS FROM observations ORDER BY created_at''')
+cols = '$OBS_COLS'.split(',')
+rows = [dict(zip(cols, r)) for r in cur.fetchall()]
+cur.execute('''SELECT $SUM_COLS FROM session_summaries ORDER BY created_at''')
+cols2 = '$SUM_COLS'.split(',')
+sums = [dict(zip(cols2, r)) for r in cur.fetchall()]
+json.dump({'observations': rows, 'summaries': sums}, open('$output', 'w'))
+print(f'{len(rows)} obs, {len(sums)} sums exported', file=sys.stderr)
+conn.close()
+"
+}
+
+import_obs() {
+    local db="$1" input="$2"
+    python3 -c "
+import sqlite3, json, sys
+conn = sqlite3.connect('$db')
+cur = conn.cursor()
+cur.execute('SELECT created_at, title FROM observations')
+existing = set((r[0],r[1]) for r in cur.fetchall())
+cur.execute('SELECT created_at, request FROM session_summaries')
+existing_s = set((r[0],r[1]) for r in cur.fetchall())
+data = json.load(open('$input'))
+oi, si = 0, 0
+obs_cols = '$OBS_COLS'.split(',')
+sum_cols = '$SUM_COLS'.split(',')
+obs_placeholders = ','.join(['?'] * len(obs_cols))
+sum_placeholders = ','.join(['?'] * len(sum_cols))
+for o in data['observations']:
+    if (o['created_at'], o['title']) not in existing:
+        cur.execute(f'INSERT INTO observations ($OBS_COLS) VALUES ({obs_placeholders})',
+            tuple(o[k] for k in obs_cols))
+        oi += 1
+for s in data['summaries']:
+    if (s['created_at'], s['request']) not in existing_s:
+        cur.execute(f'INSERT INTO session_summaries ($SUM_COLS) VALUES ({sum_placeholders})',
+            tuple(s[k] for k in sum_cols))
+        si += 1
+conn.commit()
+print(f'{oi} new obs, {si} new sums imported', file=sys.stderr)
+conn.close()
+"
+}
+
+count_db() {
+    local db="$1"
+    python3 -c "
+import sqlite3
+conn = sqlite3.connect('$db')
+cur = conn.cursor()
+cur.execute('SELECT COUNT(*) FROM observations')
+obs = cur.fetchone()[0]
+cur.execute('SELECT COUNT(*) FROM session_summaries')
+sums = cur.fetchone()[0]
+cur.execute('SELECT MAX(created_at) FROM observations')
+last = cur.fetchone()[0] or 'empty'
+print(f'{obs} obs, {sums} sums (last: {last[:19]})')
+conn.close()
+"
+}
+
+case "$COMMAND" in
+    push)
+        echo "=== Push: local → $REMOTE_HOST ==="
+        export_obs "$LOCAL_DB" "$TMPDIR/export.json"
+        scp -q "$TMPDIR/export.json" "$REMOTE_HOST:/tmp/mem-import.json"
+        # Run import on remote
+        ssh "$REMOTE_HOST" "python3 -c \"
+import sqlite3, json, sys
+conn = sqlite3.connect('$REMOTE_DB')
+cur = conn.cursor()
+cur.execute('SELECT created_at, title FROM observations')
+existing = set((r[0],r[1]) for r in cur.fetchall())
+cur.execute('SELECT created_at, request FROM session_summaries')
+existing_s = set((r[0],r[1]) for r in cur.fetchall())
+data = json.load(open('/tmp/mem-import.json'))
+obs_cols = '$OBS_COLS'.split(',')
+sum_cols = '$SUM_COLS'.split(',')
+obs_ph = ','.join(['?'] * len(obs_cols))
+sum_ph = ','.join(['?'] * len(sum_cols))
+oi, si = 0, 0
+for o in data['observations']:
+    if (o['created_at'], o['title']) not in existing:
+        cur.execute(f'INSERT INTO observations ($OBS_COLS) VALUES ({obs_ph})', tuple(o[k] for k in obs_cols))
+        oi += 1
+for s in data['summaries']:
+    if (s['created_at'], s['request']) not in existing_s:
+        cur.execute(f'INSERT INTO session_summaries ($SUM_COLS) VALUES ({sum_ph})', tuple(s[k] for k in sum_cols))
+        si += 1
+conn.commit()
+print(f'Remote: {oi} new obs, {si} new sums imported', file=sys.stderr)
+conn.close()
+\""
+        ;;
+    pull)
+        echo "=== Pull: $REMOTE_HOST → local ==="
+        ssh "$REMOTE_HOST" "python3 -c \"
+import sqlite3, json
+conn = sqlite3.connect('$REMOTE_DB')
+cur = conn.cursor()
+cur.execute('SELECT $OBS_COLS FROM observations ORDER BY created_at')
+cols = '$OBS_COLS'.split(',')
+obs = [dict(zip(cols, r)) for r in cur.fetchall()]
+cur.execute('SELECT $SUM_COLS FROM session_summaries ORDER BY created_at')
+cols2 = '$SUM_COLS'.split(',')
+sums = [dict(zip(cols2, r)) for r in cur.fetchall()]
+json.dump({'observations': obs, 'summaries': sums}, open('/tmp/mem-export.json', 'w'))
+print(f'{len(obs)} obs, {len(sums)} sums exported')
+conn.close()
+\""
+        scp -q "$REMOTE_HOST:/tmp/mem-export.json" "$TMPDIR/import.json"
+        import_obs "$LOCAL_DB" "$TMPDIR/import.json"
+        ;;
+    sync)
+        echo "=== Bidirectional sync with $REMOTE_HOST ==="
+        "$0" push "$REMOTE_HOST"
+        "$0" pull "$REMOTE_HOST"
+        "$0" status "$REMOTE_HOST"
+        ;;
+    status)
+        echo "=== Local ==="
+        count_db "$LOCAL_DB"
+        echo "=== Remote ($REMOTE_HOST) ==="
+        ssh "$REMOTE_HOST" "python3 -c \"
+import sqlite3
+conn = sqlite3.connect('$REMOTE_DB')
+cur = conn.cursor()
+cur.execute('SELECT COUNT(*) FROM observations')
+obs = cur.fetchone()[0]
+cur.execute('SELECT COUNT(*) FROM session_summaries')
+sums = cur.fetchone()[0]
+cur.execute('SELECT MAX(created_at) FROM observations')
+last = cur.fetchone()[0] or 'empty'
+print(f'{obs} obs, {sums} sums (last: {last[:19]})')
+conn.close()
+\""
+        ;;
+    *)
+        echo "Usage: claude-mem-sync <push|pull|sync|status> <remote-host>"
+        exit 1
+        ;;
+esac

src/cli/adapters/gemini-cli.ts

@@ -0,0 +1,128 @@
+import type { PlatformAdapter } from '../types.js';
+
+/**
+ * Gemini CLI Platform Adapter
+ *
+ * Normalizes Gemini CLI's hook JSON to NormalizedHookInput.
+ * Gemini CLI supports 11 lifecycle hooks; we register 8:
+ *
+ * Lifecycle:
+ *   SessionStart  → context     (inject memory context)
+ *   SessionEnd    → session-complete
+ *   PreCompress   → summarize
+ *   Notification  → observation (system events like ToolPermission)
+ *
+ * Agent:
+ *   BeforeAgent   → user-message (captures user prompt)
+ *   AfterAgent    → observation  (full agent response)
+ *
+ * Tool:
+ *   BeforeTool    → observation  (tool intent before execution)
+ *   AfterTool     → observation  (tool result after execution)
+ *
+ * Unmapped (not useful for memory):
+ *   BeforeModel, AfterModel, BeforeToolSelection — model-level events
+ *   that fire per-LLM-call, too chatty for observation capture.
+ *
+ * Base fields (all events): session_id, transcript_path, cwd, hook_event_name, timestamp
+ *
+ * Output format: { continue, stopReason, suppressOutput, systemMessage, decision, reason, hookSpecificOutput }
+ * Advisory hooks (SessionStart, SessionEnd, PreCompress, Notification) ignore flow-control fields.
+ */
+export const geminiCliAdapter: PlatformAdapter = {
+  normalizeInput(raw) {
+    const r = (raw ?? {}) as any;
+
+    // CWD resolution chain: JSON field → env vars → process.cwd()
+    const cwd = r.cwd
+      ?? process.env.GEMINI_CWD
+      ?? process.env.GEMINI_PROJECT_DIR
+      ?? process.env.CLAUDE_PROJECT_DIR
+      ?? process.cwd();
+
+    const sessionId = r.session_id
+      ?? process.env.GEMINI_SESSION_ID
+      ?? undefined;
+
+    const hookEventName: string | undefined = r.hook_event_name;
+
+    // Tool fields — present in BeforeTool, AfterTool
+    let toolName: string | undefined = r.tool_name;
+    let toolInput: unknown = r.tool_input;
+    let toolResponse: unknown = r.tool_response;
+
+    // AfterAgent: synthesize observation shape from the full agent response
+    if (hookEventName === 'AfterAgent' && r.prompt_response) {
+      toolName = toolName ?? 'GeminiAgent';
+      toolInput = toolInput ?? { prompt: r.prompt };
+      toolResponse = toolResponse ?? { response: r.prompt_response };
+    }
+
+    // BeforeTool: has tool_name and tool_input but no tool_response yet
+    // Synthesize a marker so observation handler knows this is pre-execution
+    if (hookEventName === 'BeforeTool' && toolName && !toolResponse) {
+      toolResponse = { _preExecution: true };
+    }
+
+    // Notification: capture as an observation with notification details
+    if (hookEventName === 'Notification') {
+      toolName = toolName ?? 'GeminiNotification';
+      toolInput = toolInput ?? {
+        notification_type: r.notification_type,
+        message: r.message,
+      };
+      toolResponse = toolResponse ?? { details: r.details };
+    }
+
+    // Collect platform-specific metadata
+    const metadata: Record<string, unknown> = {};
+    if (r.source) metadata.source = r.source;                     // SessionStart: startup|resume|clear
+    if (r.reason) metadata.reason = r.reason;                     // SessionEnd: exit|clear|logout|...
+    if (r.trigger) metadata.trigger = r.trigger;                  // PreCompress: auto|manual
+    if (r.mcp_context) metadata.mcp_context = r.mcp_context;     // Tool hooks: MCP server context
+    if (r.notification_type) metadata.notification_type = r.notification_type;
+    if (r.stop_hook_active !== undefined) metadata.stop_hook_active = r.stop_hook_active;
+    if (r.original_request_name) metadata.original_request_name = r.original_request_name;
+    if (hookEventName) metadata.hook_event_name = hookEventName;
+
+    return {
+      sessionId,
+      cwd,
+      prompt: r.prompt,
+      toolName,
+      toolInput,
+      toolResponse,
+      transcriptPath: r.transcript_path,
+      metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+    };
+  },
+
+  formatOutput(result) {
+    // Gemini CLI expects: { continue, stopReason, suppressOutput, systemMessage, decision, reason, hookSpecificOutput }
+    const output: Record<string, unknown> = {};
+
+    // Flow control — always include `continue` to prevent accidental agent termination
+    output.continue = result.continue ?? true;
+
+    if (result.suppressOutput !== undefined) {
+      output.suppressOutput = result.suppressOutput;
+    }
+
+    if (result.systemMessage) {
+      // Strip ANSI escape sequences: matches colors, text formatting, and terminal control codes
+      // Gemini CLI often has issues with ANSI escape sequences in tool output (showing them as raw text)
+      const ansiRegex = /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g;
+      output.systemMessage = result.systemMessage.replace(ansiRegex, '');
+    }
+
+    // hookSpecificOutput is a first-class Gemini CLI field — pass through directly
+    // This includes additionalContext for context injection in SessionStart, BeforeAgent, AfterTool
+    if (result.hookSpecificOutput) {
+      output.hookSpecificOutput = {
+        additionalContext: result.hookSpecificOutput.additionalContext,
+      };
+    }
+
+    return output;
+  }
+};

src/cli/adapters/index.ts

@@ -1,16 +1,21 @@
 import type { PlatformAdapter } from '../types.js';
 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) {
     case 'claude-code': return claudeCodeAdapter;
     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, 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
@@ -66,9 +66,15 @@ export const contextHandler: EventHandler = {
 
       const additionalContext = contextResult.trim();
       const coloredTimeline = colorResult.trim();
+      const platform = input.platform;
 
-      const systemMessage = showTerminalOutput && coloredTimeline
-        ? `${coloredTimeline}\n\nView Observations Live @ http://localhost:${port}`
+      // Use colored timeline for display if available, otherwise fall back to 
+      // plain markdown context (especially useful for platforms like Gemini 
+      // where we want to ensure visibility even if colors aren't fetched).
+      const displayContent = coloredTimeline || (platform === 'gemini-cli' || platform === 'gemini' ? additionalContext : '');
+
+      const systemMessage = showTerminalOutput && displayContent
+        ? `${displayContent}\n\nView Observations Live @ http://localhost:${port}`
         : undefined;
 
       return {

src/cli/handlers/session-init.ts

@@ -87,17 +87,18 @@ export const sessionInitHandler: EventHandler = {
 
     // Skip SDK agent re-initialization if context was already injected for this session (#1079)
     // The prompt was already saved to the database by /api/sessions/init above —
-    // no need to re-start the SDK agent on every turn
-    if (initResult.contextInjected) {
+    // no need to re-start the SDK agent on every turn.
+    // Note: we do NOT return here — semantic injection below must run on every prompt.
+    const skipAgentInit = Boolean(initResult.contextInjected);
+    if (skipAgentInit) {
       logger.info('HOOK', `INIT_COMPLETE | sessionDbId=${sessionDbId} | promptNumber=${promptNumber} | skipped_agent_init=true | reason=context_already_injected`, {
         sessionId: sessionDbId
       });
-      return { continue: true, suppressOutput: true };
     }
 
     // Only initialize SDK agent for Claude Code (not Cursor)
     // Cursor doesn't use the SDK agent - it only needs session/observation storage
-    if (input.platform !== 'cursor' && sessionDbId) {
+    if (!skipAgentInit && input.platform !== 'cursor' && sessionDbId) {
       // Strip leading slash from commands for memory agent
       // /review 101 -> review 101 (more semantic for observations)
       const cleanedPrompt = prompt.startsWith('/') ? prompt.substring(1) : prompt;
@@ -115,14 +116,58 @@ export const sessionInitHandler: EventHandler = {
         // Log but don't throw - SDK agent failure should not block the user's prompt
         logger.failure('HOOK', `SDK agent start failed: ${response.status}`, { sessionDbId, promptNumber });
       }
-    } else if (input.platform === 'cursor') {
+    } else if (!skipAgentInit && input.platform === 'cursor') {
       logger.debug('HOOK', 'session-init: Skipping SDK agent init for Cursor platform', { sessionDbId, promptNumber });
     }
 
+    // Semantic context injection: query Chroma for relevant past observations
+    // and inject as additionalContext so Claude receives relevant memory each prompt.
+    // Controlled by CLAUDE_MEM_SEMANTIC_INJECT setting (default: true).
+    const semanticInject =
+      String(settings.CLAUDE_MEM_SEMANTIC_INJECT).toLowerCase() === 'true';
+    let additionalContext = '';
+
+    if (semanticInject && prompt && prompt.length >= 20 && prompt !== '[media prompt]') {
+      try {
+        const limit = settings.CLAUDE_MEM_SEMANTIC_INJECT_LIMIT || '5';
+        const semanticRes = await workerHttpRequest('/api/context/semantic', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ q: prompt, project, limit })
+        });
+        if (semanticRes.ok) {
+          const data = await semanticRes.json() as { context: string; count: number };
+          if (data.context) {
+            additionalContext = data.context;
+            logger.debug('HOOK', `Semantic injection: ${data.count} observations for prompt`, {
+              sessionId: sessionDbId, count: data.count
+            });
+          }
+        }
+      } catch (e) {
+        // Graceful degradation — semantic injection is optional
+        logger.debug('HOOK', 'Semantic injection unavailable', {
+          error: e instanceof Error ? e.message : String(e)
+        });
+      }
+    }
+
     logger.info('HOOK', `INIT_COMPLETE | sessionDbId=${sessionDbId} | promptNumber=${promptNumber} | project=${project}`, {
       sessionId: sessionDbId
     });
 
+    // Return with semantic context if available
+    if (additionalContext) {
+      return {
+        continue: true,
+        suppressOutput: true,
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext
+        }
+      };
+    }
+
     return { continue: true, suppressOutput: true };
   }
 };

src/cli/handlers/summarize.ts

@@ -1,9 +1,16 @@
 /**
  * Summarize Handler - Stop
  *
- * Extracted from summary-hook.ts - sends summary request to worker.
- * Transcript parsing stays in the hook because only the hook has access to
- * the transcript file path.
+ * Runs in the Stop hook (120s timeout, not capped like SessionEnd).
+ * This is the ONLY place where we can reliably wait for async work.
+ *
+ * Flow:
+ * 1. Queue summarize request to worker
+ * 2. Poll worker until summary processing completes
+ * 3. Call /api/sessions/complete to clean up session
+ *
+ * SessionEnd (1.5s cap from Claude Code) is just a lightweight fallback —
+ * all real work must happen here in Stop.
  */
 
 import type { EventHandler, NormalizedHookInput, HookResult } from '../types.js';
@@ -13,6 +20,8 @@ import { extractLastMessage } from '../../shared/transcript-parser.js';
 import { HOOK_EXIT_CODES, HOOK_TIMEOUTS, getTimeout } from '../../shared/hook-constants.js';
 
 const SUMMARIZE_TIMEOUT_MS = getTimeout(HOOK_TIMEOUTS.DEFAULT);
+const POLL_INTERVAL_MS = 500;
+const MAX_WAIT_FOR_SUMMARY_MS = 110_000; // 110s — fits within Stop hook's 120s timeout
 
 export const summarizeHandler: EventHandler = {
   async execute(input: NormalizedHookInput): Promise<HookResult> {
@@ -35,13 +44,29 @@ export const summarizeHandler: EventHandler = {
     // Extract last assistant message from transcript (the work Claude did)
     // Note: "user" messages in transcripts are mostly tool_results, not actual user input.
     // The user's original request is already stored in user_prompts table.
-    const lastAssistantMessage = extractLastMessage(transcriptPath, 'assistant', true);
+    let lastAssistantMessage = '';
+    try {
+      lastAssistantMessage = extractLastMessage(transcriptPath, 'assistant', true);
+    } catch (err) {
+      logger.warn('HOOK', `Stop hook: failed to extract last assistant message for session ${sessionId}: ${err instanceof Error ? err.message : err}`);
+      return { continue: true, suppressOutput: true, exitCode: HOOK_EXIT_CODES.SUCCESS };
+    }
+
+    // Skip summary if transcript has no assistant message (prevents repeated
+    // empty summarize requests that pollute logs — upstream bug)
+    if (!lastAssistantMessage || !lastAssistantMessage.trim()) {
+      logger.debug('HOOK', 'No assistant message in transcript - skipping summary', {
+        sessionId,
+        transcriptPath
+      });
+      return { continue: true, suppressOutput: true, exitCode: HOOK_EXIT_CODES.SUCCESS };
+    }
 
     logger.dataIn('HOOK', 'Stop: Requesting summary', {
       hasLastAssistantMessage: !!lastAssistantMessage
     });
 
-    // Send to worker - worker handles privacy check and database operations
+    // 1. Queue summarize request — worker returns immediately with { status: 'queued' }
     const response = await workerHttpRequest('/api/sessions/summarize', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -53,11 +78,49 @@ export const summarizeHandler: EventHandler = {
     });
 
     if (!response.ok) {
-      // Return standard response even on failure (matches original behavior)
       return { continue: true, suppressOutput: true };
     }
 
-    logger.debug('HOOK', 'Summary request sent successfully');
+    logger.debug('HOOK', 'Summary request queued, waiting for completion');
+
+    // 2. Poll worker until pending work for this session is done.
+    //    This keeps the Stop hook alive (120s timeout) so the SDK agent
+    //    can finish processing the summary before SessionEnd kills the session.
+    const waitStart = Date.now();
+    while ((Date.now() - waitStart) < MAX_WAIT_FOR_SUMMARY_MS) {
+      await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS));
+      try {
+        const statusResponse = await workerHttpRequest(`/api/sessions/status?contentSessionId=${encodeURIComponent(sessionId)}`, {
+          timeoutMs: 5000
+        });
+        if (statusResponse.ok) {
+          const status = await statusResponse.json() as { queueLength?: number };
+          if ((status.queueLength ?? 0) === 0) {
+            logger.info('HOOK', 'Summary processing complete', {
+              waitedMs: Date.now() - waitStart
+            });
+            break;
+          }
+        }
+      } catch {
+        // Worker may be busy — keep polling
+      }
+    }
+
+    // 3. Complete the session — clean up active sessions map.
+    //    This runs here in Stop (120s timeout) instead of SessionEnd (1.5s cap)
+    //    so it reliably fires after summary work is done.
+    try {
+      await workerHttpRequest('/api/sessions/complete', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ contentSessionId: sessionId }),
+        timeoutMs: 10_000
+      });
+      logger.info('HOOK', 'Session completed in Stop hook', { contentSessionId: sessionId });
+    } catch (err) {
+      logger.warn('HOOK', `Stop hook: session-complete failed: ${err instanceof Error ? err.message : err}`);
+    }
 
     return { continue: true, suppressOutput: true };
   }

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,366 @@
+/**
+ * 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>();
+
+const MAX_SESSION_MAP_ENTRIES = 1000;
+
+function getOrCreateContentSessionId(openCodeSessionId: string): string {
+  if (!contentSessionIdsByOpenCodeSessionId.has(openCodeSessionId)) {
+    // Evict oldest entries when the map exceeds the cap (Map preserves insertion order)
+    while (contentSessionIdsByOpenCodeSessionId.size >= MAX_SESSION_MAP_ENTRIES) {
+      const oldestKey = contentSessionIdsByOpenCodeSessionId.keys().next().value;
+      if (oldestKey !== undefined) {
+        contentSessionIdsByOpenCodeSessionId.delete(oldestKey);
+      } else {
+        break;
+      }
+    }
+    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: false,
+    },
+    {
+      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,551 @@
+/**
+ * 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, rmSync } from 'fs';
+import { join } from 'path';
+
+// Non-TTY detection: @clack/prompts crashes with ENOENT in non-TTY environments
+const isInteractive = process.stdin.isTTY === true;
+
+/** Run a list of tasks, falling back to plain console.log when non-TTY */
+interface TaskDescriptor {
+  title: string;
+  task: (message: (msg: string) => void) => Promise<string>;
+}
+
+async function runTasks(tasks: TaskDescriptor[]): Promise<void> {
+  if (isInteractive) {
+    await p.tasks(tasks);
+  } else {
+    for (const t of tasks) {
+      const result = await t.task((msg: string) => console.log(`  ${msg}`));
+      console.log(`  ${result}`);
+    }
+  }
+}
+
+/** Log helpers that fall back to console.log in non-TTY */
+const log = {
+  info: (msg: string) => isInteractive ? p.log.info(msg) : console.log(`  ${msg}`),
+  success: (msg: string) => isInteractive ? p.log.success(msg) : console.log(`  ${msg}`),
+  warn: (msg: string) => isInteractive ? p.log.warn(msg) : console.warn(`  ${msg}`),
+  error: (msg: string) => isInteractive ? p.log.error(msg) : console.error(`  ${msg}`),
+};
+import {
+  claudeSettingsPath,
+  ensureDirectoryExists,
+  installedPluginsPath,
+  IS_WINDOWS,
+  knownMarketplacesPath,
+  marketplaceDirectory,
+  npmPackagePluginDirectory,
+  npmPackageRootDirectory,
+  pluginCacheDirectory,
+  pluginsDirectory,
+  readPluginVersion,
+  writeJsonFileAtomic,
+} from '../utils/paths.js';
+import { readJsonSafe } from '../../utils/json-utils.js';
+import { detectInstalledIDEs } from './ide-detection.js';
+
+// ---------------------------------------------------------------------------
+// Registration helpers
+// ---------------------------------------------------------------------------
+
+function registerMarketplace(): void {
+  const knownMarketplaces = readJsonSafe<Record<string, any>>(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 = readJsonSafe<Record<string, any>>(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 = readJsonSafe<Record<string, any>>(claudeSettingsPath(), {});
+
+  if (!settings.enabledPlugins) settings.enabledPlugins = {};
+  settings.enabledPlugins['claude-mem@thedotmack'] = true;
+
+  writeJsonFileAtomic(claudeSettingsPath(), settings);
+}
+
+// ---------------------------------------------------------------------------
+// IDE setup dispatcher
+// ---------------------------------------------------------------------------
+
+/** Returns a list of IDE IDs that failed setup. */
+async function setupIDEs(selectedIDEs: string[]): Promise<string[]> {
+  const failedIDEs: string[] = [];
+
+  for (const ideId of selectedIDEs) {
+    switch (ideId) {
+      case 'claude-code': {
+        // Claude Code uses its native plugin CLI — two commands handle
+        // marketplace registration, plugin installation, and enablement.
+        try {
+          execSync(
+            'claude plugin marketplace add thedotmack/claude-mem && claude plugin install claude-mem',
+            { stdio: 'inherit' },
+          );
+          log.success('Claude Code: plugin installed via CLI.');
+        } catch {
+          log.error('Claude Code: plugin install failed. Is `claude` CLI on your PATH?');
+          failedIDEs.push(ideId);
+        }
+        break;
+      }
+
+      case 'cursor':
+        log.warn('Cursor: integration not yet implemented. Skipping.');
+        break;
+
+      case 'gemini-cli': {
+        const { installGeminiCliHooks } = await import('../../services/integrations/GeminiCliHooksInstaller.js');
+        const geminiResult = await installGeminiCliHooks();
+        if (geminiResult === 0) {
+          log.success('Gemini CLI: hooks installed.');
+        } else {
+          log.error('Gemini CLI: hook installation failed.');
+          failedIDEs.push(ideId);
+        }
+        break;
+      }
+
+      case 'opencode': {
+        const { installOpenCodeIntegration } = await import('../../services/integrations/OpenCodeInstaller.js');
+        const openCodeResult = await installOpenCodeIntegration();
+        if (openCodeResult === 0) {
+          log.success('OpenCode: plugin installed.');
+        } else {
+          log.error('OpenCode: plugin installation failed.');
+          failedIDEs.push(ideId);
+        }
+        break;
+      }
+
+      case 'windsurf': {
+        const { installWindsurfHooks } = await import('../../services/integrations/WindsurfHooksInstaller.js');
+        const windsurfResult = await installWindsurfHooks();
+        if (windsurfResult === 0) {
+          log.success('Windsurf: hooks installed.');
+        } else {
+          log.error('Windsurf: hook installation failed.');
+          failedIDEs.push(ideId);
+        }
+        break;
+      }
+
+      case 'openclaw': {
+        const { installOpenClawIntegration } = await import('../../services/integrations/OpenClawInstaller.js');
+        const openClawResult = await installOpenClawIntegration();
+        if (openClawResult === 0) {
+          log.success('OpenClaw: plugin installed.');
+        } else {
+          log.error('OpenClaw: plugin installation failed.');
+          failedIDEs.push(ideId);
+        }
+        break;
+      }
+
+      case 'codex-cli': {
+        const { installCodexCli } = await import('../../services/integrations/CodexCliInstaller.js');
+        const codexResult = await installCodexCli();
+        if (codexResult === 0) {
+          log.success('Codex CLI: transcript watching configured.');
+        } else {
+          log.error('Codex CLI: integration setup failed.');
+          failedIDEs.push(ideId);
+        }
+        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) {
+            log.success(`${ideLabel}: MCP integration installed.`);
+          } else {
+            log.error(`${ideLabel}: MCP integration failed.`);
+            failedIDEs.push(ideId);
+          }
+        }
+        break;
+      }
+
+      default: {
+        const allIDEs = detectInstalledIDEs();
+        const ide = allIDEs.find((i) => i.id === ideId);
+        if (ide && !ide.supported) {
+          log.warn(`Support for ${ide.label} coming soon.`);
+        }
+        break;
+      }
+    }
+  }
+
+  return failedIDEs;
+}
+
+// ---------------------------------------------------------------------------
+// Interactive IDE selection
+// ---------------------------------------------------------------------------
+
+async function promptForIDESelection(): Promise<string[]> {
+  const detectedIDEs = detectInstalledIDEs();
+  const detected = detectedIDEs.filter((ide) => ide.detected);
+
+  if (detected.length === 0) {
+    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;
+
+    // Clean replace: remove stale files from previous installs before copying
+    if (existsSync(destPath)) {
+      rmSync(destPath, { recursive: true, force: true });
+    }
+    cpSync(sourcePath, destPath, {
+      recursive: true,
+      force: true,
+    });
+  }
+}
+
+function copyPluginToCache(version: string): void {
+  const sourcePluginDirectory = npmPackagePluginDirectory();
+  const cachePath = pluginCacheDirectory(version);
+
+  // Clean replace: remove stale cache before copying
+  rmSync(cachePath, { recursive: true, force: true });
+  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(): boolean {
+  const smartInstallPath = join(marketplaceDirectory(), 'plugin', 'scripts', 'smart-install.js');
+
+  if (!existsSync(smartInstallPath)) {
+    log.warn('smart-install.js not found — skipping Bun/uv auto-install.');
+    return false;
+  }
+
+  try {
+    execSync(`node "${smartInstallPath}"`, {
+      stdio: 'inherit',
+      ...(IS_WINDOWS ? { shell: true as const } : {}),
+    });
+    return true;
+  } catch {
+    log.warn('smart-install encountered an issue. You may need to install Bun/uv manually.');
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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();
+
+  if (isInteractive) {
+    p.intro(pc.bgCyan(pc.black(' claude-mem install ')));
+  } else {
+    console.log('claude-mem install');
+  }
+  log.info(`Version: ${pc.cyan(version)}`);
+  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'),
+      );
+      log.warn(`Existing installation detected (v${existingPluginJson.version ?? 'unknown'}).`);
+    } catch {
+      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) {
+      log.error(`Support for ${match.label} coming soon.`);
+      process.exit(1);
+    }
+    if (!match) {
+      log.error(`Unknown IDE: ${options.ide}`);
+      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'];
+  }
+
+  // Non-Claude-Code IDEs need the manual file copy / registration flow.
+  // Claude Code handles its own installation via `claude plugin install`.
+  const needsManualInstall = selectedIDEs.some((id) => id !== 'claude-code');
+
+  if (needsManualInstall) {
+    await runTasks([
+      {
+        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...');
+          return runSmartInstall()
+            ? `Runtime dependencies ready ${pc.green('OK')}`
+            : `Runtime setup may need attention ${pc.yellow('!')}`;
+        },
+      },
+    ]);
+  }
+
+  // IDE-specific setup
+  const failedIDEs = await setupIDEs(selectedIDEs);
+
+  // Summary
+  const installStatus = failedIDEs.length > 0 ? 'Installation Partial' : 'Installation Complete';
+  const summaryLines = [
+    `Version:     ${pc.cyan(version)}`,
+    `Plugin dir:  ${pc.cyan(marketplaceDir)}`,
+    `IDEs:        ${pc.cyan(selectedIDEs.join(', '))}`,
+  ];
+  if (failedIDEs.length > 0) {
+    summaryLines.push(`Failed:      ${pc.red(failedIDEs.join(', '))}`);
+  }
+
+  if (isInteractive) {
+    p.note(summaryLines.join('\n'), installStatus);
+  } else {
+    console.log(`\n  ${installStatus}`);
+    summaryLines.forEach(l => console.log(`  ${l}`));
+  }
+
+  const workerPort = process.env.CLAUDE_MEM_WORKER_PORT || '37777';
+  const nextSteps = [
+    'Open Claude Code and start a conversation -- memory is automatic!',
+    `View your memories: ${pc.underline(`http://localhost:${workerPort}`)}`,
+    `Search past work: use ${pc.bold('/mem-search')} in Claude Code`,
+    `Start worker: ${pc.bold('npx claude-mem start')}`,
+  ];
+
+  if (isInteractive) {
+    p.note(nextSteps.join('\n'), 'Next Steps');
+    if (failedIDEs.length > 0) {
+      p.outro(pc.yellow('claude-mem installed with some IDE setup failures.'));
+    } else {
+      p.outro(pc.green('claude-mem installed successfully!'));
+    }
+  } else {
+    console.log('\n  Next Steps');
+    nextSteps.forEach(l => console.log(`  ${l}`));
+    if (failedIDEs.length > 0) {
+      console.log('\nclaude-mem installed with some IDE setup failures.');
+      process.exitCode = 1;
+    } else {
+      console.log('\nclaude-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,218 @@
+/**
+ * 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,
+  writeJsonFileAtomic,
+} from '../utils/paths.js';
+import { readJsonSafe } from '../../utils/json-utils.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 cacheDirectory = join(pluginsDirectory(), 'cache', 'thedotmack', 'claude-mem');
+  if (existsSync(cacheDirectory)) {
+    rmSync(cacheDirectory, { recursive: true, force: true });
+    return true;
+  }
+  return false;
+}
+
+function removeFromKnownMarketplaces(): void {
+  const knownMarketplaces = readJsonSafe<Record<string, any>>(knownMarketplacesPath(), {});
+  if (knownMarketplaces['thedotmack']) {
+    delete knownMarketplaces['thedotmack'];
+    writeJsonFileAtomic(knownMarketplacesPath(), knownMarketplaces);
+  }
+}
+
+function removeFromInstalledPlugins(): void {
+  const installedPlugins = readJsonSafe<Record<string, any>>(installedPluginsPath(), {});
+  if (installedPlugins.plugins?.['claude-mem@thedotmack']) {
+    delete installedPlugins.plugins['claude-mem@thedotmack'];
+    writeJsonFileAtomic(installedPluginsPath(), installedPlugins);
+  }
+}
+
+function removeFromClaudeSettings(): void {
+  const settings = readJsonSafe<Record<string, any>>(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 and wait for it to exit before deleting files
+  const workerPort = process.env.CLAUDE_MEM_WORKER_PORT || '37777';
+  try {
+    await fetch(`http://127.0.0.1:${workerPort}/api/admin/shutdown`, {
+      method: 'POST',
+      signal: AbortSignal.timeout(5000),
+    });
+    // Poll health endpoint until worker is gone (max 10s)
+    for (let attempt = 0; attempt < 20; attempt++) {
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      try {
+        await fetch(`http://127.0.0.1:${workerPort}/api/health`, {
+          signal: AbortSignal.timeout(1000),
+        });
+        // Still alive — keep waiting
+      } catch {
+        break; // Connection refused = worker is gone
+      }
+    }
+    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')}`;
+      },
+    },
+  ]);
+
+  // Remove IDE-specific hooks and config (best-effort, each is independent)
+  const ideCleanups: Array<{ label: string; fn: () => Promise<number> | number }> = [
+    { label: 'Gemini CLI hooks', fn: async () => {
+      const { uninstallGeminiCliHooks } = await import('../../services/integrations/GeminiCliHooksInstaller.js');
+      return uninstallGeminiCliHooks();
+    }},
+    { label: 'Windsurf hooks', fn: async () => {
+      const { uninstallWindsurfHooks } = await import('../../services/integrations/WindsurfHooksInstaller.js');
+      return uninstallWindsurfHooks();
+    }},
+    { label: 'OpenCode plugin', fn: async () => {
+      const { uninstallOpenCodePlugin } = await import('../../services/integrations/OpenCodeInstaller.js');
+      return uninstallOpenCodePlugin();
+    }},
+    { label: 'OpenClaw plugin', fn: async () => {
+      const { uninstallOpenClawPlugin } = await import('../../services/integrations/OpenClawInstaller.js');
+      return uninstallOpenClawPlugin();
+    }},
+    { label: 'Codex CLI', fn: async () => {
+      const { uninstallCodexCli } = await import('../../services/integrations/CodexCliInstaller.js');
+      return uninstallCodexCli();
+    }},
+  ];
+
+  for (const { label, fn } of ideCleanups) {
+    try {
+      const result = await fn();
+      if (result === 0) {
+        p.log.info(`${label}: removed.`);
+      }
+    } catch {
+      // IDE not configured or uninstaller errored — skip silently
+    }
+  }
+
+  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,174 @@
+/**
+ * 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,156 @@
+/**
+ * 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>
+  const root = join(dirname(currentFilePath), '..', '..');
+  if (!existsSync(join(root, 'package.json'))) {
+    throw new Error(
+      `npmPackageRootDirectory: expected package.json at ${root}. ` +
+      `Bundle structure may have changed — update the path walk.`,
+    );
+  }
+  return root;
+}
+
+/**
+ * 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 });
+  }
+}
+
+/**
+ * @deprecated Use `readJsonSafe` from `../../utils/json-utils.js` instead.
+ * Kept as re-export for backward compatibility.
+ */
+export { readJsonSafe } from '../../utils/json-utils.js';
+
+export function writeJsonFileAtomic(filepath: string, data: any): void {
+  ensureDirectoryExists(dirname(filepath));
+  writeFileSync(filepath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}

src/sdk/parser.ts

@@ -75,7 +75,7 @@ export function parseObservations(text: string, correlationId?: string): ParsedO
     const cleanedConcepts = concepts.filter(c => c !== finalType);
 
     if (cleanedConcepts.length !== concepts.length) {
-      logger.error('PARSER', 'Removed observation type from concepts array', {
+      logger.debug('PARSER', 'Removed observation type from concepts array', {
         correlationId,
         type: finalType,
         originalConcepts: concepts,

src/services/context/ContextBuilder.ts

@@ -134,6 +134,12 @@ export async function generateContext(
   // Use provided projects array (for worktree support) or fall back to single project
   const projects = input?.projects || [project];
 
+  // Full mode: fetch all observations but keep normal rendering (level 1 summaries)
+  if (input?.full) {
+    config.totalObservationCount = 999999;
+    config.sessionCount = 999999;
+  }
+
   // Initialize database
   const db = initializeDatabase();
   if (!db) {
@@ -155,7 +161,7 @@ export async function generateContext(
     }
 
     // Build and return context
-    return buildContextOutput(
+    const output = buildContextOutput(
       project,
       observations,
       summaries,
@@ -164,6 +170,8 @@ export async function generateContext(
       input?.session_id,
       useColors
     );
+
+    return output;
   } finally {
     db.close();
   }

src/services/context/formatters/MarkdownFormatter.ts

@@ -1,7 +1,8 @@
 /**
- * MarkdownFormatter - Formats context output as markdown (non-colored mode)
+ * MarkdownFormatter - Formats context output as compact markdown for LLM injection
  *
- * Handles all markdown formatting for context injection.
+ * Optimized for token efficiency: flat lines instead of tables, no repeated headers.
+ * The colored terminal formatter (ColorFormatter.ts) handles human-readable display separately.
  */
 
 import type {
@@ -34,7 +35,7 @@ function formatHeaderDateTime(): string {
  */
 export function renderMarkdownHeader(project: string): string[] {
   return [
-    `# [${project}] recent context, ${formatHeaderDateTime()}`,
+    `# $CMEM ${project} ${formatHeaderDateTime()}`,
     ''
   ];
 }
@@ -44,39 +45,28 @@ export function renderMarkdownHeader(project: string): string[] {
  */
 export function renderMarkdownLegend(): string[] {
   const mode = ModeManager.getInstance().getActiveMode();
-  const typeLegendItems = mode.observation_types.map(t => `${t.emoji} ${t.id}`).join(' | ');
+  const typeLegendItems = mode.observation_types.map(t => `${t.emoji}${t.id}`).join(' ');
 
   return [
-    `**Legend:** session-request | ${typeLegendItems}`,
+    `Legend: 🎯session ${typeLegendItems}`,
+    `Format: ID TIME TYPE TITLE`,
+    `Fetch details: get_observations([IDs]) | Search: mem-search skill`,
     ''
   ];
 }
 
 /**
- * Render markdown column key
+ * Render markdown column key - no longer needed in compact format
  */
 export function renderMarkdownColumnKey(): string[] {
-  return [
-    `**Column Key**:`,
-    `- **Read**: Tokens to read this observation (cost to learn it now)`,
-    `- **Work**: Tokens spent on work that produced this record ( research, building, deciding)`,
-    ''
-  ];
+  return [];
 }
 
 /**
- * Render markdown context index instructions
+ * Render markdown context index instructions - folded into legend
  */
 export function renderMarkdownContextIndex(): string[] {
-  return [
-    `**Context Index:** This semantic index (titles, types, files, tokens) is usually sufficient to understand past work.`,
-    '',
-    `When you need implementation details, rationale, or debugging context:`,
-    `- Fetch by ID: get_observations([IDs]) for observations visible in this index`,
-    `- Search history: Use the mem-search skill for past decisions, bugs, and deeper research`,
-    `- Trust this index over re-reading code for past decisions and learnings`,
-    ''
-  ];
+  return [];
 }
 
 /**
@@ -88,21 +78,20 @@ export function renderMarkdownContextEconomics(
 ): string[] {
   const output: string[] = [];
 
-  output.push(`**Context Economics**:`);
-  output.push(`- Loading: ${economics.totalObservations} observations (${economics.totalReadTokens.toLocaleString()} tokens to read)`);
-  output.push(`- Work investment: ${economics.totalDiscoveryTokens.toLocaleString()} tokens spent on research, building, and decisions`);
+  const parts: string[] = [
+    `${economics.totalObservations} obs (${economics.totalReadTokens.toLocaleString()}t read)`,
+    `${economics.totalDiscoveryTokens.toLocaleString()}t work`
+  ];
 
   if (economics.totalDiscoveryTokens > 0 && (config.showSavingsAmount || config.showSavingsPercent)) {
-    let savingsLine = '- Your savings: ';
-    if (config.showSavingsAmount && config.showSavingsPercent) {
-      savingsLine += `${economics.savings.toLocaleString()} tokens (${economics.savingsPercent}% reduction from reuse)`;
+    if (config.showSavingsPercent) {
+      parts.push(`${economics.savingsPercent}% savings`);
     } else if (config.showSavingsAmount) {
-      savingsLine += `${economics.savings.toLocaleString()} tokens`;
-    } else {
-      savingsLine += `${economics.savingsPercent}% reduction from reuse`;
+      parts.push(`${economics.savings.toLocaleString()}t saved`);
     }
-    output.push(savingsLine);
   }
+
+  output.push(`Stats: ${parts.join(' | ')}`);
   output.push('');
 
   return output;
@@ -114,37 +103,37 @@ export function renderMarkdownContextEconomics(
 export function renderMarkdownDayHeader(day: string): string[] {
   return [
     `### ${day}`,
-    ''
   ];
 }
 
 /**
- * Render markdown file header with table header
+ * Render markdown file header - no longer renders table headers in compact format
  */
-export function renderMarkdownFileHeader(file: string): string[] {
-  return [
-    `**${file}**`,
-    `| ID | Time | T | Title | Read | Work |`,
-    `|----|------|---|-------|------|------|`
-  ];
+export function renderMarkdownFileHeader(_file: string): string[] {
+  // File grouping eliminated in compact format - file context is in observation titles
+  return [];
 }
 
 /**
- * Render markdown table row for observation
+ * Format compact time: "9:23 AM" → "9:23a", "12:05 PM" → "12:05p"
+ */
+function compactTime(time: string): string {
+  return time.toLowerCase().replace(' am', 'a').replace(' pm', 'p');
+}
+
+/**
+ * Render compact flat line for observation (replaces table row)
  */
 export function renderMarkdownTableRow(
   obs: Observation,
   timeDisplay: string,
-  config: ContextConfig
+  _config: ContextConfig
 ): string {
   const title = obs.title || 'Untitled';
   const icon = ModeManager.getInstance().getTypeIcon(obs.type);
-  const { readTokens, discoveryDisplay } = formatObservationTokenDisplay(obs, config);
+  const time = timeDisplay ? compactTime(timeDisplay) : '"';
 
-  const readCol = config.showReadTokens ? `~${readTokens}` : '';
-  const workCol = config.showWorkTokens ? discoveryDisplay : '';
-
-  return `| #${obs.id} | ${timeDisplay || '"'} | ${icon} | ${title} | ${readCol} | ${workCol} |`;
+  return `${obs.id} ${time} ${icon} ${title}`;
 }
 
 /**
@@ -159,24 +148,23 @@ export function renderMarkdownFullObservation(
   const output: string[] = [];
   const title = obs.title || 'Untitled';
   const icon = ModeManager.getInstance().getTypeIcon(obs.type);
+  const time = timeDisplay ? compactTime(timeDisplay) : '"';
   const { readTokens, discoveryDisplay } = formatObservationTokenDisplay(obs, config);
 
-  output.push(`**#${obs.id}** ${timeDisplay || '"'} ${icon} **${title}**`);
+  output.push(`**${obs.id}** ${time} ${icon} **${title}**`);
   if (detailField) {
-    output.push('');
     output.push(detailField);
-    output.push('');
   }
 
   const tokenParts: string[] = [];
   if (config.showReadTokens) {
-    tokenParts.push(`Read: ~${readTokens}`);
+    tokenParts.push(`~${readTokens}t`);
   }
   if (config.showWorkTokens) {
-    tokenParts.push(`Work: ${discoveryDisplay}`);
+    tokenParts.push(discoveryDisplay);
   }
   if (tokenParts.length > 0) {
-    output.push(tokenParts.join(', '));
+    output.push(tokenParts.join(' '));
   }
   output.push('');
 
@@ -190,10 +178,8 @@ export function renderMarkdownSummaryItem(
   summary: { id: number; request: string | null },
   formattedTime: string
 ): string[] {
-  const summaryTitle = `${summary.request || 'Session started'} (${formattedTime})`;
   return [
-    `**#S${summary.id}** ${summaryTitle}`,
-    ''
+    `S${summary.id} ${summary.request || 'Session started'} (${formattedTime})`,
   ];
 }
 
@@ -229,7 +215,7 @@ export function renderMarkdownFooter(totalDiscoveryTokens: number, totalReadToke
   const workTokensK = Math.round(totalDiscoveryTokens / 1000);
   return [
     '',
-    `Access ${workTokensK}k tokens of past research & decisions for just ${totalReadTokens.toLocaleString()}t. Use the claude-mem skill to access memories by ID.`
+    `Access ${workTokensK}k tokens of past work via get_observations([IDs]) or mem-search skill.`
   ];
 }
 
@@ -237,5 +223,5 @@ export function renderMarkdownFooter(totalDiscoveryTokens: number, totalReadToke
  * Render markdown empty state
  */
 export function renderMarkdownEmptyState(project: string): string {
-  return `# [${project}] recent context, ${formatHeaderDateTime()}\n\nNo previous sessions found for this project yet.`;
+  return `# $CMEM ${project} ${formatHeaderDateTime()}\n\nNo previous sessions found.`;
 }

src/services/context/sections/TimelineRenderer.ts

@@ -1,7 +1,8 @@
 /**
  * TimelineRenderer - Renders the chronological timeline of observations and summaries
  *
- * Handles day grouping, file grouping within days, and table rendering.
+ * Handles day grouping and rendering. In markdown (LLM) mode, uses flat compact lines.
+ * In color (terminal) mode, uses file grouping with visual formatting.
  */
 
 import type {
@@ -49,6 +50,103 @@ function getDetailField(obs: Observation, config: ContextConfig): string | null
   return obs.facts ? parseJsonArray(obs.facts).join('\n') : null;
 }
 
+/**
+ * Render a single day's timeline items (markdown/LLM mode - flat compact lines)
+ */
+function renderDayTimelineMarkdown(
+  day: string,
+  dayItems: TimelineItem[],
+  fullObservationIds: Set<number>,
+  config: ContextConfig,
+): string[] {
+  const output: string[] = [];
+
+  output.push(...Markdown.renderMarkdownDayHeader(day));
+
+  let lastTime = '';
+
+  for (const item of dayItems) {
+    if (item.type === 'summary') {
+      lastTime = '';
+
+      const summary = item.data as SummaryTimelineItem;
+      const formattedTime = formatDateTime(summary.displayTime);
+      output.push(...Markdown.renderMarkdownSummaryItem(summary, formattedTime));
+    } else {
+      const obs = item.data as Observation;
+      const time = formatTime(obs.created_at);
+      const showTime = time !== lastTime;
+      const timeDisplay = showTime ? time : '';
+      lastTime = time;
+
+      const shouldShowFull = fullObservationIds.has(obs.id);
+
+      if (shouldShowFull) {
+        const detailField = getDetailField(obs, config);
+        output.push(...Markdown.renderMarkdownFullObservation(obs, timeDisplay, detailField, config));
+      } else {
+        output.push(Markdown.renderMarkdownTableRow(obs, timeDisplay, config));
+      }
+    }
+  }
+
+  return output;
+}
+
+/**
+ * Render a single day's timeline items (color/terminal mode - file grouped with tables)
+ */
+function renderDayTimelineColor(
+  day: string,
+  dayItems: TimelineItem[],
+  fullObservationIds: Set<number>,
+  config: ContextConfig,
+  cwd: string,
+): string[] {
+  const output: string[] = [];
+
+  output.push(...Color.renderColorDayHeader(day));
+
+  let currentFile: string | null = null;
+  let lastTime = '';
+
+  for (const item of dayItems) {
+    if (item.type === 'summary') {
+      currentFile = null;
+      lastTime = '';
+
+      const summary = item.data as SummaryTimelineItem;
+      const formattedTime = formatDateTime(summary.displayTime);
+      output.push(...Color.renderColorSummaryItem(summary, formattedTime));
+    } else {
+      const obs = item.data as Observation;
+      const file = extractFirstFile(obs.files_modified, cwd, obs.files_read);
+      const time = formatTime(obs.created_at);
+      const showTime = time !== lastTime;
+      lastTime = time;
+
+      const shouldShowFull = fullObservationIds.has(obs.id);
+
+      // Check if we need a new file section
+      if (file !== currentFile) {
+        output.push(...Color.renderColorFileHeader(file));
+        currentFile = file;
+      }
+
+      if (shouldShowFull) {
+        const detailField = getDetailField(obs, config);
+        output.push(...Color.renderColorFullObservation(obs, time, showTime, detailField, config));
+      } else {
+        output.push(Color.renderColorTableRow(obs, time, showTime, config));
+      }
+    }
+  }
+
+  output.push('');
+
+  return output;
+}
+
 /**
  * Render a single day's timeline items
  */
@@ -60,93 +158,10 @@ export function renderDayTimeline(
   cwd: string,
   useColors: boolean
 ): string[] {
-  const output: string[] = [];
-
-  // Day header
   if (useColors) {
-    output.push(...Color.renderColorDayHeader(day));
-  } else {
-    output.push(...Markdown.renderMarkdownDayHeader(day));
+    return renderDayTimelineColor(day, dayItems, fullObservationIds, config, cwd);
   }
-
-  let currentFile: string | null = null;
-  let lastTime = '';
-  let tableOpen = false;
-
-  for (const item of dayItems) {
-    if (item.type === 'summary') {
-      // Close any open table before summary
-      if (tableOpen) {
-        output.push('');
-        tableOpen = false;
-        currentFile = null;
-        lastTime = '';
-      }
-
-      const summary = item.data as SummaryTimelineItem;
-      const formattedTime = formatDateTime(summary.displayTime);
-
-      if (useColors) {
-        output.push(...Color.renderColorSummaryItem(summary, formattedTime));
-      } else {
-        output.push(...Markdown.renderMarkdownSummaryItem(summary, formattedTime));
-      }
-    } else {
-      const obs = item.data as Observation;
-      const file = extractFirstFile(obs.files_modified, cwd, obs.files_read);
-      const time = formatTime(obs.created_at);
-      const showTime = time !== lastTime;
-      const timeDisplay = showTime ? time : '';
-      lastTime = time;
-
-      const shouldShowFull = fullObservationIds.has(obs.id);
-
-      // Check if we need a new file section
-      if (file !== currentFile) {
-        if (tableOpen) {
-          output.push('');
-        }
-
-        if (useColors) {
-          output.push(...Color.renderColorFileHeader(file));
-        } else {
-          output.push(...Markdown.renderMarkdownFileHeader(file));
-        }
-
-        currentFile = file;
-        tableOpen = true;
-      }
-
-      if (shouldShowFull) {
-        const detailField = getDetailField(obs, config);
-
-        if (useColors) {
-          output.push(...Color.renderColorFullObservation(obs, time, showTime, detailField, config));
-        } else {
-          // Close table for full observation in markdown mode
-          if (tableOpen && !useColors) {
-            output.push('');
-            tableOpen = false;
-          }
-          output.push(...Markdown.renderMarkdownFullObservation(obs, timeDisplay, detailField, config));
-          currentFile = null; // Reset to trigger new table header if needed
-        }
-      } else {
-        if (useColors) {
-          output.push(Color.renderColorTableRow(obs, time, showTime, config));
-        } else {
-          output.push(Markdown.renderMarkdownTableRow(obs, timeDisplay, config));
-        }
-      }
-    }
-  }
-
-  // Close any remaining open table
-  if (tableOpen) {
-    output.push('');
-  }
-
-  return output;
+  return renderDayTimelineMarkdown(day, dayItems, fullObservationIds, config);
 }
 
 /**

src/services/context/types.ts

@@ -13,6 +13,8 @@ export interface ContextInput {
   source?: "startup" | "resume" | "clear" | "compact";
   /** Array of projects to query (for worktree support: [parent, worktree]) */
   projects?: string[];
+  /** When true, return ALL observations with no limit */
+  full?: boolean;
   [key: string]: any;
 }
 

src/services/infrastructure/HealthMonitor.ts

@@ -10,6 +10,7 @@
  */
 
 import path from 'path';
+import net from 'net';
 import { readFileSync } from 'fs';
 import { logger } from '../../utils/logger.js';
 import { MARKETPLACE_ROOT } from '../../shared/paths.js';
@@ -35,17 +36,43 @@ async function httpRequestToWorker(
 }
 
 /**
- * Check if a port is in use by querying the health endpoint
+ * Check if a port is in use by attempting an atomic socket bind.
+ * More reliable than HTTP health check for daemon spawn guards —
+ * prevents TOCTOU race where two daemons both see "port free" via
+ * HTTP and then both try to listen() (upstream bug workaround).
+ *
+ * Falls back to HTTP health check on Windows where socket bind
+ * behavior differs.
  */
 export async function isPortInUse(port: number): Promise<boolean> {
-  try {
-    // Note: Removed AbortSignal.timeout to avoid Windows Bun cleanup issue (libuv assertion)
-    const response = await fetch(`http://127.0.0.1:${port}/api/health`);
-    return response.ok;
-  } catch (error) {
-    // [ANTI-PATTERN IGNORED]: Health check polls every 500ms, logging would flood
-    return false;
+  if (process.platform === 'win32') {
+    // APPROVED OVERRIDE: Windows keeps HTTP health check because socket bind
+    // semantics differ (SO_REUSEADDR defaults, firewall prompts). The TOCTOU
+    // race remains on Windows but is an accepted limitation — the atomic
+    // socket approach would cause false positives or UAC popups.
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/health`);
+      return response.ok;
+    } catch {
+      return false;
+    }
   }
+
+  // Unix: atomic socket bind check — no TOCTOU race
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'EADDRINUSE') {
+        resolve(true);
+      } else {
+        resolve(false);
+      }
+    });
+    server.once('listening', () => {
+      server.close(() => resolve(false));
+    });
+    server.listen(port, '127.0.0.1');
+  });
 }
 
 /**

src/services/infrastructure/ProcessManager.ts

@@ -646,18 +646,19 @@ export function spawnDaemon(
       return undefined;
     }
 
-    const escapedRuntimePath = runtimePath.replace(/'/g, "''");
-    const escapedScriptPath = scriptPath.replace(/'/g, "''");
-    const psCommand = `Start-Process -FilePath '${escapedRuntimePath}' -ArgumentList '${escapedScriptPath}','--daemon' -WindowStyle Hidden`;
+    // Use -EncodedCommand to avoid all shell quoting issues with spaces in paths
+    const psScript = `Start-Process -FilePath '${runtimePath.replace(/'/g, "''")}' -ArgumentList @('${scriptPath.replace(/'/g, "''")}','--daemon') -WindowStyle Hidden`;
+    const encodedCommand = Buffer.from(psScript, 'utf16le').toString('base64');
 
     try {
-      execSync(`powershell -NoProfile -Command "${psCommand}"`, {
+      execSync(`powershell -NoProfile -EncodedCommand ${encodedCommand}`, {
         stdio: 'ignore',
         windowsHide: true,
         env
       });
       return 0;
     } catch (error) {
+      // APPROVED OVERRIDE: Windows daemon spawn is best-effort; log and let callers fall back to health checks/retry flow.
       logger.error('SYSTEM', 'Failed to spawn worker daemon on Windows', { runtimePath }, error as Error);
       return undefined;
     }

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/)
-    path.join(path.dirname(__filename), 'mcp-server.cjs'),
-    // Alternative dev location
+    // Development/source 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/)
-    path.join(path.dirname(__filename), 'worker-service.cjs'),
-    // Alternative dev location
+    // Development/source location
     path.join(process.cwd(), 'plugin', 'scripts', 'worker-service.cjs'),
   ];
 

src/services/integrations/GeminiCliHooksInstaller.ts

@@ -0,0 +1,513 @@
+/**
+ * GeminiCliHooksInstaller - Gemini CLI integration for claude-mem
+ *
+ * Installs hooks into ~/.gemini/settings.json using the unified CLI:
+ *   bun worker-service.cjs hook gemini-cli <event>
+ *
+ * This routes through the hook-command.ts framework:
+ *   readJsonFromStdin() → gemini-cli adapter → event handler → POST to worker
+ *
+ * Gemini CLI supports 11 lifecycle hooks; we register 8 that map to
+ * useful memory events. See src/cli/adapters/gemini-cli.ts for the
+ * adapter that normalizes Gemini's stdin JSON to NormalizedHookInput.
+ *
+ * Hook config format (verified against Gemini CLI source):
+ *   {
+ *     "hooks": {
+ *       "AfterTool": [{
+ *         "matcher": "*",
+ *         "hooks": [{ "name": "claude-mem", "type": "command", "command": "...", "timeout": 5000 }]
+ *       }]
+ *     }
+ *   }
+ */
+
+import path from 'path';
+import { homedir } from 'os';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { logger } from '../../utils/logger.js';
+import { findWorkerServicePath, findBunPath } from './CursorHooksInstaller.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** A single hook entry in a Gemini CLI hook group */
+interface GeminiHookEntry {
+  name: string;
+  type: 'command';
+  command: string;
+  timeout: number;
+}
+
+/** A hook group — matcher selects which tools/events this applies to */
+interface GeminiHookGroup {
+  matcher: string;
+  hooks: GeminiHookEntry[];
+}
+
+/** The hooks section in ~/.gemini/settings.json */
+interface GeminiHooksConfig {
+  [eventName: string]: GeminiHookGroup[];
+}
+
+/** Full ~/.gemini/settings.json structure (partial — we only care about hooks) */
+interface GeminiSettingsJson {
+  hooks?: GeminiHooksConfig;
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const GEMINI_CONFIG_DIR = path.join(homedir(), '.gemini');
+const GEMINI_SETTINGS_PATH = path.join(GEMINI_CONFIG_DIR, 'settings.json');
+const GEMINI_MD_PATH = path.join(GEMINI_CONFIG_DIR, 'GEMINI.md');
+
+const HOOK_NAME = 'claude-mem';
+const HOOK_TIMEOUT_MS = 10000;
+
+/**
+ * Mapping from Gemini CLI hook events to internal claude-mem event types.
+ *
+ * These events are processed by hookCommand() in src/cli/hook-command.ts,
+ * which reads stdin via readJsonFromStdin(), normalizes through the
+ * gemini-cli adapter, and dispatches to the matching event handler.
+ *
+ * Events NOT mapped (too chatty for memory capture):
+ *   BeforeModel, AfterModel, BeforeToolSelection
+ */
+const GEMINI_EVENT_TO_INTERNAL_EVENT: Record<string, string> = {
+  'SessionStart': 'context',
+  'BeforeAgent': 'user-message',
+  'AfterAgent': 'observation',
+  'BeforeTool': 'observation',
+  'AfterTool': 'observation',
+  'PreCompress': 'summarize',
+  'Notification': 'observation',
+  'SessionEnd': 'session-complete',
+};
+
+// ============================================================================
+// Hook Command Builder
+// ============================================================================
+
+/**
+ * Build the hook command string for a given Gemini CLI event.
+ *
+ * The command invokes worker-service.cjs with the `hook` subcommand,
+ * which delegates to hookCommand('gemini-cli', event) — the same
+ * framework used by Claude Code and Cursor hooks.
+ *
+ * Pipeline: bun worker-service.cjs hook gemini-cli <event>
+ *   → worker-service.ts parses args, ensures worker daemon is running
+ *   → hookCommand('gemini-cli', '<event>')
+ *   → readJsonFromStdin() reads Gemini's JSON payload
+ *   → geminiCliAdapter.normalizeInput() → NormalizedHookInput
+ *   → eventHandler.execute(input)
+ *   → geminiCliAdapter.formatOutput(result)
+ *   → JSON.stringify to stdout
+ */
+function buildHookCommand(
+  bunPath: string,
+  workerServicePath: string,
+  geminiEventName: string,
+): string {
+  const internalEvent = GEMINI_EVENT_TO_INTERNAL_EVENT[geminiEventName];
+  if (!internalEvent) {
+    throw new Error(`Unknown Gemini CLI event: ${geminiEventName}`);
+  }
+
+  // Double-escape backslashes intentionally: this command string is embedded inside
+  // a JSON value, so `\\` in the source becomes `\` when the JSON is parsed by the
+  // IDE. Without double-escaping, Windows paths like C:\Users would lose their
+  // backslashes and break when the IDE deserializes the hook configuration.
+  const escapedBunPath = bunPath.replace(/\\/g, '\\\\');
+  const escapedWorkerPath = workerServicePath.replace(/\\/g, '\\\\');
+
+  return `"${escapedBunPath}" "${escapedWorkerPath}" hook gemini-cli ${internalEvent}`;
+}
+
+/**
+ * Create a hook group entry for a Gemini CLI event.
+ * Uses matcher "*" to match all tools/contexts for that event.
+ */
+function createHookGroup(hookCommand: string): GeminiHookGroup {
+  return {
+    matcher: '*',
+    hooks: [{
+      name: HOOK_NAME,
+      type: 'command',
+      command: hookCommand,
+      timeout: HOOK_TIMEOUT_MS,
+    }],
+  };
+}
+
+// ============================================================================
+// Settings JSON Management
+// ============================================================================
+
+/**
+ * Read ~/.gemini/settings.json, returning empty object if missing.
+ * Throws on corrupt JSON to prevent silent data loss.
+ */
+function readGeminiSettings(): GeminiSettingsJson {
+  if (!existsSync(GEMINI_SETTINGS_PATH)) {
+    return {};
+  }
+
+  const content = readFileSync(GEMINI_SETTINGS_PATH, 'utf-8');
+  try {
+    return JSON.parse(content) as GeminiSettingsJson;
+  } catch (error) {
+    throw new Error(`Corrupt JSON in ${GEMINI_SETTINGS_PATH}, refusing to overwrite user settings`);
+  }
+}
+
+/**
+ * Write settings back to ~/.gemini/settings.json.
+ * Creates the directory if it doesn't exist.
+ */
+function writeGeminiSettings(settings: GeminiSettingsJson): void {
+  mkdirSync(GEMINI_CONFIG_DIR, { recursive: true });
+  writeFileSync(GEMINI_SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+}
+
+/**
+ * Deep-merge claude-mem hooks into existing settings.
+ *
+ * For each event:
+ * - If the event already has a hook group with a claude-mem hook, update it
+ * - Otherwise, append a new hook group
+ *
+ * Preserves all non-claude-mem hooks and all non-hook settings.
+ */
+function mergeHooksIntoSettings(
+  existingSettings: GeminiSettingsJson,
+  newHooks: GeminiHooksConfig,
+): GeminiSettingsJson {
+  const settings = { ...existingSettings };
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+
+  for (const [eventName, newGroups] of Object.entries(newHooks)) {
+    const existingGroups: GeminiHookGroup[] = settings.hooks[eventName] ?? [];
+
+    // For each new hook group, check if there's already a group
+    // containing a claude-mem hook — update it in place
+    for (const newGroup of newGroups) {
+      const existingGroupIndex = existingGroups.findIndex((group: GeminiHookGroup) =>
+        group.hooks.some((hook: GeminiHookEntry) => hook.name === HOOK_NAME)
+      );
+
+      if (existingGroupIndex >= 0) {
+        // Update existing group: replace the claude-mem hook entry
+        const existingGroup: GeminiHookGroup = existingGroups[existingGroupIndex];
+        const hookIndex = existingGroup.hooks.findIndex((hook: GeminiHookEntry) => hook.name === HOOK_NAME);
+        if (hookIndex >= 0) {
+          existingGroup.hooks[hookIndex] = newGroup.hooks[0];
+        } else {
+          existingGroup.hooks.push(newGroup.hooks[0]);
+        }
+      } else {
+        // No existing claude-mem group — append
+        existingGroups.push(newGroup);
+      }
+    }
+
+    settings.hooks[eventName] = existingGroups;
+  }
+
+  return settings;
+}
+
+// ============================================================================
+// GEMINI.md Context Injection
+// ============================================================================
+
+/**
+ * Append or update the claude-mem context section in ~/.gemini/GEMINI.md.
+ * Uses the same <claude-mem-context> tag pattern as CLAUDE.md.
+ */
+function setupGeminiMdContextSection(): void {
+  const contextTag = '<claude-mem-context>';
+  const contextEndTag = '</claude-mem-context>';
+  const placeholder = `${contextTag}
+# Memory Context from Past Sessions
+
+*No context yet. Complete your first session and context will appear here.*
+${contextEndTag}`;
+
+  let content = '';
+  if (existsSync(GEMINI_MD_PATH)) {
+    content = readFileSync(GEMINI_MD_PATH, 'utf-8');
+  }
+
+  if (content.includes(contextTag)) {
+    // Already has claude-mem section — leave it alone (may have real context)
+    return;
+  }
+
+  // Append the section
+  const separator = content.length > 0 && !content.endsWith('\n') ? '\n\n' : content.length > 0 ? '\n' : '';
+  const newContent = content + separator + placeholder + '\n';
+
+  mkdirSync(GEMINI_CONFIG_DIR, { recursive: true });
+  writeFileSync(GEMINI_MD_PATH, newContent);
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Install claude-mem hooks into ~/.gemini/settings.json.
+ *
+ * Merges hooks non-destructively: existing settings and non-claude-mem
+ * hooks are preserved. Existing claude-mem hooks are updated in place.
+ *
+ * @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 {
+    // Build hook commands for all mapped events
+    const hooksConfig: GeminiHooksConfig = {};
+    for (const geminiEvent of Object.keys(GEMINI_EVENT_TO_INTERNAL_EVENT)) {
+      const command = buildHookCommand(bunPath, workerServicePath, geminiEvent);
+      hooksConfig[geminiEvent] = [createHookGroup(command)];
+    }
+
+    // Read existing settings and merge
+    const existingSettings = readGeminiSettings();
+    const mergedSettings = mergeHooksIntoSettings(existingSettings, hooksConfig);
+
+    // Write back
+    writeGeminiSettings(mergedSettings);
+    console.log(`  Merged hooks into ${GEMINI_SETTINGS_PATH}`);
+
+    // Setup GEMINI.md context injection
+    setupGeminiMdContextSection();
+    console.log(`  Setup context injection in ${GEMINI_MD_PATH}`);
+
+    // List installed events
+    const eventNames = Object.keys(GEMINI_EVENT_TO_INTERNAL_EVENT);
+    console.log(`  Registered ${eventNames.length} hook events:`);
+    for (const event of eventNames) {
+      const internalEvent = GEMINI_EVENT_TO_INTERNAL_EVENT[event];
+      console.log(`    ${event} → ${internalEvent}`);
+    }
+
+    console.log(`
+Installation complete!
+
+Hooks installed to: ${GEMINI_SETTINGS_PATH}
+Using unified CLI: bun worker-service.cjs hook gemini-cli <event>
+
+Next steps:
+  1. Start claude-mem worker: claude-mem start
+  2. Restart Gemini CLI to load the hooks
+  3. Memory will be captured automatically during sessions
+
+Context Injection:
+  Context from past sessions is injected via ~/.gemini/GEMINI.md
+  and automatically included in Gemini CLI conversations.
+`);
+
+    return 0;
+  } catch (error) {
+    console.error(`\nInstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+/**
+ * Uninstall claude-mem hooks from ~/.gemini/settings.json.
+ *
+ * Removes only claude-mem hooks — other hooks and settings are preserved.
+ *
+ * @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 Gemini CLI settings found — nothing to uninstall.');
+      return 0;
+    }
+
+    const settings = readGeminiSettings();
+    if (!settings.hooks) {
+      console.log('  No hooks found in Gemini CLI settings — nothing to uninstall.');
+      return 0;
+    }
+
+    let removedCount = 0;
+
+    // Remove claude-mem hooks from within each group, preserving other hooks
+    for (const [eventName, groups] of Object.entries(settings.hooks)) {
+      const filteredGroups = groups
+        .map(group => {
+          const remainingHooks = group.hooks.filter(hook => hook.name !== HOOK_NAME);
+          removedCount += group.hooks.length - remainingHooks.length;
+          return { ...group, hooks: remainingHooks };
+        })
+        .filter(group => group.hooks.length > 0);
+
+      if (filteredGroups.length > 0) {
+        settings.hooks[eventName] = filteredGroups;
+      } else {
+        delete settings.hooks[eventName];
+      }
+    }
+
+    // Clean up empty hooks object
+    if (Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks;
+    }
+
+    writeGeminiSettings(settings);
+    console.log(`  Removed ${removedCount} claude-mem hook(s) from ${GEMINI_SETTINGS_PATH}`);
+
+    // Remove claude-mem context section from GEMINI.md
+    if (existsSync(GEMINI_MD_PATH)) {
+      let mdContent = readFileSync(GEMINI_MD_PATH, 'utf-8');
+      const contextRegex = /\n?<claude-mem-context>[\s\S]*?<\/claude-mem-context>\n?/;
+      if (contextRegex.test(mdContent)) {
+        mdContent = mdContent.replace(contextRegex, '');
+        writeFileSync(GEMINI_MD_PATH, mdContent);
+        console.log(`  Removed context section from ${GEMINI_MD_PATH}`);
+      }
+    }
+
+    console.log('\nUninstallation complete!\n');
+    console.log('Restart Gemini CLI to apply changes.');
+    return 0;
+  } catch (error) {
+    console.error(`\nUninstallation failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+/**
+ * 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('Gemini CLI settings: Not found');
+    console.log(`  Expected at: ${GEMINI_SETTINGS_PATH}\n`);
+    console.log('No hooks installed. Run: claude-mem install --ide gemini-cli\n');
+    return 0;
+  }
+
+  let settings: GeminiSettingsJson;
+  try {
+    settings = readGeminiSettings();
+  } catch (error) {
+    console.log(`Gemini CLI settings: ${(error as Error).message}\n`);
+    return 0;
+  }
+
+  if (!settings.hooks) {
+    console.log('Gemini CLI settings: Found, but no hooks configured\n');
+    console.log('No hooks installed. Run: claude-mem install --ide gemini-cli\n');
+    return 0;
+  }
+
+  // Check for claude-mem hooks
+  const installedEvents: string[] = [];
+  for (const [eventName, groups] of Object.entries(settings.hooks)) {
+    const hasClaudeMem = groups.some(group =>
+      group.hooks.some(hook => hook.name === HOOK_NAME)
+    );
+    if (hasClaudeMem) {
+      installedEvents.push(eventName);
+    }
+  }
+
+  if (installedEvents.length === 0) {
+    console.log('Gemini CLI settings: Found, but no claude-mem hooks\n');
+    console.log('Run: claude-mem install --ide gemini-cli\n');
+    return 0;
+  }
+
+  console.log(`Settings: ${GEMINI_SETTINGS_PATH}`);
+  console.log(`Mode: Unified CLI (bun worker-service.cjs hook gemini-cli)`);
+  console.log(`Events: ${installedEvents.length} of ${Object.keys(GEMINI_EVENT_TO_INTERNAL_EVENT).length} mapped`);
+  for (const event of installedEvents) {
+    const internalEvent = GEMINI_EVENT_TO_INTERNAL_EVENT[event] ?? 'unknown';
+    console.log(`  ${event} → ${internalEvent}`);
+  }
+
+  // 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 missing claude-mem section');
+    }
+  } else {
+    console.log('Context: No GEMINI.md found');
+  }
+
+  console.log('');
+  return 0;
+}
+
+/**
+ * Handle gemini-cli subcommand for hooks management.
+ */
+export async function handleGeminiCliCommand(subcommand: string, _args: string[]): Promise<number> {
+  switch (subcommand) {
+    case 'install':
+      return installGeminiCliHooks();
+
+    case 'uninstall':
+      return uninstallGeminiCliHooks();
+
+    case 'status':
+      return checkGeminiCliHooksStatus();
+
+    default:
+      console.log(`
+Claude-Mem Gemini CLI Integration
+
+Usage: claude-mem gemini-cli <command>
+
+Commands:
+  install             Install hooks into ~/.gemini/settings.json
+  uninstall           Remove claude-mem hooks (preserves other hooks)
+  status              Check installation status
+
+Examples:
+  claude-mem gemini-cli install     # Install hooks
+  claude-mem gemini-cli status      # Check if installed
+  claude-mem gemini-cli uninstall   # Remove hooks
+
+For more info: https://docs.claude-mem.ai/usage/gemini-provider
+      `);
+      return 0;
+  }
+}

src/services/integrations/McpIntegrations.ts

@@ -0,0 +1,358 @@
+/**
+ * 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';
+import { readJsonSafe } from '../../utils/json-utils.js';
+import { injectContextIntoMarkdownFile } from '../../utils/context-injection.js';
+
+// ============================================================================
+// Shared Constants
+// ============================================================================
+
+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: process.execPath,
+    args: [mcpServerPath],
+  };
+}
+
+/**
+ * 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');
+}
+
+// ============================================================================
+// MCP Installer Factory (Phase 1D)
+// ============================================================================
+
+/**
+ * Configuration for a JSON-based MCP IDE integration.
+ */
+interface McpInstallerConfig {
+  ideId: string;
+  ideLabel: string;
+  configPath: string;
+  configKey: 'servers' | 'mcpServers';
+  contextFile?: {
+    path: string;
+    isWorkspaceRelative: boolean;
+  };
+}
+
+/**
+ * Factory function that creates an MCP installer for any JSON-config-based IDE.
+ * Handles MCP config writing and optional context injection.
+ */
+function installMcpIntegration(config: McpInstallerConfig): () => Promise<number> {
+  return async (): Promise<number> => {
+    console.log(`\nInstalling Claude-Mem MCP integration for ${config.ideLabel}...\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 = config.configPath;
+
+      // Warp special case: skip config write if ~/.warp/ doesn't exist
+      if (config.ideId === 'warp' && !existsSync(path.dirname(configPath))) {
+        console.log(`  Note: ~/.warp/ not found. MCP may need to be configured via Warp Drive UI.`);
+      } else {
+        writeMcpJsonConfig(configPath, mcpServerPath, config.configKey);
+        console.log(`  MCP config written to: ${configPath}`);
+      }
+
+      // Inject context if configured
+      let contextPath: string | undefined;
+      if (config.contextFile) {
+        contextPath = config.contextFile.path;
+        injectContextIntoMarkdownFile(contextPath, PLACEHOLDER_CONTEXT);
+        console.log(`  Context placeholder written to: ${contextPath}`);
+      }
+
+      // Print summary
+      const summaryLines = [`\nInstallation complete!\n`];
+      summaryLines.push(`MCP config:  ${configPath}`);
+      if (contextPath) {
+        summaryLines.push(`Context:     ${contextPath}`);
+      }
+      summaryLines.push('');
+      summaryLines.push(`Note: This is an MCP-only integration providing search tools and context.`);
+      summaryLines.push(`Transcript capture is not available for ${config.ideLabel}.`);
+      if (config.ideId === 'warp') {
+        summaryLines.push('If MCP config via file is not supported, configure MCP through Warp Drive UI.');
+      }
+      summaryLines.push('');
+      summaryLines.push('Next steps:');
+      summaryLines.push('  1. Start claude-mem worker: npx claude-mem start');
+      summaryLines.push(`  2. Restart ${config.ideLabel} to pick up the MCP server`);
+      summaryLines.push('');
+      console.log(summaryLines.join('\n'));
+
+      return 0;
+    } catch (error) {
+      console.error(`\nInstallation failed: ${(error as Error).message}`);
+      return 1;
+    }
+  };
+}
+
+// ============================================================================
+// Factory Configs for JSON-based IDEs
+// ============================================================================
+
+const COPILOT_CLI_CONFIG: McpInstallerConfig = {
+  ideId: 'copilot-cli',
+  ideLabel: 'Copilot CLI',
+  configPath: path.join(homedir(), '.github', 'copilot', 'mcp.json'),
+  configKey: 'servers',
+  contextFile: {
+    path: path.join(process.cwd(), '.github', 'copilot-instructions.md'),
+    isWorkspaceRelative: true,
+  },
+};
+
+const ANTIGRAVITY_CONFIG: McpInstallerConfig = {
+  ideId: 'antigravity',
+  ideLabel: 'Antigravity',
+  configPath: path.join(homedir(), '.gemini', 'antigravity', 'mcp_config.json'),
+  configKey: 'mcpServers',
+  contextFile: {
+    path: path.join(process.cwd(), '.agent', 'rules', 'claude-mem-context.md'),
+    isWorkspaceRelative: true,
+  },
+};
+
+const CRUSH_CONFIG: McpInstallerConfig = {
+  ideId: 'crush',
+  ideLabel: 'Crush',
+  configPath: path.join(homedir(), '.config', 'crush', 'mcp.json'),
+  configKey: 'mcpServers',
+};
+
+const ROO_CODE_CONFIG: McpInstallerConfig = {
+  ideId: 'roo-code',
+  ideLabel: 'Roo Code',
+  configPath: path.join(process.cwd(), '.roo', 'mcp.json'),
+  configKey: 'mcpServers',
+  contextFile: {
+    path: path.join(process.cwd(), '.roo', 'rules', 'claude-mem-context.md'),
+    isWorkspaceRelative: true,
+  },
+};
+
+const WARP_CONFIG: McpInstallerConfig = {
+  ideId: 'warp',
+  ideLabel: 'Warp',
+  configPath: path.join(homedir(), '.warp', 'mcp.json'),
+  configKey: 'mcpServers',
+  contextFile: {
+    path: path.join(process.cwd(), 'WARP.md'),
+    isWorkspaceRelative: true,
+  },
+};
+
+// ============================================================================
+// Goose (YAML-based — separate handler)
+// ============================================================================
+
+/**
+ * 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: ${process.execPath}`,
+    '    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: ${process.execPath}`,
+    '    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|^\S|$))/m;
+        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;
+  }
+}
+
+// ============================================================================
+// 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': installMcpIntegration(COPILOT_CLI_CONFIG),
+  'antigravity': installMcpIntegration(ANTIGRAVITY_CONFIG),
+  'goose': installGooseMcpIntegration,
+  'crush': installMcpIntegration(CRUSH_CONFIG),
+  'roo-code': installMcpIntegration(ROO_CODE_CONFIG),
+  'warp': installMcpIntegration(WARP_CONFIG),
+};

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,372 @@
+/**
+ * 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 { fileURLToPath } from 'url';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, unlinkSync } from 'fs';
+import { logger } from '../../utils/logger.js';
+import { CONTEXT_TAG_OPEN, CONTEXT_TAG_CLOSE, injectContextIntoMarkdownFile } from '../../utils/context-injection.js';
+import { getWorkerPort } from '../../shared/worker-utils.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 this module's package root)
+    path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '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)
+// ============================================================================
+
+/**
+ * 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();
+
+  try {
+    injectContextIntoMarkdownFile(agentsMdPath, contextContent, '# Claude-Mem Memory Context');
+    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()) {
+      const injectResult = injectContextIntoAgentsMd(contextText);
+      if (injectResult !== 0) {
+        logger.warn('OPENCODE', 'Failed to inject context into AGENTS.md during sync');
+      }
+    }
+  } 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 or only has our header, remove it
+        const trimmedContent = content.trim();
+        if (
+          trimmedContent.length === 0 ||
+          trimmedContent === '# Claude-Mem Memory Context'
+        ) {
+          unlinkSync(agentsMdPath);
+          console.log(`  Removed empty AGENTS.md`);
+        } else {
+          writeFileSync(agentsMdPath, trimmedContent + '\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 workerPort = getWorkerPort();
+    const healthResponse = await fetch(`http://127.0.0.1:${workerPort}/api/readiness`);
+    if (healthResponse.ok) {
+      const contextResponse = await fetch(
+        `http://127.0.0.1:${workerPort}/api/context/inject?project=opencode`,
+      );
+      if (contextResponse.ok) {
+        const realContext = await contextResponse.text();
+        if (realContext && realContext.trim()) {
+          const injectResult = injectContextIntoAgentsMd(realContext);
+          if (injectResult !== 0) {
+            logger.warn('OPENCODE', 'Failed to inject real context into AGENTS.md during install');
+          } else {
+            console.log('  Context injected from existing memory');
+          }
+        } else {
+          const injectResult = injectContextIntoAgentsMd(placeholderContext);
+          if (injectResult !== 0) {
+            logger.warn('OPENCODE', 'Failed to inject placeholder context into AGENTS.md during install');
+          } else {
+            console.log('  Placeholder context created (will populate after first session)');
+          }
+        }
+      } else {
+        const injectResult = injectContextIntoAgentsMd(placeholderContext);
+        if (injectResult !== 0) {
+          logger.warn('OPENCODE', 'Failed to inject placeholder context into AGENTS.md during install');
+        }
+      }
+    } else {
+      const injectResult = injectContextIntoAgentsMd(placeholderContext);
+      if (injectResult !== 0) {
+        logger.warn('OPENCODE', 'Failed to inject placeholder context into AGENTS.md during install');
+      } else {
+        console.log('  Placeholder context created (worker not running)');
+      }
+    }
+  } catch {
+    const injectResult = injectContextIntoAgentsMd(placeholderContext);
+    if (injectResult !== 0) {
+      logger.warn('OPENCODE', 'Failed to inject placeholder context into AGENTS.md during install');
+    } else {
+      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,514 @@
+/**
+ * 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 {
+  [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.
+ * Keys by full workspacePath to avoid collisions between directories with the same basename.
+ */
+export function registerWindsurfProject(workspacePath: string): void {
+  const registry = readWindsurfRegistry();
+  registry[workspacePath] = {
+    installedAt: new Date().toISOString(),
+  };
+  writeWindsurfRegistry(registry);
+  logger.info('WINDSURF', 'Registered project for auto-context updates', { workspacePath });
+}
+
+/**
+ * Unregister a project from auto-context updates
+ */
+export function unregisterWindsurfProject(workspacePath: string): void {
+  const registry = readWindsurfRegistry();
+  if (registry[workspacePath]) {
+    delete registry[workspacePath];
+    writeWindsurfRegistry(registry);
+    logger.info('WINDSURF', 'Unregistered project', { workspacePath });
+  }
+}
+
+/**
+ * Update Windsurf context files for a registered project.
+ * Called by SDK agents after saving a summary.
+ */
+export async function updateWindsurfContextForProject(projectName: string, workspacePath: string, port: number): Promise<void> {
+  const registry = readWindsurfRegistry();
+  const entry = registry[workspacePath];
+
+  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(workspacePath, context);
+    logger.debug('WINDSURF', 'Updated context file', { projectName, workspacePath });
+  } catch (error) {
+    // Background context update — failure is non-critical
+    logger.error('WINDSURF', 'Failed to update context file', { projectName, workspacePath }, 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';
+
+  return `"${bunPath}" "${workerServicePath}" 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) {
+      throw new Error(`Corrupt hooks.json at ${WINDSURF_HOOKS_JSON_PATH}, refusing to overwrite`);
+    }
+  }
+
+  // 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();
+  if (!bunPath) {
+    console.error('Could not find Bun runtime');
+    console.error('   Install Bun: curl -fsSL https://bun.sh/install | bash');
+    return 1;
+  }
+
+  // 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(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) {
+        console.log(`  Warning: could not parse hooks.json — leaving file intact to preserve other hooks`);
+      }
+    } 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
+    unregisterWindsurfProject(workspaceRoot);
+    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/sqlite/PendingMessageStore.ts

@@ -397,6 +397,19 @@ export class PendingMessageStore {
     return result.count;
   }
 
+  /**
+   * Peek at pending message types for a session (for tier routing).
+   * Returns list of { message_type, tool_name } without claiming.
+   */
+  peekPendingTypes(sessionDbId: number): Array<{ message_type: string; tool_name: string | null }> {
+    const stmt = this.db.prepare(`
+      SELECT message_type, tool_name FROM pending_messages
+      WHERE session_db_id = ? AND status IN ('pending', 'processing')
+      ORDER BY id ASC
+    `);
+    return stmt.all(sessionDbId) as Array<{ message_type: string; tool_name: string | null }>;
+  }
+
   /**
    * Check if any session has pending work.
    * Excludes 'processing' messages stuck for >5 minutes (resets them to 'pending' as a side effect).

src/services/sqlite/migrations.ts

@@ -509,6 +509,38 @@ export const migration007: Migration = {
 };
 
 
+/**
+ * All migrations in order
+ */
+/**
+ * Migration 008: Observation feedback table for tracking observation usage
+ *
+ * Tracks how observations are used (semantic injection hits, search access,
+ * explicit retrieval). Foundation for future Thompson Sampling optimization.
+ */
+export const migration008: Migration = {
+  version: 25,
+  up: (db: Database) => {
+    db.run(`
+      CREATE TABLE IF NOT EXISTS observation_feedback (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        observation_id INTEGER NOT NULL,
+        signal_type TEXT NOT NULL,
+        session_db_id INTEGER,
+        created_at_epoch INTEGER NOT NULL,
+        metadata TEXT,
+        FOREIGN KEY (observation_id) REFERENCES observations(id) ON DELETE CASCADE
+      )
+    `);
+    db.run(`CREATE INDEX IF NOT EXISTS idx_feedback_observation ON observation_feedback(observation_id)`);
+    db.run(`CREATE INDEX IF NOT EXISTS idx_feedback_signal ON observation_feedback(signal_type)`);
+    console.log('✅ Created observation_feedback table for usage tracking');
+  },
+  down: (db: Database) => {
+    db.run(`DROP TABLE IF EXISTS observation_feedback`);
+  }
+};
+
 /**
  * All migrations in order
  */
@@ -519,5 +551,6 @@ export const migrations: Migration[] = [
   migration004,
   migration005,
   migration006,
-  migration007
+  migration007,
+  migration008
 ];

src/services/sqlite/migrations/runner.ts

@@ -34,6 +34,7 @@ export class MigrationRunner {
     this.addOnUpdateCascadeToForeignKeys();
     this.addObservationContentHashColumn();
     this.addSessionCustomTitleColumn();
+    this.createObservationFeedbackTable();
   }
 
   /**
@@ -863,4 +864,31 @@ export class MigrationRunner {
 
     this.db.prepare('INSERT OR IGNORE INTO schema_versions (version, applied_at) VALUES (?, ?)').run(23, new Date().toISOString());
   }
+
+  /**
+   * Create observation_feedback table for tracking observation usage signals.
+   * Foundation for tier routing optimization and future Thompson Sampling.
+   * Schema version 24.
+   */
+  private createObservationFeedbackTable(): void {
+    const applied = this.db.query('SELECT 1 FROM schema_versions WHERE version = 24').get();
+    if (applied) return;
+
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS observation_feedback (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        observation_id INTEGER NOT NULL,
+        signal_type TEXT NOT NULL,
+        session_db_id INTEGER,
+        created_at_epoch INTEGER NOT NULL,
+        metadata TEXT,
+        FOREIGN KEY (observation_id) REFERENCES observations(id) ON DELETE CASCADE
+      )
+    `);
+    this.db.run('CREATE INDEX IF NOT EXISTS idx_feedback_observation ON observation_feedback(observation_id)');
+    this.db.run('CREATE INDEX IF NOT EXISTS idx_feedback_signal ON observation_feedback(signal_type)');
+
+    this.db.prepare('INSERT OR IGNORE INTO schema_versions (version, applied_at) VALUES (?, ?)').run(24, new Date().toISOString());
+    logger.debug('DB', 'Created observation_feedback table for usage tracking');
+  }
 }

src/services/sync/ChromaSync.ts

@@ -283,11 +283,41 @@ export class ChromaSync {
           metadatas: cleanMetadatas
         });
       } catch (error) {
-        logger.error('CHROMA_SYNC', 'Batch add failed, continuing with remaining batches', {
-          collection: this.collectionName,
-          batchStart: i,
-          batchSize: batch.length
-        }, error as Error);
+        const errMsg = error instanceof Error ? error.message : String(error);
+        // APPROVED OVERRIDE: Duplicate IDs from partial write before timeout/crash.
+        // chroma_update_documents only updates *existing* IDs — it silently ignores
+        // missing ones. So we delete-then-add to guarantee all IDs are written.
+        if (errMsg.includes('already exist')) {
+          try {
+            await chromaMcp.callTool('chroma_delete_documents', {
+              collection_name: this.collectionName,
+              ids: batch.map(d => d.id)
+            });
+            await chromaMcp.callTool('chroma_add_documents', {
+              collection_name: this.collectionName,
+              ids: batch.map(d => d.id),
+              documents: batch.map(d => d.document),
+              metadatas: cleanMetadatas
+            });
+            logger.info('CHROMA_SYNC', 'Batch reconciled via delete+add after duplicate conflict', {
+              collection: this.collectionName,
+              batchStart: i,
+              batchSize: batch.length
+            });
+          } catch (reconcileError) {
+            logger.error('CHROMA_SYNC', 'Batch reconcile (delete+add) failed', {
+              collection: this.collectionName,
+              batchStart: i,
+              batchSize: batch.length
+            }, reconcileError as Error);
+          }
+        } else {
+          logger.error('CHROMA_SYNC', 'Batch add failed, continuing with remaining batches', {
+            collection: this.collectionName,
+            batchStart: i,
+            batchSize: batch.length
+          }, error as Error);
+        }
       }
     }
 

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'
     }
   ]

src/services/worker-service.ts

@@ -101,6 +101,9 @@ import {
   updateCursorContextForProject,
   handleCursorCommand
 } from './integrations/CursorHooksInstaller.js';
+import {
+  handleGeminiCliCommand
+} from './integrations/GeminiCliHooksInstaller.js';
 
 // Service layer imports
 import { DatabaseManager } from './worker/DatabaseManager.js';
@@ -128,6 +131,10 @@ import { MemoryRoutes } from './worker/http/routes/MemoryRoutes.js';
 // Process management for zombie cleanup (Issue #737)
 import { startOrphanReaper, reapOrphanedProcesses, getProcessBySession, ensureProcessExit } from './worker/ProcessRegistry.js';
 
+// Transcript watcher for external CLI session monitoring
+import { TranscriptWatcher } from './transcripts/watcher.js';
+import { loadTranscriptWatchConfig, expandHomePath, DEFAULT_CONFIG_PATH as TRANSCRIPT_CONFIG_PATH } from './transcripts/config.js';
+
 /**
  * Build JSON status output for hook framework communication.
  * This is a pure function extracted for testability.
@@ -189,6 +196,9 @@ export class WorkerService {
   // Stale session reaper interval (Issue #1168)
   private staleSessionReaperInterval: ReturnType<typeof setInterval> | null = null;
 
+  // Transcript watcher for external CLI sessions (e.g. Codex, Gemini)
+  private transcriptWatcher: TranscriptWatcher | null = null;
+
   // AI interaction tracking for health endpoint
   private lastAiInteraction: {
     timestamp: number;
@@ -421,6 +431,22 @@ export class WorkerService {
       this.resolveInitialization();
       logger.info('SYSTEM', 'Core initialization complete (DB + search ready)');
 
+      // Auto-start transcript watchers if configured
+      if (existsSync(TRANSCRIPT_CONFIG_PATH)) {
+        try {
+          const transcriptConfig = loadTranscriptWatchConfig(TRANSCRIPT_CONFIG_PATH);
+          if (transcriptConfig.watches.length > 0) {
+            const transcriptStatePath = expandHomePath(transcriptConfig.stateFile ?? '~/.claude-mem/transcript-watch-state.json');
+            this.transcriptWatcher = new TranscriptWatcher(transcriptConfig, transcriptStatePath);
+            await this.transcriptWatcher.start();
+            logger.info('SYSTEM', `Transcript watcher started with ${transcriptConfig.watches.length} watch target(s)`);
+          }
+        } catch (transcriptError) {
+          logger.warn('SYSTEM', 'Failed to start transcript watcher (non-fatal)', {}, transcriptError as Error);
+          // Non-fatal — worker continues without transcript watching
+        }
+      }
+
       // Auto-backfill Chroma for all projects if out of sync with SQLite (fire-and-forget)
       if (this.chromaMcpManager) {
         ChromaSync.backfillAllProjects().then(() => {
@@ -578,6 +604,13 @@ export class WorkerService {
           'ENOENT',
           'spawn',
           'Invalid API key',
+          'API_KEY_INVALID',
+          'API key expired',
+          'API key not valid',
+          'PERMISSION_DENIED',
+          'Gemini API error: 400',
+          'Gemini API error: 401',
+          'Gemini API error: 403',
           'FOREIGN KEY constraint failed',
         ];
         if (unrecoverablePatterns.some(pattern => errorMessage.includes(pattern))) {
@@ -653,30 +686,26 @@ export class WorkerService {
 
         // Do NOT restart after unrecoverable errors - prevents infinite loops
         if (hadUnrecoverableError) {
-          logger.warn('SYSTEM', 'Skipping restart due to unrecoverable error', {
-            sessionId: session.sessionDbId
-          });
-          this.broadcastProcessingStatus();
+          this.terminateSession(session.sessionDbId, 'unrecoverable_error');
           return;
         }
 
-        // Store for pending-count check below
-        const { PendingMessageStore } = require('./sqlite/PendingMessageStore.js');
-        const pendingStore = new PendingMessageStore(this.dbManager.getSessionStore().db, 3);
-
-        // Idle timeout means no new work arrived for 3 minutes - don't restart
-        // No need to reset stale processing messages here — claimNextMessage() self-heals
-        if (session.idleTimedOut) {
-          logger.info('SYSTEM', 'Generator exited due to idle timeout, not restarting', {
-            sessionId: session.sessionDbId
-          });
-          session.idleTimedOut = false; // Reset flag
-          this.broadcastProcessingStatus();
-          return;
-        }
+        const pendingStore = this.sessionManager.getPendingMessageStore();
 
         // Check if there's pending work that needs processing with a fresh AbortController
         const pendingCount = pendingStore.getPendingCount(session.sessionDbId);
+
+        // Idle timeout means no new work arrived for 3 minutes - don't restart
+        // But check pendingCount first: a message may have arrived between idle
+        // abort and .finally(), and we must not abandon it
+        if (session.idleTimedOut) {
+          session.idleTimedOut = false; // Reset flag
+          if (pendingCount === 0) {
+            this.terminateSession(session.sessionDbId, 'idle_timeout');
+            return;
+          }
+          // Fall through to pending-work restart below
+        }
         const MAX_PENDING_RESTARTS = 3;
 
         if (pendingCount > 0) {
@@ -690,7 +719,7 @@ export class WorkerService {
               consecutiveRestarts: session.consecutiveRestarts
             });
             session.consecutiveRestarts = 0;
-            this.broadcastProcessingStatus();
+            this.terminateSession(session.sessionDbId, 'max_restarts_exceeded');
             return;
           }
 
@@ -703,12 +732,13 @@ export class WorkerService {
           session.abortController = new AbortController();
           // Restart processor
           this.startSessionProcessor(session, 'pending-work-restart');
+          this.broadcastProcessingStatus();
         } else {
-          // Successful completion with no pending work — reset counter
+          // Successful completion with no pending work — clean up session
+          // removeSessionImmediate fires onSessionDeletedCallback → broadcastProcessingStatus()
           session.consecutiveRestarts = 0;
+          this.sessionManager.removeSessionImmediate(session.sessionDbId);
         }
-
-        this.broadcastProcessingStatus();
       });
   }
 
@@ -784,6 +814,30 @@ export class WorkerService {
     this.sessionEventBroadcaster.broadcastSessionCompleted(sessionDbId);
   }
 
+  /**
+   * Terminate a session that will not restart.
+   * Enforces the restart-or-terminate invariant: every generator exit
+   * must either call startSessionProcessor() or terminateSession().
+   * No zombie sessions allowed.
+   *
+   * GENERATOR EXIT INVARIANT:
+   *   .finally() → restart? → startSessionProcessor()
+   *                    no?  → terminateSession()
+   */
+  private terminateSession(sessionDbId: number, reason: string): void {
+    const pendingStore = this.sessionManager.getPendingMessageStore();
+    const abandoned = pendingStore.markAllSessionMessagesAbandoned(sessionDbId);
+
+    logger.info('SYSTEM', 'Session terminated', {
+      sessionId: sessionDbId,
+      reason,
+      abandonedMessages: abandoned
+    });
+
+    // removeSessionImmediate fires onSessionDeletedCallback → broadcastProcessingStatus()
+    this.sessionManager.removeSessionImmediate(sessionDbId);
+  }
+
   /**
    * Process pending session queues
    */
@@ -894,6 +948,13 @@ export class WorkerService {
       this.staleSessionReaperInterval = null;
     }
 
+    // Stop transcript watcher
+    if (this.transcriptWatcher) {
+      this.transcriptWatcher.stop();
+      this.transcriptWatcher = null;
+      logger.info('SYSTEM', 'Transcript watcher stopped');
+    }
+
     await performGracefulShutdown({
       server: this.server.getHttpServer(),
       sessionManager: this.sessionManager,
@@ -907,8 +968,8 @@ export class WorkerService {
    * Broadcast processing status change to SSE clients
    */
   broadcastProcessingStatus(): void {
-    const isProcessing = this.sessionManager.isAnySessionProcessing();
     const queueDepth = this.sessionManager.getTotalActiveWork();
+    const isProcessing = queueDepth > 0;
     const activeSessions = this.sessionManager.getActiveSessionCount();
 
     logger.info('WORKER', 'Broadcasting processing status', {
@@ -1146,14 +1207,21 @@ async function main() {
       break;
     }
 
+    case 'gemini-cli': {
+      const geminiSubcommand = process.argv[3];
+      const geminiResult = await handleGeminiCliCommand(geminiSubcommand, process.argv.slice(4));
+      process.exit(geminiResult);
+      break;
+    }
+
     case 'hook': {
       // Validate CLI args first (before any I/O)
       const platform = process.argv[3];
       const event = process.argv[4];
       if (!platform || !event) {
         console.error('Usage: claude-mem hook <platform> <event>');
-        console.error('Platforms: claude-code, cursor, raw');
-        console.error('Events: context, session-init, observation, summarize, session-complete');
+        console.error('Platforms: claude-code, cursor, gemini-cli, raw');
+        console.error('Events: context, session-init, observation, summarize, session-complete, user-message');
         process.exit(1);
       }
 
@@ -1241,7 +1309,10 @@ async function main() {
 // Check if running as main module in both ESM and CommonJS
 const isMainModule = typeof require !== 'undefined' && typeof module !== 'undefined'
   ? require.main === module || !module.parent
-  : import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('worker-service');
+  : import.meta.url === `file://${process.argv[1]}`
+    || process.argv[1]?.endsWith('worker-service')
+    || process.argv[1]?.endsWith('worker-service.cjs')
+    || process.argv[1]?.replaceAll('\\', '/') === __filename?.replaceAll('\\', '/');
 
 if (isMainModule) {
   main().catch((error) => {

src/services/worker-types.ts

@@ -40,6 +40,8 @@ export interface ActiveSession {
   // CLAIM-CONFIRM FIX: Track IDs of messages currently being processed
   // These IDs will be confirmed (deleted) after successful storage
   processingMessageIds: number[];
+  // Tier routing: model override per session based on queue complexity
+  modelOverride?: string;
 }
 
 export interface PendingMessage {

src/services/worker/SDKAgent.ts

@@ -49,8 +49,8 @@ export class SDKAgent {
     // Find Claude executable
     const claudePath = this.findClaudeExecutable();
 
-    // Get model ID and disallowed tools
-    const modelId = this.getModelId();
+    // Get model ID (tier routing override takes precedence)
+    const modelId = session.modelOverride || this.getModelId();
     // Memory agent is OBSERVER ONLY - no tools allowed
     const disallowedTools = [
       'Bash',           // Prevent infinite loops

src/services/worker/SessionManager.ts

@@ -350,7 +350,7 @@ export class SessionManager {
     this.sessions.delete(sessionDbId);
     this.sessionQueues.delete(sessionDbId);
 
-    logger.info('SESSION', 'Session removed (orphaned after SDK termination)', {
+    logger.info('SESSION', 'Session removed from active sessions', {
       sessionId: sessionDbId,
       project: session.project
     });
@@ -402,10 +402,11 @@ export class SessionManager {
   }
 
   /**
-   * Check if any session has pending messages (for spinner tracking)
+   * Check if any active session has pending messages (for spinner tracking).
+   * Scoped to in-memory sessions only.
    */
   hasPendingMessages(): boolean {
-    return this.getPendingStore().hasAnyPendingWork();
+    return this.getTotalQueueDepth() > 0;
   }
 
   /**
@@ -437,12 +438,12 @@ export class SessionManager {
   }
 
   /**
-   * Check if any session is actively processing (has pending messages OR active generator)
-   * Used for activity indicator to prevent spinner from stopping while SDK is processing
+   * Check if any active session has pending work.
+   * Scoped to in-memory sessions only — orphaned DB messages from dead
+   * sessions must not keep the spinner spinning forever.
    */
   isAnySessionProcessing(): boolean {
-    // hasAnyPendingWork checks for 'pending' OR 'processing'
-    return this.getPendingStore().hasAnyPendingWork();
+    return this.getTotalQueueDepth() > 0;
   }
 
   /**

src/services/worker/events/SessionEventBroadcaster.ts

@@ -33,12 +33,6 @@ export class SessionEventBroadcaster {
       prompt
     });
 
-    // Start activity indicator (work is about to begin)
-    this.sseBroadcaster.broadcast({
-      type: 'processing_status',
-      isProcessing: true
-    });
-
     // Update processing status based on queue depth
     this.workerService.broadcastProcessingStatus();
   }

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

@@ -38,6 +38,7 @@ export class SearchRoutes extends BaseRouteHandler {
     app.get('/api/context/timeline', this.handleGetContextTimeline.bind(this));
     app.get('/api/context/preview', this.handleContextPreview.bind(this));
     app.get('/api/context/inject', this.handleContextInject.bind(this));
+    app.post('/api/context/semantic', this.handleSemanticContext.bind(this));
 
     // Timeline and help endpoints
     app.get('/api/timeline/by-query', this.handleGetTimelineByQuery.bind(this));
@@ -208,6 +209,7 @@ export class SearchRoutes extends BaseRouteHandler {
     // Support both legacy `project` and new `projects` parameter
     const projectsParam = (req.query.projects as string) || (req.query.project as string);
     const useColors = req.query.colors === 'true';
+    const full = req.query.full === 'true';
 
     if (!projectsParam) {
       this.badRequest(res, 'Project(s) parameter is required');
@@ -234,7 +236,8 @@ export class SearchRoutes extends BaseRouteHandler {
       {
         session_id: 'context-inject-' + Date.now(),
         cwd: cwd,
-        projects: projects
+        projects: projects,
+        full
       },
       useColors
     );
@@ -244,6 +247,54 @@ export class SearchRoutes extends BaseRouteHandler {
     res.send(contextText);
   });
 
+  /**
+   * Semantic context search for per-prompt injection
+   * POST /api/context/semantic  { q, project?, limit? }
+   *
+   * Queries Chroma for observations semantically similar to the user's prompt.
+   * Returns compact markdown for injection as additionalContext.
+   */
+  private handleSemanticContext = this.wrapHandler(async (req: Request, res: Response): Promise<void> => {
+    const query = (req.body?.q || req.query.q) as string;
+    const project = (req.body?.project || req.query.project) as string;
+    const limit = Math.min(Math.max(parseInt(String(req.body?.limit || req.query.limit || '5'), 10) || 5, 1), 20);
+
+    if (!query || query.length < 20) {
+      res.json({ context: '', count: 0 });
+      return;
+    }
+
+    try {
+      const result = await this.searchManager.search({
+        query,
+        type: 'observations',
+        project,
+        limit: String(limit),
+        format: 'json'
+      });
+
+      const observations = (result as any)?.observations || [];
+      if (!observations.length) {
+        res.json({ context: '', count: 0 });
+        return;
+      }
+
+      // Format as compact markdown for context injection
+      const lines: string[] = ['## Relevant Past Work (semantic match)\n'];
+      for (const obs of observations.slice(0, limit)) {
+        const date = obs.created_at?.slice(0, 10) || '';
+        lines.push(`### ${obs.title || 'Observation'} (${date})`);
+        if (obs.narrative) lines.push(obs.narrative);
+        lines.push('');
+      }
+
+      res.json({ context: lines.join('\n'), count: observations.length });
+    } catch (error) {
+      logger.error('SEARCH', 'Semantic context query failed', {}, error as Error);
+      res.json({ context: '', count: 0 });
+    }
+  });
+
   /**
    * Get timeline by query (search first, then get timeline around best match)
    * GET /api/timeline/by-query?query=...&mode=auto&depth_before=10&depth_after=10

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

@@ -106,6 +106,8 @@ export class SessionRoutes extends BaseRouteHandler {
 
     // Start generator if not running
     if (!session.generatorPromise) {
+      // Apply tier routing before starting the generator
+      this.applyTierRouting(session);
       this.spawnInProgress.set(sessionDbId, true);
       this.startGeneratorWithProvider(session, selectedProvider, source);
       return;
@@ -126,6 +128,7 @@ export class SessionRoutes extends BaseRouteHandler {
       session.abortController = new AbortController();
       session.lastGeneratorActivity = Date.now();
       // Start a fresh generator
+      this.applyTierRouting(session);
       this.spawnInProgress.set(sessionDbId, true);
       this.startGeneratorWithProvider(session, selectedProvider, 'stale-recovery');
       return;
@@ -283,6 +286,7 @@ export class SessionRoutes extends BaseRouteHandler {
                 this.crashRecoveryScheduled.delete(sessionDbId);
                 const stillExists = this.sessionManager.getSession(sessionDbId);
                 if (stillExists && !stillExists.generatorPromise) {
+                  this.applyTierRouting(stillExists);
                   this.startGeneratorWithProvider(stillExists, this.getSelectedProvider(), 'crash-recovery');
                 }
               }, backoffMs);
@@ -321,6 +325,7 @@ export class SessionRoutes extends BaseRouteHandler {
     app.post('/api/sessions/observations', this.handleObservationsByClaudeId.bind(this));
     app.post('/api/sessions/summarize', this.handleSummarizeByClaudeId.bind(this));
     app.post('/api/sessions/complete', this.handleCompleteByClaudeId.bind(this));
+    app.get('/api/sessions/status', this.handleStatusByClaudeId.bind(this));
   }
 
   /**
@@ -631,6 +636,39 @@ export class SessionRoutes extends BaseRouteHandler {
     res.json({ status: 'queued' });
   });
 
+  /**
+   * Get session status by contentSessionId (summarize handler polls this)
+   * GET /api/sessions/status?contentSessionId=...
+   *
+   * Returns queue depth so the Stop hook can wait for summary completion.
+   */
+  private handleStatusByClaudeId = this.wrapHandler((req: Request, res: Response): void => {
+    const contentSessionId = req.query.contentSessionId as string;
+
+    if (!contentSessionId) {
+      return this.badRequest(res, 'Missing contentSessionId query parameter');
+    }
+
+    const store = this.dbManager.getSessionStore();
+    const sessionDbId = store.createSDKSession(contentSessionId, '', '');
+    const session = this.sessionManager.getSession(sessionDbId);
+
+    if (!session) {
+      res.json({ status: 'not_found', queueLength: 0 });
+      return;
+    }
+
+    const pendingStore = this.sessionManager.getPendingMessageStore();
+    const queueLength = pendingStore.getPendingCount(sessionDbId);
+
+    res.json({
+      status: 'active',
+      sessionDbId,
+      queueLength,
+      uptime: Date.now() - session.startTime
+    });
+  });
+
   /**
    * Complete session by contentSessionId (session-complete hook uses this)
    * POST /api/sessions/complete
@@ -669,6 +707,8 @@ export class SessionRoutes extends BaseRouteHandler {
     }
 
     // Complete the session (removes from active sessions map)
+    // Note: The Stop hook (summarize handler) waits for pending work before calling
+    // this endpoint. No polling here — that's the hook's responsibility.
     await this.completionHandler.completeByDbId(sessionDbId);
 
     logger.info('SESSION', 'Session completed via API', {
@@ -777,4 +817,60 @@ export class SessionRoutes extends BaseRouteHandler {
       contextInjected
     });
   });
+
+  // Simple tool names that produce low-complexity observations
+  private static readonly SIMPLE_TOOLS = new Set([
+    'Read', 'Glob', 'Grep', 'LS', 'ListMcpResourcesTool'
+  ]);
+
+  /**
+   * Apply tier routing: select model based on pending queue complexity.
+   * - Summarize in queue → summary model (e.g., Opus)
+   * - All simple tools → simple model (e.g., Haiku)
+   * - Otherwise → default model (no override)
+   */
+  private applyTierRouting(session: NonNullable<ReturnType<typeof this.sessionManager.getSession>>): void {
+    const settings = SettingsDefaultsManager.loadFromFile(USER_SETTINGS_PATH);
+    if (settings.CLAUDE_MEM_TIER_ROUTING_ENABLED === 'false') {
+      session.modelOverride = undefined;
+      return;
+    }
+
+    // Clear stale override before re-evaluating — prevents previous tier
+    // from persisting when queue composition changes between spawns.
+    session.modelOverride = undefined;
+
+    const pendingStore = this.sessionManager.getPendingMessageStore();
+    const pending = pendingStore.peekPendingTypes(session.sessionDbId);
+
+    if (pending.length === 0) {
+      session.modelOverride = undefined;
+      return;
+    }
+
+    const hasSummarize = pending.some(m => m.message_type === 'summarize');
+    const allSimple = pending.every(m =>
+      m.message_type === 'observation' && m.tool_name && SessionRoutes.SIMPLE_TOOLS.has(m.tool_name)
+    );
+
+    if (hasSummarize) {
+      const summaryModel = settings.CLAUDE_MEM_TIER_SUMMARY_MODEL;
+      if (summaryModel) {
+        session.modelOverride = summaryModel;
+        logger.debug('SESSION', `Tier routing: summary model`, {
+          sessionId: session.sessionDbId, model: summaryModel
+        });
+      }
+    } else if (allSimple) {
+      const simpleModel = settings.CLAUDE_MEM_TIER_SIMPLE_MODEL;
+      if (simpleModel) {
+        session.modelOverride = simpleModel;
+        logger.debug('SESSION', `Tier routing: simple model`, {
+          sessionId: session.sessionDbId, model: simpleModel
+        });
+      }
+    } else {
+      session.modelOverride = undefined;
+    }
+  }
 }

src/services/worker/session/SessionCompletionHandler.ts

@@ -24,9 +24,30 @@ export class SessionCompletionHandler {
    * Used by DELETE /api/sessions/:id and POST /api/sessions/:id/complete
    */
   async completeByDbId(sessionDbId: number): Promise<void> {
-    // Delete from session manager (aborts SDK agent)
+    // Delete from session manager (aborts SDK agent via SIGTERM)
     await this.sessionManager.deleteSession(sessionDbId);
 
+    // Drain orphaned pending messages left by SIGTERM.
+    // When deleteSession() aborts the generator, pending messages in the queue
+    // are never processed. Without drain, they stay in 'pending' status forever
+    // since no future generator will pick them up for a completed session.
+    // Note: this is best-effort — if a generator outlives the 30s SIGTERM timeout
+    // (SessionManager.deleteSession), it may enqueue messages after this drain.
+    // In practice this race is rare (zero orphans over 23 days, 3400+ observations).
+    try {
+      const pendingStore = this.sessionManager.getPendingMessageStore();
+      const drainedCount = pendingStore.markAllSessionMessagesAbandoned(sessionDbId);
+      if (drainedCount > 0) {
+        logger.warn('SESSION', `Drained ${drainedCount} orphaned pending messages on session completion`, {
+          sessionId: sessionDbId, drainedCount
+        });
+      }
+    } catch (e) {
+      logger.debug('SESSION', 'Failed to drain pending queue on session completion', {
+        sessionId: sessionDbId, error: e instanceof Error ? e.message : String(e)
+      });
+    }
+
     // Broadcast session completed event
     this.eventBroadcaster.broadcastSessionCompleted(sessionDbId);
   }

src/shared/SettingsDefaultsManager.ts

@@ -54,6 +54,13 @@ export interface SettingsDefaults {
   // Exclusion Settings
   CLAUDE_MEM_EXCLUDED_PROJECTS: string;  // Comma-separated glob patterns for excluded project paths
   CLAUDE_MEM_FOLDER_MD_EXCLUDE: string;  // JSON array of folder paths to exclude from CLAUDE.md generation
+  // Semantic Context Injection (per-prompt via Chroma)
+  CLAUDE_MEM_SEMANTIC_INJECT: string;        // 'true' | 'false' - inject relevant observations on each prompt
+  CLAUDE_MEM_SEMANTIC_INJECT_LIMIT: string;  // Max observations to inject per prompt
+  // Tier Routing (model selection by queue complexity)
+  CLAUDE_MEM_TIER_ROUTING_ENABLED: string;   // 'true' | 'false' - enable model tier routing
+  CLAUDE_MEM_TIER_SIMPLE_MODEL: string;      // Tier alias or model ID for simple tool observations (Read, Glob, Grep)
+  CLAUDE_MEM_TIER_SUMMARY_MODEL: string;     // Tier alias or model ID for session summaries
   // Chroma Vector Database Configuration
   CLAUDE_MEM_CHROMA_ENABLED: string;   // 'true' | 'false' - set to 'false' for SQLite-only mode
   CLAUDE_MEM_CHROMA_MODE: string;      // 'local' | 'remote'
@@ -113,6 +120,13 @@ export class SettingsDefaultsManager {
     // Exclusion Settings
     CLAUDE_MEM_EXCLUDED_PROJECTS: '',  // Comma-separated glob patterns for excluded project paths
     CLAUDE_MEM_FOLDER_MD_EXCLUDE: '[]',  // JSON array of folder paths to exclude from CLAUDE.md generation
+    // Semantic Context Injection (per-prompt via Chroma vector search)
+    CLAUDE_MEM_SEMANTIC_INJECT: 'true',              // Inject relevant past observations on every UserPromptSubmit
+    CLAUDE_MEM_SEMANTIC_INJECT_LIMIT: '5',           // Top-N most relevant observations to inject per prompt
+    // Tier Routing (model selection by queue complexity)
+    CLAUDE_MEM_TIER_ROUTING_ENABLED: 'true',         // Route observations to models by complexity
+    CLAUDE_MEM_TIER_SIMPLE_MODEL: 'haiku', // Portable tier alias — works across Direct API, Bedrock, Vertex, Azure (see #1463)
+    CLAUDE_MEM_TIER_SUMMARY_MODEL: '',                // Empty = use default model for summaries
     // Chroma Vector Database Configuration
     CLAUDE_MEM_CHROMA_ENABLED: 'true',         // Set to 'false' to disable Chroma and use SQLite-only search
     CLAUDE_MEM_CHROMA_MODE: 'local',           // 'local' uses persistent chroma-mcp via uvx, 'remote' connects to existing server

src/supervisor/env-sanitizer.ts

@@ -6,11 +6,18 @@ export const ENV_EXACT_MATCHES = new Set([
   'MCP_SESSION_ID',
 ]);
 
+/** Vars that start with CLAUDE_CODE_ but must be preserved for subprocess auth/tooling */
+export const ENV_PRESERVE = new Set([
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'CLAUDE_CODE_GIT_BASH_PATH',
+]);
+
 export function sanitizeEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
   const sanitized: NodeJS.ProcessEnv = {};
 
   for (const [key, value] of Object.entries(env)) {
     if (value === undefined) continue;
+    if (ENV_PRESERVE.has(key)) { sanitized[key] = value; continue; }
     if (ENV_EXACT_MATCHES.has(key)) continue;
     if (ENV_PREFIXES.some(prefix => key.startsWith(prefix))) continue;
     sanitized[key] = value;

src/utils/context-injection.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared context injection utilities for claude-mem.
+ *
+ * Provides tag constants and a function to inject or update a
+ * <claude-mem-context> section in any markdown file. Used by
+ * MCP integrations and OpenCode installer.
+ */
+
+import path from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+
+// ============================================================================
+// Tag Constants
+// ============================================================================
+
+export const CONTEXT_TAG_OPEN = '<claude-mem-context>';
+export const CONTEXT_TAG_CLOSE = '</claude-mem-context>';
+
+// ============================================================================
+// Context Injection
+// ============================================================================
+
+/**
+ * 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.
+ *
+ * @param filePath - Absolute path to the target markdown file.
+ * @param contextContent - The content to place between the context tags.
+ * @param headerLine - Optional first line written when creating a new file
+ *                     (e.g. `"# Claude-Mem Memory Context"` for AGENTS.md).
+ */
+export function injectContextIntoMarkdownFile(
+  filePath: string,
+  contextContent: string,
+  headerLine?: 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 {
+    // Create new file
+    if (headerLine) {
+      writeFileSync(filePath, `${headerLine}\n\n${wrappedContent}\n`, 'utf-8');
+    } else {
+      writeFileSync(filePath, wrappedContent + '\n', 'utf-8');
+    }
+  }
+}

src/utils/json-utils.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared JSON file utilities for claude-mem.
+ *
+ * Provides safe read/write helpers used across the CLI and services.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { logger } from './logger.js';
+
+/**
+ * Read a JSON file safely, returning a default value if the file
+ * does not exist. Throws on corrupt JSON to prevent silent data loss
+ * when callers merge and write back.
+ *
+ * @param filePath - Absolute path to the JSON file.
+ * @param defaultValue - Value returned when the file is missing.
+ * @returns The parsed JSON content, or `defaultValue` when file is missing.
+ * @throws {Error} When the file exists but contains invalid JSON.
+ */
+export function readJsonSafe<T>(filePath: string, defaultValue: T): T {
+  if (!existsSync(filePath)) return defaultValue;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch (error) {
+    throw new Error(`Corrupt JSON file, refusing to overwrite: ${filePath}`);
+  }
+}

src/utils/tag-stripping.ts

@@ -1,11 +1,13 @@
 /**
  * Tag Stripping Utilities
  *
- * Implements the dual-tag system for meta-observation control:
+ * Implements the tag system for meta-observation control:
  * 1. <claude-mem-context> - System-level tag for auto-injected observations
  *    (prevents recursive storage when context injection is active)
  * 2. <private> - User-level tag for manual privacy control
  *    (allows users to mark content they don't want persisted)
+ * 3. <system_instruction> / <system-instruction> - Conductor-injected system instructions
+ *    (should not be persisted to memory)
  *
  * EDGE PROCESSING PATTERN: Filter at hook layer before sending to worker/storage.
  * This keeps the worker service simple and follows one-way data stream.
@@ -27,7 +29,9 @@ const MAX_TAG_COUNT = 100;
 function countTags(content: string): number {
   const privateCount = (content.match(/<private>/g) || []).length;
   const contextCount = (content.match(/<claude-mem-context>/g) || []).length;
-  return privateCount + contextCount;
+  const systemInstructionCount = (content.match(/<system_instruction>/g) || []).length;
+  const systemInstructionHyphenCount = (content.match(/<system-instruction>/g) || []).length;
+  return privateCount + contextCount + systemInstructionCount + systemInstructionHyphenCount;
 }
 
 /**
@@ -49,6 +53,8 @@ function stripTagsInternal(content: string): string {
   return content
     .replace(/<claude-mem-context>[\s\S]*?<\/claude-mem-context>/g, '')
     .replace(/<private>[\s\S]*?<\/private>/g, '')
+    .replace(/<system_instruction>[\s\S]*?<\/system_instruction>/g, '')
+    .replace(/<system-instruction>[\s\S]*?<\/system-instruction>/g, '')
     .trim();
 }
 

tests/context-injection.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import {
+  injectContextIntoMarkdownFile,
+  CONTEXT_TAG_OPEN,
+  CONTEXT_TAG_CLOSE,
+} from '../src/utils/context-injection';
+
+/**
+ * Tests for the shared context injection utility.
+ *
+ * injectContextIntoMarkdownFile is used by MCP integrations and OpenCode
+ * installer to inject or update a <claude-mem-context> section in markdown files.
+ */
+
+describe('Context Injection', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = join(tmpdir(), `context-injection-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  describe('tag constants', () => {
+    it('exports correct open and close tags', () => {
+      expect(CONTEXT_TAG_OPEN).toBe('<claude-mem-context>');
+      expect(CONTEXT_TAG_CLOSE).toBe('</claude-mem-context>');
+    });
+  });
+
+  describe('inject into new file', () => {
+    it('creates a new file with context tags when file does not exist', () => {
+      const filePath = join(tempDir, 'CLAUDE.md');
+
+      injectContextIntoMarkdownFile(filePath, 'Hello world');
+
+      expect(existsSync(filePath)).toBe(true);
+      const content = readFileSync(filePath, 'utf-8');
+      expect(content).toContain(CONTEXT_TAG_OPEN);
+      expect(content).toContain('Hello world');
+      expect(content).toContain(CONTEXT_TAG_CLOSE);
+    });
+
+    it('creates parent directories if they do not exist', () => {
+      const filePath = join(tempDir, 'nested', 'deep', 'CLAUDE.md');
+
+      injectContextIntoMarkdownFile(filePath, 'test content');
+
+      expect(existsSync(filePath)).toBe(true);
+    });
+
+    it('writes content wrapped in context tags', () => {
+      const filePath = join(tempDir, 'CLAUDE.md');
+      const contextContent = '# Recent Activity\n\nSome memory data here.';
+
+      injectContextIntoMarkdownFile(filePath, contextContent);
+
+      const content = readFileSync(filePath, 'utf-8');
+      const expected = `${CONTEXT_TAG_OPEN}\n${contextContent}\n${CONTEXT_TAG_CLOSE}\n`;
+      expect(content).toBe(expected);
+    });
+  });
+
+  describe('headerLine support', () => {
+    it('prepends headerLine when creating a new file', () => {
+      const filePath = join(tempDir, 'AGENTS.md');
+      const headerLine = '# Claude-Mem Memory Context';
+
+      injectContextIntoMarkdownFile(filePath, 'context data', headerLine);
+
+      const content = readFileSync(filePath, 'utf-8');
+      expect(content.startsWith(headerLine)).toBe(true);
+      expect(content).toContain(CONTEXT_TAG_OPEN);
+      expect(content).toContain('context data');
+    });
+
+    it('places a blank line between headerLine and context tags', () => {
+      const filePath = join(tempDir, 'AGENTS.md');
+      const headerLine = '# My Header';
+
+      injectContextIntoMarkdownFile(filePath, 'data', headerLine);
+
+      const content = readFileSync(filePath, 'utf-8');
+      expect(content).toBe(`${headerLine}\n\n${CONTEXT_TAG_OPEN}\ndata\n${CONTEXT_TAG_CLOSE}\n`);
+    });
+
+    it('does not use headerLine when file already exists', () => {
+      const filePath = join(tempDir, 'AGENTS.md');
+      writeFileSync(filePath, '# Existing Content\n\nSome stuff.\n');
+
+      injectContextIntoMarkdownFile(filePath, 'new context', '# Should Not Appear');
+
+      const content = readFileSync(filePath, 'utf-8');
+      expect(content).toContain('# Existing Content');
+      expect(content).not.toContain('# Should Not Appear');
+      expect(content).toContain('new context');
+    });
+  });
+
+  describe('replace existing context section', () => {
+    it('replaces content between existing context tags', () => {
+      const filePath = join(tempDir, 'CLAUDE.md');
+      const initialContent = [
+        '# Project Instructions',
+        '',
+        `${CONTEXT_TAG_OPEN}`,
+        'Old context data',
+        `${CONTEXT_TAG_CLOSE}`,
+        '',
+        '## Other stuff',
+      ].join('\n');
+      writeFileSync(filePath, initialContent);
+
+      injectContextIntoMarkdownFile(filePath, 'New context data');
+
+      const content = readFileSync(filePath, 'utf-8');
+      expect(content).toContain('New context data');
+      expect(content).not.toContain('Old context data');
+      expect(content).toContain('# Project Instructions');
+      expect(content).toContain('## Other stuff');
+    });
+
+    it('preserves content before and after the context section', () => {
+      const filePath = join(tempDir, 'CLAUDE.md');
+      const before = '# Header\n\nSome instructions.\n\n';
+      const after = '\n\n## Footer\n\nMore content.\n';
+      const initialContent = `${before}${CONTEXT_TAG_OPEN}\nold\n${CONTEXT_TAG_CLOSE}${after}`;
+      writeFileSync(filePath, initialContent);
+
+      injectContextIntoMarkdownFile(filePath, 'replaced');
+
+      const content = readFileSync(filePath, 'utf-8');
+      expect(content).toContain('# Header');
+      expect(content).toContain('Some instructions.');
+      expect(content).toContain('## Footer');
+      expect(content).toContain('More content.');
+      expect(content).toContain('replaced');
+      expect(content).not.toContain('old');
+    });
+  });
+
+  describe('append to existing file', () => {
+    it('appends context section to file without existing tags', () => {
+      const filePath = join(tempDir, 'CLAUDE.md');
+      writeFileSync(filePath, '# My Project\n\nInstructions here.\n');
+
+      injectContextIntoMarkdownFile(filePath, 'appended context');
+
+      const content = readFileSync(filePath, 'utf-8');
+      expect(content).toContain('# My Project');
+      expect(content).toContain('Instructions here.');
+      expect(content).toContain(CONTEXT_TAG_OPEN);
+      expect(content).toContain('appended context');
+      expect(content).toContain(CONTEXT_TAG_CLOSE);
+    });
+
+    it('separates appended section with a blank line', () => {
+      const filePath = join(tempDir, 'CLAUDE.md');
+      writeFileSync(filePath, '# Header');
+
+      injectContextIntoMarkdownFile(filePath, 'data');
+
+      const content = readFileSync(filePath, 'utf-8');
+      // Should have double newline before the tag
+      expect(content).toContain(`# Header\n\n${CONTEXT_TAG_OPEN}`);
+    });
+
+    it('trims trailing whitespace before appending', () => {
+      const filePath = join(tempDir, 'CLAUDE.md');
+      writeFileSync(filePath, '# Header\n\n\n   \n');
+
+      injectContextIntoMarkdownFile(filePath, 'data');
+
+      const content = readFileSync(filePath, 'utf-8');
+      // Should not have excessive whitespace before the tag
+      expect(content).toContain(`# Header\n\n${CONTEXT_TAG_OPEN}`);
+    });
+  });
+
+  describe('idempotency', () => {
+    it('produces same result when called twice with same content', () => {
+      const filePath = join(tempDir, 'CLAUDE.md');
+
+      injectContextIntoMarkdownFile(filePath, 'stable content');
+      const firstWrite = readFileSync(filePath, 'utf-8');
+
+      injectContextIntoMarkdownFile(filePath, 'stable content');
+      const secondWrite = readFileSync(filePath, 'utf-8');
+
+      expect(secondWrite).toBe(firstWrite);
+    });
+
+    it('updates content when called with different data', () => {
+      const filePath = join(tempDir, 'CLAUDE.md');
+
+      injectContextIntoMarkdownFile(filePath, 'version 1');
+      injectContextIntoMarkdownFile(filePath, 'version 2');
+
+      const content = readFileSync(filePath, 'utf-8');
+      expect(content).toContain('version 2');
+      expect(content).not.toContain('version 1');
+    });
+  });
+});

tests/infrastructure/health-monitor.test.ts

@@ -1,4 +1,5 @@
-import { describe, it, expect, beforeEach, afterEach, mock } from 'bun:test';
+import { describe, it, expect, beforeEach, afterEach, mock, spyOn } from 'bun:test';
+import net from 'net';
 import {
   isPortInUse,
   waitForHealth,
@@ -15,45 +16,73 @@ describe('HealthMonitor', () => {
   });
 
   describe('isPortInUse', () => {
-    it('should return true for occupied port (health check succeeds)', async () => {
-      global.fetch = mock(() => Promise.resolve({ ok: true } as Response));
+    // Note: Since we are on Linux (as per session_context), isPortInUse uses 'net'
+    // instead of 'fetch'. We need to mock 'net.createServer().listen()'
+
+    it('should return true for occupied port (EADDRINUSE)', async () => {
+      // Create a specific mock for this test
+      const createServerMock = mock(() => ({
+        once: mock((event: string, cb: Function) => {
+          if (event === 'error') {
+            // Trigger EADDRINUSE immediately
+            setTimeout(() => cb({ code: 'EADDRINUSE' }), 0);
+          }
+        }),
+        listen: mock(() => {})
+      }));
+      
+      const spy = spyOn(net, 'createServer').mockImplementation(createServerMock as any);
 
       const result = await isPortInUse(37777);
 
       expect(result).toBe(true);
-      expect(global.fetch).toHaveBeenCalledWith('http://127.0.0.1:37777/api/health');
+      expect(net.createServer).toHaveBeenCalled();
+      
+      spy.mockRestore();
     });
 
-    it('should return false for free port (connection refused)', async () => {
-      global.fetch = mock(() => Promise.reject(new Error('ECONNREFUSED')));
+    it('should return false for free port (listening succeeds)', async () => {
+      const closeMock = mock((cb: Function) => cb());
+      const createServerMock = mock(() => ({
+        once: mock((event: string, cb: Function) => {
+          if (event === 'listening') {
+            // Trigger listening success
+            setTimeout(() => cb(), 0);
+          }
+        }),
+        listen: mock(() => {}),
+        close: closeMock
+      }));
+      
+      const spy = spyOn(net, 'createServer').mockImplementation(createServerMock as any);
 
       const result = await isPortInUse(39999);
 
       expect(result).toBe(false);
+      expect(net.createServer).toHaveBeenCalled();
+      expect(closeMock).toHaveBeenCalled();
+      
+      spy.mockRestore();
     });
 
-    it('should return false when health check returns non-ok', async () => {
-      global.fetch = mock(() => Promise.resolve({ ok: false, status: 503 } as Response));
-
-      const result = await isPortInUse(37777);
-
-      expect(result).toBe(false);
-    });
-
-    it('should return false on network timeout', async () => {
-      global.fetch = mock(() => Promise.reject(new Error('ETIMEDOUT')));
-
-      const result = await isPortInUse(37777);
-
-      expect(result).toBe(false);
-    });
-
-    it('should return false on fetch failed error', async () => {
-      global.fetch = mock(() => Promise.reject(new Error('fetch failed')));
+    it('should return false for other socket errors', async () => {
+      const createServerMock = mock(() => ({
+        once: mock((event: string, cb: Function) => {
+          if (event === 'error') {
+            // Trigger other error (e.g., EACCES)
+            setTimeout(() => cb({ code: 'EACCES' }), 0);
+          }
+        }),
+        listen: mock(() => {})
+      }));
+      
+      const spy = spyOn(net, 'createServer').mockImplementation(createServerMock as any);
 
       const result = await isPortInUse(37777);
 
       expect(result).toBe(false);
+      
+      spy.mockRestore();
     });
   });
 
@@ -203,54 +232,80 @@ describe('HealthMonitor', () => {
 
   describe('waitForPortFree', () => {
     it('should return true immediately when port is already free', async () => {
-      global.fetch = mock(() => Promise.reject(new Error('ECONNREFUSED')));
+      const createServerMock = mock(() => ({
+        once: mock((event: string, cb: Function) => {
+          if (event === 'listening') setTimeout(() => cb(), 0);
+        }),
+        listen: mock(() => {}),
+        close: mock((cb: Function) => cb())
+      }));
+      const spy = spyOn(net, 'createServer').mockImplementation(createServerMock as any);
 
       const start = Date.now();
       const result = await waitForPortFree(39999, 5000);
       const elapsed = Date.now() - start;
 
       expect(result).toBe(true);
-      // Should return quickly
       expect(elapsed).toBeLessThan(1000);
+      spy.mockRestore();
     });
 
     it('should timeout when port remains occupied', async () => {
-      global.fetch = mock(() => Promise.resolve({ ok: true } as Response));
+      const createServerMock = mock(() => ({
+        once: mock((event: string, cb: Function) => {
+          if (event === 'error') setTimeout(() => cb({ code: 'EADDRINUSE' }), 0);
+        }),
+        listen: mock(() => {})
+      }));
+      const spy = spyOn(net, 'createServer').mockImplementation(createServerMock as any);
 
       const start = Date.now();
       const result = await waitForPortFree(37777, 1500);
       const elapsed = Date.now() - start;
 
       expect(result).toBe(false);
-      // Should take close to timeout duration
       expect(elapsed).toBeGreaterThanOrEqual(1400);
       expect(elapsed).toBeLessThan(2500);
+      spy.mockRestore();
     });
 
     it('should succeed when port becomes free', async () => {
       let callCount = 0;
-      global.fetch = mock(() => {
-        callCount++;
-        // Port occupied for first 2 checks, then free
-        if (callCount < 3) {
-          return Promise.resolve({ ok: true } as Response);
-        }
-        return Promise.reject(new Error('ECONNREFUSED'));
-      });
+      const spy = spyOn(net, 'createServer').mockImplementation(() => ({
+        once: mock((event: string, cb: Function) => {
+          callCount++;
+          // Port occupied for first 2 checks, then free
+          if (callCount < 3) {
+            if (event === 'error') setTimeout(() => cb({ code: 'EADDRINUSE' }), 0);
+          } else {
+            if (event === 'listening') setTimeout(() => cb(), 0);
+          }
+        }),
+        listen: mock(() => {}),
+        close: mock((cb: Function) => cb())
+      } as any));
 
       const result = await waitForPortFree(37777, 5000);
 
       expect(result).toBe(true);
       expect(callCount).toBeGreaterThanOrEqual(3);
+      spy.mockRestore();
     });
 
     it('should use default timeout when not specified', async () => {
-      global.fetch = mock(() => Promise.reject(new Error('ECONNREFUSED')));
+      const createServerMock = mock(() => ({
+        once: mock((event: string, cb: Function) => {
+          if (event === 'listening') setTimeout(() => cb(), 0);
+        }),
+        listen: mock(() => {}),
+        close: mock((cb: Function) => cb())
+      }));
+      const spy = spyOn(net, 'createServer').mockImplementation(createServerMock as any);
 
-      // Just verify it doesn't throw and returns quickly
       const result = await waitForPortFree(39999);
 
       expect(result).toBe(true);
+      spy.mockRestore();
     });
   });
 });

tests/infrastructure/plugin-distribution.test.ts

@@ -67,11 +67,14 @@ describe('Plugin Distribution - hooks.json Integrity', () => {
     expect(parsed.hooks).toBeDefined();
   });
 
-  it('should reference CLAUDE_PLUGIN_ROOT in all hook commands', () => {
+  it('should reference CLAUDE_PLUGIN_ROOT in all hook commands (except inline hooks)', () => {
     const hooksPath = path.join(projectRoot, 'plugin/hooks/hooks.json');
     const parsed = JSON.parse(readFileSync(hooksPath, 'utf-8'));
+    // SessionEnd uses a lightweight inline node -e command (no plugin root needed)
+    const inlineHookEvents = new Set(['SessionEnd']);
 
     for (const [eventName, matchers] of Object.entries(parsed.hooks)) {
+      if (inlineHookEvents.has(eventName)) continue;
       for (const matcher of matchers as any[]) {
         for (const hook of matcher.hooks) {
           if (hook.type === 'command') {
@@ -82,12 +85,14 @@ describe('Plugin Distribution - hooks.json Integrity', () => {
     }
   });
 
-  it('should include CLAUDE_PLUGIN_ROOT fallback in all hook commands (#1215)', () => {
+  it('should include CLAUDE_PLUGIN_ROOT fallback in all hook commands except inline hooks (#1215)', () => {
     const hooksPath = path.join(projectRoot, 'plugin/hooks/hooks.json');
     const parsed = JSON.parse(readFileSync(hooksPath, 'utf-8'));
     const expectedFallbackPath = '$HOME/.claude/plugins/marketplaces/thedotmack/plugin';
+    const inlineHookEvents = new Set(['SessionEnd']);
 
     for (const [eventName, matchers] of Object.entries(parsed.hooks)) {
+      if (inlineHookEvents.has(eventName)) continue;
       for (const matcher of matchers as any[]) {
         for (const hook of matcher.hooks) {
           if (hook.type === 'command') {
@@ -97,6 +102,18 @@ describe('Plugin Distribution - hooks.json Integrity', () => {
       }
     }
   });
+
+  it('should use lightweight inline node command for SessionEnd hook', () => {
+    const hooksPath = path.join(projectRoot, 'plugin/hooks/hooks.json');
+    const parsed = JSON.parse(readFileSync(hooksPath, 'utf-8'));
+    const sessionEndHooks = parsed.hooks.SessionEnd;
+    expect(sessionEndHooks).toBeDefined();
+    expect(sessionEndHooks.length).toBe(1);
+    const command = sessionEndHooks[0].hooks[0].command;
+    expect(command).toContain('node -e');
+    expect(command).toContain('/api/sessions/complete');
+    expect(sessionEndHooks[0].hooks[0].timeout).toBeLessThanOrEqual(10);
+  });
 });
 
 describe('Plugin Distribution - package.json Files Field', () => {

tests/install-non-tty.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'bun:test';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Tests for the non-TTY detection in the install command.
+ *
+ * The install command (src/npx-cli/commands/install.ts) has non-interactive
+ * fallbacks so it works in CI/CD, Docker, and piped environments where
+ * process.stdin.isTTY is undefined.
+ *
+ * Since isInteractive, runTasks, and log are not exported, we verify
+ * their presence and correctness via source inspection. This is a valid
+ * approach for testing private module-level constructs that can't be
+ * imported directly.
+ */
+
+const installSourcePath = join(
+  __dirname,
+  '..',
+  'src',
+  'npx-cli',
+  'commands',
+  'install.ts',
+);
+const installSource = readFileSync(installSourcePath, 'utf-8');
+
+describe('Install Non-TTY Support', () => {
+  describe('isInteractive flag', () => {
+    it('defines isInteractive based on process.stdin.isTTY', () => {
+      expect(installSource).toContain('const isInteractive = process.stdin.isTTY === true');
+    });
+
+    it('uses strict equality (===) not truthy check for isTTY', () => {
+      // Ensures undefined isTTY is treated as false, not just falsy
+      const match = installSource.match(/const isInteractive = process\.stdin\.isTTY === true/);
+      expect(match).not.toBeNull();
+    });
+  });
+
+  describe('runTasks helper', () => {
+    it('defines a runTasks function', () => {
+      expect(installSource).toContain('async function runTasks');
+    });
+
+    it('has interactive branch using p.tasks', () => {
+      expect(installSource).toContain('await p.tasks(tasks)');
+    });
+
+    it('has non-interactive fallback using console.log', () => {
+      // In non-TTY mode, tasks iterate and log output directly
+      expect(installSource).toContain('console.log(`  ${msg}`)');
+    });
+
+    it('branches on isInteractive', () => {
+      expect(installSource).toContain('if (isInteractive)');
+    });
+  });
+
+  describe('log wrapper', () => {
+    it('defines log.info that falls back to console.log', () => {
+      expect(installSource).toContain('info: (msg: string) =>');
+      // Should have console.log fallback
+      expect(installSource).toMatch(/info:.*console\.log/);
+    });
+
+    it('defines log.success that falls back to console.log', () => {
+      expect(installSource).toContain('success: (msg: string) =>');
+      expect(installSource).toMatch(/success:.*console\.log/);
+    });
+
+    it('defines log.warn that falls back to console.warn', () => {
+      expect(installSource).toContain('warn: (msg: string) =>');
+      expect(installSource).toMatch(/warn:.*console\.warn/);
+    });
+
+    it('defines log.error that falls back to console.error', () => {
+      expect(installSource).toContain('error: (msg: string) =>');
+      expect(installSource).toMatch(/error:.*console\.error/);
+    });
+  });
+
+  describe('non-interactive install path', () => {
+    it('defaults to claude-code when not interactive and no IDE specified', () => {
+      // The non-interactive path should have a fallback
+      expect(installSource).toContain("selectedIDEs = ['claude-code']");
+    });
+
+    it('uses console.log for intro in non-interactive mode', () => {
+      expect(installSource).toContain("console.log('claude-mem install')");
+    });
+
+    it('uses console.log for note/summary in non-interactive mode', () => {
+      expect(installSource).toContain("console.log(`\\n  ${installStatus}`)");
+    });
+  });
+
+  describe('TaskDescriptor interface', () => {
+    it('defines a task interface with title and task function', () => {
+      expect(installSource).toContain('interface TaskDescriptor');
+      expect(installSource).toContain('title: string');
+      expect(installSource).toContain('task: (message: (msg: string) => void) => Promise<string>');
+    });
+  });
+
+  describe('InstallOptions interface', () => {
+    it('exports InstallOptions with optional ide field', () => {
+      expect(installSource).toContain('export interface InstallOptions');
+      expect(installSource).toContain('ide?: string');
+    });
+  });
+});